Nuitka the Python Compiler

https://nuitka.net/
Admin
Nuitka is the optimizing Python compiler written in Python that creates executables that run without...
Tokens:1,134,381
Snippets:9,564
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Method freelist setup

Source: https://nuitka.net/apidoc/CompiledMethodType_8c_source.html

Freelist setup for method objects, with a maximum count of 100.

```c
// Freelist setup
#define MAX_METHOD_FREE_LIST_COUNT 100
static struct Nuitka_MethodObject *free_list_methods = NULL;
static int free_list_methods_count = 0;
```

--------------------------------

### Configure Nuitka options in setup.py for setuptools

Source: https://nuitka.net/user-documentation/use-cases.html

Shows two ways to pass Nuitka options via command_options in setup.py: one for setups without other build systems, and one for setups with other build systems (e.g., setuptools_rust) where tuple values are required. Both examples include boolean, valueless, single-value, and multi-value options.

```python
# For setup.py if you don't use other build systems:
setup(
   # Data files are to be handled by setuptools and not Nuitka
   package_data={"some_package": ["some_file.txt"]},
   ...,
   # This is to pass Nuitka options.
   command_options={
      'nuitka': {
         # boolean option, e.g. if you cared for C compilation commands
         '--show-scons': True,
         # options without value, e.g. enforce using Clang
         '--clang': None,
         # options with single values, e.g. enable a plugin of Nuitka
         '--enable-plugin': "pyside2",
         # options with several values, e.g. avoid including modules
         '--nofollow-import-to' : ["*.tests", "*.distutils"],
      }
   },
)

# For setup.py with other build systems:
# The tuple nature of the arguments is required by the dark nature of
# "setuptools" and plugins to it, that insist on full compatibility,
# e.g. "setuptools_rust"

setup(
   # Data files are to be handled by setuptools and not Nuitka
   package_data={"some_package": ["some_file.txt"]},
   ...,
   # This is to pass Nuitka options.
   ...,
   command_options={
      'nuitka': {
         # boolean option, e.g. if you cared for C compilation commands
         '--show-scons': ("setup.py", True),
         # options without value, e.g. enforce using Clang
         '--clang': ("setup.py", None),
         # options with single values, e.g. enable a plugin of Nuitka
         '--enable-plugin': ("setup.py", "pyside2"),
         # options with several values, e.g. avoid including modules
         '--nofollow-import-to' : ("setup.py", ["*.tests", "*.distutils"]),
      }
   },
)

```

--------------------------------

### Create installers with --windows-create-installer, --macos-create-installer, --linux-create-installer

Source: https://nuitka.net/user-documentation/user-manual.html

Creates installers for standalone builds on Windows (NSIS), macOS (DMG), and Linux (AppImage). The Linux installer uses appimagetool from PATH or a cached download.

```bash
python -m nuitka --mode=standalone --windows-create-installer program.py
python -m nuitka --mode=standalone --macos-create-installer program.py
python -m nuitka --mode=standalone --linux-create-installer program.py
```

--------------------------------

### Nuitka project configuration with conditional directives

Source: https://nuitka.net/changelog/Changelog-0.x.html

Example project configuration file for Nuitka. It uses conditional directives to select compilation mode based on the OS, enables plugins for PySide2, pkg-resources, and commercial features, and includes Qt data files. Refer to the User Manual for a table of directives and allowed variables.

```python
# Compilation mode, support OS specific.
# nuitka-project-if: {OS} in ("Windows", "Linux"):
#    nuitka-project: --onefile
# nuitka-project-if: {OS} not in ("Windows", "Linux"):
#    nuitka-project: --standalone

# The PySide2 plugin covers qt-plugins
# nuitka-project: --enable-plugin=pyside2
# nuitka-project: --include-qt-plugins=sensible,qml

# The pkg-resources plugin is not yet automatic
# nuitka-project: --enable-plugin=pkg-resources

# Nuitka Commercial only features follow:

# Protect the constants from being readable.
# nuitka-project: --enable-plugin=data-hiding

# Include datafiles for Qt into the binary directory.
# nuitka-project: --enable-plugin=datafile-inclusion
# nuitka-project: --qt-datadir={MAIN_DIRECTORY}
# nuitka-project: --qt-datafile-pattern=*.js
# nuitka-project: --qt-datafile-pattern=*.qml
# nuitka-project: --qt-datafile-pattern=*.svg
# nuitka-project: --qt-datafile-pattern=*.png

```

--------------------------------

### Unpacking length detection examples

Source: https://nuitka.net/changelog/Changelog-0.x.html

Illustrates iterator tracing for unpacking length checks. The first assignment is safe, while the second always raises because the source has three items but the target has two.

```python
a, b = b, a  # Will never raise due to unpacking
a, b = b, a, c  # Will always raise, 3 items cannot unpack to 2
```

--------------------------------

### Reproduce importlib.resources.read_bytes() error

Source: https://nuitka.net/changelog/Changelog-0.x.html

This example shows a call to `importlib.resources.read_bytes()` that previously gave an error because hard imported sub-modules of hard imports were falsely resolved to their parent. It is used to reproduce the bug fix.

```python
importlib.resources.read_bytes() # gave importlib has no attribute...

```

--------------------------------

### Loop example for two-pass SSA analysis

Source: https://nuitka.net/doc/developer-manual.html

