Struct Py

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

Available on crate feature tls only.

Expand description

A reference to an object allocated on the Python heap.

To access the contained data use the following methods:

Py::bind or Py::into_bound, to bind the reference to the lifetime of the Python<'py> token.
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, Py::call_method 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 proves the thread is attached to the Python interpreter 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::attach(|py| {
            // `py` will only last for this scope.

            // `Bound<'py, PyDict>` inherits the Python token lifetime from `py`
            // and so won't be able to outlive this closure.
            let dict: Bound<'_, 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 removing the lifetime from dict and with it the proof of attachment.

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

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

#[pymethods]
impl Foo {
    #[new]
    fn __new__() -> Foo {
        Python::attach(|py| {
            let dict: Py<PyDict> = PyDict::new(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::attach(|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 is recommended; the Clone implementation will panic if the thread is not attached to the Python interpreter (and is gated behind the py-clone feature flag).

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

Python::attach(|py| {
    let first: Py<PyDict> = PyDict::new(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 thread is attached to the Python interpreter.

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

If you have a Python<'py> token, 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`

Py<T> implements Send and Sync, as Python allows objects to be freely shared between threads.

Implementations§

§

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

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

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

§Examples

use pyo3::prelude::*;

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

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

§

impl<T> Py<T>

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

Returns the raw FFI pointer represented by self.

§Safety

Callers are responsible for ensuring that the pointer does not outlive self.

The reference is borrowed; callers should not decrease the reference count when they are finished with the pointer.

pub fn into_ptr(self) -> *mut PyObject

Returns an owned raw FFI pointer represented by self.

§Safety

The reference is owned; when finished the caller should either transfer ownership of the pointer or decrease the reference count (e.g. with pyo3::ffi::Py_DecRef).

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

Helper to cast to Py<PyAny>.

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

Helper to cast to Py<PyAny>, transferring ownership.

§

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

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

Immutably borrows the value T.

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

For frozen classes, the simpler get is available.

Equivalent to self.bind(py).borrow() - see Bound::borrow.

§Examples

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

Python::attach(|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.

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

Mutably borrows the value T.

This borrow lasts while the returned PyRefMut exists.

Equivalent to self.bind(py).borrow_mut() - see Bound::borrow_mut.

§Examples

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

Python::attach(|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 borrowed. For a non-panicking variant, use try_borrow_mut.

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

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.

For frozen classes, the simpler get is available.

Equivalent to self.bind(py).try_borrow() - see Bound::try_borrow.

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

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.bind(py).try_borrow_mut() - see Bound::try_borrow_mut.

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

Provide an immutable borrow of the value T.

This is available if the class is frozen and Sync, and does not require attaching to the Python interpreter.

§Examples

use std::sync::atomic::{AtomicUsize, Ordering};

#[pyclass(frozen)]
struct FrozenCounter {
    value: AtomicUsize,
}

let cell  = Python::attach(|py| {
    let counter = FrozenCounter { value: AtomicUsize::new(0) };

    Py::new(py, counter).unwrap()
});

cell.get().value.fetch_add(1, Ordering::Relaxed);

§

impl<T> Py<T>

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

Attaches this Py to the given Python context, allowing access to further Python APIs.

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

Same as bind but takes ownership of self.

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

Same as bind but produces a Borrowed<T> instead of a Bound<T>.

pub fn is(&self, o: U) -> bool
where U: AsRef<Py<PyAny>>,

Returns whether self and other point to the same object. To compare the equality of two objects (the == operator), use eq.

This is equivalent to the Python expression self is other.

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

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

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

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.

§Examples

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

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

    // Both point to the same object
    assert!(first.is(&second));
});

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

Drops self and immediately decreases its reference count.

This method is a micro-optimisation over Drop if you happen to have a Python<'py> token to prove attachment to the Python interpreter.

Note that if you are using Bound, you do not need to use Self::drop_ref since Bound guarantees that the thread is attached to the interpreter.

§Examples

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

Python::attach(|py| {
    let object: Py<PyDict> = PyDict::new(py).unbind();

    // some usage of object

    object.drop_ref(py);
});

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

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

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

Returns whether the object is considered to be true.

This applies truth value testing equivalent to the Python expression bool(self).

pub fn extract<'a, 'py, D>( &'a self, py: Python<'py>, ) -> Result<D, <D as FromPyObject<'a, 'py>>::Error>
where D: FromPyObject<'a, 'py>,

Extracts some type from the Python object.

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

pub fn getattr<'py, N>( &self, py: Python<'py>, attr_name: N, ) -> Result<Py<PyAny>, PyErr>
where N: IntoPyObject<'py, Target = PyString>,

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

If calling this method becomes performance-critical, the intern! macro can be used to intern attr_name, thereby avoiding repeated temporary allocations of Python strings.

§Example: `intern!`ing the attribute name

#[pyfunction]
fn version(sys: Py<PyModule>, py: Python<'_>) -> PyResult<Py<PyAny>> {
    sys.getattr(py, intern!(py, "version"))
}

pub fn setattr<'py, N, V>( &self, py: Python<'py>, attr_name: N, value: V, ) -> Result<(), PyErr>
where N: IntoPyObject<'py, Target = PyString>, V: IntoPyObject<'py>,

Sets an attribute value.

This is equivalent to the Python expression self.attr_name = value.

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern attr_name.

§Example: `intern!`ing the attribute name

#[pyfunction]
fn set_answer(ob: Py<PyAny>, py: Python<'_>) -> PyResult<()> {
    ob.setattr(py, intern!(py, "answer"), 42)
}

pub fn call<'py, A>( &self, py: Python<'py>, args: A, kwargs: Option<&Bound<'py, PyDict>>, ) -> Result<Py<PyAny>, PyErr>
where A: PyCallArgs<'py>,

Calls the object.

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

pub fn call1<'py, A>( &self, py: Python<'py>, args: A, ) -> Result<Py<PyAny>, PyErr>
where A: PyCallArgs<'py>,

Calls the object with only positional arguments.

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

pub fn call0(&self, py: Python<'_>) -> Result<Py<PyAny>, PyErr>

Calls the object without arguments.

This is equivalent to the Python expression self().

pub fn call_method<'py, N, A>( &self, py: Python<'py>, name: N, args: A, kwargs: Option<&Bound<'py, PyDict>>, ) -> Result<Py<PyAny>, PyErr>
where N: IntoPyObject<'py, Target = PyString>, A: PyCallArgs<'py>,

Calls a method on the object.

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

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn call_method1<'py, N, A>( &self, py: Python<'py>, name: N, args: A, ) -> Result<Py<PyAny>, PyErr>
where N: IntoPyObject<'py, Target = PyString>, A: PyCallArgs<'py>,

Calls a method on the object with only positional arguments.

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

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn call_method0<'py, N>( &self, py: Python<'py>, name: N, ) -> Result<Py<PyAny>, PyErr>
where N: IntoPyObject<'py, Target = PyString>,

Calls a method on the object with no arguments.

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

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

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

👎Deprecated since 0.28.0:

use Bound::from_owned_ptr instead

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

§Safety

ptr must be a valid pointer to a Python object (or null, which will cause a panic)
ptr must be an owned Python reference, as the Py<T> will assume ownership

§Panics

Panics if ptr is null.

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

👎Deprecated since 0.28.0:

use Bound::from_owned_ptr_or_err instead

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

ptr must be a valid pointer to a Python object, or null
a non-null ptr must be an owned Python reference, as the Py<T> will assume ownership

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

👎Deprecated since 0.28.0:

use Bound::from_owned_ptr_or_opt instead

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

If ptr is null then None is returned.

§Safety

ptr must be a valid pointer to a Python object, or null
a non-null ptr must be an owned Python reference, as the Py<T> will assume ownership

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

👎Deprecated since 0.28.0:

use Borrowed::from_borrowed_ptr instead

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.

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

👎Deprecated since 0.28.0:

use Borrowed::from_borrowed_ptr_or_err instead

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.

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

👎Deprecated since 0.28.0:

use Borrowed::from_borrowed_ptr_or_opt instead

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, or null.

§

impl Py<PyAny>

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

👎Deprecated since 0.27.0:

use Py::cast_bound instead

Downcast this Py<PyAny> to a concrete Python type or pyclass.

Note that you can often avoid casting yourself by just specifying the desired type in function or method signatures. However, manual casting is sometimes necessary.

For extracting a Rust-only type, see Py::extract.

§Example: Downcasting to a specific Python object

use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::attach(|py| {
    let any = PyDict::new(py).into_any().unbind();

    assert!(any.downcast_bound::<PyDict>(py).is_ok());
    assert!(any.downcast_bound::<PyList>(py).is_err());
});

§Example: Getting a reference to a pyclass

This is useful if you want to mutate a Py<PyAny> that might actually be a pyclass.

use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.downcast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})

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

👎Deprecated since 0.27.0:

use Py::cast_bound_unchecked instead

Casts the Py<PyAny> to a concrete Python object type without checking validity.

§Safety

Callers must ensure that the type is valid or risk type confusion.

§

impl<T> Py<T>

pub fn cast_bound<'py, U>( &self, py: Python<'py>, ) -> Result<&Bound<'py, U>, CastError<'_, 'py>>
where U: PyTypeCheck,

Cast this Py<T> to a concrete Python type or pyclass.

Note that you can often avoid casting yourself by just specifying the desired type in function or method signatures. However, manual casting is sometimes necessary.

For extracting a Rust-only type, see Py::extract.

§Example: Casting to a specific Python object

use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::attach(|py| {
    let any = PyDict::new(py).into_any().unbind();

    assert!(any.cast_bound::<PyDict>(py).is_ok());
    assert!(any.cast_bound::<PyList>(py).is_err());
});

§Example: Getting a reference to a pyclass

This is useful if you want to mutate a Py<PyAny> that might actually be a pyclass.

use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.cast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})

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

Casts the Py<T> to a concrete Python object type without checking validity.

§Safety

Callers must ensure that the type is valid or risk type confusion.

§

impl Py<PyBytes>

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

Gets the Python bytes as a byte slice. Because Python bytes are immutable, the result may be used for as long as the reference to self is held, including when the GIL is released.

§

impl Py<PyString>

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

Available on Py_3_10 or non-Py_LIMITED_API only.

Gets the Python string as a Rust UTF-8 string slice.

Returns a UnicodeEncodeError if the input is not valid unicode (containing unpaired surrogates).

Because str objects are immutable, the returned slice is independent of the GIL lifetime.

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

Converts the PyString into a Rust string, avoiding copying when possible.

Returns a UnicodeEncodeError if the input is not valid unicode (containing unpaired surrogates).

Because str objects are immutable, the returned slice is independent of the GIL lifetime.

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

Converts the PyString into a Rust string.

Unpaired surrogates invalid UTF-8 sequences are replaced with U+FFFD REPLACEMENT CHARACTER.

Because str objects are immutable, the returned slice is independent of the GIL lifetime.

Trait Implementations§

§

impl<T> AsRef<Py<PyAny>> for Borrowed<'_, '_, T>

§

fn as_ref(&self) -> &Py<PyAny>

Converts this type into a shared reference of the (usually inferred) input type.

§

impl<T> AsRef<Py<PyAny>> for Bound<'_, T>

§

fn as_ref(&self) -> &Py<PyAny>

Converts this type into a shared reference of the (usually inferred) input type.

§

impl<T> AsRef<Py<PyAny>> for Py<T>

§

fn as_ref(&self) -> &Py<PyAny>

Converts this type into a shared reference of the (usually inferred) input type.

§

impl<T> Debug for Py<T>

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

§

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

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

§

impl<T> Drop for Py<T>

Dropping a Py instance decrements the reference count on the object by one if the thread is attached to the Python interpreter.

Otherwise and by default, this registers the underlying pointer to have its reference count decremented the next time PyO3 attaches to the Python interpreter.

However, if the pyo3_disable_reference_pool conditional compilation flag is enabled, it will abort the process.

§

fn drop(&mut self)

Executes the destructor for this type. Read more

§