PythonInterpreterConfig

class starlark_pyoxidizer.PythonInterpreterConfig

This type configures the default behavior of the embedded Python interpreter.

Embedded Python interpreters are configured and instantiated using a Rust pyembed::OxidizedPythonInterpreterConfig data structure. The pyembed crate defines a default instance of this data structure with parameters defined by the settings in this type.

Note

If you are writing custom Rust code and constructing a custom pyembed::OxidizedPythonInterpreterConfig instance and don’t use the default instance, this config type is not relevant to you and can be omitted from your config file.

Danger

Some of the settings exposed by Python’s initialization APIs are extremely low level and brittle. Various combinations can cause the process to crash/exit ungracefully. Be very cautious when setting these low-level settings.

Instances are constructed by calling PythonDistribution.make_python_interpreter_config().

Instance state is managed via attributes.

There are a ton of attributes and most attributes are not relevant to most applications. The bulk of the attributes exist to give full control over Python interpreter initialization.

The following attributes control features provided by the pyembed Rust crate, which manages the embedded Python interpreter in generated executables. These attributes provide features and level of control over embedded Python interpreters beyond what is possible with Python’s initialization C API.

• allocator_backend

• allocator_raw

• allocator_mem

• allocator_obj

• allocator_pymalloc_arena

• allocator_debug

• oxidized_importer

• filesystem_importer

• argvb

• multiprocessing_auto_dispatch

• multiprocessing_start_method

• sys_frozen

• sys_meipass

• terminfo_resolution

• write_modules_directory_env

The following attributes correspond to fields of the PyPreConfig C struct used to initialize the Python interpreter.

• config_profile

• allocator

• configure_locale

• coerce_c_locale

• coerce_c_locale_warn

• development_mode

• isolated

• legacy_windows_fs_encoding

• parse_argv

• use_environment

• utf8_mode

The following attributes correspond to fields of the PyConfig C struct used to initialize the Python interpreter.

• base_exec_prefix

• base_executable

• base_prefix

• buffered_stdio

• bytes_warning

• check_hash_pycs_mode

• configure_c_stdio

• dump_refs

• exec_prefix

• executable

• fault_handler

• filesystem_encoding

• hash_seed

• home

• import_time

• inspect

• install_signal_handlers

• interactive

• legacy_windows_stdio

• malloc_stats

• module_search_paths

• optimization_level

• parser_debug

• pathconfig_warnings

• prefix

• program_name

• pycache_prefix

• python_path_env

• quiet

• run_command

• run_filename

• run_module

• show_ref_count

• site_import

• skip_first_source_line

• stdio_encoding

• stdio_errors

• tracemalloc

• user_site_directory

• verbose

• warn_options

• write_bytecode

• x_options

allocator_backend

(string)

See allocator_backend Field.

The jemalloc, mimalloc, and snmalloc allocators require the presence of additional Rust crates. A run-time error will occur if these allocators are configured but the binary was built without these crates. (This should not occur when using pyoxidizer to build the binary.)

