Struct PyClassGuard 

#[repr(transparent)]
pub struct PyClassGuard<'a, T: PyClass> {
    ptr: NonNull<PyObject>,
    marker: PhantomData<&'a Py<T>>,
}

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.

Fields

ptr: NonNull<PyObject>

marker: PhantomData<&'a Py<T>>

Implementations

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

pub(crate) fn try_borrow(obj: &'a Py<T>) -> Result<Self, PyBorrowError>

pub(crate) fn try_borrow_from_borrowed( obj: Borrowed<'a, '_, T>, ) -> Result<Self, PyBorrowError>

fn try_from_class_object( obj: &'a <T as PyClassImpl>::Layout, ) -> Result<Self, PyBorrowError>

pub(crate) fn as_class_object(&self) -> &'a <T as PyClassImpl>::Layout

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> PyClassGuard<'a, T>

where T: PyClass, T::BaseType: PyClass,

pub fn as_super(&self) -> &PyClassGuard<'a, T::BaseType>

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, T::BaseType>

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> FromPyObject<'a, 'py> for PyClassGuard<'a, T>

const INPUT_TYPE: PyStaticExpr = T::TYPE_HINT

Available on crate feature experimental-inspect only.

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

type Error = PyClassGuardError<'a, 'py>

The type returned in the event of a conversion error.

fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error>

Extracts Self from the bound smart pointer obj.

#[doc(hidden)]

fn sequence_extractor( _obj: Borrowed<'_, 'py, PyAny>, _: Token, ) -> Option<impl FromPyObjectSequence<Target = Self>>

Specialization hook for extracting sequences for types like Vec<u8> and [u8; N], where the bytes can be directly copied from some python objects without going through iteration.

fn as_local_tz(_: Token) -> Option<Self>

Available on crate feature chrono-local only.

Helper used to make a specialized path in extracting DateTime<Tz> where Tz is chrono::Local, which will accept “naive” datetime objects as being in the local timezone.

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

const OUTPUT_TYPE: PyStaticExpr = T::TYPE_HINT

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.

#[doc(hidden)]

fn owned_sequence_into_pyobject<I>( iter: I, py: Python<'py>, _: Token, ) -> Result<Bound<'py, PyAny>, PyErr>

where I: IntoIterator<Item = Self> + AsRef<[Self]>, I::IntoIter: ExactSizeIterator<Item = Self>,

Converts sequence of Self into a Python object. Used to specialize Vec<u8>, [u8; N] and SmallVec<[u8; N]> as a sequence of bytes into a bytes object.

#[doc(hidden)]

fn borrowed_sequence_into_pyobject<I>( iter: I, py: Python<'py>, _: Token, ) -> Result<Bound<'py, PyAny>, PyErr>

where Self: Reference, I: IntoIterator<Item = Self> + AsRef<[<Self as Reference>::BaseType]>, I::IntoIter: ExactSizeIterator<Item = Self>,

Converts sequence of Self into a Python object. Used to specialize &[u8] and Cow<[u8]> as a sequence of bytes into a bytes object.

#[doc(hidden)]

const SEQUENCE_OUTPUT_TYPE: PyStaticExpr = _

Available on crate feature experimental-inspect only.

The output type of IntoPyObject::owned_sequence_into_pyobject and IntoPyObject::borrowed_sequence_into_pyobject

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

const OUTPUT_TYPE: PyStaticExpr = T::TYPE_HINT

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.

#[doc(hidden)]

fn owned_sequence_into_pyobject<I>( iter: I, py: Python<'py>, _: Token, ) -> Result<Bound<'py, PyAny>, PyErr>

where I: IntoIterator<Item = Self> + AsRef<[Self]>, I::IntoIter: ExactSizeIterator<Item = Self>,

Converts sequence of Self into a Python object. Used to specialize Vec<u8>, [u8; N] and SmallVec<[u8; N]> as a sequence of bytes into a bytes object.

#[doc(hidden)]

const SEQUENCE_OUTPUT_TYPE: PyStaticExpr = _

Available on crate feature experimental-inspect only.

The output type of IntoPyObject::owned_sequence_into_pyobject and IntoPyObject::borrowed_sequence_into_pyobject

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

type Error = PyBorrowError

The type returned in the event of a conversion error.

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

Performs the conversion.

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

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