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::bindorPy::into_bound, to borrow a GIL-bound reference to the contained object.Py::borrow,Py::try_borrow,Py::borrow_mut, orPy::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
PywithPy::call_bound,Py::call_method_boundand 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.
Implementations§
Source§impl<T> Py<T>where
T: PyClass,
impl<T> Py<T>where
T: PyClass,
Sourcepub fn new(
py: Python<'_>,
value: impl Into<PyClassInitializer<T>>,
) -> PyResult<Py<T>>
pub fn new( py: Python<'_>, value: impl Into<PyClassInitializer<T>>, ) -> PyResult<Py<T>>
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::with_gil(|py| -> PyResult<_> {
let foo: Py<Foo> = Py::new(py, Foo {})?;
Ok(foo)
})?;Source§impl<T> Py<T>
impl<T> Py<T>
Sourcepub fn as_ptr(&self) -> *mut PyObject
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.
Source§impl<T> Py<T>where
T: PyClass,
impl<T> Py<T>where
T: PyClass,
Sourcepub fn borrow<'py>(&'py self, py: Python<'py>) -> PyRef<'py, T>
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::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.
Sourcepub fn borrow_mut<'py>(&'py self, py: Python<'py>) -> PyRefMut<'py, T>where
T: PyClass<Frozen = False>,
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::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 borrowed. For a non-panicking variant, use
try_borrow_mut.
Sourcepub fn try_borrow<'py>(
&'py self,
py: Python<'py>,
) -> Result<PyRef<'py, T>, PyBorrowError>
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.
Sourcepub fn try_borrow_mut<'py>(
&'py self,
py: Python<'py>,
) -> Result<PyRefMut<'py, T>, PyBorrowMutError>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>,
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.
Sourcepub fn get(&self) -> &T
pub fn get(&self) -> &T
Provide an immutable borrow of the value T without acquiring the GIL.
This is available if the class is frozen and Sync.
§Examples
use std::sync::atomic::{AtomicUsize, Ordering};
#[pyclass(frozen)]
struct FrozenCounter {
value: AtomicUsize,
}
let cell = Python::with_gil(|py| {
let counter = FrozenCounter { value: AtomicUsize::new(0) };
Py::new(py, counter).unwrap()
});
cell.get().value.fetch_add(1, Ordering::Relaxed);Source§impl<T> Py<T>
impl<T> Py<T>
Sourcepub fn bind<'py>(&self, _py: Python<'py>) -> &Bound<'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.
Sourcepub fn into_bound(self, py: Python<'_>) -> Bound<'_, T>
pub fn into_bound(self, py: Python<'_>) -> Bound<'_, T>
Same as bind but takes ownership of self.
Sourcepub fn bind_borrowed<'a, 'py>(&'a self, py: Python<'py>) -> Borrowed<'a, 'py, T>
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>.
Sourcepub fn is<U: AsPyPointer>(&self, o: &U) -> bool
pub fn is<U: AsPyPointer>(&self, o: &U) -> bool
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.
Sourcepub fn get_refcnt(&self, _py: Python<'_>) -> isize
pub fn get_refcnt(&self, _py: Python<'_>) -> isize
Gets the reference count of the ffi::PyObject pointer.
Sourcepub fn clone_ref(&self, _py: Python<'_>) -> Py<T>
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 if you happen to be holding the GIL already.
§Examples
use pyo3::prelude::*;
use pyo3::types::PyDict;
Python::with_gil(|py| {
let first: Py<PyDict> = PyDict::new_bound(py).unbind();
let second = Py::clone_ref(&first, py);
// Both point to the same object
assert!(first.is(&second));
});Sourcepub fn drop_ref(self, py: Python<'_>)
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 be holding the GIL
already.
Note that if you are using Bound, you do not need to use Self::drop_ref since
Bound guarantees that the GIL is held.
§Examples
use pyo3::prelude::*;
use pyo3::types::PyDict;
Python::with_gil(|py| {
let object: Py<PyDict> = PyDict::new_bound(py).unbind();
// some usage of object
object.drop_ref(py);
});Sourcepub fn is_none(&self, _py: Python<'_>) -> bool
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.
Sourcepub fn is_ellipsis(&self) -> bool
👎Deprecated since 0.20.0: use .is(py.Ellipsis()) instead
pub fn is_ellipsis(&self) -> bool
.is(py.Ellipsis()) insteadReturns whether the object is Ellipsis, e.g. ....
This is equivalent to the Python expression self is ....
Sourcepub fn is_true(&self, py: Python<'_>) -> PyResult<bool>
👎Deprecated since 0.21.0: use .is_truthy() instead
pub fn is_true(&self, py: Python<'_>) -> PyResult<bool>
.is_truthy() insteadReturns whether the object is considered to be true.
This is equivalent to the Python expression bool(self).
Sourcepub fn is_truthy(&self, py: Python<'_>) -> PyResult<bool>
pub fn is_truthy(&self, py: Python<'_>) -> PyResult<bool>
Returns whether the object is considered to be true.
This applies truth value testing equivalent to the Python expression bool(self).
Sourcepub fn extract<'a, 'py, D>(&'a self, py: Python<'py>) -> PyResult<D>where
D: FromPyObjectBound<'a, 'py>,
'py: 'a,
pub fn extract<'a, 'py, D>(&'a self, py: Python<'py>) -> PyResult<D>where
D: FromPyObjectBound<'a, 'py>,
'py: 'a,
Extracts some type from the Python object.
This is a wrapper function around FromPyObject::extract().
Sourcepub fn getattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<PyObject>
pub fn getattr<N>(&self, py: Python<'_>, attr_name: N) -> PyResult<PyObject>
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<PyObject> {
sys.getattr(py, intern!(py, "version"))
}Sourcepub fn setattr<N, V>(
&self,
py: Python<'_>,
attr_name: N,
value: V,
) -> PyResult<()>
pub fn setattr<N, V>( &self, py: Python<'_>, attr_name: N, value: V, ) -> PyResult<()>
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: PyObject, py: Python<'_>) -> PyResult<()> {
ob.setattr(py, intern!(py, "answer"), 42)
}Sourcepub fn call_bound(
&self,
py: Python<'_>,
args: impl IntoPy<Py<PyTuple>>,
kwargs: Option<&Bound<'_, PyDict>>,
) -> PyResult<PyObject>
pub fn call_bound( &self, py: Python<'_>, args: impl IntoPy<Py<PyTuple>>, kwargs: Option<&Bound<'_, PyDict>>, ) -> PyResult<PyObject>
Calls the object.
This is equivalent to the Python expression self(*args, **kwargs).
Sourcepub fn call1(
&self,
py: Python<'_>,
args: impl IntoPy<Py<PyTuple>>,
) -> PyResult<PyObject>
pub fn call1( &self, py: Python<'_>, args: impl IntoPy<Py<PyTuple>>, ) -> PyResult<PyObject>
Calls the object with only positional arguments.
This is equivalent to the Python expression self(*args).
Sourcepub fn call0(&self, py: Python<'_>) -> PyResult<PyObject>
pub fn call0(&self, py: Python<'_>) -> PyResult<PyObject>
Calls the object without arguments.
This is equivalent to the Python expression self().
Sourcepub fn call_method_bound<N, A>(
&self,
py: Python<'_>,
name: N,
args: A,
kwargs: Option<&Bound<'_, PyDict>>,
) -> PyResult<PyObject>
pub fn call_method_bound<N, A>( &self, py: Python<'_>, name: N, args: A, kwargs: Option<&Bound<'_, PyDict>>, ) -> PyResult<PyObject>
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.
Sourcepub fn call_method1<N, A>(
&self,
py: Python<'_>,
name: N,
args: A,
) -> PyResult<PyObject>
pub fn call_method1<N, A>( &self, py: Python<'_>, name: N, args: A, ) -> PyResult<PyObject>
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.
Sourcepub fn call_method0<N>(&self, py: Python<'_>, name: N) -> PyResult<PyObject>
pub fn call_method0<N>(&self, py: Python<'_>, name: N) -> PyResult<PyObject>
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.
Sourcepub unsafe fn from_owned_ptr_or_opt(
_py: Python<'_>,
ptr: *mut PyObject,
) -> Option<Self>
pub unsafe fn from_owned_ptr_or_opt( _py: Python<'_>, ptr: *mut PyObject, ) -> Option<Self>
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.
Sourcepub unsafe fn from_borrowed_ptr_or_err(
py: Python<'_>,
ptr: *mut PyObject,
) -> PyResult<Self>
pub unsafe fn from_borrowed_ptr_or_err( py: Python<'_>, ptr: *mut PyObject, ) -> PyResult<Self>
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.
Source§impl Py<PyAny>
impl Py<PyAny>
Sourcepub fn downcast_bound<'py, T>(
&self,
py: Python<'py>,
) -> Result<&Bound<'py, T>, DowncastError<'_, 'py>>where
T: PyTypeCheck,
pub fn downcast_bound<'py, T>(
&self,
py: Python<'py>,
) -> Result<&Bound<'py, T>, DowncastError<'_, 'py>>where
T: PyTypeCheck,
Downcast this PyObject to a concrete Python type or pyclass.
Note that you can often avoid downcasting yourself by just specifying the desired type in function or method signatures. However, manual downcasting 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::with_gil(|py| {
let any: PyObject = PyDict::new_bound(py).into();
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 PyObject that
might actually be a pyclass.
use pyo3::prelude::*;
#[pyclass]
struct Class {
i: i32,
}
Python::with_gil(|py| {
let class: PyObject = Py::new(py, Class { i: 0 }).unwrap().into_py(py);
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(())
})Sourcepub unsafe fn downcast_bound_unchecked<'py, T>(
&self,
py: Python<'py>,
) -> &Bound<'py, T>
pub unsafe fn downcast_bound_unchecked<'py, T>( &self, py: Python<'py>, ) -> &Bound<'py, T>
Casts the PyObject to a concrete Python object type without checking validity.
§Safety
Callers must ensure that the type is valid or risk type confusion.
Source§impl Py<PyString>
impl Py<PyString>
Sourcepub fn to_str<'a>(&'a self, py: Python<'_>) -> PyResult<&'a str>
pub fn to_str<'a>(&'a self, py: Python<'_>) -> PyResult<&'a str>
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.
Sourcepub fn to_cow<'a>(&'a self, py: Python<'_>) -> PyResult<Cow<'a, str>>
pub fn to_cow<'a>(&'a self, py: Python<'_>) -> PyResult<Cow<'a, str>>
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.
Sourcepub fn to_string_lossy<'a>(&'a self, py: Python<'_>) -> Cow<'a, str>
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§
Source§impl<T> AsPyPointer for Py<T>
impl<T> AsPyPointer for Py<T>
Source§impl<T> Display for Py<T>where
T: PyTypeInfo,
impl<T> Display for Py<T>where
T: PyTypeInfo,
Source§impl<T> Drop for Py<T>
Dropping a Py instance decrements the reference count
on the object by one if the GIL is held.
impl<T> Drop for Py<T>
Dropping a Py instance decrements the reference count
on the object by one if the GIL is held.
Otherwise and by default, this registers the underlying pointer to have its reference count decremented the next time PyO3 acquires the GIL.
However, if the pyo3_disable_reference_pool conditional compilation flag
is enabled, it will abort the process.