Struct pyo3::pycell::PyCell

#[repr(C)]pub struct PyCell<T: PyClass> { /* fields omitted */ }

PyCell is the container type for PyClass.

From Python side, PyCell<T> is the concrete layout of T: PyClass in the Python heap, which means we can convert *const PyClass<T> to *mut ffi::PyObject.

From Rust side, PyCell<T> is the mutable container of T. Since PyCell<T: PyClass> is always on the Python heap, we don't have the ownership of it. Thus, to mutate the data behind &PyCell<T> safely, we employ the Interior Mutability Pattern like std::cell::RefCell.

Examples

In most cases, PyCell is hidden behind #[pymethods]. However, you can construct &PyCell directly to test your pyclass in Rust code.

#[pyclass]
struct Book {
    #[pyo3(get)]
    name: &'static str,
    author: &'static str,
}
let gil = Python::acquire_gil();
let py = gil.python();
let book = Book {
    name: "The Man in the High Castle",
    author: "Philip Kindred Dick",
};
let book_cell = PyCell::new(py, book).unwrap();
// you can expose PyCell to Python snippets
pyo3::py_run!(py, book_cell, "assert book_cell.name[-6:] == 'Castle'");

You can use slf: &PyCell<Self> as an alternative self receiver of #[pymethod], though you rarely need it.

use std::collections::HashMap;
#[pyclass]
#[derive(Default)]
struct Counter {
    counter: HashMap<String, usize>
}
#[pymethods]
impl Counter {
    // You can use &mut self here, but now we use &PyCell for demonstration
    fn increment(slf: &PyCell<Self>, name: String) -> PyResult<usize> {
        let mut slf_mut = slf.try_borrow_mut()?;
        // Now a mutable reference exists so we cannot get another one
        assert!(slf.try_borrow().is_err());
        assert!(slf.try_borrow_mut().is_err());
        let counter = slf_mut.counter.entry(name).or_insert(0);
        *counter += 1;
        Ok(*counter)
    }
}

Implementations

impl<T: PyClass> PyCell<T>

pub fn new(
    py: Python,
    value: impl Into<PyClassInitializer<T>>
) -> PyResult<&Self> where
    T::BaseLayout: PyBorrowFlagLayout<T::BaseType>, 

Make new PyCell on the Python heap and returns the reference of it.

pub fn borrow(&self) -> PyRef<T>

Immutably borrows the value T. This borrow lasts untill the returned PyRef exists.

Panics

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

pub fn borrow_mut(&self) -> PyRefMut<T>

Mutably borrows the value T. This borrow lasts untill the returned PyRefMut exists.

Panics

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

pub fn try_borrow(&self) -> Result<PyRef<T>, PyBorrowError>

Immutably borrows the value T, returning an error if the value is currently mutably borrowed. This borrow lasts untill the returned PyRef exists.

This is the non-panicking variant of borrow.

Examples

#[pyclass]
struct Class {}
let gil = Python::acquire_gil();
let py = gil.python();
let c = PyCell::new(py, Class {}).unwrap();
{
    let m = c.borrow_mut();
    assert!(c.try_borrow().is_err());
}

{
    let m = c.borrow();
    assert!(c.try_borrow().is_ok());
}

pub fn try_borrow_mut(&self) -> Result<PyRefMut<T>, PyBorrowMutError>

Mutably borrows the value T, returning an error if the value is currently borrowed. This borrow lasts untill the returned PyRefMut exists.

This is the non-panicking variant of borrow_mut.

Examples

#[pyclass]
struct Class {}
let gil = Python::acquire_gil();
let py = gil.python();
let c = PyCell::new(py, Class {}).unwrap();
{
    let m = c.borrow();
    assert!(c.try_borrow_mut().is_err());
}

assert!(c.try_borrow_mut().is_ok());

pub unsafe fn try_borrow_unguarded(&self) -> Result<&T, PyBorrowError>

Immutably borrows the value T, returning an error if the value is currently mutably borrowed.

Safety

This method is unsafe because it does not return a PyRef, thus leaving the borrow flag untouched. Mutably borrowing the PyCell while the reference returned by this method is alive is undefined behaviour.

Examples

#[pyclass]
struct Class {}
let gil = Python::acquire_gil();
let py = gil.python();
let c = PyCell::new(py, Class {}).unwrap();

{
    let m = c.borrow_mut();
    assert!(unsafe { c.try_borrow_unguarded() }.is_err());
}

