Struct Python 

pub struct Python<'py>(/* private fields */);

A marker token that represents holding the GIL.

It serves three main purposes:

• It provides a global API for the Python interpreter, such as Python::eval.
• It can be passed to functions that require a proof of holding the GIL, such as Py::clone_ref.
• Its lifetime represents the scope of holding the GIL which can be used to create Rust references that are bound to it, such as Bound<'py, PyAny>.

Note that there are some caveats to using it that you might need to be aware of. See the Deadlocks and Releasing and freeing memory paragraphs for more information about that.

Obtaining a Python token

The following are the recommended ways to obtain a Python<'py> token, in order of preference:

• If you already have something with a lifetime bound to the GIL, such as Bound<'py, PyAny>, you can use its .py() method to get a token.
• In a function or method annotated with #[pyfunction] or #[pymethods] you can declare it as a parameter, and PyO3 will pass in the token when Python code calls it.
• When you need to acquire the GIL yourself, such as when calling Python code from Rust, you should call Python::attach to do that and pass your code as a closure to it.

The first two options are zero-cost; Python::attach requires runtime checking and may need to block to acquire the GIL.

Deadlocks

Note that the GIL can be temporarily released by the Python interpreter during a function call (e.g. importing a module). In general, you don’t need to worry about this because the GIL is reacquired before returning to the Rust code:

`Python` exists   |=====================================|
GIL actually held |==========|         |================|
Rust code running |=======|                |==|  |======|

This behaviour can cause deadlocks when trying to lock a Rust mutex while holding the GIL:

• Thread 1 acquires the GIL
• Thread 1 locks a mutex
• Thread 1 makes a call into the Python interpreter which releases the GIL
• Thread 2 acquires the GIL
• Thread 2 tries to locks the mutex, blocks
• Thread 1’s Python interpreter call blocks trying to reacquire the GIL held by thread 2

To avoid deadlocking, you should release the GIL before trying to lock a mutex or awaiting in asynchronous code, e.g. with Python::detach.

Releasing and freeing memory

The Python<'py> type can be used to create references to variables owned by the Python interpreter, using functions such as Python::eval and PyModule::import.

Implementations

impl Python<'_>

pub fn with_gil<F, R>(f: F) -> R

where F: for<'py> FnOnce(Python<'py>) -> R,

👎Deprecated since 0.26.0: use Python::attach instead

See Python::attach

pub fn attach<F, R>(f: F) -> R

where F: for<'py> FnOnce(Python<'py>) -> R,

Acquires the global interpreter lock, allowing access to the Python interpreter. The provided closure F will be executed with the acquired Python marker token.

If implementing #[pymethods] or #[pyfunction], declare py: Python as an argument. PyO3 will pass in the token to grant access to the GIL context in which the function is running, avoiding the need to call attach.

If the auto-initialize feature is enabled and the Python runtime is not already initialized, this function will initialize it. See Python::initialize for details.

If the current thread does not yet have a Python “thread state” associated with it, a new one will be automatically created before F is executed and destroyed after F completes.

Panics

• If the auto-initialize feature is not enabled and the Python interpreter is not initialized.
• If the Python interpreter is in the process of shutting down.
• If the middle of GC traversal.

To avoid possible initialization or panics if calling in a context where the Python interpreter might be unavailable, consider using Python::try_attach.

Examples

use pyo3::prelude::*;
use pyo3::ffi::c_str;

Python::attach(|py| -> PyResult<()> {
    let x: i32 = py.eval(c_str!("5"), None, None)?.extract()?;
    assert_eq!(x, 5);
    Ok(())
})

pub fn try_attach<F, R>(f: F) -> Option<R>

where F: for<'py> FnOnce(Python<'py>) -> R,

Variant of Python::attach which will return without attaching to the Python interpreter if the interpreter is in a state where it cannot be attached to:

• in the middle of GC traversal
• in the process of shutting down
• not initialized

Note that due to the nature of the underlying Python APIs used to implement this, the behavior is currently provided on a best-effort basis; it is expected that a future CPython version will introduce APIs which guarantee this behaviour. This function is still recommended for use in the meanwhile as it provides the best possible behaviour and should transparently change to an optimal implementation once such APIs are available.

