Struct pyo3::instance::Borrowed

source ·
#[repr(transparent)]
pub struct Borrowed<'a, 'py, T>(NonNull<PyObject>, PhantomData<&'a Py<T>>, Python<'py>);
Expand description

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).

Tuple Fields§

§0: NonNull<PyObject>§1: PhantomData<&'a Py<T>>§2: Python<'py>

Implementations§

source§

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

source

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_bound(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(())
})
source§

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

source

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.
source

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.
source

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.
source

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

§Safety

This is similar to std::slice::from_raw_parts, the lifetime 'a is completely defined by the caller and it’s the caller’s responsibility to ensure that the reference this is derived from is valid for the lifetime 'a.

source

pub(crate) fn downcast<T>( self ) -> Result<Borrowed<'a, 'py, T>, DowncastError<'a, 'py>>
where T: PyTypeCheck,

Available on non-crate feature gil-refs only.
source

pub(crate) unsafe fn downcast_unchecked<T>(self) -> Borrowed<'a, 'py, T>

Converts this PyAny to a concrete Python type without checking validity.

§Safety

Callers must ensure that the type is valid or risk type confusion.

source§

impl<'py, T> Borrowed<'py, 'py, T>
where T: HasPyGilRef,

source

pub(crate) fn into_gil_ref(self) -> &'py T::AsRefTarget

source§

impl<'a> Borrowed<'a, '_, PyByteArray>

source

fn data(&self) -> *mut u8

source

unsafe fn as_bytes(self) -> &'a [u8]

source

unsafe fn as_bytes_mut(self) -> &'a mut [u8]

source§

impl<'a> Borrowed<'a, '_, PyBytes>

source

pub(crate) fn as_bytes(self) -> &'a [u8]

Gets the Python string as a byte slice.

source§

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

source

pub(crate) unsafe fn iter_borrowed(self) -> BorrowedDictIter<'a, 'py>

Iterates over the contents of this dictionary without incrementing reference counts.

§Safety

It must be known that this dictionary will not be modified during iteration.

source§

impl<'py> Borrowed<'_, 'py, PyIterator>

source

fn next(self) -> Option<PyResult<Bound<'py, PyAny>>>

source§

impl<'a> Borrowed<'a, '_, PyString>

source

pub(crate) fn to_str(self) -> PyResult<&'a str>

Available on Py_3_10 or non-Py_LIMITED_API only.
source

pub(crate) fn to_cow(self) -> PyResult<Cow<'a, str>>

source

fn to_string_lossy(self) -> Cow<'a, str>

source

unsafe fn data(self) -> PyResult<PyStringData<'a>>

Available on neither Py_LIMITED_API nor GraalPy nor PyPy.
source§

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

source

fn get_borrowed_item(self, index: usize) -> PyResult<Borrowed<'a, 'py, PyAny>>

source

unsafe fn get_borrowed_item_unchecked( self, index: usize ) -> Borrowed<'a, 'py, PyAny>

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.
source

pub(crate) fn iter_borrowed(self) -> BorrowedTupleIterator<'a, 'py>

source§

impl<'a> Borrowed<'a, '_, PyType>

source

fn name(self) -> PyResult<Cow<'a, str>>

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

source

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.

source

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.

source

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.

source

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.

source

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);
});
source

pub(crate) fn get_class_object(&self) -> &PyClassObject<T>

source

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

Returns the GIL token associated with this object.

source

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.

source

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

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

source

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

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

source

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.

source

pub fn as_gil_ref(&'py self) -> &'py T::AsRefTarget
where T: HasPyGilRef,

Casts this Bound<T> as the corresponding “GIL Ref” type.

This is a helper to be used for migration from the deprecated “GIL Refs” API.

source

pub(crate) fn lookup_special<N>( &self, attr_name: N ) -> PyResult<Option<Bound<'py, PyAny>>>
where N: IntoPy<Py<PyString>>,

Retrieve an attribute value, skipping the instance dictionary during the lookup but still binding the object to the instance.

This is useful when trying to resolve Python’s “magic” methods like __getitem__, which are looked up starting from the type object. This returns an Option as it is not typically a direct error for the special lookup to fail, as magic methods are optional in many situations in which they might be called.

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern attr_name.

Trait Implementations§

source§

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

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.
§

type Output = Bound<'py, PyComplex>

The resulting type after applying the + operator.
source§

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

Performs the + operation. Read more
source§

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

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

§

type Target = Bound<'py, T>

The resulting type after dereferencing.
source§

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

Dereferences the value.
source§

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

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.
§

type Output = Bound<'py, PyComplex>

The resulting type after applying the / operator.
source§

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

Performs the / operation. Read more
source§

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

source§

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

Create borrow on a Bound

source§

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

source§

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

Converts Py instance -> PyObject.

source§

fn type_output() -> TypeInfo

Available on crate feature experimental-inspect only.
Extracts the type hint information for this type when it appears as a return value. Read more
source§

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

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.
§

type Output = Bound<'py, PyComplex>

The resulting type after applying the * operator.
source§

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

Performs the * operation. Read more
source§

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

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.
§

type Output = Bound<'py, PyComplex>

The resulting type after applying the - operator.
source§

fn neg(self) -> Self::Output

Performs the unary - operation. Read more
source§

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

Available on neither Py_LIMITED_API nor PyPy nor GraalPy.
§

type Output = Bound<'py, PyComplex>

The resulting type after applying the - operator.
source§

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

Performs the - operation. Read more
source§

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

source§

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

Converts Py instance -> PyObject.

source§

impl<'py> WrapPyFunctionArg<'py, Bound<'py, PyCFunction>> for &Borrowed<'_, 'py, PyModule>

source§

fn wrap_pyfunction( self, method_def: &PyMethodDef ) -> PyResult<Bound<'py, PyCFunction>>

source§

impl<'py> WrapPyFunctionArg<'py, Bound<'py, PyCFunction>> for Borrowed<'_, 'py, PyModule>

source§

fn wrap_pyfunction( self, method_def: &PyMethodDef ) -> PyResult<Bound<'py, PyCFunction>>

source§

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

Auto Trait Implementations§

§

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

§

impl<'a, 'py, T> RefUnwindSafe for Borrowed<'a, 'py, T>
where T: RefUnwindSafe,

§

impl<'a, 'py, T> !Send for Borrowed<'a, 'py, T>

§

impl<'a, 'py, T> !Sync for Borrowed<'a, 'py, T>

§

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

§

impl<'a, 'py, T> UnwindSafe for Borrowed<'a, 'py, T>
where T: RefUnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> AssertNotZeroSized for T

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> IntoPyCallbackOutput<*mut PyObject> for T
where T: IntoPy<Py<PyAny>>,

source§

impl<T> IntoPyCallbackOutput<Py<PyAny>> for T
where T: IntoPy<Py<PyAny>>,

source§

fn convert(self, py: Python<'_>) -> Result<Py<PyAny>, PyErr>

source§

impl<T> OkWrap<T> for T
where T: IntoPy<Py<PyAny>>,

source§

impl<T> SizedTypeProperties for T

source§

#[doc(hidden)] const IS_ZST: bool = _

🔬This is a nightly-only experimental API. (sized_type_properties)
true if this type requires no storage. false if its size is greater than zero. Read more
source§

impl<T> SomeWrap<T> for T

source§

fn wrap(self) -> Option<T>

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> Printable for T
where T: Copy + Debug,

⚠️ Internal Docs ⚠️ Not Public API 👉 Official Docs Here