Struct Borrowed

pub struct Borrowed<'a, 'py, T>(/* private fields */);

A borrowed equivalent to Bound.

The advantage of this over &Bound is that it avoids the need to have a pointer-to-pointer, as Bound is already a pointer to an `ffi::PyObject``.

Similarly, this type is Copy and Clone, like a shared reference (&T).

Implementations

impl<'a, 'py, T> Borrowed<'a, 'py, T>

pub fn to_owned(self) -> Bound<'py, T>

Creates a new owned Bound<T> from this borrowed reference by increasing the reference count.

Example

use pyo3::{prelude::*, types::PyTuple};

Python::with_gil(|py| -> PyResult<()> {
    let tuple = PyTuple::new(py, [1, 2, 3])?;

    // borrows from `tuple`, so can only be
    // used while `tuple` stays alive
    let borrowed = tuple.get_borrowed_item(0)?;

    // creates a new owned reference, which
    // can be used indendently of `tuple`
    let bound = borrowed.to_owned();
    drop(tuple);

    assert_eq!(bound.extract::<i32>().unwrap(), 1);
    Ok(())
})

pub fn as_ptr(self) -> *mut PyObject

Returns the raw FFI pointer represented by self.

Safety

Callers are responsible for ensuring that the pointer does not outlive self.

The reference is borrowed; callers should not decrease the reference count when they are finished with the pointer.

impl<'a, 'py> Borrowed<'a, 'py, PyAny>

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

Constructs a new Borrowed<'a, 'py, PyAny> from a pointer. Panics if ptr is null.

Prefer to use Bound::from_borrowed_ptr, as that avoids the major safety risk of needing to precisely define the lifetime 'a for which the borrow is valid.

Safety

• ptr must be a valid pointer to a Python object
• similar to std::slice::from_raw_parts, the lifetime 'a is completely defined by the caller and it is the caller’s responsibility to ensure that the reference this is derived from is valid for the lifetime 'a.

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

Constructs a new Borrowed<'a, 'py, PyAny> from a pointer. Returns None if ptr is null.

Prefer to use Bound::from_borrowed_ptr_or_opt, as that avoids the major safety risk of needing to precisely define the lifetime 'a for which the borrow is valid.

Safety

• ptr must be a valid pointer to a Python object, or null
• similar to std::slice::from_raw_parts, the lifetime 'a is completely defined by the caller and it is the caller’s responsibility to ensure that the reference this is derived from is valid for the lifetime 'a.

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

Constructs a new Borrowed<'a, 'py, PyAny> from a pointer. Returns an Err by calling PyErr::fetch if ptr is null.

Prefer to use Bound::from_borrowed_ptr_or_err, as that avoids the major safety risk of needing to precisely define the lifetime 'a for which the borrow is valid.

Safety

• ptr must be a valid pointer to a Python object, or null
• similar to std::slice::from_raw_parts, the lifetime 'a is completely defined by the caller and it is the caller’s responsibility to ensure that the reference this is derived from is valid for the lifetime 'a.

Methods from Deref<Target = Bound<'py, T>>

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

Immutably borrows the value T.

This borrow lasts while the returned PyRef exists. Multiple immutable borrows can be taken out at the same time.

For frozen classes, the simpler get is available.

Examples

#[pyclass]
struct Foo {
    inner: u8,
}

Python::with_gil(|py| -> PyResult<()> {
    let foo: Bound<'_, Foo> = Bound::new(py, Foo { inner: 73 })?;
    let inner: &u8 = &foo.borrow().inner;

    assert_eq!(*inner, 73);
    Ok(())
})?;

Panics

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

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

where T: PyClass<Frozen = False>,

Mutably borrows the value T.

This borrow lasts while the returned PyRefMut exists.

Examples

#[pyclass]
struct Foo {
    inner: u8,
}

Python::with_gil(|py| -> PyResult<()> {
    let foo: Bound<'_, Foo> = Bound::new(py, Foo { inner: 73 })?;
    foo.borrow_mut().inner = 35;

    assert_eq!(foo.borrow().inner, 35);
    Ok(())
})?;

Panics

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

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

Attempts to immutably borrow the value T, returning an error if the value is currently mutably borrowed.

The borrow lasts while the returned PyRef exists.

This is the non-panicking variant of borrow.

For frozen classes, the simpler get is available.

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

where T: PyClass<Frozen = False>,

Attempts to mutably borrow the value T, returning an error if the value is currently borrowed.

The borrow lasts while the returned PyRefMut exists.

This is the non-panicking variant of borrow_mut.

pub fn get(&self) -> &T

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

Provide an immutable borrow of the value T without acquiring the GIL.

This is available if the class is frozen and Sync.

Examples

use std::sync::atomic::{AtomicUsize, Ordering};

#[pyclass(frozen)]
struct FrozenCounter {
    value: AtomicUsize,
}

Python::with_gil(|py| {
    let counter = FrozenCounter { value: AtomicUsize::new(0) };

    let py_counter = Bound::new(py, counter).unwrap();

    py_counter.get().value.fetch_add(1, Ordering::Relaxed);
});

pub fn as_super(&self) -> &Bound<'py, T::BaseType>

Upcast this Bound<PyClass> to its base type by reference.

If this type defined an explicit base class in its pyclass declaration (e.g. #[pyclass(extends = BaseType)]), the returned type will be &Bound<BaseType>. If an explicit base class was not declared, the return value will be &Bound<PyAny> (making this method equivalent to as_any).

This method is particularly useful for calling methods defined in an extension trait that has been implemented for Bound<BaseType>.

See also the into_super method to upcast by value, and the PyRef::as_super/PyRefMut::as_super methods for upcasting a pyclass that has already been borrowed.

Example: Calling a method defined on the Bound base type

use pyo3::prelude::*;

#[pyclass(subclass)]
struct BaseClass;

trait MyClassMethods<'py> {
    fn pyrepr(&self) -> PyResult<String>;
}
impl<'py> MyClassMethods<'py> for Bound<'py, BaseClass> {
    fn pyrepr(&self) -> PyResult<String> {
        self.call_method0("__repr__")?.extract()
    }
}

#[pyclass(extends = BaseClass)]
struct SubClass;

Python::with_gil(|py| {
    let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
    assert!(obj.as_super().pyrepr().is_ok());
})

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

Returns the GIL token associated with this object.

pub fn as_ptr(&self) -> *mut PyObject

Returns the raw FFI pointer represented by self.

Safety

Callers are responsible for ensuring that the pointer does not outlive self.

The reference is borrowed; callers should not decrease the reference count when they are finished with the pointer.

pub fn as_any(&self) -> &Bound<'py, PyAny>

Helper to cast to Bound<'py, PyAny>.

pub fn as_borrowed<'a>(&'a self) -> Borrowed<'a, 'py, T>

Casts this Bound<T> to a Borrowed<T> smart pointer.

pub fn as_unbound(&self) -> &Py<T>

Removes the connection for this Bound<T> from the GIL, allowing it to cross thread boundaries, without transferring ownership.

pub fn send(&self, value: &Bound<'py, PyAny>) -> PyResult<PySendResult<'py>>

Sends a value into a python generator. This is the equivalent of calling generator.send(value) in Python. This resumes the generator and continues its execution until the next yield or return statement. If the generator exits without returning a value, this function returns a StopException. The first call to send must be made with None as the argument to start the generator, failing to do so will raise a TypeError.

Trait Implementations

impl<'py> Add for Borrowed<'_, 'py, PyComplex>

type Output = Bound<'py, PyComplex>

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self::Output

Performs the + operation.

impl<'a, 'py, T> BoundObject<'py, T> for Borrowed<'a, 'py, T>

type Any = Borrowed<'a, 'py, PyAny>

Type erased version of Self

fn as_borrowed(&self) -> Borrowed<'a, 'py, T>

Borrow this smart pointer.

fn into_bound(self) -> Bound<'py, T>

Turns this smart pointer into an owned [Bound<'py, T>]

fn into_any(self) -> Self::Any

Upcast the target type of this smart pointer

fn into_ptr(self) -> *mut PyObject

Turn this smart pointer into a strong reference pointer

fn as_ptr(&self) -> *mut PyObject

Turn this smart pointer into a borrowed reference pointer

fn unbind(self) -> Py<T>

Turn this smart pointer into an owned Py<T>

impl<T> Clone for Borrowed<'_, '_, T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<'py, T> Deref for Borrowed<'_, 'py, T>

type Target = Bound<'py, T>

The resulting type after dereferencing.

fn deref(&self) -> &Bound<'py, T>

Dereferences the value.

impl<'py> Div for Borrowed<'_, 'py, PyComplex>

type Output = Bound<'py, PyComplex>

The resulting type after applying the / operator.

fn div(self, other: Self) -> Self::Output

Performs the / operation.

impl<'a, 'py, T> From<&'a Bound<'py, T>> for Borrowed<'a, 'py, T>

fn from(instance: &'a Bound<'py, T>) -> Self

Create borrow on a Bound

impl<T> IntoPy<Py<PyAny>> for Borrowed<'_, '_, T>

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

👎Deprecated since 0.23.0: IntoPy is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Converts Py instance -> PyObject.

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

type Target = T

The Python output type

type Output = Borrowed<'a, 'py, <&Borrowed<'a, 'py, T> as IntoPyObject<'py>>::Target>

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.

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

type Target = T

The Python output type

type Output = Borrowed<'a, 'py, <Borrowed<'a, 'py, T> as IntoPyObject<'py>>::Target>

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.

impl<'py> Mul for Borrowed<'_, 'py, PyComplex>

type Output = Bound<'py, PyComplex>

The resulting type after applying the * operator.

fn mul(self, other: Self) -> Self::Output

Performs the * operation.

impl<'py> Neg for Borrowed<'_, 'py, PyComplex>

type Output = Bound<'py, PyComplex>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq<&[u8]> for Borrowed<'_, '_, PyBytes>

Compares whether the Python bytes object is equal to the u8.

In some cases Python equality might be more appropriate; see the note on PyBytes.

fn eq(&self, other: &&[u8]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&bool> for Borrowed<'_, '_, PyBool>

Compare Borrowed<PyBool> with &bool

fn eq(&self, other: &&bool) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&f32> for Borrowed<'_, '_, PyFloat>

fn eq(&self, other: &&f32) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&f64> for Borrowed<'_, '_, PyFloat>

fn eq(&self, other: &&f64) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&str> for Borrowed<'_, '_, PyString>

Compares whether the data in the Python string is equal to the given UTF8.

In some cases Python equality might be more appropriate; see the note on PyString.

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<[u8]> for Borrowed<'_, '_, PyBytes>

Compares whether the Python bytes object is equal to the u8.

In some cases Python equality might be more appropriate; see the note on PyBytes.

fn eq(&self, other: &[u8]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyBool>> for &bool

Compare &bool with Borrowed<PyBool>

fn eq(&self, other: &Borrowed<'_, '_, PyBool>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyBool>> for bool

Compare bool with Borrowed<PyBool>

fn eq(&self, other: &Borrowed<'_, '_, PyBool>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyBytes>> for &[u8]

Compares whether the Python bytes object is equal to the u8.

In some cases Python equality might be more appropriate; see the note on PyBytes.

fn eq(&self, other: &Borrowed<'_, '_, PyBytes>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyBytes>> for [u8]

Compares whether the Python bytes object is equal to the u8.

In some cases Python equality might be more appropriate; see the note on PyBytes.

fn eq(&self, other: &Borrowed<'_, '_, PyBytes>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyFloat>> for &f32

fn eq(&self, other: &Borrowed<'_, '_, PyFloat>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyFloat>> for &f64

fn eq(&self, other: &Borrowed<'_, '_, PyFloat>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyFloat>> for f32

fn eq(&self, other: &Borrowed<'_, '_, PyFloat>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyFloat>> for f64

fn eq(&self, other: &Borrowed<'_, '_, PyFloat>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyString>> for &str

Compares whether the data in the Python string is equal to the given UTF8.

In some cases Python equality might be more appropriate; see the note on PyString.

fn eq(&self, other: &Borrowed<'_, '_, PyString>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Borrowed<'_, '_, PyString>> for str

Compares whether the data in the Python string is equal to the given UTF8.

In some cases Python equality might be more appropriate; see the note on PyString.

fn eq(&self, other: &Borrowed<'_, '_, PyString>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<bool> for Borrowed<'_, '_, PyBool>

Compare Borrowed<PyBool> with bool

fn eq(&self, other: &bool) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<f32> for Borrowed<'_, '_, PyFloat>

fn eq(&self, other: &f32) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<f64> for Borrowed<'_, '_, PyFloat>

fn eq(&self, other: &f64) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Borrowed<'_, '_, PyString>

Compares whether the data in the Python string is equal to the given UTF8.

In some cases Python equality might be more appropriate; see the note on PyString.

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'py> Sub for Borrowed<'_, 'py, PyComplex>

type Output = Bound<'py, PyComplex>

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Self::Output

Performs the - operation.

impl<T> ToPyObject for Borrowed<'_, '_, T>

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

👎Deprecated since 0.23.0: ToPyObject is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Converts Py instance -> PyObject.

impl<T> Copy for Borrowed<'_, '_, T>

impl<'py> PyCallArgs<'py> for Borrowed<'_, 'py, PyTuple>