Crate pyembed

Control an embedded Python interpreter.

The pyembed crate contains functionality for controlling an embedded Python interpreter running in the current process.

pyembed provides additional functionality over what is covered by the official Embedding Python in Another Application docs and provided by the CPython C API. For example, pyembed can utilize a custom Python meta path importer that can import Python module bytecode from memory using 0-copy.

This crate was initially designed for and is maintained as part of the PyOxidizer project. However, the crate is generic and can be used outside the PyOxidizer project.

The most important types in this crate are OxidizedPythonInterpreterConfig and MainPythonInterpreter. An OxidizedPythonInterpreterConfig defines how a Python interpreter is to behave. A MainPythonInterpreter creates and manages that interpreter and serves as a high-level interface for running code in the interpreter.

Dependencies

Under the hood, pyembed makes direct use of the pyo3 crate for low-level Python FFI bindings as well as higher-level interfacing.

It is an explicit goal of this crate to rely on as few external dependencies as possible. This is because we want to minimize bloat in produced binaries.

Features

The optional allocator-jemalloc feature controls support for using jemalloc as Python’s memory allocator. Use of Jemalloc from Python is a run-time configuration option controlled by the OxidizedPythonInterpreterConfig type and having jemalloc compiled into the binary does not mean it is being used!

The optional allocator-mimalloc feature controls support for using mimalloc as Python’s memory allocator. The feature behaves similarly to jemalloc, which is documented above.

The optional allocator-snmalloc feature controls support for using snmalloc as Python’s memory allocator. The feature behaves similarly to jemalloc, which is documented above.

The optional serialization feature controls whether configuration types (such as OxidizedPythonInterpreterConfig) implement Serialize and Deserialize.

Modules

technotes

Technical Implementation Notes

Structs

ExtensionModule

Defines a Python extension module and its initialization function.

MainPythonInterpreter

Manages an embedded Python interpreter.

OxidizedPythonInterpreterConfig

Configuration for a Python interpreter.

PythonInterpreterConfig

Holds configuration of a Python interpreter.

PythonMemoryAllocator

Represents a custom memory allocator that can be registered with Python.

PythonResourcesState

Defines Python resources available for import.

ResolvedOxidizedPythonInterpreterConfig

An OxidizedPythonInterpreterConfig that has fields resolved.

Enums

Allocator

Name of the Python memory allocators.

BytecodeOptimizationLevel

An optimization level for Python bytecode.

BytesWarning

Defines what to do when comparing bytes or bytesarray with str or comparing bytes with int.

CheckHashPycsMode

Control the validation behavior of hash-based .pyc files.

CoerceCLocale

Holds values for coerce_c_locale.

MemoryAllocatorBackend

Defines a backend for a memory allocator.

MultiprocessingStartMethod

Defines how to call multiprocessing.set_start_method() when multiprocessing is imported.

NewInterpreterError

Represents an error encountered when creating an embedded Python interpreter.

PackedResourcesSource

A source for packed resources data.

PythonInterpreterProfile

Defines the profile to use to configure a Python interpreter.

TerminfoResolution

Defines terminfo database resolution semantics.