Example loop used to illustrate the two-pass handling of loops in SSA analysis. The loop start may have an assumption from before it started, but that is only true for the first iteration, so knowledge from outside cannot be passed directly into the loop body. The loop is re-formulated with break statements, and the loop end is considered a continue for the analysis.

```python
a = 1

while 1:  # think loop: here
    b = a + 1
    a = b

    if cond():
        break

print(a)

```

--------------------------------

### Example 1: Include DLL with known prefix

Source: https://nuitka.net/doc/nuitka-package-config.html

Very simple example, the normal case, include a DLL with a known prefix from its package directory.

```yaml
- module-name: 'vosk'
  dlls:
    - from_filenames:
        prefixes:
          - 'libvosk'

```

--------------------------------

### Context manager naming example

Source: https://nuitka.net/doc/developer-manual.html

Demonstrates the naming convention for context managers, which start with 'with' to make them easily recognizable.

```python
with withEnvironmentPathAdded(os.path.join(sys.prefix, "bin")):
    with withDirectoryChange(self.qt_datadir):
        ...

```

--------------------------------

### variables configuration example

Source: https://nuitka.net/doc/nuitka-package-config.html

Shows how to define compile-time package variables using setup_code and declarations.

```yaml
variables:
  setup_code: 'import whatever'
  declarations:
    'variable1_name': 'whatever.something()'
    'variable2_name': 'whatever.something2()'

```

--------------------------------

### Frame guard example: explicit frame guard

Source: https://nuitka.net/doc/developer-manual.html

Starting point for frame guard optimization: the frame guard is explicit and covers the whole function body.

```python
def f():
    with frame_guard("f"):
        if someNotRaisingCall():
            return somePotentiallyRaisingCall()
        else:
            return None

```

--------------------------------

### Run initial binary (Version 1.0)

Source: https://nuitka.net/doc/commercial/automatic-updates.html

Copies the 1.0 binary to the current directory and runs it. The output shows that no update occurs because the configuration points to itself.

```bash
cp auto-update-test/1.0/AutoUpdatingTest.bin .
./AutoUpdatingTest.bin

```

--------------------------------

### Check package version with version()

Source: https://nuitka.net/doc/nuitka-package-config.html

Use version('rich') to get the package version as a tuple. Returns None if the package is not installed, which may need handling.

```python
version("rich") is not None and version("rich") >= (10, 2, 2)

```

--------------------------------

### Start local HTTP server for update files

Source: https://nuitka.net/doc/commercial/automatic-updates.html

Sets up a local HTTP server on port 27272 serving the auto-update-test directory. Required for the demo.

```bash
rm -rf auto-update-test
mkdir auto-update-test
python -m http.server --bind localhost --dir auto-update-test 27272

```

--------------------------------

### Anti-bloat replacement for imageio error message

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Example of a Nuitka anti-bloat configuration that replaces misleading error messages in non-deployment mode. It changes a pip install suggestion to point to the '--include-module' option and converts ImportError to RuntimeError.

```yaml
- module-name: 'imageio.core.imopen'
  anti-bloat:
    - replacements_plain:
        '`pip install imageio[{config.install_name}]` to install it': '`--include-module={config.module_name}` with Nuitka to include it'
        'err_type = ImportError': 'err_type = RuntimeError'
      when: 'not deployment'

```

--------------------------------

### Create installers with Nuitka for Windows, macOS, and Linux

Source: https://nuitka.net/user-documentation/use-cases.html

Use these commands to create installers for standalone builds. On Windows, NSIS-based installer is created with --windows-create-installer; on Linux, AppImage with --linux-create-installer. The macOS option is also shown.

```bash
python -m nuitka --mode=standalone --windows-create-installer program.py
python -m nuitka --mode=standalone --macos-create-installer program.py
python -m nuitka --mode=standalone --linux-create-installer program.py

```

--------------------------------

### In-place bitwise XOR int-object operation setup

Source: https://nuitka.net/apidoc/HelpersOperationInplaceBitxor_8c_source.html

Starts the in-place bitwise XOR operation for an int and an object in Python 2. It declares result variables and sets up the binary function slots, noting that no in-place nb_inplace_xor slot is available for this type.

```C
static HEDLEY_NEVER_INLINE bool __INPLACE_OPERATION_BITXOR_INT_OBJECT(PyObject **operand1, PyObject *operand2) {
    PyTypeObject *type2 = Py_TYPE(operand2);

#if defined(_MSC_VER)
#pragma warning(push)
#pragma warning(disable : 4101)
#endif
    NUITKA_MAY_BE_UNUSED bool cbool_result;
    NUITKA_MAY_BE_UNUSED PyObject *obj_result;
#if defined(_MSC_VER)
#pragma warning(pop)
#endif

    // No inplace number slot nb_inplace_xor available for this type.

    {
        binaryfunc slot1 = PyInt_Type.tp_as_number->nb_xor;
        binaryfunc slot2 = NULL;

        if (!(&PyInt_Type == type2)) {
            // Different types, need to consider second value slot.

```

--------------------------------

### Steps to reproduce

Source: https://nuitka.net/posts/urllib3-wheel-with-nuitka.html

Commands to reproduce the comparison: install requirements, run regular pytest, build Nuitka wheel, install it, and run pytest again.

```bash
python -m pip install -r dev-requirements.txt
```

```bash
python -m pytest --disable-warnings
```

```bash
python setup.py develop
```

```bash
python setup.py bdist_nuitka
```

```bash
python -m pip install
```

```bash
python -m pytest --disable-warnings
```
Tokens:
Raw