Struct VirtualMachine

pub struct VirtualMachine {

    pub builtins: PyRef<PyModule>,
    pub sys_module: PyRef<PyModule>,
    pub ctx: PyRc<Context>,
    pub frames: RefCell<Vec<FrameRef>>,
    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,
    /* 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<FrameRef>>

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

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: &PyBaseExceptionRef, ) -> Result<(), W::Error>

pub fn write_exception_inner<W: Write>( &self, output: &mut W, exc: &PyBaseExceptionRef, ) -> 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>

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

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

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_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_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: String, ) -> 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: String, 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_lookup_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_attribute_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_type_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_name_error(&self, msg: String, name: PyStrRef) -> PyBaseExceptionRef

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

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

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

pub fn new_os_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_errno_error(&self, errno: i32, msg: String) -> PyBaseExceptionRef

pub fn new_system_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_unicode_decode_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_unicode_encode_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_value_error(&self, msg: String) -> PyBaseExceptionRef

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

pub fn new_buffer_error(&self, msg: String) -> PyBaseExceptionRef

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

pub fn new_index_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_not_implemented_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_recursion_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_zero_division_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_overflow_error(&self, msg: String) -> PyBaseExceptionRef

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

pub fn new_import_error( &self, msg: String, name: PyStrRef, ) -> PyBaseExceptionRef

pub fn new_runtime_error(&self, msg: String) -> PyBaseExceptionRef

pub fn new_memory_error(&self, msg: String) -> PyBaseExceptionRef

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

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 _contains( &self, haystack: &PyObject, needle: &PyObject, ) -> PyResult<bool>

impl VirtualMachine

pub fn add_native_module<S>(&mut self, name: S, module: StdlibInitFunc)

where S: Into<Cow<'static, str>>,

Can only be used in the initialization closure passed to Interpreter::with_init

pub fn add_native_modules<I>(&mut self, iter: I)

where I: IntoIterator<Item = (Cow<'static, str>, StdlibInitFunc)>,

pub fn add_frozen<I>(&mut self, frozen: I)

where I: IntoIterator<Item = (&'static str, FrozenModule)>,

Can only be used in the initialization closure passed to Interpreter::with_init

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

Set the custom signal channel for the interpreter

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 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 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<Ref<'_, FrameRef>>

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

pub fn current_globals(&self) -> Ref<'_, 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 [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: PyTupleTyped<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: &PyBaseExceptionRef, 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) -> u8

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

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

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.