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 sys_frozen: bool,
    pub sys_meipass: bool,
    pub terminfo_resolution: TerminfoResolution,
    pub tcl_library: Option<PathBuf>,
    pub write_modules_directory_env: Option<String>,
}

Configure a Python interpreter.

This type defines the configuration of a Python interpreter. It is used to initialize a Python interpreter embedded in the current process.

The type contains a reference to a PythonInterpreterConfig instance, which is an abstraction over the low-level C structs that Python uses during interpreter initialization.

The PythonInterpreterConfig has a single non-optional field: profile. This defines the defaults for various fields of the PyPreConfig and PyConfig instances that are initialized as part of interpreter initialization. See https://docs.python.org/3/c-api/init_config.html#isolated-configuration for more.

During interpreter initialization, we produce a PyPreConfig and PyConfig derived from this type. Config settings are applied in layers. First, we use the PythonInterpreterConfig.profile to derive a default instance given a profile. Next, we override fields if the PythonInterpreterConfig has Some(T) value set. Finally, we populate some fields if they are missing but required for the given configuration. For example, when in isolated mode, we set program_name and home unless an explicit value was provided in the PythonInterpreterConfig.

Generally speaking, the PythonInterpreterConfig exists to hold configuration that is defined in the CPython initialization and configuration API and OxidizedPythonInterpreterConfig exists to hold higher-level configuration for features specific to this crate.

Fields

exe: Option<PathBuf>

The path of the currently executing executable.

If not set, std::env::current_exe() will be used.

In all cases, the path will be canonicalized.

origin: Option<PathBuf>

The filesystem path from which relative paths will be interpreted.

interpreter_config: PythonInterpreterConfig

Low-level configuration of Python interpreter.

allocator_backend: MemoryAllocatorBackend

Memory allocator backend to use.

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.

Has no effect if 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.

Has no effect if 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.

Has no effect if 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.

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 a custom allocator backend to not be MemoryAllocatorBackend::Default.

allocator_debug: bool

Whether to set up Python allocator debug hooks to detect memory bugs.

This setting triggers the calling of PyMem_SetupDebugHooks() during interpreter initialization. It can be used with or without custom Python allocators.

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.

oxidized_importer: bool

Whether to install our custom meta path importer on interpreter init, and, if filesystem_importer is true, to add its path_hook method to sys.path_hooks for PathFinder’s and pkgutil’s use.

filesystem_importer: bool

Whether to install the default PathFinder meta path finder and, if oxidized_importer is true, to add our custom meta path importer’s path_hook method to sys.path_hooks for PathFinder’s and pkgutil’s use.

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.

For Path-based sources, the special string $ORIGIN will be expanded to the directory of the current executable or the value of self.origin if set. Relative paths without $ORIGIN will be evaluated relative to the process’s current working directory.

extra_extension_modules: Option<Vec<ExtensionModule>>

Extra extension modules to make available to the interpreter.

The values will effectively be passed to PyImport_ExtendInitTab().

argv: Option<Vec<OsString>>

Command line arguments to initialize sys.argv with.

If Some(T), interpreter initialization will set PyConfig.argv to a value derived from this value, overwriting an existing .interpreter_config.argv value, if set.

None is evaluated to Some(std::env::args_os().collect::<Vec<_>>() if .interpreter_config.argv is None or None if .interpreter_config.argv is Some(T).

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().

sys_frozen: bool

Whether to set sys.frozen=True.

Setting this will enable Python to emulate “frozen” binaries, such as those used by PyInstaller.

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.

terminfo_resolution: TerminfoResolution

How to resolve the terminfo database.

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.

$ORIGIN in the path is expanded to the directory of the current executable.

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.

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.