Struct PyClassGuard 

pub struct PyClassGuard<'a, T: PyClass> { /* private fields */ }

A wrapper type for an immutably borrowed value from a PyClass.

Rust has strict aliasing rules - you can either have any number of immutable (shared) references or one mutable reference. Python’s ownership model is the complete opposite of that - any Python object can be referenced any number of times, and mutation is allowed from any reference.

PyO3 deals with these differences by employing the Interior Mutability pattern. This requires that PyO3 enforces the borrowing rules and it has two mechanisms for doing so:

• Statically it can enforce thread-safe access with the Python<'py> token. All Rust code holding that token, or anything derived from it, can assume that they have safe access to the Python interpreter’s state. For this reason all the native Python objects can be mutated through shared references.
• However, methods and functions in Rust usually do need &mut references. While PyO3 can use the Python<'py> token to guarantee thread-safe access to them, it cannot statically guarantee uniqueness of &mut references. As such those references have to be tracked dynamically at runtime, using PyClassGuard and PyClassGuardMut defined in this module. This works similar to std’s RefCell type. Especially when building for free-threaded Python it gets harder to track which thread borrows which object at any time. This can lead to method calls failing with PyBorrowError. In these cases consider using frozen classes together with Rust interior mutability primitives like Mutex instead of using PyClassGuardMut to get mutable access.

Examples

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

• you need to access the pointer of the PyClass, 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: PyClassGuard<'_, Self>) -> String {
        // We can get &Self::BaseType by as_super
        let basename = slf.as_super().basename;
        format!("{}(base: {})", slf.name, basename)
    }
}

See also PyClassGuardMut and the guide for more information.

Implementations

impl<'a, T: PyClass> PyClassGuard<'a, T>

pub fn map<F, U: ?Sized>(self, f: F) -> PyClassGuardMap<'a, U, false>

where F: FnOnce(&T) -> &U,

Consumes the PyClassGuard and returns a PyClassGuardMap for a component of the borrowed data

Examples

#[pyclass]
pub struct MyClass {
    msg: String,
}

let obj = Bound::new(py, MyClass { msg: String::from("hello") })?;
let msg = obj.extract::<PyClassGuard<'_, MyClass>>()?.map(|c| &c.msg);
assert_eq!(&*msg, "hello");

impl<'a, T, U> PyClassGuard<'a, T>

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

pub fn as_super(&self) -> &PyClassGuard<'a, U>

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

With the help of this method, you can access attributes and call methods on the superclass without consuming the PyClassGuard<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: PyClassGuard<'_, Self>) -> String {
        format!("{} {}", slf.as_super().base_name_len(), slf.sub_name_len())
    }
}

pub fn into_super(self) -> PyClassGuard<'a, U>

Gets a PyClassGuard<T::BaseType>.

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: PyClassGuard<'_, Self>) -> String {
        let subname = slf.name3;
        let super_ = slf.into_super();
        format!("{} {} {}", super_.as_super().name1, super_.name2, subname)
    }
}

Trait Implementations

impl<T: PyClass> Deref for PyClassGuard<'_, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: PyClass> Drop for PyClassGuard<'_, T>

fn drop(&mut self)

Releases the shared borrow

impl<'a, 'py, T: PyClass> FromPyObjectBound<'a, 'py> for PyClassGuard<'a, T>

fn from_py_object_bound(obj: Borrowed<'a, 'py, PyAny>) -> PyResult<Self>

Extracts Self from the bound smart pointer obj.

const INPUT_TYPE: &'static str = "typing.Any"

Available on crate feature experimental-inspect only.

Provides the type hint information for this type when it appears as an argument.

fn type_input() -> TypeInfo

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as an argument.

impl<'a, 'py, T: PyClass> IntoPyObject<'py> for &PyClassGuard<'a, T>

const OUTPUT_TYPE: &'static str = T::PYTHON_TYPE

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as a return value.

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<Self::Output, Self::Error>

Performs the conversion.

fn type_output() -> TypeInfo

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as a return value.

impl<'a, 'py, T: PyClass> IntoPyObject<'py> for PyClassGuard<'a, T>

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<Self::Output, Self::Error>

Performs the conversion.

const OUTPUT_TYPE: &'static str = "typing.Any"

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as a return value.

fn type_output() -> TypeInfo

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as a return value.

impl<T: PyClass + Sync> Send for PyClassGuard<'_, T>

impl<T: PyClass + Sync> Sync for PyClassGuard<'_, T>