Struct pyo3::Py

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

A Python object of known type.

Accessing this object is thread-safe, since any access to its API requires a Python<'py> GIL token.

See the guide for an explanation of the different Python object types.

Technically, it is a safe wrapper around NonNull<ffi::PyObject> with specified type information.

Implementations

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

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.

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

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.

pub fn borrow_mut<'py>(&'py self, py: Python<'py>) -> PyRefMut<'py, T>

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.

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

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>

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)

impl<T> Py<T>

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

Creates a Py<T> instance for the given FFI pointer.

This moves ownership over the pointer into the Py<T>. Undefined behavior if the pointer is NULL or invalid.

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

Creates a Py<T> instance for the given FFI pointer.

Panics if the pointer is NULL. Undefined behavior if the pointer is invalid.

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

Construct Py<T> from the result of a Python FFI call that

Returns a new reference (owned pointer). Returns Err(PyErr) if the pointer is NULL. Unsafe because the pointer might be invalid.

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

Creates a Py<T> instance for the given Python FFI pointer.

Calls Py_INCREF() on the ptr. Undefined behavior if the pointer is NULL or invalid.

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>

Clones self by calling Py_INCREF() on the ptr.

Trait Implementations

impl<T> AsPyPointer for Py<T>

fn as_ptr(&self) -> *mut PyObject

Gets the underlying FFI pointer, returns a borrowed pointer.

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

type Target = T::AsRefTarget

fn as_ref<'p>(&'p self, _py: Python<'p>) -> &'p Self::Target

Return reference to object.

impl<T> Clone for Py<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Py<T>

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

Formats the value using the given formatter.

impl<T> Drop for Py<T>

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

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T, '_> From<&'_ PyCell<T>> for Py<T> where
    T: PyClass, 

fn from(cell: &PyCell<T>) -> Self

Performs the conversion.

impl<'a, T> From<&'a T> for Py<T> where
    T: AsPyPointer + PyNativeType, 

fn from(obj: &'a T) -> Self

Performs the conversion.

impl<T> From<Py<T>> for PyObject

fn from(ob: Py<T>) -> Self

Performs the conversion.

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

fn from(pyref: PyRef<'a, T>) -> Self

Performs the conversion.

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

fn from(pyref: PyRefMut<'a, T>) -> Self

Performs the conversion.

impl<'a> FromPy<&'a PyTuple> for Py<PyTuple>

fn from_py(tuple: &'a PyTuple, _py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl FromPy<()> for Py<PyTuple>

Converts () to an empty Python tuple.

fn from_py(_: (), py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<'a, T> FromPyObject<'a> for Py<T> where
    T: PyTypeInfo,
    &'a T::AsRefTarget: FromPyObject<'a>,
    T::AsRefTarget: 'a + AsPyPointer, 

fn extract(ob: &'a PyAny) -> PyResult<Self>

Extracts Self from the source PyObject.

impl<A: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A,)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>, D: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C, D)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>, D: IntoPy<PyObject>, E: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C, D, E)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>, D: IntoPy<PyObject>, E: IntoPy<PyObject>, F: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C, D, E, F)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>, D: IntoPy<PyObject>, E: IntoPy<PyObject>, F: IntoPy<PyObject>, G: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C, D, E, F, G)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>, D: IntoPy<PyObject>, E: IntoPy<PyObject>, F: IntoPy<PyObject>, G: IntoPy<PyObject>, H: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C, D, E, F, G, H)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<A: IntoPy<PyObject>, B: IntoPy<PyObject>, C: IntoPy<PyObject>, D: IntoPy<PyObject>, E: IntoPy<PyObject>, F: IntoPy<PyObject>, G: IntoPy<PyObject>, H: IntoPy<PyObject>, I: IntoPy<PyObject>> IntoPy<Py<PyTuple>> for (A, B, C, D, E, F, G, H, I)

fn into_py(self, py: Python<'_>) -> Py<PyTuple>

Performs the conversion.

impl<T> IntoPy<PyObject> for Py<T>

fn into_py(self, _py: Python<'_>) -> PyObject

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

impl<T> IntoPyPointer for Py<T>

#[must_use]fn into_ptr(self) -> *mut PyObject

Gets the underlying FFI pointer, returns a owned pointer.

impl<T> PartialEq<Py<T>> for Py<T>

fn eq(&self, o: &Py<T>) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> Send for Py<T>

impl<T> Sync for Py<T>

impl<T> ToPyObject for Py<T>

fn to_object(&self, py: Python<'_>) -> PyObject

Converts Py instance -> PyObject.