When a custom allocator is configured, the autogenerated Rust crate used to build the binary will configure the Rust global allocator (#[global_allocator] attribute) to use the specified allocator.

Important

The rust allocator is not recommended because it introduces performance overhead. But it may help with debugging in some situations.

Note

Both mimalloc and snmalloc require the cmake build tool to compile code as part of their build process. If this tool is not available in the build environment, you will encounter a build error with a message similar to failed to execute command: The system cannot find the file specified. (os error 2) is `cmake` not installed?.

The workaround is to install cmake or use a different allocator.

Note

snmalloc only supports targeting to macOS 10.14 or newer. You will likely see build errors when building a binary targeting macOS 10.13 or older.

Default is jemalloc on non-Windows targets and default on Windows. (The jemalloc-sys crate doesn’t work on Windows MSVC targets.)

allocator_raw

(bool)

See allocator_raw Field.

Defaults to True.

allocator_mem

(bool)

See allocator_mem Field.

Defaults to False.

allocator_obj

(bool)

See allocator_obj Field.

Defaults to False.

allocator_pymalloc_arena

(bool)

See allocator_pymalloc_arena Field.

Defaults to False.

allocator_debug

(bool)

See allocator_debug Field.

Defaults to False.

oxidized_importer

(bool)

See oxidized_importer Field.

Defaults to True.

filesystem_importer

(bool)

See filesystem_importer Field.

The filesystem importer is enabled automatically if PythonInterpreterConfig.module_search_paths is non-empty.

argvb

(bool)

See argvb Field.

multiprocessing_auto_dispatch

(bool)

See multiprocessing_auto_dispatch Field.

Default value is True.

See Automatic Detection and Dispatch of multiprocessing Processes for more.

multiprocessing_start_method

(str)

See multiprocessing_start_method Field.

sys_frozen

(bool)

See sys_frozen Field.

Default is True.

sys_meipass

(bool)

See sys_meipass Field.

Default is False.

terminfo_resolution

(string)

See terminfo_resolution Field.

See Terminfo Database for more about terminal databases.

write_modules_directory_env

(string or None)

See write_modules_directory_env Field.

config_profile

(string)

See profile Field.

allocator

(string or None)

See allocator Field.

configure_locale

(bool or None)

See configure_locale Field.

coerce_c_locale

(string or None)

See coerce_c_locale Field.

coerce_c_locale_warn

(bool or None)

See coerce_c_locale_warn Field.

development_mode

(bool or None)

See development_mode Field.

isolated

(bool or None)

See isolated Field.

legacy_windows_fs_encoding

(bool or None)

See legacy_windows_fs_encoding Field.

parse_argv

(bool or None)

See parse_argv Field.

use_environment

(bool or None)

See use_environment Field.

utf8_mode

(bool or None)

See utf8_mode Field.

base_exec_prefix

(string or None)

See base_exec_prefix Field.

base_executable

(string or None)

See base_executable Field.

base_prefix

(string or None)

See base_prefix Field.

buffered_stdio

(bool or None)

See buffered_stdio Field.

bytes_warning

(string or None)

See bytes_warning Field.

check_hash_pycs_mode

(string or None)

See check_hash_pycs_mode Field.

configure_c_stdio

(bool or None)

See configure_c_stdio Field.

dump_refs

(bool or None)

See dump_refs Field.

exec_prefix

(string or None)

See exec_prefix Field.

executable

(string or None)

See executable Field.

fault_handler

(bool or None)

See fault_handler Field.

filesystem_encoding

(string or None)

See filesystem_encoding Field.

filesystem_errors

(string or None)

See filesystem_errors Field.

hash_seed

(int or None)

See hash_seed Field.

PyConfig.use_hash_seed will automatically be set if this attribute is defined.

home

(string or None)

See home Field.

import_time

See import_time Field.

inspect

(bool or None)

See inspect Field.

install_signal_handlers

(bool or None)

See install_signal_handlers Field.

interactive

(bool or None)

See interactive Field.

legacy_windows_stdio

(bool or None)

See legacy_windows_stdio Field.

malloc_stats

(bool or None)

See malloc_stats Field.

module_search_paths

(list[string] or None)

See module_search_paths Field.

Setting this to a non-empty value also has the side-effect of setting filesystem_importer = True

optimization_level

(int or None)

See optimization_level Field.

parser_debug

(bool or None)

See parser_debug Field.

pathconfig_warnings

(bool or None)

See pathconfig_warnings Field.

prefix

(string or None)

See prefix Field.

program_name

(string or None)

See program_name Field.

pycache_prefix

(string or None)

See pycache_prefix Field.

python_path_env

(string or None)

See python_path_env Field.

quiet

(bool or None)

See quiet Field.

run_command

(string or None)

See run_command Field.

run_filename

(string or None)

See run_filename Field.

run_module

(string or None)

See run_module Field.

show_ref_count

(bool or None)

See show_ref_count Field.

site_import

(bool or None)

See site_import Field.

The site module is typically not needed for standalone/isolated Python applications.

skip_first_source_line

(bool or None)

See skip_first_source_line Field.

stdio_encoding

(string or None)

See stdio_encoding Field.

stdio_errors

(string or None)

See stdio_errors Field.

tracemalloc

(bool or None)

See tracemalloc Field.

user_site_directory

(bool or None)

See user_site_directory Field.

verbose

(bool or None)

See verbose Field.

warn_options

(list[string] or None)

See warn_options Field.

write_bytecode

(bool or None)

See write_bytecode Field.

x_options

(list[string] or None)

See x_options Field.

Starlark Caveats

The PythonInterpreterConfig Starlark type is backed by a Rust data structure. And when attributes are retrieved, a copy of the underlying Rust struct field is returned.

This means that if you attempt to mutate a Starlark value (as opposed to assigning an attribute), the mutation won’t be reflected on the underlying Rust data structure.

For example:

config = dist.make_python_interpreter_config()

# assigns vec!["foo", "bar"].
config.module_search_paths = ["foo", "bar"]

# Creates a copy of the underlying list and appends to that copy.
# The stored value of `module_search_paths` is still `["foo", "bar"]`.
config.module_search_paths.append("baz")

To append to a list, do something like the following:

value = config.module_search_paths
value.append("baz")
config.module_search_paths = value