Struct pyo3::Py

source ·

pub struct Py<T>(/* private fields */);

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:

Py::bind or Py::into_bound, to borrow a GIL-bound reference to the contained object.
Py::borrow, Py::try_borrow, Py::borrow_mut, or Py::try_borrow_mut,

to get a (mutable) reference to a contained pyclass, using a scheme similar to std’s RefCell. See the guide entry for more information.

You can call methods directly on Py with Py::call_bound, Py::call_method_bound and friends.

These require passing in the Python<'py> token but are otherwise similar to the corresponding methods on PyAny.

§Example: Storing Python objects in `#[pyclass]` structs

Usually Bound<'py, T> is recommended for interacting with Python objects as its lifetime 'py is an association to the GIL and that enables many operations to be done as efficiently as possible.

However, #[pyclass] structs cannot carry a lifetime, so Py<T> is the only way to store a Python object in a #[pyclass] struct.

For example, this won’t compile:

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

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

            // `Bound<'py, PyDict>` inherits the GIL lifetime from `py` and
            // so won't be able to outlive this closure.
            let dict: Bound<'_, PyDict> = PyDict::new_bound(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_bound(py).unbind();
            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::prelude::*;
use pyo3::types::PyDict;

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

    // All of these are valid syntax
    let second = Py::clone_ref(&first, py);
    let third = first.clone_ref(py);
    #[cfg(feature = "py-clone")]
    let fourth = Py::clone(&first);
    #[cfg(feature = "py-clone")]
    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!(second.is(&third));
    #[cfg(feature = "py-clone")]
    assert!(fourth.is(&fifth));
    #[cfg(feature = "py-clone")]
    assert!(second.is(&fourth));
});

§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 integrate with the garbage collector. If your pyclass contains other Python objects you should implement it 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.

If you happen to be already holding the GIL, Py::drop_ref will decrease the Python reference count immediately and will execute slightly faster than relying on implicit Drops.

§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.

Struct pyo3::PyCopy item path

§Example: Storing Python objects in #[pyclass] structs

§Example: Shared ownership of Python objects

§Preventing reference cycles

§A note on Python reference counts

§A note on Send and Sync

Implementations§

impl<T> Py<T>where T: PyClass,

pub fn new( py: Python<'_>, value: impl Into<PyClassInitializer<T>>, ) -> PyResult<Py<T>>

§Examples

impl<T> Py<T>

pub fn as_ptr(&self) -> *mut PyObject

§Safety

pub fn into_ptr(self) -> *mut PyObject

§Safety

pub fn as_any(&self) -> &Py<PyAny>

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

impl<T> Py<T>where T: PyClass,

pub fn borrow<'py>(&'py self, py: Python<'py>) -> PyRef<'py, T>

§Examples

§Panics

pub fn borrow_mut<'py>(&'py self, py: Python<'py>) -> PyRefMut<'py, T>where T: PyClass<Frozen = False>,

§Examples

§Panics

pub fn try_borrow<'py>( &'py self, py: Python<'py>, ) -> Result<PyRef<'py, T>, PyBorrowError>

pub fn try_borrow_mut<'py>( &'py self, py: Python<'py>, ) -> Result<PyRefMut<'py, T>, PyBorrowMutError>where T: PyClass<Frozen = False>,

pub fn get(&self) -> &Twhere T: PyClass<Frozen = True> + Sync,

§Examples

impl<T> Py<T>

pub fn bind<'py>(&self, _py: Python<'py>) -> &Bound<'py, T>