{
    let m = c.borrow();
    assert!(unsafe { c.try_borrow_unguarded() }.is_ok());
}

pub fn replace(&self, t: T) -> T

Replaces the wrapped value with a new one, returning the old value,

Panics

Panics if the value is currently borrowed.

pub fn replace_with<F: FnOnce(&mut T) -> T>(&self, f: F) -> T

Replaces the wrapped value with a new one computed from f, returning the old value.

Panics

Panics if the value is currently borrowed.

pub fn swap(&self, other: &Self)

Swaps the wrapped value of self with the wrapped value of other.

Panics

Panics if the value in either PyCell is currently borrowed.

Trait Implementations

impl<T: PyClass> AsPyPointer for PyCell<T>

fn as_ptr(&self) -> *mut PyObject

Retrieves the underlying FFI pointer (as a borrowed pointer).

impl<T: PyClass + Debug> Debug for PyCell<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a, '_, T> From<&'_ PyCell<T>> for Py<T> where
    T: PyClass, 

fn from(cell: &PyCell<T>) -> Self

Performs the conversion.

impl<'a, T> FromPyObject<'a> for &'a PyCell<T> where
    T: PyClass, 

fn extract(obj: &'a PyAny) -> PyResult<Self>

Extracts Self from the source PyObject.

impl<'p, T> FromPyPointer<'p> for PyCell<T> where
    T: PyClass, 

unsafe fn from_owned_ptr_or_opt(
    py: Python<'p>,
    ptr: *mut PyObject
) -> Option<&'p Self>

unsafe fn from_borrowed_ptr_or_opt(
    py: Python<'p>,
    ptr: *mut PyObject
) -> Option<&'p Self>

unsafe fn from_owned_ptr_or_panic(
    py: Python<'p>,
    ptr: *mut PyObject
) -> &'p Self

unsafe fn from_owned_ptr(py: Python<'p>, ptr: *mut PyObject) -> &'p Self

unsafe fn from_owned_ptr_or_err(
    py: Python<'p>,
    ptr: *mut PyObject
) -> PyResult<&'p Self>

unsafe fn from_borrowed_ptr_or_panic(
    py: Python<'p>,
    ptr: *mut PyObject
) -> &'p Self

unsafe fn from_borrowed_ptr(py: Python<'p>, ptr: *mut PyObject) -> &'p Self

unsafe fn from_borrowed_ptr_or_err(
    py: Python<'p>,
    ptr: *mut PyObject
) -> PyResult<&'p Self>

impl<T: PyClass> PyDowncastImpl for PyCell<T>

unsafe fn unchecked_downcast(obj: &PyAny) -> &Self

Cast &PyAny to &Self without no type checking.

fn __private__(&self) -> PrivateMarker

This trait is private to implement; this method exists to make it impossible to implement outside the crate.

impl<T: PyClass> PyLayout<T> for PyCell<T>

const IS_NATIVE_TYPE: bool

fn get_super(&mut self) -> Option<&mut T::BaseLayout>

unsafe fn py_init(&mut self, value: T)

unsafe fn py_drop(&mut self, py: Python)

impl<'v, T> PyTryFrom<'v> for PyCell<T> where
    T: 'v + PyClass, 

fn try_from<V: Into<&'v PyAny>>(value: V) -> Result<&'v Self, PyDowncastError>

Cast from a concrete Python object type to PyObject.

fn try_from_exact<V: Into<&'v PyAny>>(
    value: V
) -> Result<&'v Self, PyDowncastError>

Cast from a concrete Python object type to PyObject. With exact type check.

unsafe fn try_from_unchecked<V: Into<&'v PyAny>>(value: V) -> &'v Self

Cast a PyAny to a specific type of PyObject. The caller must have already verified the reference is for this type.

impl<'_, T: PyClass> ToPyObject for &'_ PyCell<T>

fn to_object(&self, py: Python) -> PyObject

Converts self into a Python object.

impl<'a, T: PyClass> TryFrom<&'a PyCell<T>> for PyRef<'a, T>

type Error = PyBorrowError

The type returned in the event of a conversion error.

fn try_from(cell: &'a PyCell<T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: PyClass> TryFrom<&'a PyCell<T>> for PyRefMut<'a, T>

type Error = PyBorrowMutError

The type returned in the event of a conversion error.

fn try_from(cell: &'a PyCell<T>) -> Result<Self, Self::Error>

Performs the conversion.