Struct pyo3::prelude::Py[][src]

#[repr(transparent)]
pub struct Py<T>(_, _);
Expand description

A GIL-independent reference to an object allocated on the Python heap.

This type does not auto-dereference to the inner object because you must prove you hold the GIL to access it. Instead, call one of its methods to access the inner object:

Example: Storing Python objects in structs

As all the native Python objects only appear as references, storing them in structs doesn’t work well. For example, this won’t compile:

#[pyclass]
struct Foo<'py> {
    inner: &'py PyDict,
}

impl Foo {
    fn new() -> Foo {
        let foo = Python::with_gil(|py| {
            // `py` will only last for this scope.

            // `&PyDict` derives its lifetime from `py` and
            // so won't be able to outlive this closure.
            let dict: &PyDict = PyDict::new(py);

            // because `Foo` contains `dict` its lifetime
            // is now also tied to `py`.
            Foo { inner: dict }
        });
        // Foo is no longer valid.
        // Returning it from this function is a 💥 compiler error 💥
        foo
    }
}

Py<T> can be used to get around this by converting dict into a GIL-independent reference:

use pyo3::prelude::*;
use pyo3::types::PyDict;

#[pyclass]
struct Foo {
    inner: Py<PyDict>,
}

#[pymethods]
impl Foo {
    #[new]
    fn __new__() -> Foo {
        Python::with_gil(|py| {
            let dict: Py<PyDict> = PyDict::new(py).into();
            Foo { inner: dict }
        })
    }
}

This can also be done with other pyclasses:

use pyo3::prelude::*;

#[pyclass]
struct Bar {/* ... */}

#[pyclass]
struct Foo {
    inner: Py<Bar>,
}

#[pymethods]
impl Foo {
    #[new]
    fn __new__() -> PyResult<Foo> {
        Python::with_gil(|py| {
            let bar: Py<Bar> = Py::new(py, Bar {})?;
            Ok(Foo { inner: bar })
        })
    }
}

Example: Shared ownership of Python objects

Py<T> can be used to share ownership of a Python object, similar to std’s Rc<T>. As with Rc<T>, cloning it increases its reference count rather than duplicating the underlying object.

This can be done using either Py::clone_ref or Py<T>’s Clone trait implementation. Py::clone_ref will be faster if you happen to be already holding the GIL.

use pyo3::conversion::AsPyPointer;
use pyo3::prelude::*;
use pyo3::types::PyDict;

Python::with_gil(|py| {
    let first: Py<PyDict> = PyDict::new(py).into();

    // All of these are valid syntax
    let second = Py::clone_ref(&first, py);
    let third = first.clone_ref(py);
    let fourth = Py::clone(&first);
    let fifth = first.clone();

    // Disposing of our original `Py<PyDict>` just decrements the reference count.
    drop(first);

    // They all point to the same object
    assert_eq!(second.as_ptr(), third.as_ptr());
    assert_eq!(fourth.as_ptr(), fifth.as_ptr());
    assert_eq!(second.as_ptr(), fourth.as_ptr());
});

Preventing reference cycles

It is easy to accidentally create reference cycles using Py<T>. The Python interpreter can break these reference cycles within pyclasses if they implement the PyGCProtocol. If your pyclass contains other Python objects you should implement this protocol to avoid leaking memory.

A note on Python reference counts

Dropping a Py<T> will eventually decrease Python’s reference count of the pointed-to variable, allowing Python’s garbage collector to free the associated memory, but this may not happen immediately. This is because a Py<T> can be dropped at any time, but the Python reference count can only be modified when the GIL is held.

If a Py<T> is dropped while its thread happens to be holding the GIL then the Python reference count will be decreased immediately. Otherwise, the reference count will be decreased the next time the GIL is reacquired.

A note on Send and Sync

Accessing this object is threadsafe, since any access to its API requires a Python<'py> token. As you can only get this by acquiring the GIL, Py<...> “implements Send and Sync.

Implementations

Creates a new instance Py<T> of a #[pyclass] on the Python heap.

Examples
use pyo3::prelude::*;

#[pyclass]
struct Foo {/* fields omitted */}

Python::with_gil(|py| -> PyResult<Py<Foo>> {
    let foo: Py<Foo> = Py::new(py, Foo {})?;
    Ok(foo)
})?;

