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. Thepyembed
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.The following attributes correspond to fields of the PyPreConfig C struct used to initialize the Python interpreter.
The following attributes correspond to fields of the PyConfig C struct used to initialize the Python interpreter.
- allocator_backend¶
(
string
)The
jemalloc
,mimalloc
, andsnmalloc
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 usingpyoxidizer
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
andsnmalloc
require thecmake
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 tofailed 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 anddefault
on Windows. (Thejemalloc-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
)Defaults to
False
.
- oxidized_importer¶
(
bool
)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
)
- 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
orNone
)
- config_profile¶
(
string
)See profile Field.
- allocator¶
(
string
orNone
)See allocator Field.
- configure_locale¶
(
bool
orNone
)
- coerce_c_locale¶
(
string
orNone
)
- coerce_c_locale_warn¶
(
bool
orNone
)
- development_mode¶
(
bool
orNone
)
- isolated¶
(
bool
orNone
)See isolated Field.
- legacy_windows_fs_encoding¶
(
bool
orNone
)
- parse_argv¶
(
bool
orNone
)See parse_argv Field.
- use_environment¶
(
bool
orNone
)
- utf8_mode¶
(
bool
orNone
)See utf8_mode Field.
- base_exec_prefix¶
(
string
orNone
)
- base_executable¶
(
string
orNone
)
- base_prefix¶
(
string
orNone
)See base_prefix Field.
- buffered_stdio¶
(
bool
orNone
)See buffered_stdio Field.
- bytes_warning¶
(
string
orNone
)See bytes_warning Field.
- check_hash_pycs_mode¶
(
string
orNone
)
- configure_c_stdio¶
(
bool
orNone
)
- dump_refs¶
(
bool
orNone
)See dump_refs Field.
- exec_prefix¶
(
string
orNone
)See exec_prefix Field.
- executable¶
(
string
orNone
)See executable Field.
- fault_handler¶
(
bool
orNone
)See fault_handler Field.
- filesystem_encoding¶
(
string
orNone
)
- filesystem_errors¶
(
string
orNone
)
- hash_seed¶
(
int
orNone
)See hash_seed Field.
PyConfig.use_hash_seed
will automatically be set if this attribute is defined.
- home¶
(
string
orNone
)See home Field.
- import_time¶
See import_time Field.
- inspect¶
(
bool
orNone
)See inspect Field.
- install_signal_handlers¶
(
bool
orNone
)
- interactive¶
(
bool
orNone
)See interactive Field.
- legacy_windows_stdio¶
(
bool
orNone
)
- malloc_stats¶
(
bool
orNone
)See malloc_stats Field.
- module_search_paths¶
(
list[string]
orNone
)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
orNone
)
- parser_debug¶
(
bool
orNone
)See parser_debug Field.
- pathconfig_warnings¶
(
bool
orNone
)
- prefix¶
(
string
orNone
)See prefix Field.
- program_name¶
(
string
orNone
)See program_name Field.
- pycache_prefix¶
(
string
orNone
)See pycache_prefix Field.
- python_path_env¶
(
string
orNone
)
- quiet¶
(
bool
orNone
)See quiet Field.
- run_command¶
(
string
orNone
)See run_command Field.
- run_filename¶
(
string
orNone
)See run_filename Field.
- run_module¶
(
string
orNone
)See run_module Field.
- show_ref_count¶
(
bool
orNone
)See show_ref_count Field.
- site_import¶
(
bool
orNone
)See site_import Field.
The
site
module is typically not needed for standalone/isolated Python applications.
- skip_first_source_line¶
(
bool
orNone
)
- stdio_encoding¶
(
string
orNone
)See stdio_encoding Field.
- stdio_errors¶
(
string
orNone
)See stdio_errors Field.
- tracemalloc¶
(
bool
orNone
)See tracemalloc Field.
- user_site_directory¶
(
bool
orNone
)
- verbose¶
(
bool
orNone
)See verbose Field.
- warn_options¶
(
list[string]
orNone
)See warn_options Field.
- write_bytecode¶
(
bool
orNone
)See write_bytecode Field.
- x_options¶
(
list[string]
orNone
)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