Struct VirtualMachine 

pub struct VirtualMachine {

    pub builtins: PyRef<PyModule>,
    pub sys_module: PyRef<PyModule>,
    pub ctx: PyRc<Context>,
    pub frames: RefCell<Vec<FramePtr>>,
    pub wasm_id: Option<String>,
    pub import_func: PyObjectRef,
    pub profile_func: RefCell<PyObjectRef>,
    pub trace_func: RefCell<PyObjectRef>,
    pub use_tracing: Cell<bool>,
    pub recursion_limit: Cell<usize>,
    pub repr_guards: RefCell<HashSet<usize>>,
    pub state: PyRc<PyGlobalState>,
    pub initialized: bool,
    pub async_gen_firstiter: RefCell<Option<PyObjectRef>>,
    pub async_gen_finalizer: RefCell<Option<PyObjectRef>>,
    pub asyncio_running_loop: RefCell<Option<PyObjectRef>>,
    pub asyncio_running_task: RefCell<Option<PyObjectRef>>,
    /* private fields */
}

Top level container of a python virtual machine. In theory you could create more instances of this struct and have them operate fully isolated.

To construct this, please refer to the Interpreter

Fields

builtins: PyRef<PyModule>

sys_module: PyRef<PyModule>

ctx: PyRc<Context>

frames: RefCell<Vec<FramePtr>>

wasm_id: Option<String>

import_func: PyObjectRef

profile_func: RefCell<PyObjectRef>

trace_func: RefCell<PyObjectRef>

use_tracing: Cell<bool>

recursion_limit: Cell<usize>

repr_guards: RefCell<HashSet<usize>>

state: PyRc<PyGlobalState>

initialized: bool

async_gen_firstiter: RefCell<Option<PyObjectRef>>

Async generator firstiter hook (per-thread, set via sys.set_asyncgen_hooks)

async_gen_finalizer: RefCell<Option<PyObjectRef>>

Async generator finalizer hook (per-thread, set via sys.set_asyncgen_hooks)

asyncio_running_loop: RefCell<Option<PyObjectRef>>

Current running asyncio event loop for this thread

asyncio_running_task: RefCell<Option<PyObjectRef>>

Current running asyncio task for this thread

Implementations

impl VirtualMachine

pub fn print_exception(&self, exc: PyBaseExceptionRef)

Print exception chain by calling sys.excepthook

pub fn write_exception<W: Write>( &self, output: &mut W, exc: &Py<PyBaseException>, ) -> Result<(), W::Error>

pub fn write_exception_inner<W: Write>( &self, output: &mut W, exc: &Py<PyBaseException>, ) -> Result<(), W::Error>

Print exception with traceback

pub fn split_exception( &self, exc: PyBaseExceptionRef, ) -> (PyObjectRef, PyObjectRef, PyObjectRef)

pub fn normalize_exception( &self, exc_type: PyObjectRef, exc_val: PyObjectRef, exc_tb: PyObjectRef, ) -> PyResult<PyBaseExceptionRef>

Similar to PyErr_NormalizeException in CPython

pub fn invoke_exception( &self, cls: PyTypeRef, args: Vec<PyObjectRef>, ) -> PyResult<PyBaseExceptionRef>

impl VirtualMachine

pub fn compile( &self, source: &str, mode: Mode, source_path: String, ) -> Result<PyRef<PyCode>, CompileError>

pub fn compile_with_opts( &self, source: &str, mode: Mode, source_path: String, opts: CompileOpts, ) -> Result<PyRef<PyCode>, CompileError>

impl VirtualMachine

pub fn run_script(&self, scope: Scope, path: &str) -> PyResult<()>

impl VirtualMachine

pub fn run_simple_string(&self, source: &str) -> PyResult

PyRun_SimpleString

Execute a string of Python code in a new scope with builtins.

pub fn run_string( &self, scope: Scope, source: &str, source_path: String, ) -> PyResult

PyRun_String

Execute a string of Python code with explicit scope and source path.

pub fn run_code_string( &self, scope: Scope, source: &str, source_path: String, ) -> PyResult

👎Deprecated:

use run_string instead

pub fn run_block_expr(&self, scope: Scope, source: &str) -> PyResult

impl VirtualMachine

Collection of object creation helpers

pub fn new_pyobj(&self, value: impl ToPyObject) -> PyObjectRef

Create a new python object