Borrows a GIL-bound reference to the contained T.

By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python<'py> for any of its methods, which makes calling methods on it more ergonomic.

For native types, this reference is &T. For pyclasses, this is &PyCell<T>.

Note that the lifetime of the returned reference is the shortest of &self and Python<'py>. Consider using Py::into_ref instead if this poses a problem.

Examples

Get access to &PyList from Py<PyList>:

Python::with_gil(|py| {
    let list: Py<PyList> = PyList::empty(py).into();
    let list: &PyList = list.as_ref(py);
    assert_eq!(list.len(), 0);
});

Get access to &PyCell<MyClass> from Py<MyClass>:

#[pyclass]
struct MyClass {}

Python::with_gil(|py| {
    let my_class: Py<MyClass> = Py::new(py, MyClass {}).unwrap();
    let my_class_cell: &PyCell<MyClass> = my_class.as_ref(py);
    assert!(my_class_cell.try_borrow().is_ok());
});

Borrows a GIL-bound reference to the contained T independently of the lifetime of T.

This method is similar to as_ref but consumes self and registers the Python object reference in PyO3’s object storage. The reference count for the Python object will not be decreased until the GIL lifetime ends.

You should prefer using as_ref if you can as it’ll have less overhead.

Examples

Py::as_ref’s lifetime limitation forbids creating a function that references a variable created inside the function.

fn new_py_any<'py>(py: Python<'py>, value: impl IntoPy<Py<PyAny>>) -> &'py PyAny {
    let obj: Py<PyAny> = value.into_py(py);

    // The lifetime of the return value of this function is the shortest
    // of `obj` and `py`. As `obj` is owned by the current function,
    // Rust won't let the return value escape this function!
    obj.as_ref(py)
}

This can be solved by using Py::into_ref instead, which does not suffer from this issue. Note that the lifetime of the Python<'py> token is transferred to the returned reference.

fn new_py_any<'py>(py: Python<'py>, value: impl IntoPy<Py<PyAny>>) -> &'py PyAny {
    let obj: Py<PyAny> = value.into_py(py);

    // This reference's lifetime is determined by `py`'s lifetime.
    // Because that originates from outside this function,
    // this return value is allowed.
    obj.into_ref(py)
}

Immutably borrows the value T.

This borrow lasts while the returned PyRef exists. Multiple immutable borrows can be taken out at the same time.

Equivalent to self.as_ref(py).borrow() - see PyCell::borrow.

Examples
#[pyclass]
struct Foo {
    inner: u8,
}

Python::with_gil(|py| -> PyResult<()> {
    let foo: Py<Foo> = Py::new(py, Foo { inner: 73 })?;
    let inner: &u8 = &foo.borrow(py).inner;

    assert_eq!(*inner, 73);
    Ok(())
})?;
Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use try_borrow.

Mutably borrows the value T.

This borrow lasts while the returned PyRefMut exists.

Equivalent to self.as_ref(py).borrow_mut() - see PyCell::borrow_mut.

Examples
#[pyclass]
struct Foo {
    inner: u8,
}

Python::with_gil(|py| -> PyResult<()> {
    let foo: Py<Foo> = Py::new(py, Foo { inner: 73 })?;
    foo.borrow_mut(py).inner = 35;

    assert_eq!(foo.borrow(py).inner, 35);
    Ok(())
})?;
Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use try_borrow_mut.

Attempts to immutably borrow the value T, returning an error if the value is currently mutably borrowed.

The borrow lasts while the returned PyRef exists.

This is the non-panicking variant of borrow.

Equivalent to self.as_ref(py).borrow_mut() - see PyCell::try_borrow.

Attempts to mutably borrow the value T, returning an error if the value is currently borrowed.

The borrow lasts while the returned PyRefMut exists.

This is the non-panicking variant of borrow_mut.

Equivalent to self.as_ref(py).try_borrow_mut() - see PyCell::try_borrow_mut.

Gets the reference count of the ffi::PyObject pointer.

Makes a clone of self.

This creates another pointer to the same object, increasing its reference count.

You should prefer using this method over Clone if you happen to be holding the GIL already.

