Python Interpreter Configuration Data Structures¶
This document describes the data structures for configuring the behavior of
a Python interpreter. The data structures are consumed by the pyembed
Rust crate.
All type names should correspond to public symbols in the pyembed
crate.
This documentation is auto-generated from the inline documentation in Rust source files. Some formatting has been lost as part of the conversion. See https://docs.rs/pyembed/ for the native Rust API documentation
Structs:
Enums:
OxidizedPythonInterpreterConfig
Struct¶
Configuration for a Python interpreter.
This type is used to create a crate::MainPythonInterpreter
, which manages
a Python interpreter running in the current process.
This type wraps a PythonInterpreterConfig
, which is an abstraction over
the low-level C structs (PyPreConfig
and PyConfig
) used as part of
Python’s C initialization API. In addition to this data structure, the
fields on this type facilitate control of additional features provided by
this crate.
The PythonInterpreterConfig
has a single non-optional field:
PythonInterpreterConfig::profile
. This defines the defaults for various
fields of the PyPreConfig
and PyConfig
C structs. See
https://docs.python.org/3/c-api/init_config.html#isolated-configuration for
more.
When this type is converted to PyPreConfig
and PyConfig
, instances
of these C structs are created from the specified profile. e.g. by calling
PyPreConfig_InitPythonConfig()
, PyPreConfig_InitIsolatedConfig
,
PyConfig_InitPythonConfig
, and PyConfig_InitIsolatedConfig
. Then
for each field in PyPreConfig
and PyConfig
, if a corresponding field
on PythonInterpreterConfig
is Some
, then the PyPreConfig
or
PyConfig
field will be updated accordingly.
During interpreter initialization, Self::resolve()
is called to
resolve/finalize any missing values and convert the instance into a
ResolvedOxidizedPythonInterpreterConfig
. It is this type that is
used to produce a PyPreConfig
and PyConfig
, which are used to
initialize the Python interpreter.
Some fields on this type are redundant or conflict with those on
PythonInterpreterConfig
. Read the documentation of each field to
understand how they interact. Since PythonInterpreterConfig
is defined
in a different crate, its docs are not aware of the existence of
this crate/type.
This struct implements Deserialize
and Serialize
and therefore can be
serialized to any format supported by the serde
crate. This feature is
used by pyoxy
to allow YAML-based configuration of Python interpreters.
exe
Field¶
The path of the currently executing executable.
This value will always be Some
on ResolvedOxidizedPythonInterpreterConfig
instances.
Default value: None
.
Self::resolve()
behavior: sets to std::env::current_exe()
if not set.
Will canonicalize the final path, which may entail filesystem I/O.
Type: Option<PathBuf>
origin
Field¶
The filesystem path from which relative paths will be interpreted.
This value will always be Some
on ResolvedOxidizedPythonInterpreterConfig
instances.
Default value: None
.
Self::resolve()
behavior: sets to Self::exe.parent()
if not set.
Type: Option<PathBuf>
interpreter_config
Field¶
Low-level configuration of Python interpreter.
Default value: PythonInterpreterConfig::default()
with
PythonInterpreterConfig::profile
always set to PythonInterpreterProfile::Python
.
Self::resolve()
behavior: most fields are copied verbatim.
PythonInterpreterConfig::module_search_paths
entries have the special token
$ORIGIN
expanded to the resolved value of Self::origin
.
Type: PythonInterpreterConfig
allocator_backend
Field¶
Memory allocator backend to use.
Default value: MemoryAllocatorBackend::Default
.
Interpreter initialization behavior: after Py_PreInitialize()
is called,
crate::pyalloc::PythonMemoryAllocator::from_backend()
is called. If this
resolves to a crate::pyalloc::PythonMemoryAllocator
, that allocator will
be installed as per Self::allocator_raw
, Self::allocator_mem
,
Self::allocator_obj
, and Self::allocator_pymalloc_arena
. If a custom
allocator backend is defined but all the allocator_*
flags are false
,
the allocator won’t be used.
Type: MemoryAllocatorBackend
allocator_raw
Field¶
Whether to install the custom allocator for the raw
memory domain.
See https://docs.python.org/3/c-api/memory.html for documentation on how Python memory allocator domains work.
Default value: true
Interpreter initialization behavior: controls whether Self::allocator_backend
is used for the raw
memory domain.
Has no effect if Self::allocator_backend
is MemoryAllocatorBackend::Default
.
Type: bool
allocator_mem
Field¶
Whether to install the custom allocator for the mem
memory domain.
See https://docs.python.org/3/c-api/memory.html for documentation on how Python memory allocator domains work.
Default value: false
Interpreter initialization behavior: controls whether Self::allocator_backend
is used for the mem
memory domain.
Has no effect if Self::allocator_backend
is MemoryAllocatorBackend::Default
.
Type: bool
allocator_obj
Field¶
Whether to install the custom allocator for the obj
memory domain.
See https://docs.python.org/3/c-api/memory.html for documentation on how Python memory allocator domains work.
Default value: false
Interpreter initialization behavior: controls whether Self::allocator_backend
is used for the obj
memory domain.
Has no effect if Self::allocator_backend
is MemoryAllocatorBackend::Default
.
Type: bool
allocator_pymalloc_arena
Field¶
Whether to install the custom allocator for the pymalloc
arena allocator.
See https://docs.python.org/3/c-api/memory.html for documentation on how Python memory allocation works.
Default value: false
Interpreter initialization behavior: controls whether Self::allocator_backend
is used for the pymalloc
arena allocator.
This setting requires the pymalloc
allocator to be used for the mem
or obj
domains (allocator_mem = false
and allocator_obj = false
- this is
the default behavior) and for Self::allocator_backend
to not be
MemoryAllocatorBackend::Default
.
Type: bool
allocator_debug
Field¶
Whether to set up Python allocator debug hooks to detect memory bugs.
Default value: false
Interpreter initialization behavior: triggers the calling of
PyMem_SetupDebugHooks()
after custom allocators are installed.
This setting can be used with or without custom memory allocators
(see other allocator_*
fields).
Type: bool
set_missing_path_configuration
Field¶
Whether to automatically set missing “path configuration” fields.
If true
, various path configuration
(https://docs.python.org/3/c-api/init_config.html#path-configuration) fields
will be set automatically if their corresponding .interpreter_config
fields are None
. For example, program_name
will be set to the current
executable and home
will be set to the executable’s directory.
If this is false
, the default path configuration built into libpython
is used.
Setting this to false
likely enables isolated interpreters to be used
with “external” Python installs. If this is true
, the default isolated
configuration expects files like the Python standard library to be installed
relative to the current executable. You will need to either ensure these
files are present, define packed_resources
, and/or set
.interpreter_config.module_search_paths
to ensure the interpreter can find
the Python standard library, otherwise the interpreter will fail to start.
Without this set or corresponding .interpreter_config
fields set, you
may also get run-time errors like
Could not find platform independent libraries <prefix>
or
Consider setting $PYTHONHOME to <prefix>[:<exec_prefix>]
. If you see
these errors, it means the automatic path config resolutions built into
libpython didn’t work because the run-time layout didn’t match the
build-time configuration.
Default value: true
Type: bool
oxidized_importer
Field¶
Whether to install oxidized_importer
during interpreter initialization.
If true
, oxidized_importer
will be imported during interpreter
initialization and an instance of oxidized_importer.OxidizedFinder
will be installed on sys.meta_path
as the first element.
If Self::packed_resources
are defined, they will be loaded into the
OxidizedFinder
.
If Self::filesystem_importer
is true
, its path hook will be
registered on sys.path_hooks
so PathFinder
(the standard filesystem
based importer) and pkgutil
can use it.
Default value: false
Interpreter initialization behavior: See above.
Type: bool
filesystem_importer
Field¶
Whether to install the path-based finder.
Controls whether to install the Python standard library PathFinder
meta
path finder (this is the meta path finder that loads Python modules and
resources from the filesystem).
Also controls whether to add OxidizedFinder
’s path hook to
sys.path_hooks
.
Due to lack of control over low-level Python interpreter initialization,
the standard library PathFinder
will be registered on sys.meta_path
and sys.path_hooks
for a brief moment when the interpreter is initialized.
If sys.path
contains valid entries that would be serviced by this finder
and oxidized_importer
isn’t able to service imports, it is possible for the
path-based finder to be used to import some Python modules needed to initialize
the Python interpreter. In many cases, this behavior is harmless. In all cases,
the path-based importer is removed after Python interpreter initialization, so
future imports won’t be serviced by this path-based importer if it is disabled
by this flag.
Default value: true
Interpreter initialization behavior: If false, path-based finders are removed
from sys.meta_path
and sys.path_hooks
is cleared.
Type: bool
packed_resources
Field¶
References to packed resources data.
The format of the data is defined by the python-packed-resources
crate. The data will be parsed as part of initializing the custom
meta path importer during interpreter initialization when
oxidized_importer=true
. If oxidized_importer=false
, this field
is ignored.
If paths are relative, that will be evaluated relative to the process’s current working directory following the operating system’s standard path expansion behavior.
Default value: vec![]
Self::resolve()
behavior: PackedResourcesSource::MemoryMappedPath
members
have the special string $ORIGIN
expanded to the string value that
Self::origin
resolves to.
This field is ignored during serialization.
Type: Vec<PackedResourcesSource>
extra_extension_modules
Field¶
Extra extension modules to make available to the interpreter.
The values will effectively be passed to PyImport_ExtendInitTab()
.
Default value: None
Interpreter initialization behavior: PyImport_Inittab
will be extended
with entries from this list. This makes the extensions available as
built-in extension modules.
This field is ignored during serialization.
Type: Option<Vec<ExtensionModule>>
argv
Field¶
Command line arguments to initialize sys.argv
with.
Default value: None
Self::resolve()
behavior: Some
value is used if set. Otherwise
PythonInterpreterConfig::argv
is used if set. Otherwise
std::env::args_os()
is called.
Interpreter initialization behavior: the resolved Some
value is used
to populate PyConfig.argv
.
Type: Option<Vec<OsString>>
argvb
Field¶
Whether to set sys.argvb
with bytes versions of process arguments.
On Windows, bytes will be UTF-16. On POSIX, bytes will be raw char*
values passed to int main()
.
Enabling this feature will give Python applications access to the raw
bytes
values of raw argument data passed into the executable. The single
or double width bytes nature of the data is preserved.
Unlike sys.argv
which may chomp off leading argument depending on the
Python execution mode, sys.argvb
has all the arguments used to initialize
the process. i.e. the first argument is always the executable.
Default value: false
Interpreter initialization behavior: sys.argvb
will be set to a
list[bytes]
. sys.argv
and sys.argvb
should have the same number
of elements.
Type: bool
multiprocessing_auto_dispatch
Field¶
Automatically detect and run in multiprocessing
mode.
If set, crate::MainPythonInterpreter::run()
will detect when the invoked
interpreter looks like it is supposed to be a multiprocessing
worker and
will automatically call into the multiprocessing
module instead of running
the configured code.
Enabling this has the same effect as calling multiprocessing.freeze_support()
in your application code’s __main__
and replaces the need to do so.
Default value: true
Type: bool
multiprocessing_start_method
Field¶
Controls how to call multiprocessing.set_start_method()
.
Default value: MultiprocessingStartMethod::Auto
Interpreter initialization behavior: if Self::oxidized_importer
is true
,
the OxidizedImporter
will be taught to call multiprocessing.set_start_method()
when multiprocessing
is imported. If false
, this value has no effect.
Type: MultiprocessingStartMethod
sys_frozen
Field¶
Whether to set sys.frozen=True.
Setting this will enable Python to emulate “frozen” binaries, such as those used by PyInstaller.
Default value: false
Interpreter initialization behavior: If true
, sys.frozen = True
.
If false
, sys.frozen
is not defined.
Type: bool
sys_meipass
Field¶
Whether to set sys._MEIPASS to the directory of the executable.
Setting this will enable Python to emulate PyInstaller’s behavior of setting this attribute. This could potentially help with self-contained application compatibility by masquerading as PyInstaller and causing code to activate PyInstaller mode.
Default value: false
Interpreter initialization behavior: If true
, sys._MEIPASS
will
be set to a str
holding the value of Self::origin
. If false
,
sys._MEIPASS
will not be defined.
Type: bool
terminfo_resolution
Field¶
How to resolve the terminfo
database.
Default value: TerminfoResolution::Dynamic
Interpreter initialization behavior: the TERMINFO_DIRS
environment
variable may be set for this process depending on what TerminfoResolution
instructs to do.
terminfo
is not used on Windows and this setting is ignored on that
platform.
Type: TerminfoResolution
tcl_library
Field¶
Path to use to define the TCL_LIBRARY
environment variable.
This directory should contain an init.tcl
file. It is commonly
a directory named tclX.Y
. e.g. tcl8.6
.
Default value: None
Self::resolve()
behavior: the token $ORIGIN
is expanded to the
resolved value of Self::origin
.
Interpreter initialization behavior: if set, the TCL_LIBRARY
environment
variable will be set for the current process.
Type: Option<PathBuf>
write_modules_directory_env
Field¶
Environment variable holding the directory to write a loaded modules file.
If this value is set and the environment it refers to is set,
on interpreter shutdown, we will write a modules-<random>
file to
the directory specified containing a \n
delimited list of modules
loaded in sys.modules
.
This setting is useful to record which modules are loaded during the execution of a Python interpreter.
Default value: None
Type: Option<String>
PythonInterpreterConfig
Struct¶
Holds configuration of a Python interpreter.
This struct holds fields that are exposed by PyPreConfig
and
PyConfig
in the CPython API.
Other than the profile (which is used to initialize instances of
PyPreConfig
and PyConfig
), all fields are optional. Only fields
with Some(T)
will be updated from the defaults.
profile
Field¶
Profile to use to initialize pre-config and config state of interpreter.
Type: PythonInterpreterProfile
allocator
Field¶
Name of the memory allocator.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.allocator.
Type: Option<Allocator>
configure_locale
Field¶
Whether to set the LC_CTYPE locale to the user preferred locale.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.configure_locale.
Type: Option<bool>
coerce_c_locale
Field¶
How to coerce the locale settings.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.coerce_c_locale.
Type: Option<CoerceCLocale>
coerce_c_locale_warn
Field¶
Whether to emit a warning if the C locale is coerced.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.coerce_c_locale_warn.
Type: Option<bool>
development_mode
Field¶
Whether to enable Python development mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.dev_mode.
Type: Option<bool>
isolated
Field¶
Isolated mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.isolated.
Type: Option<bool>
legacy_windows_fs_encoding
Field¶
Whether to use legacy filesystem encodings on Windows.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.legacy_windows_fs_encoding.
Type: Option<bool>
parse_argv
Field¶
Whether argv should be parsed the way python
parses them.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.parse_argv.
Type: Option<bool>
use_environment
Field¶
Whether environment variables are read to control the interpreter configuration.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.use_environment.
Type: Option<bool>
utf8_mode
Field¶
Controls Python UTF-8 mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.utf8_mode.
Type: Option<bool>
argv
Field¶
Command line arguments.
These will become sys.argv
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.argv.
Type: Option<Vec<OsString>>
base_exec_prefix
Field¶
Controls sys.base_exec_prefix
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.base_exec_prefix.
Type: Option<PathBuf>
base_executable
Field¶
Controls sys._base_executable
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.base_executable.
Type: Option<PathBuf>
base_prefix
Field¶
Controls sys.base_prefix
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.base_prefix.
Type: Option<PathBuf>
buffered_stdio
Field¶
Controls buffering on stdout
and stderr
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.buffered_stdio.
Type: Option<bool>
bytes_warning
Field¶
Controls warnings/errors for some bytes type coercions.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.bytes_warning.
Type: Option<BytesWarning>
check_hash_pycs_mode
Field¶
Validation mode for .pyc
files.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.check_hash_pycs_mode.
Type: Option<CheckHashPycsMode>
configure_c_stdio
Field¶
Controls binary mode and buffering on C standard streams.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.configure_c_stdio.
Type: Option<bool>
dump_refs
Field¶
Dump Python references.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.dump_refs.
Type: Option<bool>
exec_prefix
Field¶
Controls sys.exec_prefix
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.exec_prefix.
Type: Option<PathBuf>
executable
Field¶
Controls sys.executable
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.executable.
Type: Option<PathBuf>
fault_handler
Field¶
Enable faulthandler
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.faulthandler.
Type: Option<bool>
filesystem_encoding
Field¶
Controls the encoding to use for filesystems/paths.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.filesystem_encoding.
Type: Option<String>
filesystem_errors
Field¶
Filesystem encoding error handler.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.filesystem_errors.
Type: Option<String>
hash_seed
Field¶
Randomized hash function seed.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.hash_seed.
Type: Option<c_ulong>
home
Field¶
Python home directory.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.home.
Type: Option<PathBuf>
import_time
Field¶
Whether to profile import
time.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.import_time.
Type: Option<bool>
inspect
Field¶
Enter interactive mode after executing a script or a command.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.inspect.
Type: Option<bool>
install_signal_handlers
Field¶
Whether to install Python signal handlers.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.install_signal_handlers.
Type: Option<bool>
interactive
Field¶
Whether to enable the interactive REPL mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.interactive.
Type: Option<bool>
legacy_windows_stdio
Field¶
Controls legacy stdio behavior on Windows.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.legacy_windows_stdio.
Type: Option<bool>
malloc_stats
Field¶
Whether to dump statistics from the pymalloc
allocator on exit.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.malloc_stats.
Type: Option<bool>
module_search_paths
Field¶
Defines sys.path
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.module_search_paths.
This value effectively controls the initial value of sys.path
.
The special string $ORIGIN
in values will be expanded to the absolute path of the
directory of the executable at run-time. For example, if the executable is
/opt/my-application/pyapp
, $ORIGIN
will expand to /opt/my-application
and the
value $ORIGIN/lib
will expand to /opt/my-application/lib
.
Type: Option<Vec<PathBuf>>
optimization_level
Field¶
Bytecode optimization level.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.optimization_level.
This setting is only relevant if write_bytecode
is true and Python modules are
being imported from the filesystem using Python’s standard filesystem importer.
Type: Option<BytecodeOptimizationLevel>
parser_debug
Field¶
Parser debug mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.parser_debug.
Type: Option<bool>
pathconfig_warnings
Field¶
Whether calculating the Python path configuration can emit warnings.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.pathconfig_warnings.
Type: Option<bool>
prefix
Field¶
Defines sys.prefix
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.prefix.
Type: Option<PathBuf>
program_name
Field¶
Program named used to initialize state during path configuration.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.program_name.
Type: Option<PathBuf>
pycache_prefix
Field¶
Directory where .pyc
files are written.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.pycache_prefix.
Type: Option<PathBuf>
python_path_env
Field¶
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.pythonpath_env.
Type: Option<String>
quiet
Field¶
Quiet mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.quiet.
Type: Option<bool>
run_command
Field¶
Value of the -c
command line option.
Effectively defines Python code to evaluate in Py_RunMain()
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.run_command.
Type: Option<String>
run_filename
Field¶
Filename passed on the command line.
Effectively defines the Python file to run in Py_RunMain()
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.run_filename.
Type: Option<PathBuf>
run_module
Field¶
Value of the -m
command line option.
Effectively defines the Python module to run as __main__
in Py_RunMain()
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.run_module.
Type: Option<String>
show_ref_count
Field¶
Whether to show the total reference count at exit.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.show_ref_count.
Type: Option<bool>
site_import
Field¶
Whether to import the site
module at startup.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.site_import.
The site
module is typically not needed for standalone applications and disabling
it can reduce application startup time.
Type: Option<bool>
skip_first_source_line
Field¶
Whether to skip the first line of Self::run_filename
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.skip_source_first_line.
Type: Option<bool>
stdio_encoding
Field¶
Encoding of sys.stdout
, sys.stderr
, and sys.stdin
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.stdio_encoding.
Type: Option<String>
stdio_errors
Field¶
Encoding error handler for sys.stdout
and sys.stdin
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.stdio_errors.
Type: Option<String>
tracemalloc
Field¶
Whether to enable tracemalloc
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.tracemalloc.
Type: Option<bool>
user_site_directory
Field¶
Whether to add the user site directory to sys.path
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.user_site_directory.
Type: Option<bool>
verbose
Field¶
Verbose mode.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.verbose.
Type: Option<bool>
warn_options
Field¶
Options of the warning
module to control behavior.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.warnoptions.
Type: Option<Vec<String>>
write_bytecode
Field¶
Controls sys.dont_write_bytecode
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.write_bytecode.
Type: Option<bool>
x_options
Field¶
Values of the -X
command line options / sys._xoptions
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.xoptions.
Type: Option<Vec<String>>
MemoryAllocatorBackend
Enum¶
Defines a backend for a memory allocator.
This says which memory allocator API / library to configure the Python interpreter to use.
Not all allocators are available in all program builds.
Serialization type: string
Default
VariantThe default allocator as configured by Python.
This likely utilizes the system default allocator, normally the
malloc()
,free()
, etc functions from the libc implementation being linked against.Serialized value:
default
Jemalloc
VariantUse the jemalloc allocator.
Requires the binary to be built with jemalloc support.
Never available on Windows.
Serialized value:
jemalloc
Mimalloc
VariantUse the mimalloc allocator (https://github.com/microsoft/mimalloc).
Requires the binary to be built with mimalloc support.
Serialized value:
mimalloc
Snmalloc
VariantUse the snmalloc allocator (https://github.com/microsoft/snmalloc).
Not always available.
Serialized value:
snmalloc
Rust
VariantUse Rust’s global allocator.
The Rust allocator is less efficient than other allocators because of overhead tracking allocations. For optimal performance, use the default allocator. Or if Rust is using a custom global allocator, use the enum variant corresponding to that allocator.
Serialized value:
rust
PythonInterpreterProfile
Enum¶
Defines the profile to use to configure a Python interpreter.
This effectively provides a template for seeding the initial values of
PyPreConfig
and PyConfig
C structs.
Serialization type: string
.
Isolated
VariantPython is isolated from the system.
See https://docs.python.org/3/c-api/init_config.html#isolated-configuration.
Serialized value:
isolated
Python
VariantPython interpreter behaves like
python
.See https://docs.python.org/3/c-api/init_config.html#python-configuration.
Serialized value:
python
Allocator
Enum¶
Name of the Python memory allocators.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.allocator.
Serialization type: string
NotSet
VariantDon’t change memory allocators (use defaults).
Serialized value:
not-set
Default
VariantDefault memory allocators.
Serialized value:
default
Debug
VariantDefault memory allocators with debug hooks.
Serialized value:
debug
Malloc
VariantUse
malloc()
from the C library.Serialized value:
malloc
MallocDebug
VariantForce usage of
malloc()
with debug hooks.Serialized value:
malloc-debug
PyMalloc
VariantPython
pymalloc
allocator.Serialized value:
py-malloc
PyMallocDebug
VariantPython
pymalloc
allocator with debug hooks.Serialized value:
py-malloc-debug
BytecodeOptimizationLevel
Enum¶
An optimization level for Python bytecode.
Serialization type: int
Zero
VariantOptimization level 0.
Serialized value:
0
One
VariantOptimization level 1.
Serialized value:
1
Two
VariantOptimization level 2.
Serialized value:
2
BytesWarning
Enum¶
Defines what to do when comparing bytes
or bytesarray
with str
or comparing bytes
with int
.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.bytes_warning.
Serialization type: string
None
VariantDo nothing.
Serialization value:
none
Warn
VariantIssue a warning.
Serialization value:
warn
Raise
VariantRaise a
BytesWarning
.Serialization value:
raise
CheckHashPycsMode
Enum¶
Control the validation behavior of hash-based .pyc files.
See https://docs.python.org/3/c-api/init_config.html#c.PyConfig.check_hash_pycs_mode.
Serialization type: string
Always
VariantHash the source file for invalidation regardless of value of the
check_source
flag.Serialized value:
always
Never
VariantAssume that hash-based pycs always are valid.
Serialized value:
never
Default
VariantThe
check_source
flag in hash-based pycs determines invalidation.Serialized value:
default
CoerceCLocale
Enum¶
Holds values for coerce_c_locale
.
See https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.coerce_c_locale.
Serialization type: string
LCCtype
VariantRead the LC_CTYPE locale to decide if it should be coerced.
Serialized value:
LC_CTYPE
C
VariantCoerce the C locale.
Serialized value:
C
MultiprocessingStartMethod
Enum¶
Defines how to call multiprocessing.set_start_method()
when multiprocessing
is imported.
When set to a value that is not none
, when oxidized_importer.OxidizedFinder
services
an import of the multiprocessing
module, it will automatically call
multiprocessing.set_start_method()
to configure how worker processes are created.
If the multiprocessing
module is not imported by oxidized_importer.OxidizedFinder
,
this setting has no effect.
Serialization type: string
None
VariantDo not call
multiprocessing.set_start_method()
.This mode is what Python programs do by default.
Serialized value:
none
Fork
VariantCall with value
fork
.Serialized value:
fork
ForkServer
VariantCall with value
forkserver
Serialized value:
forkserver
Spawn
VariantCall with value
spawn
Serialized value:
spawn
Auto
VariantCall with a valid appropriate for the given environment.
This likely maps to
spawn
on Windows andfork
on non-Windows.Serialized value:
auto
TerminfoResolution
Enum¶
Defines terminfo
database resolution semantics.
Python links against libraries like readline
, libedit
, and ncurses
which need to utilize a terminfo
database (a set of files defining
terminals and their capabilities) in order to work properly.
The absolute path to the terminfo database is typically compiled into these libraries at build time. If the compiled path on the building machine doesn’t match the path on the runtime machine, these libraries cannot find the terminfo database and terminal interactions won’t work correctly because these libraries don’t know how to resolve terminal features. This can result in quirks like the backspace key not working in prompts.
The pyembed
Rust crate is able to point libraries at a terminfo database
at runtime, overriding the compiled-in default path. This enum is used
to control that behavior.
Serialization type: string
.
Dynamic
VariantResolve
terminfo
database using appropriate behavior for current OS.We will look for the terminfo database in paths that are common for the current OS / distribution. The terminfo database is present in most systems (except the most barebones containers or sandboxes) and this method is usually successfully in locating the terminfo database.
Serialized value:
dynamic
None
VariantDo not attempt to resolve the
terminfo
database. Basically a no-op.This is what should be used for applications that don’t interact with the terminal. Using this option will prevent some I/O syscalls that would be incurred by
dynamic
.Serialized value:
none
Static
VariantUse a specified string as the
TERMINFO_DIRS
value.Serialized value:
static:<path>
e.g.
static:/usr/share/terminfo
.