Struct PyRef

pub struct PyRef<'p, T>
where
    T: PyClass,
{ /* private fields */ }

Available on crate features dep_pyo3 and std only.

A wrapper type for an immutably borrowed value from a [Bound<'py, T>].

See the Bound documentation for more information.

Examples

You can use PyRef as an alternative to a &self receiver when

• you need to access the pointer of the Bound, or
• you want to get a super class.

#[pyclass(subclass)]
struct Parent {
    basename: &'static str,
}

#[pyclass(extends=Parent)]
struct Child {
    name: &'static str,
 }

#[pymethods]
impl Child {
    #[new]
    fn new() -> (Self, Parent) {
        (Child { name: "Caterpillar" }, Parent { basename: "Butterfly" })
    }

    fn format(slf: PyRef<'_, Self>) -> String {
        // We can get *mut ffi::PyObject from PyRef
        let refcnt = unsafe { pyo3::ffi::Py_REFCNT(slf.as_ptr()) };
        // We can get &Self::BaseType by as_ref
        let basename = slf.as_ref().basename;
        format!("{}(base: {}, cnt: {})", slf.name, basename, refcnt)
    }
}

See the module-level documentation for more information.

Implementations

impl<'p, T> PyRef<'p, T>

where T: PyClass,

pub fn py(&self) -> Python<'p>

Returns a Python token that is bound to the lifetime of the PyRef.

impl<'py, T> PyRef<'py, T>

where T: PyClass,

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

impl<'p, T, U> PyRef<'p, T>

where T: PyClass<BaseType = U>, U: PyClass,

pub fn into_super(self) -> PyRef<'p, U>

Gets a PyRef<T::BaseType>.

While as_ref() returns a reference of type &T::BaseType, this cannot be used to get the base of T::BaseType.

But with the help of this method, you can get hold of instances of the super-superclass when needed.

Examples

#[pyclass(subclass)]
struct Base1 {
    name1: &'static str,
}

#[pyclass(extends=Base1, subclass)]
struct Base2 {
    name2: &'static str,
}

#[pyclass(extends=Base2)]
struct Sub {
    name3: &'static str,
}

#[pymethods]
impl Sub {
    #[new]
    fn new() -> PyClassInitializer<Self> {
        PyClassInitializer::from(Base1 { name1: "base1" })
            .add_subclass(Base2 { name2: "base2" })
            .add_subclass(Self { name3: "sub" })
    }
    fn name(slf: PyRef<'_, Self>) -> String {
        let subname = slf.name3;
        let super_ = slf.into_super();
        format!("{} {} {}", super_.as_ref().name1, super_.name2, subname)
    }
}

pub fn as_super(&self) -> &PyRef<'p, U>

Borrows a shared reference to PyRef<T::BaseType>.

With the help of this method, you can access attributes and call methods on the superclass without consuming the PyRef<T>. This method can also be chained to access the super-superclass (and so on).

Examples

#[pyclass(subclass)]
struct Base {
    base_name: &'static str,
}
#[pymethods]
impl Base {
    fn base_name_len(&self) -> usize {
        self.base_name.len()
    }
}

#[pyclass(extends=Base)]
struct Sub {
    sub_name: &'static str,
}

#[pymethods]
impl Sub {
    #[new]
    fn new() -> (Self, Base) {
        (Self { sub_name: "sub_name" }, Base { base_name: "base_name" })
    }
    fn sub_name_len(&self) -> usize {
        self.sub_name.len()
    }
    fn format_name_lengths(slf: PyRef<'_, Self>) -> String {
        format!("{} {}", slf.as_super().base_name_len(), slf.sub_name_len())
    }
}

Trait Implementations

impl<T> AsPyPointer for PyRef<'_, T>

where T: PyClass,

fn as_ptr(&self) -> *mut PyObject

Returns the underlying FFI pointer as a borrowed pointer.

impl<T, U> AsRef<U> for PyRef<'_, T>

where T: PyClass<BaseType = U>, U: PyClass,

fn as_ref(&self) -> &<T as PyClassImpl>::BaseType

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

impl<T> Debug for PyRef<'_, T>

where T: PyClass + Debug,

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

Formats the value using the given formatter.

impl<T> Deref for PyRef<'_, T>

where T: PyClass,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> Drop for PyRef<'_, T>

where T: PyClass,

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T> From<PyRef<'a, T>> for Py<T>

where T: PyClass,

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

Converts to this type from the input type.

impl<'py, T> FromPyObject<'py> for PyRef<'py, T>

where T: PyClass,

fn extract_bound(obj: &Bound<'py, PyAny>) -> Result<PyRef<'py, T>, PyErr>

Extracts Self from the bound smart pointer obj.

impl<T> IntoPy<Py<PyAny>> for &PyRef<'_, T>

where T: PyClass,

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

👎Deprecated since 0.23.0: IntoPy is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Performs the conversion.

impl<T> IntoPy<Py<PyAny>> for PyRef<'_, T>

where T: PyClass,

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

👎Deprecated since 0.23.0: IntoPy is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Performs the conversion.

impl<'a, 'py, T> IntoPyObject<'py> for &'a PyRef<'py, T>

where T: PyClass,

type Target = T

The Python output type

type Output = Borrowed<'a, 'py, T>

The smart pointer type to use.

type Error = Infallible

The type returned in the event of a conversion error.

fn into_pyobject( self, _py: Python<'py>, ) -> Result<<&'a PyRef<'py, T> as IntoPyObject<'py>>::Output, <&'a PyRef<'py, T> as IntoPyObject<'py>>::Error>

Performs the conversion.

impl<'py, T> IntoPyObject<'py> for PyRef<'py, T>

where T: PyClass,

type Target = T

The Python output type

type Output = Bound<'py, T>

The smart pointer type to use.

type Error = Infallible

The type returned in the event of a conversion error.

fn into_pyobject( self, _py: Python<'py>, ) -> Result<<PyRef<'py, T> as IntoPyObject<'py>>::Output, <PyRef<'py, T> as IntoPyObject<'py>>::Error>

Performs the conversion.

impl<'a, 'py, T> TryFrom<BoundRef<'a, 'py, T>> for PyRef<'py, T>

where T: PyClass,

type Error = PyBorrowError

The type returned in the event of a conversion error.

fn try_from( value: BoundRef<'a, 'py, T>, ) -> Result<PyRef<'py, T>, <PyRef<'py, T> as TryFrom<BoundRef<'a, 'py, T>>>::Error>

Performs the conversion.