Struct pyo3::PyRef

pub struct PyRef<'a, T: PyTypeInfo>(_, _);

A special reference of type T. PyRef<T> refers a instance of T, which exists in the Python heap as a part of a Python object.

We can't implement AsPyPointer or ToPyObject for pyclasses, because they're not Python objects until copied to the Python heap. So, instead of treating &pyclasses as Python objects, we need to use special reference types PyRef and PyRefMut.

Example

use pyo3::prelude::*;
use pyo3::types::IntoPyDict;
#[pyclass]
struct Point {
    x: i32,
    y: i32,
}
#[pymethods]
impl Point {
    fn length(&self) -> i32 {
        self.x * self.y
    }
}
let gil = Python::acquire_gil();
let py = gil.python();
let obj = PyRef::new(gil.python(), Point { x: 3, y: 4 }).unwrap();
let d = [("p", obj)].into_py_dict(py);
py.run("assert p.length() == 12", None, Some(d)).unwrap();

Methods

impl<'p, T> PyRef<'p, T> where
    T: PyTypeInfo + PyTypeObject + PyTypeCreate, 

pub fn new(py: Python<'p>, value: T) -> PyResult<PyRef<T>>

Trait Implementations

impl<'a, T: PyTypeInfo> AsPyPointer for PyRef<'a, T>

fn as_ptr(&self) -> *mut PyObject

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

impl<'a, T: Debug + PyTypeInfo> Debug for PyRef<'a, T>

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

Formats the value using the given formatter.

impl<'a, T: PyTypeInfo> Deref for PyRef<'a, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, T> From<PyRef<'a, T>> for Py<T> where
    T: PyTypeInfo, 

fn from(ob: PyRef<'a, T>) -> Self

Performs the conversion.

impl<'a, T> From<PyRef<'a, T>> for &'a PyAny where
    T: PyTypeInfo, 

fn from(pref: PyRef<'a, T>) -> &'a PyAny

Performs the conversion.

impl<'p, T> FromPyPointer<'p> for PyRef<'p, T> where
    T: PyTypeInfo, 

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

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

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

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

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

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

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

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

impl<'a, T: PyTypeInfo> IntoPy<PyObject> for PyRef<'a, T>

fn into_py(self, py: Python) -> PyObject

Performs the conversion.

impl<'a, T: PyTypeInfo> ToPyObject for PyRef<'a, T>

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

Converts self into a Python object.