Struct PyClassGuardMut 

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

A wrapper type for a mutably borrowed value from a PyClass

When not to use PyClassGuardMut

Usually you can use &mut references as method and function receivers and arguments, and you won’t need to use PyClassGuardMut directly:

use pyo3::prelude::*;

#[pyclass]
struct Number {
    inner: u32,
}

#[pymethods]
impl Number {
    fn increment(&mut self) {
        self.inner += 1;
    }
}

The #[pymethods] proc macro will generate this wrapper function (and more), using PyClassGuardMut under the hood:

// The function which is exported to Python looks roughly like the following
unsafe extern "C" fn __pymethod_increment__(
    _slf: *mut ::pyo3::ffi::PyObject,
    _args: *mut ::pyo3::ffi::PyObject,
) -> *mut ::pyo3::ffi::PyObject {
    unsafe fn inner<'py>(
        py: ::pyo3::Python<'py>,
        _slf: *mut ::pyo3::ffi::PyObject,
    ) -> ::pyo3::PyResult<*mut ::pyo3::ffi::PyObject> {
        let function = Number::increment;
        let mut holder_0 = ::pyo3::impl_::extract_argument::FunctionArgumentHolder::INIT;
        let result = {
            let ret = function(::pyo3::impl_::extract_argument::extract_pyclass_ref_mut::<Number>(
                unsafe { ::pyo3::impl_::extract_argument::cast_function_argument(py, _slf) },
                &mut holder_0,
            )?);
            {
                let result = {
                    let obj = ret;
                    ::pyo3::impl_::wrap::converter(&obj)
                        .wrap(obj)
                        .map_err(::core::convert::Into::<::pyo3::PyErr>::into)
                };
                ::pyo3::impl_::wrap::converter(&result).map_into_ptr(py, result)
            }
        };
        result
    }

    unsafe {
        ::pyo3::impl_::trampoline::get_trampoline_function!(noargs, inner)(
            _slf,
            _args,
        )
    }
}

When to use PyClassGuardMut

Using PyClasses from Rust

However, we do need PyClassGuardMut if we want to call its methods from Rust:

Python::attach(|py| {
    let n = Py::new(py, Number { inner: 0 })?;

    // We borrow the guard and then dereference
    // it to get a mutable reference to Number
    let mut guard: PyClassGuardMut<'_, Number> = n.extract(py)?;
    let n_mutable: &mut Number = &mut *guard;

    n_mutable.increment();

    // To avoid panics we must dispose of the
    // `PyClassGuardMut` before borrowing again.
    drop(guard);

    let n_immutable: &Number = &*n.extract::<PyClassGuard<'_, Number>>(py)?;
    assert_eq!(n_immutable.inner, 1);

    Ok(())
})

Dealing with possibly overlapping mutable references

It is also necessary to use PyClassGuardMut if you can receive mutable arguments that may overlap. Suppose the following function that swaps the values of two Numbers:

#[pyfunction]
fn swap_numbers(a: &mut Number, b: &mut Number) {
    std::mem::swap(&mut a.inner, &mut b.inner);
}

When users pass in the same Number as both arguments, one of the mutable borrows will fail and raise a RuntimeError:

>>> a = Number()
>>> swap_numbers(a, a)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  RuntimeError: Already borrowed

It is better to write that function like this:

#[pyfunction]
fn swap_numbers(a: &Bound<'_, Number>, b: &Bound<'_, Number>) -> PyResult<()> {
    // Check that the pointers are unequal
    if !a.is(b) {
        let mut a: PyClassGuardMut<'_, Number> = a.extract()?;
        let mut b: PyClassGuardMut<'_, Number> = b.extract()?;
        std::mem::swap(&mut a.inner, &mut b.inner);
    } else {
        // Do nothing - they are the same object, so don't need swapping.
    }
    Ok(())
}

See PyClassGuard and the guide for more information.

Fields

ptr: NonNull<PyObject>

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

Implementations

impl<'a, T: PyClass<Frozen = False>> PyClassGuardMut<'a, T>

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

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

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

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

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

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

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

Examples

#[pyclass]
pub struct MyClass {
    data: [i32; 100],
}

let obj = Bound::new(py, MyClass { data: [0; 100] })?;
let mut data = obj.extract::<PyClassGuardMut<'_, MyClass>>()?.map(|c| c.data.as_mut_slice());
data[0] = 42;

impl<'a, T> PyClassGuardMut<'a, T>

where T: PyClass<Frozen = False>, T::BaseType: PyClass<Frozen = False>,

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

Borrows a mutable reference to PyClassGuardMut<T::BaseType>.

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

See PyClassGuard::as_super for more.

pub fn into_super(self) -> PyClassGuardMut<'a, T::BaseType>

Gets a PyClassGuardMut<T::BaseType>.

See PyClassGuard::into_super for more.

Trait Implementations

impl<T: PyClass<Frozen = False>> Deref for PyClassGuardMut<'_, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: PyClass<Frozen = False>> DerefMut for PyClassGuardMut<'_, T>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T: PyClass<Frozen = False>> Drop for PyClassGuardMut<'_, T>

fn drop(&mut self)

Releases the mutable borrow

impl<'a, 'py, T: PyClass<Frozen = False>> FromPyObject<'a, 'py> for PyClassGuardMut<'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 = PyClassGuardMutError<'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<Frozen = False>> IntoPyObject<'py> for &PyClassGuardMut<'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<Frozen = False>> IntoPyObject<'py> for PyClassGuardMut<'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<Frozen = False>> TryFrom<&'a Bound<'py, T>> for PyClassGuardMut<'a, T>

type Error = PyBorrowMutError

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<Frozen = False> + Send + Sync> Send for PyClassGuardMut<'_, T>

impl<T: PyClass<Frozen = False> + Sync> Sync for PyClassGuardMut<'_, T>