Struct BoundRef

pub struct BoundRef<'a, 'py, T>(pub &'a Bound<'py, T>);

Used in #[classmethod] to pass the class object to the method and also in #[pyfunction(pass_module)].

This is a wrapper to avoid implementing From<Bound> for GIL Refs.

Once the GIL Ref API is fully removed, it should be possible to simplify this to just &'a Bound<'py, T> and From implementations.

Tuple Fields

0: &'a Bound<'py, T>

Implementations

impl<'a, 'py> BoundRef<'a, 'py, PyAny>

pub unsafe fn ref_from_ptr(py: Python<'py>, ptr: &'a *mut PyObject) -> Self

pub unsafe fn ref_from_ptr_or_opt( py: Python<'py>, ptr: &'a *mut PyObject, ) -> Option<Self>

pub fn downcast<T: PyTypeCheck>( self, ) -> Result<BoundRef<'a, 'py, T>, DowncastError<'a, 'py>>

pub unsafe fn downcast_unchecked<T>(self) -> BoundRef<'a, 'py, T>

Methods from Deref<Target = Bound<'py, T>>

pub(crate) fn get_slot<const S: c_int>( &self, slot: Slot<S>, ) -> <Slot<S> as GetSlotImpl>::Type

where Slot<S>: GetSlotImpl,

pub fn borrow(&self) -> 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.

Examples

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

Python::with_gil(|py| -> PyResult<()> {
    let foo: Bound<'_, Foo> = Bound::new(py, Foo { inner: 73 })?;
    let inner: &u8 = &foo.borrow().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(&self) -> PyRefMut<'py, T>

where T: PyClass<Frozen = False>,

Mutably borrows the value T.

This borrow lasts while the returned PyRefMut exists.

Examples

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

Python::with_gil(|py| -> PyResult<()> {
    let foo: Bound<'_, Foo> = Bound::new(py, Foo { inner: 73 })?;
    foo.borrow_mut().inner = 35;

    assert_eq!(foo.borrow().inner, 35);
    Ok(())
})?;

Panics

Panics if the value is currently borrowed. For a non-panicking variant, use try_borrow_mut.

pub fn try_borrow(&self) -> 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.

pub fn try_borrow_mut(&self) -> 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.

pub fn get(&self) -> &T

where T: PyClass<Frozen = True> + Sync,

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,
}

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

    let py_counter = Bound::new(py, counter).unwrap();

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

pub fn as_super(&self) -> &Bound<'py, T::BaseType>

Upcast this Bound<PyClass> to its base type by reference.

If this type defined an explicit base class in its pyclass declaration (e.g. #[pyclass(extends = BaseType)]), the returned type will be &Bound<BaseType>. If an explicit base class was not declared, the return value will be &Bound<PyAny> (making this method equivalent to as_any).

This method is particularly useful for calling methods defined in an extension trait that has been implemented for Bound<BaseType>.

See also the into_super method to upcast by value, and the PyRef::as_super/PyRefMut::as_super methods for upcasting a pyclass that has already been borrowed.

Example: Calling a method defined on the Bound base type

use pyo3::prelude::*;

#[pyclass(subclass)]
struct BaseClass;

trait MyClassMethods<'py> {
    fn pyrepr(&self) -> PyResult<String>;
}
impl<'py> MyClassMethods<'py> for Bound<'py, BaseClass> {
    fn pyrepr(&self) -> PyResult<String> {
        self.call_method0("__repr__")?.extract()
    }
}

#[pyclass(extends = BaseClass)]
struct SubClass;

Python::with_gil(|py| {
    let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
    assert!(obj.as_super().pyrepr().is_ok());
})

pub(crate) fn get_class_object(&self) -> &PyClassObject<T>

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

Returns the GIL token associated with this object.

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 as_any(&self) -> &Bound<'py, PyAny>

Helper to cast to Bound<'py, PyAny>.

pub fn as_borrowed<'a>(&'a self) -> Borrowed<'a, 'py, T>

Casts this Bound<T> to a Borrowed<T> smart pointer.

pub fn as_unbound(&self) -> &Py<T>

Removes the connection for this Bound<T> from the GIL, allowing it to cross thread boundaries, without transferring ownership.

pub(crate) fn lookup_special<N>( &self, attr_name: N, ) -> PyResult<Option<Bound<'py, PyAny>>>

where N: IntoPyObject<'py, Target = PyString>,

Retrieve an attribute value, skipping the instance dictionary during the lookup but still binding the object to the instance.

This is useful when trying to resolve Python’s “magic” methods like __getitem__, which are looked up starting from the type object. This returns an Option as it is not typically a direct error for the special lookup to fail, as magic methods are optional in many situations in which they might be called.

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

Trait Implementations

impl<'py, T> Deref for BoundRef<'_, 'py, T>

type Target = Bound<'py, T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> From<BoundRef<'_, '_, T>> for Py<T>

fn from(bound: BoundRef<'_, '_, T>) -> Self

Converts to this type from the input type.

impl<'a, 'py, T> From<BoundRef<'a, 'py, T>> for &'a Bound<'py, T>

fn from(bound: BoundRef<'a, 'py, T>) -> Self

Converts to this type from the input type.

impl<'a, 'py, T> From<BoundRef<'a, 'py, T>> for Bound<'py, T>

fn from(bound: BoundRef<'a, 'py, T>) -> Self

Converts to this type from the input type.

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

type Error = PyBorrowError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<'a, 'py, T: PyClass<Frozen = False>> TryFrom<BoundRef<'a, 'py, T>> for PyRefMut<'py, T>

type Error = PyBorrowMutError

The type returned in the event of a conversion error.

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

Performs the conversion.