pub fn initialize()

Prepares the use of Python.

If the Python interpreter is not already initialized, this function will initialize it with signal handling disabled (Python will not raise the KeyboardInterrupt exception). Python signal handling depends on the notion of a ‘main thread’, which must be the thread that initializes the Python interpreter.

If the Python interpreter is already initialized, this function has no effect.

This function is unavailable under PyPy because PyPy cannot be embedded in Rust (or any other software). Support for this is tracked on the PyPy issue tracker.

Examples

use pyo3::prelude::*;

Python::initialize();
Python::attach(|py| py.run(pyo3::ffi::c_str!("print('Hello World')"), None, None))

pub unsafe fn with_gil_unchecked<F, R>(f: F) -> R

where F: for<'py> FnOnce(Python<'py>) -> R,

👎Deprecated since 0.26.0: use Python::attach_unchecked instead

See Python::attach_unchecked

Safety

If Python::attach would succeed, it is safe to call this function.

pub unsafe fn attach_unchecked<F, R>(f: F) -> R

where F: for<'py> FnOnce(Python<'py>) -> R,

Like Python::attach except Python interpreter state checking is skipped.

Normally when attaching to the Python interpreter, PyO3 checks that it is in an appropriate state (e.g. it is fully initialized). This function skips those checks.

Safety

If Python::attach would succeed, it is safe to call this function.

impl<'py> Python<'py>

pub fn allow_threads<T, F>(self, f: F) -> T

where F: Ungil + FnOnce() -> T, T: Ungil,

👎Deprecated since 0.26.0: use Python::detach instead

See Python::detach

pub fn detach<T, F>(self, f: F) -> T

where F: Ungil + FnOnce() -> T, T: Ungil,

Temporarily releases the GIL, thus allowing other Python threads to run. The GIL will be reacquired when F’s scope ends.

If you don’t need to touch the Python interpreter for some time and have other Python threads around, this will let you run Rust-only code while letting those other Python threads make progress.

Only types that implement Ungil can cross the closure. See the module level documentation for more information.

If you need to pass Python objects into the closure you can use Py<T>to create a reference independent of the GIL lifetime. However, you cannot do much with those without a Python token, for which you’d need to reacquire the GIL.

Example: Releasing the GIL while running a computation in Rust-only code

use pyo3::prelude::*;

#[pyfunction]
fn sum_numbers(py: Python<'_>, numbers: Vec<u32>) -> PyResult<u32> {
    // We release the GIL here so any other Python threads get a chance to run.
    py.detach(move || {
        // An example of an "expensive" Rust calculation
        let sum = numbers.iter().sum();

        Ok(sum)
    })
}

Please see the Parallelism chapter of the guide for a thorough discussion of using Python::detach in this manner.

Example: Passing borrowed Python references into the closure is not allowed

use pyo3::prelude::*;
use pyo3::types::PyString;

fn parallel_print(py: Python<'_>) {
    let s = PyString::new(py, "This object cannot be accessed without holding the GIL >_<");
    py.detach(move || {
        println!("{:?}", s); // This causes a compile error.
    });
}

pub fn eval( self, code: &CStr, globals: Option<&Bound<'py, PyDict>>, locals: Option<&Bound<'py, PyDict>>, ) -> PyResult<Bound<'py, PyAny>>

Evaluates a Python expression in the given context and returns the result.

If globals is None, it defaults to Python module __main__. If locals is None, it defaults to the value of globals.

If globals doesn’t contain __builtins__, default __builtins__ will be added automatically.

Examples

let result = py.eval(c_str!("[i * 10 for i in range(5)]"), None, None).unwrap();
let res: Vec<i64> = result.extract().unwrap();
assert_eq!(res, vec![0, 10, 20, 30, 40])

pub fn run( self, code: &CStr, globals: Option<&Bound<'py, PyDict>>, locals: Option<&Bound<'py, PyDict>>, ) -> PyResult<()>

Executes one or more Python statements in the given context.

If globals is None, it defaults to Python module __main__. If locals is None, it defaults to the value of globals.

If globals doesn’t contain __builtins__, default __builtins__ will be added automatically.

