Struct pyembed::OxidizedPythonInterpreterConfig

pub struct OxidizedPythonInterpreterConfig<'a> {
    pub exe: Option<PathBuf>,
    pub origin: Option<PathBuf>,
    pub interpreter_config: PythonInterpreterConfig,
    pub raw_allocator: Option<PythonRawAllocator>,
    pub set_missing_path_configuration: bool,
    pub oxidized_importer: bool,
    pub filesystem_importer: bool,
    pub packed_resources: Vec<&'a [u8]>,
    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.

origin: Option<PathBuf>

The filesystem path from which relative paths will be interpreted.

interpreter_config: PythonInterpreterConfig

Low-level configuration of Python interpreter.

raw_allocator: Option<PythonRawAllocator>

Allocator to use for Python's raw allocator.

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.

filesystem_importer: bool

Whether to install the default PathFinder meta path finder.

packed_resources: Vec<&'a [u8]>

Reference to packed resources data.

The referenced data contains Python module data. It likely comes from an include_bytes!(...) of a file generated by PyOxidizer.

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.

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>, &'static str>

Create a new type with all values resolved.

pub fn resolve_sys_argv(&self) -> Option<Vec<OsString>>

Resolve OsString to use for sys.argv.

Returns Some(T) if we should populate PyConfig.argv or None if we should leave this value alone.

pub fn resolve_sys_argvb(&self) -> Vec<OsString>

Resolve the value to use for sys.argvb.

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.