pub fn new_tuple(&self, value: impl IntoPyTuple) -> PyTupleRef

pub fn new_module( &self, name: &str, dict: PyDictRef, doc: Option<PyStrRef>, ) -> PyRef<PyModule>

pub fn new_scope_with_builtins(&self) -> Scope

pub fn new_scope_with_main(&self) -> PyResult<Scope>

pub fn new_function<F, FKind>( &self, name: &'static str, f: F, ) -> PyRef<PyNativeFunction>

where F: IntoPyNativeFn<FKind>,

pub fn new_method<F, FKind>( &self, name: &'static str, class: &'static Py<PyType>, f: F, ) -> PyRef<PyMethodDescriptor>

where F: IntoPyNativeFn<FKind>,

pub fn new_exception( &self, exc_type: PyTypeRef, args: Vec<PyObjectRef>, ) -> PyBaseExceptionRef

Instantiate an exception with arguments. This function should only be used with builtin exception types; if a user-defined exception type is passed in, it may not be fully initialized; try using vm.invoke_exception() or exceptions::ExceptionCtor instead.

pub fn new_os_error(&self, msg: impl ToPyObject) -> PyRef<PyBaseException>

pub fn new_os_subtype_error( &self, exc_type: PyTypeRef, errno: Option<i32>, msg: impl ToPyObject, ) -> PyRef<PyOSError>

pub fn new_exception_empty(&self, exc_type: PyTypeRef) -> PyBaseExceptionRef

Instantiate an exception with no arguments. This function should only be used with builtin exception types; if a user-defined exception type is passed in, it may not be fully initialized; try using vm.invoke_exception() or exceptions::ExceptionCtor instead.

pub fn new_exception_msg( &self, exc_type: PyTypeRef, msg: Wtf8Buf, ) -> PyBaseExceptionRef

Instantiate an exception with msg as the only argument. This function should only be used with builtin exception types; if a user-defined exception type is passed in, it may not be fully initialized; try using vm.invoke_exception() or exceptions::ExceptionCtor instead.

pub fn new_exception_msg_dict( &self, exc_type: PyTypeRef, msg: Wtf8Buf, dict: PyDictRef, ) -> PyBaseExceptionRef

Instantiate an exception with msg as the only argument and dict for object This function should only be used with builtin exception types; if a user-defined exception type is passed in, it may not be fully initialized; try using vm.invoke_exception() or exceptions::ExceptionCtor instead.

pub fn new_no_attribute_error( &self, obj: PyObjectRef, name: PyStrRef, ) -> PyBaseExceptionRef

pub fn new_name_error( &self, msg: impl Into<Wtf8Buf>, name: PyStrRef, ) -> PyBaseExceptionRef

pub fn new_unsupported_unary_error( &self, a: &PyObject, op: &str, ) -> PyBaseExceptionRef

pub fn new_unsupported_bin_op_error( &self, a: &PyObject, b: &PyObject, op: &str, ) -> PyBaseExceptionRef

pub fn new_unsupported_ternary_op_error( &self, a: &PyObject, b: &PyObject, c: &PyObject, op: &str, ) -> PyBaseExceptionRef

pub fn new_last_os_error(&self) -> PyBaseExceptionRef

Create a new OSError from the last OS error.

On windows, windows-sys errors are expected to be handled by this function. This is identical to new_last_errno_error on non-Windows platforms.

pub fn new_last_errno_error(&self) -> PyBaseExceptionRef

Create a new OSError from the last POSIX errno.

On windows, CRT errno are expected to be handled by this function. This is identical to new_last_os_error on non-Windows platforms.

pub fn new_errno_error( &self, errno: i32, msg: impl ToPyObject, ) -> PyRef<PyOSError>

pub fn new_unicode_decode_error_real( &self, encoding: PyStrRef, object: PyBytesRef, start: usize, end: usize, reason: PyStrRef, ) -> PyBaseExceptionRef

pub fn new_unicode_encode_error_real( &self, encoding: PyStrRef, object: PyStrRef, start: usize, end: usize, reason: PyStrRef, ) -> PyBaseExceptionRef

pub fn new_key_error(&self, obj: PyObjectRef) -> PyBaseExceptionRef

pub fn new_syntax_error_maybe_incomplete( &self, error: &CompileError, source: Option<&str>, allow_incomplete: bool, ) -> PyBaseExceptionRef

pub fn new_syntax_error( &self, error: &CompileError, source: Option<&str>, ) -> PyBaseExceptionRef

pub fn new_import_error( &self, msg: impl Into<Wtf8Buf>, name: impl Into<PyStrRef>, ) -> PyBaseExceptionRef

pub fn new_stop_iteration( &self, value: Option<PyObjectRef>, ) -> PyBaseExceptionRef

pub fn new_lookup_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python LookupError object. Useful for raising errors from python functions implemented in rust.

pub fn new_eof_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python EOFError object. Useful for raising errors from python functions implemented in rust.

pub fn new_attribute_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python AttributeError object. Useful for raising errors from python functions implemented in rust.

pub fn new_type_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python TypeError object. Useful for raising errors from python functions implemented in rust.

pub fn new_system_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python SystemError object. Useful for raising errors from python functions implemented in rust.

pub fn new_unicode_decode_error( &self, msg: impl Into<Wtf8Buf>, ) -> PyBaseExceptionRef

Create a new python UnicodeDecodeError object. Useful for raising errors from python functions implemented in rust.

pub fn new_unicode_encode_error( &self, msg: impl Into<Wtf8Buf>, ) -> PyBaseExceptionRef

Create a new python UnicodeEncodeError object. Useful for raising errors from python functions implemented in rust.

pub fn new_value_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python ValueError object. Useful for raising errors from python functions implemented in rust.

pub fn new_buffer_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python BufferError object. Useful for raising errors from python functions implemented in rust.

pub fn new_index_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python IndexError object. Useful for raising errors from python functions implemented in rust.

pub fn new_not_implemented_error( &self, msg: impl Into<Wtf8Buf>, ) -> PyBaseExceptionRef

Create a new python NotImplementedError object. Useful for raising errors from python functions implemented in rust.

pub fn new_recursion_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python RecursionError object. Useful for raising errors from python functions implemented in rust.

pub fn new_zero_division_error( &self, msg: impl Into<Wtf8Buf>, ) -> PyBaseExceptionRef

Create a new python ZeroDivisionError object. Useful for raising errors from python functions implemented in rust.

pub fn new_overflow_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python OverflowError object. Useful for raising errors from python functions implemented in rust.

pub fn new_runtime_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python RuntimeError object. Useful for raising errors from python functions implemented in rust.

pub fn new_python_finalization_error( &self, msg: impl Into<Wtf8Buf>, ) -> PyBaseExceptionRef

Create a new python PythonFinalizationError object. Useful for raising errors from python functions implemented in rust.

pub fn new_memory_error(&self, msg: impl Into<Wtf8Buf>) -> PyBaseExceptionRef

Create a new python MemoryError object. Useful for raising errors from python functions implemented in rust.

impl VirtualMachine

PyObject support

pub fn unwrap_pyresult<T>(&self, result: PyResult<T>) -> T

pub fn expect_pyresult<T>(&self, result: PyResult<T>, msg: &str) -> T

pub fn is_none(&self, obj: &PyObject) -> bool

Test whether a python object is None.

pub fn option_if_none(&self, obj: PyObjectRef) -> Option<PyObjectRef>

pub fn unwrap_or_none(&self, obj: Option<PyObjectRef>) -> PyObjectRef

pub fn call_get_descriptor_specific( &self, descr: &PyObject, obj: Option<PyObjectRef>, cls: Option<PyObjectRef>, ) -> Option<PyResult>

pub fn call_get_descriptor( &self, descr: &PyObject, obj: PyObjectRef, ) -> Option<PyResult>

pub fn call_if_get_descriptor( &self, attr: &PyObject, obj: PyObjectRef, ) -> PyResult

pub fn call_method<T>( &self, obj: &PyObject, method_name: &str, args: T, ) -> PyResult

where T: IntoFuncArgs,

pub fn dir(&self, obj: Option<PyObjectRef>) -> PyResult<PyList>

pub fn print(&self, args: impl IntoFuncArgs) -> PyResult<()>

Same as builtins.print in Python. A convenience function to provide a simple way to print objects for debug purpose.

pub fn invoke(&self, obj: &impl AsObject, args: impl IntoFuncArgs) -> PyResult

👎Deprecated:

in favor of obj.call(args, vm)

impl VirtualMachine

Collection of operators

pub fn bool_eq(&self, a: &PyObject, b: &PyObject) -> PyResult<bool>

pub fn identical_or_equal(&self, a: &PyObject, b: &PyObject) -> PyResult<bool>

pub fn bool_seq_lt(&self, a: &PyObject, b: &PyObject) -> PyResult<Option<bool>>

pub fn bool_seq_gt(&self, a: &PyObject, b: &PyObject) -> PyResult<Option<bool>>

pub fn length_hint_opt(&self, iter: PyObjectRef) -> PyResult<Option<usize>>

pub fn check_repeat_or_overflow_error( &self, length: usize, n: isize, ) -> PyResult<usize>

Checks that the multiplication is able to be performed. On Ok returns the index as a usize for sequences to be able to use immediately.

pub fn binary_op1( &self, a: &PyObject, b: &PyObject, op_slot: PyNumberBinaryOp, ) -> PyResult

Calling scheme used for binary operations:

Order operations are tried until either a valid result or error: b.rop(b,a)[*], a.op(a,b), b.rop(b,a)

[*] - only when Py_TYPE(a) != Py_TYPE(b) && Py_TYPE(b) is a subclass of Py_TYPE(a)

pub fn binary_op( &self, a: &PyObject, b: &PyObject, op_slot: PyNumberBinaryOp, op: &str, ) -> PyResult

pub fn _sub(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _mod(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _divmod(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _lshift(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _rshift(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _and(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _xor(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _or(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _floordiv(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _truediv(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _matmul(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _isub(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _imod(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _ilshift(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _irshift(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _iand(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _ixor(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _ior(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _ifloordiv(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _itruediv(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _imatmul(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _pow(&self, a: &PyObject, b: &PyObject, c: &PyObject) -> PyResult

pub fn _ipow(&self, a: &PyObject, b: &PyObject, c: &PyObject) -> PyResult

pub fn _add(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _iadd(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _mul(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _imul(&self, a: &PyObject, b: &PyObject) -> PyResult

pub fn _abs(&self, a: &PyObject) -> PyResult<PyObjectRef>

pub fn _pos(&self, a: &PyObject) -> PyResult

pub fn _neg(&self, a: &PyObject) -> PyResult

pub fn _invert(&self, a: &PyObject) -> PyResult

pub fn format( &self, obj: &PyObject, format_spec: PyStrRef, ) -> PyResult<PyStrRef>

pub fn format_utf8( &self, obj: &PyObject, format_spec: PyStrRef, ) -> PyResult<PyRef<PyUtf8Str>>

pub fn _contains( &self, haystack: &PyObject, needle: &PyObject, ) -> PyResult<bool>

impl VirtualMachine

pub fn allow_threads<R>(&self, f: impl FnOnce() -> R) -> R

Temporarily detach the current thread (ATTACHED → DETACHED) while running f, then re-attach afterwards. Allows stop_the_world to park this thread during blocking syscalls.

Equivalent to CPython’s Py_BEGIN_ALLOW_THREADS / Py_END_ALLOW_THREADS.

pub fn set_user_signal_channel(&mut self, signal_rx: UserSignalReceiver)

Set the custom signal channel for the interpreter

pub fn run_pyc_bytes(&self, pyc_bytes: &[u8], scope: Scope) -> PyResult<()>

Execute Python bytecode (.pyc) from an in-memory buffer.

When the RustPython CLI is available, .pyc files are normally executed by invoking rustpython <input>.pyc. This method provides an alternative for environments where the binary is unavailable or file I/O is restricted (e.g. WASM).

Preparing a .pyc file

First, compile a Python source file into bytecode:

# Generate a .pyc file
$ rustpython -m py_compile <input>.py

Running the bytecode

Load the resulting .pyc file into memory and execute it using the VM:

use rustpython_vm::Interpreter;
Interpreter::without_stdlib(Default::default()).enter(|vm| {
    let bytes = std::fs::read("__pycache__/<input>.rustpython-314.pyc").unwrap();
    let main_scope = vm.new_scope_with_main().unwrap();
    vm.run_pyc_bytes(&bytes, main_scope);
});

pub fn run_code_obj(&self, code: PyRef<PyCode>, scope: Scope) -> PyResult

pub fn run_unraisable( &self, e: PyBaseExceptionRef, msg: Option<String>, object: PyObjectRef, )

pub fn run_frame(&self, frame: FrameRef) -> PyResult

pub fn finalize_modules(&self)

Clear module references during shutdown. Follows the same phased algorithm as pylifecycle.c finalize_modules(): no hardcoded module names, reverse import order, only builtins/sys last.

pub fn current_recursion_depth(&self) -> usize

pub fn with_recursion<R, F: FnOnce() -> PyResult<R>>( &self, _where: &str, f: F, ) -> PyResult<R>

Used to run the body of a (possibly) recursive function. It will raise a RecursionError if recursive functions are nested far too many times, preventing a stack overflow.

pub fn with_frame<R, F: FnOnce(FrameRef) -> PyResult<R>>( &self, frame: FrameRef, f: F, ) -> PyResult<R>

pub fn with_frame_exc<R, F: FnOnce(FrameRef) -> PyResult<R>>( &self, frame: FrameRef, exc: Option<PyBaseExceptionRef>, f: F, ) -> PyResult<R>

Like with_frame but allows specifying the initial exception state.

pub fn resume_gen_frame<R, F: FnOnce(&Py<Frame>) -> PyResult<R>>( &self, frame: &FrameRef, exc: Option<PyBaseExceptionRef>, f: F, ) -> PyResult<R>

Lightweight frame execution for generator/coroutine resume. Pushes to the thread frame stack and fires trace/profile events, but skips the thread exception update for performance.

pub fn compile_opts(&self) -> CompileOpts

Returns a basic CompileOpts instance with options accurate to the vm. Used as the CompileOpts for vm.compile().

pub fn current_frame(&self) -> Option<FrameRef>

pub fn current_locals(&self) -> PyResult<ArgMapping>

pub fn current_globals(&self) -> PyDictRef

pub fn try_class( &self, module: &'static str, class: &'static str, ) -> PyResult<PyTypeRef>

pub fn class(&self, module: &'static str, class: &'static str) -> PyTypeRef

pub fn import<'a>( &self, module_name: impl AsPyStr<'a>, level: usize, ) -> PyResult

Call Python import function without from_list. Roughly equivalent to import module_name or import top.submodule.

See also VirtualMachine::import_from for more advanced import. See also rustpython_vm::import::import_source and other primitive import functions.

pub fn import_from<'a>( &self, module_name: impl AsPyStr<'a>, from_list: &Py<PyTuple<PyStrRef>>, level: usize, ) -> PyResult

Call Python import function caller with from_list. Roughly equivalent to from module_name import item1, item2 or from top.submodule import item1, item2

pub fn extract_elements_with<T, F>( &self, value: &PyObject, func: F, ) -> PyResult<Vec<T>>

where F: Fn(PyObjectRef) -> PyResult<T>,

pub fn map_iterable_object<F, R>( &self, obj: &PyObject, f: F, ) -> PyResult<PyResult<Vec<R>>>

where F: FnMut(PyObjectRef) -> PyResult<R>,

pub fn get_attribute_opt<'a>( &self, obj: PyObjectRef, attr_name: impl AsPyStr<'a>, ) -> PyResult<Option<PyObjectRef>>

pub fn set_attribute_error_context( &self, exc: &Py<PyBaseException>, obj: PyObjectRef, name: PyStrRef, )

pub fn get_method_or_type_error<F>( &self, obj: PyObjectRef, method_name: &'static PyStrInterned, err_msg: F, ) -> PyResult

where F: FnOnce() -> String,

pub fn check_signals(&self) -> PyResult<()>

Checks for triggered signals and calls the appropriate handlers. A no-op on platforms where signals are not supported.

pub fn handle_exit_exception(&self, exc: PyBaseExceptionRef) -> u32

pub fn insert_sys_path(&self, obj: PyObjectRef) -> PyResult<()>

pub fn run_module(&self, module: &str) -> PyResult<()>

pub fn fs_encoding(&self) -> &'static PyStrInterned

pub fn fs_encode_errors(&self) -> &'static PyUtf8StrInterned

pub fn fsdecode(&self, s: impl Into<OsString>) -> PyStrRef

pub fn fsencode<'a>(&self, s: &'a Py<PyStr>) -> PyResult<Cow<'a, OsStr>>

Trait Implementations

impl<'a> AsBag for &'a VirtualMachine

type Bag = PyObjBag<'a>

fn as_bag(self) -> PyObjBag<'a>

impl AsRef<Context> for VirtualMachine

fn as_ref(&self) -> &Context

Converts this type into a shared reference of the (usually inferred) input type.