Struct pyembed::OxidizedPythonInterpreterConfig

pub struct OxidizedPythonInterpreterConfig<'a> {

    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>,
}

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

impl<'a> OxidizedPythonInterpreterConfig<'a>

pub fn resolve(
    self
) -> Result<ResolvedOxidizedPythonInterpreterConfig<'a>, NewInterpreterError>

Create a new type with all values resolved.

Trait Implementations

impl<'a> Clone for OxidizedPythonInterpreterConfig<'a>

fn clone(&self) -> OxidizedPythonInterpreterConfig<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for OxidizedPythonInterpreterConfig<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for OxidizedPythonInterpreterConfig<'a>

fn default() -> Self

Returns the “default value” for a type.

impl<'a> TryFrom<OxidizedPythonInterpreterConfig<'a>> for ResolvedOxidizedPythonInterpreterConfig<'a>

type Error = NewInterpreterError

The type returned in the event of a conversion error.

fn try_from(
    value: OxidizedPythonInterpreterConfig<'a>
) -> Result<Self, Self::Error>

Performs the conversion.