Struct PyClassGuardMut 

pub struct PyClassGuardMut<'a, T>
where
    T: PyClass<Frozen = False>,
{ /* private fields */ }

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) {
    core::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()?;
        core::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.

Implementations

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

where T: PyClass<Frozen = False>,

pub fn map<F, U>(self, f: F) -> PyClassGuardMapMut<'a, U>

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

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 as PyClassImpl>::BaseType: PyClass<Frozen = False>, T: PyClass<Frozen = False>,

pub fn as_super( &mut self, ) -> PyClassGuardMutSuper<'_, 'a, <T as PyClassImpl>::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.

Note

The mutable reference to the base type is not exposed directly, but through PyClassGuardMutSuper.

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

Gets a PyClassGuardMut<T::BaseType>.

See PyClassGuard::into_super for more.

Trait Implementations

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

where T: PyClass<Frozen = False> + Debug,

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

Formats the value using the given formatter.

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

where T: PyClass<Frozen = False>,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> DerefMut for PyClassGuardMut<'_, T>

where T: PyClass<Frozen = False>,

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

Mutably dereferences the value.

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

where T: PyClass<Frozen = False>,

fn drop(&mut self)

Releases the mutable borrow

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<'a, 'py, T> FromPyObject<'a, 'py> for PyClassGuardMut<'a, T>

where T: PyClass<Frozen = False>,

type Error = PyClassGuardMutError<'a, 'py>

The type returned in the event of a conversion error.

fn extract( obj: Borrowed<'a, 'py, PyAny>, ) -> Result<PyClassGuardMut<'a, T>, <PyClassGuardMut<'a, T> as FromPyObject<'a, 'py>>::Error>

Extracts Self from the bound smart pointer obj.

impl<'a, 'py, T> IntoPyObject<'py> for PyClassGuardMut<'a, T>

where T: PyClass<Frozen = False>,

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<<PyClassGuardMut<'a, T> as IntoPyObject<'py>>::Output, <PyClassGuardMut<'a, T> as IntoPyObject<'py>>::Error>

Performs the conversion.

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

where T: PyClass<Frozen = False>,

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<<&PyClassGuardMut<'a, T> as IntoPyObject<'py>>::Output, <&PyClassGuardMut<'a, T> as IntoPyObject<'py>>::Error>

Performs the conversion.

impl<T> Send for PyClassGuardMut<'_, T>

where T: PyClass<Frozen = False> + Send + Sync,

impl<T> Sync for PyClassGuardMut<'_, T>

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

impl<'a, 'py, T> TryFrom<&'a Bound<'py, T>> for PyClassGuardMut<'a, T>

where T: PyClass<Frozen = False>,

type Error = PyBorrowMutError

The type returned in the event of a conversion error.

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

Performs the conversion.