Examples
use pyo3::conversion::AsPyPointer;
use pyo3::prelude::*;
use pyo3::types::PyDict;

Python::with_gil(|py| {
    let first: Py<PyDict> = PyDict::new(py).into();
    let second = Py::clone_ref(&first, py);

    // Both point to the same object
    assert_eq!(first.as_ptr(), second.as_ptr());
});

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

Returns whether the object is considered to be true.

This is equivalent to the Python expression bool(self).

Extracts some type from the Python object.

This is a wrapper function around FromPyObject::extract().

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

Calls the object.

This is equivalent to the Python expression self(*args, **kwargs).

Calls the object with only positional arguments.

This is equivalent to the Python expression self(*args).

Calls the object without arguments.

This is equivalent to the Python expression self().

Calls a method on the object.

This is equivalent to the Python expression self.name(*args, **kwargs).

Calls a method on the object with only positional arguments.

This is equivalent to the Python expression self.name(*args).

Calls a method on the object with no arguments.

This is equivalent to the Python expression self.name().

Create a Py<T> instance by taking ownership of the given FFI pointer.

Safety

ptr must be a pointer to a Python object of type T.

Callers must own the object referred to by ptr, as this function implicitly takes ownership of that object.

Panics

Panics if ptr is null.

Create a Py<T> instance by taking ownership of the given FFI pointer.

If ptr is null then the current Python exception is fetched as a PyErr.

Safety

If non-null, ptr must be a pointer to a Python object of type T.

Create a Py<T> instance by taking ownership of the given FFI pointer.

If ptr is null then None is returned.

Safety

If non-null, ptr must be a pointer to a Python object of type T.

Create a Py<T> instance by creating a new reference from the given FFI pointer.

Safety

ptr must be a pointer to a Python object of type T.

Panics

Panics if ptr is null.

Create a Py<T> instance by creating a new reference from the given FFI pointer.

If ptr is null then the current Python exception is fetched as a PyErr.

Safety

ptr must be a pointer to a Python object of type T.

Create a Py<T> instance by creating a new reference from the given FFI pointer.

If ptr is null then None is returned.

Safety

ptr must be a pointer to a Python object of type T.

Casts the PyObject to a concrete Python object type.

This can cast only to native Python types, not types implemented in Rust. For a more flexible alternative, see Py::extract.

Borrows a GIL-bound reference to the PyIterator. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

Similar to as_ref, and also consumes this Py and registers the Python object reference in PyO3’s object storage. The reference count for the Python object will not be decreased until the GIL lifetime ends.

Borrows a GIL-bound reference to the PyMapping. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

Similar to as_ref, and also consumes this Py and registers the Python object reference in PyO3’s object storage. The reference count for the Python object will not be decreased until the GIL lifetime ends.

Borrows a GIL-bound reference to the PySequence. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

let seq: Py<PySequence> = PyList::empty(py).as_sequence().into();
let seq: &PySequence = seq.as_ref(py);
assert_eq!(seq.len().unwrap(), 0);

Similar to as_ref, and also consumes this Py and registers the Python object reference in PyO3’s object storage. The reference count for the Python object will not be decreased until the GIL lifetime ends.

Trait Implementations

Gets the underlying FFI pointer, returns a borrowed pointer.

If the GIL is held this increments self’s reference count. Otherwise this registers the Py<T> instance to have its reference count incremented the next time PyO3 acquires the GIL.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Dropping a Py instance decrements the reference count on the object by 1.

Executes the destructor for this type. Read more

Py can be used as an error when T is an Error.

However for GIL lifetime reasons, cause() cannot be implemented for Py. Use .as_ref() to get the GIL-scoped error if you need to inspect the cause.

The lower-level source of this error, if any. Read more

🔬 This is a nightly-only experimental API. (backtrace)

Returns a stack backtrace, if available, of where this error occurred. Read more

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Extracts Self from the source PyObject.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Converts a Py instance to PyObject. Consumes self without calling Py_DECREF().

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Converts () to an empty Python tuple.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Gets the underlying FFI pointer, returns a owned pointer.

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Serialize this value into the given Serde serializer. Read more

Converts Py instance -> PyObject.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

Converts self into a Python object and calls the specified closure on the native FFI pointer underlying the Python object. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.