Struct pyo3::pycell::PyCell

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

PyCell is the container type for PyClass values.

From the 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 the 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.

PyCell implements Deref<Target = PyAny>, so you can also call methods from PyAny when you have a PyCell<T>.

Examples

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

#[pyclass]
struct Book {
    #[pyo3(get)]
    name: &'static str,
    author: &'static str,
}
let book = Book {
    name: "The Man in the High Castle",
    author: "Philip Kindred Dick",
};
Python::with_gil(|py| {
    let book_cell = PyCell::new(py, book).unwrap();
    // `&PyCell` implements `ToPyObject`, so you can use it in a Python snippet
    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’ll 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>

Makes a new PyCell on the Python heap and return the reference to it.

In cases where the value in the cell does not need to be accessed immediately after creation, consider Py::new as a more efficient alternative.

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

Immutably borrows the value T. This borrow lasts as long as 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 as long as 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 as long as the returned PyRef exists.

This is the non-panicking variant of borrow.

Examples

#[pyclass]
struct Class {}
Python::with_gil(|py| {
    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 as long as the returned PyRefMut exists.

This is the non-panicking variant of borrow_mut.

Examples

#[pyclass]
struct Class {}
Python::with_gil(|py| {
    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 {}
Python::with_gil(|py| {
    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.

Methods from Deref<Target = PyAny>

pub fn downcast<T>(&self) -> Result<&T, PyDowncastError<'_>> where
    for<'py> T: PyTryFrom<'py>, 

Converts this PyAny to a concrete Python type.

Examples

use pyo3::prelude::*;
use pyo3::types::{PyAny, PyDict, PyList};

Python::with_gil(|py| {
    let dict = PyDict::new(py);
    assert!(dict.is_instance::<PyAny>().unwrap());
    let any: &PyAny = dict.as_ref();
    assert!(any.downcast::<PyDict>().is_ok());
    assert!(any.downcast::<PyList>().is_err());
});

pub fn hasattr<N>(&self, attr_name: N) -> PyResult<bool> where
    N: ToPyObject, 

Determines whether this object has the given attribute.

This is equivalent to the Python expression hasattr(self, attr_name).

pub fn getattr<N>(&self, attr_name: N) -> PyResult<&PyAny> where
    N: ToPyObject, 

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

pub fn setattr<N, V>(&self, attr_name: N, value: V) -> PyResult<()> where
    N: ToBorrowedObject,
    V: ToBorrowedObject, 

Sets an attribute value.

This is equivalent to the Python expression self.attr_name = value.

pub fn delattr<N>(&self, attr_name: N) -> PyResult<()> where
    N: ToPyObject, 

Deletes an attribute.

This is equivalent to the Python statement del self.attr_name.

pub fn compare<O>(&self, other: O) -> PyResult<Ordering> where
    O: ToPyObject, 

Returns an Ordering between self and other.

This is equivalent to the following Python code:

if self == other:
    return Equal
elif a < b:
    return Less
elif a > b:
    return Greater
else:
    raise TypeError("PyAny::compare(): All comparisons returned false")

Examples

use pyo3::prelude::*;
use pyo3::types::PyFloat;
use std::cmp::Ordering;

Python::with_gil(|py| -> PyResult<()> {
    let a = PyFloat::new(py, 0_f64);
    let b = PyFloat::new(py, 42_f64);
    assert_eq!(a.compare(b)?, Ordering::Less);
    Ok(())
})?;

It will return PyErr for values that cannot be compared:

use pyo3::prelude::*;
use pyo3::types::{PyFloat, PyString};

Python::with_gil(|py| -> PyResult<()> {
    let a = PyFloat::new(py, 0_f64);
    let b = PyString::new(py, "zero");
    assert!(a.compare(b).is_err());
    Ok(())
})?;

pub fn rich_compare<O>(
    &self,
    other: O,
    compare_op: CompareOp
) -> PyResult<&PyAny> where
    O: ToPyObject, 

Tests whether two Python objects obey a given CompareOp.

Depending on the value of compare_op, this is equivalent to one of the following Python expressions:

compare_op	Python expression
CompareOp::Eq	self == other
CompareOp::Ne	self != other
CompareOp::Lt	self < other
CompareOp::Le	self <= other
CompareOp::Gt	self > other
CompareOp::Ge	self >= other

Examples

use pyo3::prelude::*;
use pyo3::types::PyInt;
use pyo3::class::basic::CompareOp;

Python::with_gil(|py| -> PyResult<()> {
    let a: &PyInt = 0_u8.into_py(py).into_ref(py).downcast()?;
    let b: &PyInt = 42_u8.into_py(py).into_ref(py).downcast()?;
    assert!(a.rich_compare(b, CompareOp::Le)?.is_true()?);
    Ok(())
  })?;

pub fn is_callable(&self) -> bool

Determines whether this object appears callable.

This is equivalent to Python’s callable() function.

Examples

use pyo3::prelude::*;

Python::with_gil(|py| -> PyResult<()> {
       let builtins = PyModule::import(py, "builtins")?;
       let print = builtins.getattr("print")?;
       assert!(print.is_callable());
       Ok(())
})?;

This is equivalent to the Python statement assert callable(print).

Note that unless an API needs to distinguish between callable and non-callable objects, there is no point in checking for callability. Instead, it is better to just do the call and handle potential exceptions.

pub fn call(
    &self,
    args: impl IntoPy<Py<PyTuple>>,
    kwargs: Option<&PyDict>
) -> PyResult<&PyAny>

Calls the object.

This is equivalent to the Python expression self(*args, **kwargs).

pub fn call0(&self) -> PyResult<&PyAny>

Calls the object without arguments.

This is equivalent to the Python expression self().

Examples

use pyo3::prelude::*;

Python::with_gil(|py| -> PyResult<()> {
    let module = PyModule::import(py, "builtins")?;
    let help = module.getattr("help")?;
    help.call0()?;
    Ok(())
})?;

This is equivalent to the Python expression help().

pub fn call1(&self, args: impl IntoPy<Py<PyTuple>>) -> PyResult<&PyAny>

Calls the object with only positional arguments.

This is equivalent to the Python expression self(*args).

Examples

use pyo3::prelude::*;

Python::with_gil(|py| -> PyResult<()> {
    let module = PyModule::import(py, "operator")?;
    let add = module.getattr("add")?;
    let args = (1,2);
    let value = add.call1(args)?;
    assert_eq!(value.extract::<i32>()?, 3);
    Ok(())
})?;

This is equivalent to the following Python code:

from operator import add

value = add(1,2)
assert value == 3

pub fn call_method(
    &self,
    name: &str,
    args: impl IntoPy<Py<PyTuple>>,
    kwargs: Option<&PyDict>
) -> PyResult<&PyAny>

Calls a method on the object.

This is equivalent to the Python expression self.name(*args, **kwargs).

Examples

use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};
use crate::pyo3::types::IntoPyDict;

Python::with_gil(|py| -> PyResult<()> {
    let list = PyList::new(py, vec![3, 6, 5, 4, 7]);
    let kwargs = vec![("reverse", true)].into_py_dict(py);

    list.call_method("sort", (), Some(kwargs))?;
    assert_eq!(list.extract::<Vec<i32>>()?, vec![7, 6, 5, 4, 3]);
    Ok(())
})?;

This is equivalent to the following Python code:

my_list = [3, 6, 5, 4, 7]
my_list.sort(reverse = True)
assert my_list == [7, 6, 5, 4, 3]

pub fn call_method0(&self, name: &str) -> PyResult<&PyAny>

Calls a method on the object without arguments.

This is equivalent to the Python expression self.name().

Examples

use pyo3::prelude::*;
use pyo3::types::PyFloat;
use std::f64::consts::PI;

Python::with_gil(|py| -> PyResult<()> {
    let pi = PyFloat::new(py, PI);
    let ratio = pi.call_method0("as_integer_ratio")?;
    let (a, b) = ratio.extract::<(u64, u64)>()?;
    assert_eq!(a, 884_279_719_003_555);
    assert_eq!(b, 281_474_976_710_656);
    Ok(())
})?;

This is equivalent to the following Python code:

import math

a, b = math.pi.as_integer_ratio()

pub fn call_method1(
    &self,
    name: &str,
    args: impl IntoPy<Py<PyTuple>>
) -> PyResult<&PyAny>

Calls a method on the object with only positional arguments.

This is equivalent to the Python expression self.name(*args).

Examples

use pyo3::prelude::*;
use pyo3::types::PyList;

Python::with_gil(|py| -> PyResult<()> {
    let list = PyList::new(py, vec![1, 3, 4]);
    list.call_method1("insert", (1, 2))?;
    assert_eq!(list.extract::<Vec<u8>>()?, [1, 2, 3, 4]);
    Ok(())
})?;

This is equivalent to the following Python code:

list_ = [1,3,4]
list_.insert(1,2)
assert list_ == [1,2,3,4]

pub fn is_true(&self) -> PyResult<bool>

Returns whether the object is considered to be true.

This is equivalent to the Python expression bool(self).

pub fn is_none(&self) -> bool

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

pub fn is_empty(&self) -> PyResult<bool>

Returns true if the sequence or mapping has a length of 0.

This is equivalent to the Python expression len(self) == 0.

pub fn get_item<K>(&self, key: K) -> PyResult<&PyAny> where
    K: ToBorrowedObject, 

Gets an item from the collection.

This is equivalent to the Python expression self[key].

pub fn set_item<K, V>(&self, key: K, value: V) -> PyResult<()> where
    K: ToBorrowedObject,
    V: ToBorrowedObject, 

Sets a collection item value.

This is equivalent to the Python expression self[key] = value.

pub fn del_item<K>(&self, key: K) -> PyResult<()> where
    K: ToBorrowedObject, 

Deletes an item from the collection.

This is equivalent to the Python expression del self[key].

pub fn iter(&self) -> PyResult<&PyIterator>

Takes an object and returns an iterator for it.

This is typically a new iterator but if the argument is an iterator, this returns itself.

pub fn get_type(&self) -> &PyType

Returns the Python type object for this object’s type.

pub fn get_type_ptr(&self) -> *mut PyTypeObject

Returns the Python type pointer for this object.

pub fn cast_as<'a, D>(&'a self) -> Result<&'a D, PyDowncastError<'_>> where
    D: PyTryFrom<'a>, 

Casts the PyObject to a concrete Python object type.

This can cast only to native Python types, not types implemented in Rust.

pub fn extract<'a, D>(&'a self) -> PyResult<D> where
    D: FromPyObject<'a>, 

Extracts some type from the Python object.

This is a wrapper function around FromPyObject::extract().

pub fn get_refcnt(&self) -> isize

Returns the reference count for the Python object.

pub fn repr(&self) -> PyResult<&PyString>

Computes the “repr” representation of self.

This is equivalent to the Python expression repr(self).

pub fn str(&self) -> PyResult<&PyString>

Computes the “str” representation of self.

This is equivalent to the Python expression str(self).

pub fn hash(&self) -> PyResult<isize>

Retrieves the hash code of self.

This is equivalent to the Python expression hash(self).

pub fn len(&self) -> PyResult<usize>

Returns the length of the sequence or mapping.

This is equivalent to the Python expression len(self).

pub fn dir(&self) -> &PyList

Returns the list of attributes of this object.

This is equivalent to the Python expression dir(self).

pub fn is_instance<T: PyTypeObject>(&self) -> PyResult<bool>

Checks whether this object is an instance of type T.

This is equivalent to the Python expression isinstance(self, T).

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> AsRef<PyAny> for PyCell<T>

fn as_ref(&self) -> &PyAny

Performs the conversion.

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

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

Formats the value using the given formatter.

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

type Target = PyAny

The resulting type after dereferencing.

fn deref(&self) -> &PyAny

Dereferences the value.

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<T: PyClass> PyNativeType for PyCell<T>

fn py(&self) -> Python<'_>

Returns a GIL marker constrained to the lifetime of this type.

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

Cast &PyAny to &Self without no type checking.

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<'v>>

Cast from a concrete Python object type to PyObject.

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

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.

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

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