Struct pyo3::Py [−][src]
#[repr(transparent)]pub struct Py<T>(_, _);
Expand description
A Python object of known type T.
Accessing this object is thread-safe, since any access to its API requires a Python<'py>
GIL
token. There are a few different ways to use the Python object contained:
Py::as_ref
to borrow a GIL-bound reference to the contained object.Py::borrow
,Py::try_borrow
,Py::borrow_mut
, orPy::try_borrow_mut
, to directly access a#[pyclass]
value (which has RefCell-like behavior, see thePyCell
guide entry ).- Use methods directly on
Py
, such asPy::call
andPy::call_method
.
See the guide for an explanation of the different Python object types.
Implementations
pub fn new(
py: Python<'_>,
value: impl Into<PyClassInitializer<T>>
) -> PyResult<Py<T>> where
T::BaseLayout: PyBorrowFlagLayout<T::BaseType>,
pub fn new(
py: Python<'_>,
value: impl Into<PyClassInitializer<T>>
) -> PyResult<Py<T>> where
T::BaseLayout: PyBorrowFlagLayout<T::BaseType>,
Create a new instance Py<T>
of a #[pyclass]
on the Python heap.
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
for any of its methods.
For native types, this reference is &T
. For pyclasses, this is &PyCell<T>
.
Examples
Get access to &PyList
from Py<PyList>
:
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 { }
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());
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.
Example
Useful when returning GIL-bound references from functions. In the snippet below, note that
the 'py
lifetime of the input GIL lifetime is also given to the returned reference:
fn new_py_any<'py>(py: Python<'py>, value: impl IntoPy<PyObject>) -> &'py PyAny {
let obj: PyObject = value.into_py(py);
// .as_ref(py) would not be suitable here, because a reference to `obj` may not be
// returned from the function.
obj.into_ref(py)
}
Immutably borrows the value T
. This borrow lasts untill the returned PyRef
exists.
Equivalent to self.as_ref(py).borrow()
-
see PyCell::borrow
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 untill the returned PyRefMut
exists.
Equivalent to self.as_ref(py).borrow_mut()
-
see PyCell::borrow_mut
Panics
Panics if the value is currently mutably borrowed. For a non-panicking variant, use
try_borrow_mut
.
Immutably borrows the value T
, returning an error if the value is currently
mutably borrowed. This borrow lasts untill the returned PyRef
exists.
This is the non-panicking variant of borrow
.
Equivalent to self.as_ref(py).try_borrow()
-
see PyCell::try_borrow
pub fn try_borrow_mut<'py>(
&'py self,
py: Python<'py>
) -> Result<PyRefMut<'py, T>, PyBorrowMutError>
pub fn try_borrow_mut<'py>(
&'py self,
py: Python<'py>
) -> Result<PyRefMut<'py, T>, PyBorrowMutError>
Mutably borrows the value T
, returning an error if the value is currently borrowed.
This borrow lasts untill 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`](../pycell/struct.PyCell.html#method.try_borrow_mut)
Gets the reference count of the ffi::PyObject
pointer.
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()
.
👎 Deprecated: this is a deprecated alias for Py::from_owned_ptr
this is a deprecated alias for Py::from_owned_ptr
Deprecated alias for from_owned_ptr
.
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.
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.
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.
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
.
Trait Implementations
Dropping a Py
instance decrements the reference count on the object by 1.
Py
However for GIL lifetime reasons, cause() cannot be implemented for Py
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.
impl<'a, T> FromPyObject<'a> for Py<T> where
T: PyTypeInfo,
&'a T::AsRefTarget: FromPyObject<'a>,
T::AsRefTarget: 'a + AsPyPointer,
impl<'a, T> FromPyObject<'a> for Py<T> where
T: PyTypeInfo,
&'a T::AsRefTarget: FromPyObject<'a>,
T::AsRefTarget: 'a + AsPyPointer,
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.
Auto Trait Implementations
impl<T> RefUnwindSafe for Py<T> where
T: RefUnwindSafe,
impl<T> UnwindSafe for Py<T> where
T: UnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more