pub fn into_bound(self, py: Python<'_>) -> Bound<'_, T>

pub fn bind_borrowed<'a, 'py>(&'a self, py: Python<'py>) -> Borrowed<'a, 'py, T>

pub fn is<U: AsPyPointer>(&self, o: &U) -> bool

pub fn get_refcnt(&self, _py: Python<'_>) -> isize

pub fn clone_ref(&self, _py: Python<'_>) -> Py<T>

§Examples

pub fn drop_ref(self, py: Python<'_>)

§Examples

pub fn is_none(&self, _py: Python<'_>) -> bool

pub fn is_truthy(&self, py: Python<'_>) -> PyResult<bool>

pub fn extract<'a, 'py, D>(&'a self, py: Python<'py>) -> PyResult<D>where D: FromPyObjectBound<'a, 'py>, 'py: 'a,

pub fn getattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<PyObject>where N: IntoPy<Py<PyString>>,

§Example: intern!ing the attribute name

pub fn setattr<N, V>( &self, py: Python<'_>, attr_name: N, value: V, ) -> PyResult<()>where N: IntoPy<Py<PyString>>, V: IntoPy<Py<PyAny>>,

§Example: intern!ing the attribute name

pub fn call_bound( &self, py: Python<'_>, args: impl IntoPy<Py<PyTuple>>, kwargs: Option<&Bound<'_, PyDict>>, ) -> PyResult<PyObject>

pub fn call1( &self, py: Python<'_>, args: impl IntoPy<Py<PyTuple>>, ) -> PyResult<PyObject>

pub fn call0(&self, py: Python<'_>) -> PyResult<PyObject>

pub fn call_method_bound<N, A>( &self, py: Python<'_>, name: N, args: A, kwargs: Option<&Bound<'_, PyDict>>, ) -> PyResult<PyObject>where N: IntoPy<Py<PyString>>, A: IntoPy<Py<PyTuple>>,

pub fn call_method1<N, A>( &self, py: Python<'_>, name: N, args: A, ) -> PyResult<PyObject>where N: IntoPy<Py<PyString>>, A: IntoPy<Py<PyTuple>>,

pub fn call_method0<N>(&self, py: Python<'_>, name: N) -> PyResult<PyObject>where N: IntoPy<Py<PyString>>,

pub unsafe fn from_owned_ptr(py: Python<'_>, ptr: *mut PyObject) -> Py<T>

§Safety

§Panics

pub unsafe fn from_owned_ptr_or_err( py: Python<'_>, ptr: *mut PyObject, ) -> PyResult<Py<T>>

§Safety

pub unsafe fn from_owned_ptr_or_opt( _py: Python<'_>, ptr: *mut PyObject, ) -> Option<Self>

§Safety

pub unsafe fn from_borrowed_ptr(py: Python<'_>, ptr: *mut PyObject) -> Py<T>

§Safety

§Panics

pub unsafe fn from_borrowed_ptr_or_err( py: Python<'_>, ptr: *mut PyObject, ) -> PyResult<Self>

§Safety

pub unsafe fn from_borrowed_ptr_or_opt( _py: Python<'_>, ptr: *mut PyObject, ) -> Option<Self>

§Safety

impl Py<PyAny>

pub fn downcast_bound<'py, T>( &self, py: Python<'py>, ) -> Result<&Bound<'py, T>, DowncastError<'_, 'py>>where T: PyTypeCheck,

§Example: Downcasting to a specific Python object

§Example: Getting a reference to a pyclass

pub unsafe fn downcast_bound_unchecked<'py, T>( &self, py: Python<'py>, ) -> &Bound<'py, T>

§Safety

impl Py<PyBytes>

pub fn as_bytes<'a>(&'a self, py: Python<'_>) -> &'a [u8] ⓘ

impl Py<PyString>

pub fn to_str<'a>(&'a self, py: Python<'_>) -> PyResult<&'a str>

pub fn to_cow<'a>(&'a self, py: Python<'_>) -> PyResult<Cow<'a, str>>

pub fn to_string_lossy<'a>(&'a self, py: Python<'_>) -> Cow<'a, str>

Trait Implementations§

impl<T> AsPyPointer for Py<T>

fn as_ptr(&self) -> *mut PyObject

Struct pyo3::Py

§Example: Storing Python objects in `#[pyclass]` structs

§A note on `Send` and `Sync`

impl<T> Py<T>
where T: PyClass,

impl<T> Py<T>
where T: PyClass,

pub fn borrow_mut<'py>(&'py self, py: Python<'py>) -> PyRefMut<'py, T>
where T: PyClass<Frozen = False>,

pub fn try_borrow_mut<'py>( &'py self, py: Python<'py>, ) -> Result<PyRefMut<'py, T>, PyBorrowMutError>
where T: PyClass<Frozen = False>,

pub fn get(&self) -> &T
where T: PyClass<Frozen = True> + Sync,

pub fn extract<'a, 'py, D>(&'a self, py: Python<'py>) -> PyResult<D>
where D: FromPyObjectBound<'a, 'py>, 'py: 'a,

pub fn getattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<PyObject>
where N: IntoPy<Py<PyString>>,

§Example: `intern!`ing the attribute name

pub fn setattr<N, V>( &self, py: Python<'_>, attr_name: N, value: V, ) -> PyResult<()>
where N: IntoPy<Py<PyString>>, V: IntoPy<Py<PyAny>>,

§Example: `intern!`ing the attribute name

pub fn call_method_bound<N, A>( &self, py: Python<'_>, name: N, args: A, kwargs: Option<&Bound<'_, PyDict>>, ) -> PyResult<PyObject>
where N: IntoPy<Py<PyString>>, A: IntoPy<Py<PyTuple>>,

pub fn call_method1<N, A>( &self, py: Python<'_>, name: N, args: A, ) -> PyResult<PyObject>
where N: IntoPy<Py<PyString>>, A: IntoPy<Py<PyTuple>>,

pub fn call_method0<N>(&self, py: Python<'_>, name: N) -> PyResult<PyObject>
where N: IntoPy<Py<PyString>>,

pub fn downcast_bound<'py, T>( &self, py: Python<'py>, ) -> Result<&Bound<'py, T>, DowncastError<'_, 'py>>
where T: PyTypeCheck,

impl<'de, T> Deserialize<'de> for Py<T>
where T: PyClass<BaseType = PyAny> + Deserialize<'de>,

fn deserialize<D>(deserializer: D) -> Result<Py<T>, D::Error>
where D: Deserializer<'de>,

impl<T> Display for Py<T>
where T: PyTypeInfo,

impl<T> From<Py<T>> for PyObject
where T: AsRef<PyAny>,

impl<'a, T> From<PyRef<'a, T>> for Py<T>
where T: PyClass,

impl<'a, T> From<PyRefMut<'a, T>> for Py<T>
where T: PyClass<Frozen = False>,

impl<T> FromPyObject<'_> for Py<T>
where T: PyTypeCheck,

impl<T> IntoPy<Py<PyAny>> for &T
where T: AsRef<PyAny>,