Struct Interpreter 

pub struct Interpreter {
    pub global_state: PyRc<PyGlobalState>,
    /* private fields */
}

One isolated Python interpreter in the process (≈ CPython PyInterpreterState + main tstate).

Historically RustPython exposed a single process-level Interpreter. For PEP 734 (multiple interpreters / subinterpreters) this type is now the owned handle for one interpreter. Use Interpreter::create_subinterpreter to create additional isolated interpreters that share the process-wide type context but not modules or PyGlobalState.

Examples

Runs a simple embedded hello world program.

use rustpython_vm::Interpreter;
use rustpython_vm::compiler::Mode;
Interpreter::without_stdlib(Default::default()).enter(|vm| {
    let scope = vm.new_scope_with_builtins();
    let source = r#"print("Hello World!")"#;
    let code_obj = vm.compile(
            source,
            Mode::Exec,
            "<embedded>",
    ).map_err(|err| err.into_pyexception(vm, Some(source))).unwrap();
    vm.run_code_obj(code_obj, scope).unwrap();
});

Fields

global_state: PyRc<PyGlobalState>

Implementations

impl Interpreter

pub fn builder(settings: Settings) -> InterpreterBuilder

Create a new interpreter configuration builder.

Example

use rustpython_vm::Interpreter;

let builder = Interpreter::builder(Default::default());
// In practice, add stdlib: builder.add_native_modules(&stdlib_module_defs(&builder.ctx))
let interp = builder.build();

pub fn without_stdlib(settings: Settings) -> Self

This is a bare unit to build up an interpreter without the standard library. To create an interpreter with the standard library with the rustpython crate, use rustpython::InterpreterBuilder. To create an interpreter without the rustpython crate, but only with rustpython-vm, try to build one from the source code of InterpreterBuilder. It will not be a one-liner but it also will not be too hard.

pub fn with_init<F>(settings: Settings, init: F) -> Self

where F: FnOnce(&mut VirtualMachine),

Create with initialize function taking mutable vm reference.

Note: This is a legacy API. To add stdlib, use Interpreter::builder() instead.

pub fn id(&self) -> i64

Process-global interpreter id (main is super::MAIN_INTERPRETER_ID).

pub fn whence(&self) -> InterpreterWhence

Where this interpreter was created.

pub fn is_main(&self) -> bool

Whether this is a top-level interpreter rather than a subinterpreter.

Every top-level interpreter answers true; for the process main, use Interpreter::is_process_main.

pub fn is_process_main(&self) -> bool

Whether this is the PEP 734 process main interpreter (get_main()).

Unlike Interpreter::is_main, which is set for every top-level interpreter, this is true for only the single first-registered main.

pub fn create_subinterpreter(&self) -> Self

Create an isolated subinterpreter sharing this interpreter’s type context (Context) and module definitions, but with its own sys.modules, builtins module instance, thread registry, and stop-the-world state.

May be called while the parent is entered (matching CPython, where _interpreters.create() runs under the main interpreter). When the calling thread is currently attached to a VM, that attachment is temporarily saved so the subinterpreter can bootstrap as an outermost enter (correct thread-slot / stop-the-world state).

pub fn create_subinterpreter_from_vm( parent: &VirtualMachine, config: InterpreterConfig, ) -> Result<Self, &'static str>

Create a subinterpreter from a parent VM (the currently entered one).

pub fn create_subinterpreter_with_config( &self, config: InterpreterConfig, ) -> Result<Self, &'static str>

Create a subinterpreter with an explicit PEP 734 / PyInterpreterConfig.

pub fn enter<F, R>(&self, f: F) -> R

where F: FnOnce(&VirtualMachine) -> R,

Run a function with the main virtual machine and return a PyResult of the result.

To enter vm context multiple times or to avoid buffer/exception management, this function is preferred. enter is lightweight and it returns a python object in PyResult. You can stop or continue the execution multiple times by calling enter.

To finalize the vm once all desired enters are called, calling finalize will be helpful.

See also Interpreter::run for managed way to run the interpreter.

pub fn enter_and_expect<F, R>(&self, f: F, msg: &str) -> R

where F: FnOnce(&VirtualMachine) -> PyResult<R>,

Run Interpreter::enter and call VirtualMachine::expect_pyresult for the result.

This function is useful when you want to expect a result from the function, but also print useful panic information when exception raised.

See also Interpreter::enter and VirtualMachine::expect_pyresult for more information.

pub fn run<F>(self, f: F) -> u32

where F: FnOnce(&VirtualMachine) -> PyResult<()>,

Run a function with the main virtual machine and return exit code.

To enter vm context only once and safely terminate the vm, this function is preferred. Unlike Interpreter::enter, run calls finalize and returns exit code. You will not be able to obtain Python exception in this way.

See Interpreter::finalize for the finalization steps. See also Interpreter::enter for pure function call to obtain Python exception.

pub fn finalize(self, exc: Option<PyBaseExceptionRef>) -> u32

Finalize vm and turns an exception to exit code.

Finalization steps (matching Py_FinalizeEx):

1. Flush stdout and stderr.
2. Handle exit exception and turn it to exit code.
3. Call threading._shutdown() to join non-daemon threads.
4. Run atexit exit functions.
5. Set finalizing flag and hang remaining daemon threads.
6. Forced GC collection pass (collect cycles while builtins are available).
7. Module finalization (finalize_modules).
8. Clear interpreter-owned cross-interpreter data.
9. Final stdout/stderr flush.

Note that calling finalize is not necessary by purpose though.