Struct Context

pub struct Context { /* private fields */ }

An execution context for Python code.

This can be used to keep all global variables and imports intact between macro invocations:

let c = Context::new();

c.run(python! {
  foo = 5
});

c.run(python! {
  assert foo == 5
});

You may also use it to inspect global variables after the execution of the Python code, or set global variables before running:

let c = Context::new();

c.set("x", 13);

c.run(python! {
  foo = x + 2
});

assert_eq!(c.get::<i32>("foo"), 15);

Implementations

impl Context

pub fn new() -> Self

Create a new context for running Python code.

This function temporarily acquires the GIL. If you already have the GIL, you can use Context::new_with_gil instead.

This function panics if it fails to create the context.

pub fn new_with_gil(py: Python<'_>) -> Self

Create a new context for running Python code.

You must acquire the GIL to call this function.

This function panics if it fails to create the context.

pub fn globals<'p>(&'p self, py: Python<'p>) -> &'p PyDict

Get the globals as dictionary.

pub fn get<T: for<'p> FromPyObject<'p>>(&self, name: &str) -> T

Retrieve a global variable from the context.

This function temporarily acquires the GIL. If you already have the GIL, you can use Context::get_with_gil instead.

This function panics if the variable doesn’t exist, or the conversion fails.

pub fn get_with_gil<'p, T: FromPyObject<'p>>( &'p self, py: Python<'p>, name: &str, ) -> T

Retrieve a global variable from the context.

This function panics if the variable doesn’t exist, or the conversion fails.

pub fn set<T: ToPyObject>(&self, name: &str, value: T)

Set a global variable in the context.

This function temporarily acquires the GIL. If you already have the GIL, you can use Context::set_with_gil instead.

This function panics if the conversion fails.

pub fn set_with_gil<'p, T: ToPyObject>( &self, py: Python<'p>, name: &str, value: T, )

Set a global variable in the context.

This function panics if the conversion fails.

pub fn add_wrapped( &self, wrapper: &impl Fn(Python<'_>) -> PyResult<&PyCFunction>, )

Add a wrapped #[pyfunction] or #[pymodule] using its own __name__.

Use this with pyo3::wrap_pyfunction or pyo3::wrap_pymodule.

use pyo3::{prelude::*, wrap_pyfunction};

#[pyfunction]
fn get_five() -> i32 {
    5
}

fn main() {
    let c = Context::new();

    c.add_wrapped(wrap_pyfunction!(get_five));

    c.run(python! {
        assert get_five() == 5
    });
}

This function temporarily acquires the GIL. If you already have the GIL, you can use Context::add_wrapped_with_gil instead.

pub fn add_wrapped_with_gil<'p>( &self, py: Python<'p>, wrapper: &impl Fn(Python<'_>) -> PyResult<&PyCFunction>, )

Add a wrapped #[pyfunction] or #[pymodule] using its own __name__.

See Context::add_wrapped.

pub fn run<F: FnOnce(&PyDict)>(&self, code: PythonBlock<F>)

Run Python code using this context.

This function should be called using the python!{} macro:

let c = Context::new();

c.run(python!{
    print("Hello World")
});

This function temporarily acquires the GIL. If you already have the GIL, you can use Context::run_with_gil instead.

This function panics if the Python code fails.

pub fn run_with_gil<F: FnOnce(&PyDict)>( &self, py: Python<'_>, code: PythonBlock<F>, )

Run Python code using this context.

This function should be called using the python!{} macro, just like Context::run.

This function panics if the Python code fails.