Struct pyembed::OxidizedPythonInterpreterConfig
source · pub struct OxidizedPythonInterpreterConfig<'a> {Show 23 fields
pub exe: Option<PathBuf>,
pub origin: Option<PathBuf>,
pub interpreter_config: PythonInterpreterConfig,
pub allocator_backend: MemoryAllocatorBackend,
pub allocator_raw: bool,
pub allocator_mem: bool,
pub allocator_obj: bool,
pub allocator_pymalloc_arena: bool,
pub allocator_debug: bool,
pub set_missing_path_configuration: bool,
pub oxidized_importer: bool,
pub filesystem_importer: bool,
pub packed_resources: Vec<PackedResourcesSource<'a>>,
pub extra_extension_modules: Option<Vec<ExtensionModule>>,
pub argv: Option<Vec<OsString>>,
pub argvb: bool,
pub multiprocessing_auto_dispatch: bool,
pub multiprocessing_start_method: MultiprocessingStartMethod,
pub sys_frozen: bool,
pub sys_meipass: bool,
pub terminfo_resolution: TerminfoResolution,
pub tcl_library: Option<PathBuf>,
pub write_modules_directory_env: Option<String>,
}
Expand description
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.
Fields§
§exe: Option<PathBuf>
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.
origin: Option<PathBuf>
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.
interpreter_config: PythonInterpreterConfig
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.
allocator_backend: MemoryAllocatorBackend
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.
allocator_raw: bool
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.
allocator_mem: bool
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.
allocator_obj: bool
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.
allocator_pymalloc_arena: bool
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.
allocator_debug: bool
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).
set_missing_path_configuration: bool
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
oxidized_importer: bool
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.
filesystem_importer: bool
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.
packed_resources: Vec<PackedResourcesSource<'a>>
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.
extra_extension_modules: Option<Vec<ExtensionModule>>
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.
argv: Option<Vec<OsString>>
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
.
argvb: bool
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.
multiprocessing_auto_dispatch: bool
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
multiprocessing_start_method: MultiprocessingStartMethod
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.
sys_frozen: bool
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.
sys_meipass: bool
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.
terminfo_resolution: TerminfoResolution
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.
tcl_library: Option<PathBuf>
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.
write_modules_directory_env: Option<String>
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
Implementations§
source§impl<'a> OxidizedPythonInterpreterConfig<'a>
impl<'a> OxidizedPythonInterpreterConfig<'a>
sourcepub fn resolve(
self
) -> Result<ResolvedOxidizedPythonInterpreterConfig<'a>, NewInterpreterError>
pub fn resolve(
self
) -> Result<ResolvedOxidizedPythonInterpreterConfig<'a>, NewInterpreterError>
Create a new type with all values resolved.
Trait Implementations§
source§impl<'a> Clone for OxidizedPythonInterpreterConfig<'a>
impl<'a> Clone for OxidizedPythonInterpreterConfig<'a>
source§fn clone(&self) -> OxidizedPythonInterpreterConfig<'a>
fn clone(&self) -> OxidizedPythonInterpreterConfig<'a>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more