Examples

use pyo3::{
    prelude::*,
    types::{PyBytes, PyDict},
    ffi::c_str,
};
Python::attach(|py| {
    let locals = PyDict::new(py);
    py.run(c_str!(
        r#"
import base64
s = 'Hello Rust!'
ret = base64.b64encode(s.encode('utf-8'))
"#),
        None,
        Some(&locals),
    )
    .unwrap();
    let ret = locals.get_item("ret").unwrap().unwrap();
    let b64 = ret.cast::<PyBytes>().unwrap();
    assert_eq!(b64.as_bytes(), b"SGVsbG8gUnVzdCE=");
});

You can use py_run! for a handy alternative of run if you don’t need globals and unwrapping is OK.

pub fn get_type<T>(self) -> Bound<'py, PyType>

where T: PyTypeInfo,

Gets the Python type object for type T.

pub fn import<N>(self, name: N) -> PyResult<Bound<'py, PyModule>>

where N: IntoPyObject<'py, Target = PyString>,

Imports the Python module with the specified name.

pub fn None(self) -> Py<PyAny>

Gets the Python builtin value None.

pub fn Ellipsis(self) -> Py<PyAny>

Gets the Python builtin value Ellipsis, or ....

pub fn NotImplemented(self) -> Py<PyAny>

Gets the Python builtin value NotImplemented.

pub fn version(self) -> &'py str

Gets the running Python interpreter version as a string.

Examples

Python::attach(|py| {
    // The full string could be, for example:
    // "3.10.0 (tags/v3.10.0:b494f59, Oct  4 2021, 19:00:18) [MSC v.1929 64 bit (AMD64)]"
    assert!(py.version().starts_with("3."));
});

pub fn version_info(self) -> PythonVersionInfo<'py>

Gets the running Python interpreter version as a struct similar to sys.version_info.

Examples

Python::attach(|py| {
    // PyO3 supports Python 3.7 and up.
    assert!(py.version_info() >= (3, 7));
    assert!(py.version_info() >= (3, 7, 0));
});

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

Lets the Python interpreter check and handle any pending signals. This will invoke the corresponding signal handlers registered in Python (if any).

Returns Err(PyErr) if any signal handler raises an exception.

These signals include SIGINT (normally raised by CTRL + C), which by default raises KeyboardInterrupt. For this reason it is good practice to call this function regularly as part of long-running Rust functions so that users can cancel it.

Example

use pyo3::prelude::*;

#[pyfunction]
fn loop_forever(py: Python<'_>) -> PyResult<()> {
    loop {
        // As this loop is infinite it should check for signals every once in a while.
        // Using `?` causes any `PyErr` (potentially containing `KeyboardInterrupt`)
        // to break out of the loop.
        py.check_signals()?;

        // do work here
    }
}

Note

This function calls PyErr_CheckSignals() which in turn may call signal handlers. As Python’s signal API allows users to define custom signal handlers, calling this function allows arbitrary Python code inside signal handlers to run.

If the function is called from a non-main thread, or under a non-main Python interpreter, it does nothing yet still returns Ok(()).

impl<'unbound> Python<'unbound>

pub unsafe fn assume_gil_acquired() -> Python<'unbound>

👎Deprecated since 0.26.0: use Python::assume_attached instead

Deprecated version of Python::assume_attached

Safety

See Python::assume_attached

pub unsafe fn assume_attached() -> Python<'unbound>

Unsafely creates a Python token with an unbounded lifetime.

Many of PyO3 APIs use Python<'_> as proof that the calling thread is attached to the interpreter, but this function can be used to call them unsafely.

Safety

• This token and any borrowed Python references derived from it can only be safely used whilst the currently executing thread is actually attached to the interpreter.
• This function creates a token with an unbounded lifetime. Safe code can assume that holding a Python<'py> token means the thread is attached and stays attached for the lifetime 'py. If you let it or borrowed Python references escape to safe code you are responsible for bounding the lifetime 'unbound appropriately. For more on unbounded lifetimes, see the nomicon.

Trait Implementations

impl<'py> Clone for Python<'py>

fn clone(&self) -> Python<'py>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'py> Copy for Python<'py>