Struct Interpreter 

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

The general interface for the VM

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>".to_owned(),
    ).map_err(|err| vm.new_syntax_error(&err, 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 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 (suppresses unraisable exceptions from del).
6. Forced GC collection pass (collect cycles while builtins are available).
7. Module finalization (finalize_modules).
8. Final stdout/stderr flush.

Note that calling finalize is not necessary by purpose though.