pub struct BoundRef<'a, 'py, T>(pub &'a Bound<'py, T>);
Expand description
Used in #[classmethod]
to pass the class object to the method
and also in #[pyfunction(pass_module)]
.
This is a wrapper to avoid implementing From<Bound>
for GIL Refs.
Once the GIL Ref API is fully removed, it should be possible to simplify
this to just &'a Bound<'py, T>
and From
implementations.
Tuple Fields§
§0: &'a Bound<'py, T>
Implementations§
Source§impl<'a, 'py> BoundRef<'a, 'py, PyAny>
impl<'a, 'py> BoundRef<'a, 'py, PyAny>
pub unsafe fn ref_from_ptr(py: Python<'py>, ptr: &'a *mut PyObject) -> Self
pub unsafe fn ref_from_ptr_or_opt( py: Python<'py>, ptr: &'a *mut PyObject, ) -> Option<Self>
pub fn downcast<T: PyTypeCheck>( self, ) -> Result<BoundRef<'a, 'py, T>, DowncastError<'a, 'py>>
pub unsafe fn downcast_unchecked<T>(self) -> BoundRef<'a, 'py, T>
Methods from Deref<Target = Bound<'py, T>>§
Sourcepub fn borrow(&self) -> PyRef<'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
.
Sourcepub fn borrow_mut(&self) -> PyRefMut<'py, T>
pub fn borrow_mut(&self) -> PyRefMut<'py, T>
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
.
Sourcepub fn try_borrow(&self) -> Result<PyRef<'py, T>, PyBorrowError>
pub fn try_borrow(&self) -> Result<PyRef<'py, T>, PyBorrowError>
Sourcepub fn try_borrow_mut(&self) -> Result<PyRefMut<'py, T>, PyBorrowMutError>
pub fn try_borrow_mut(&self) -> Result<PyRefMut<'py, T>, PyBorrowMutError>
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
.
Sourcepub fn get(&self) -> &T
pub fn get(&self) -> &T
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);
});
Sourcepub fn as_super(&self) -> &Bound<'py, T::BaseType>
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 borrow
ed.
§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(crate) fn get_class_object(&self) -> &PyClassObject<T>
Sourcepub fn as_ptr(&self) -> *mut PyObject
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.
Sourcepub fn as_borrowed<'a>(&'a self) -> Borrowed<'a, 'py, T>
pub fn as_borrowed<'a>(&'a self) -> Borrowed<'a, 'py, T>
Casts this Bound<T>
to a Borrowed<T>
smart pointer.
Sourcepub fn as_unbound(&self) -> &Py<T>
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.
Trait Implementations§
Auto Trait Implementations§
impl<'a, 'py, T> Freeze for BoundRef<'a, 'py, T>
impl<'a, 'py, T> RefUnwindSafe for BoundRef<'a, 'py, T>where
T: RefUnwindSafe,
impl<'a, 'py, T> !Send for BoundRef<'a, 'py, T>
impl<'a, 'py, T> !Sync for BoundRef<'a, 'py, T>
impl<'a, 'py, T> Unpin for BoundRef<'a, 'py, T>
impl<'a, 'py, T> UnwindSafe for BoundRef<'a, 'py, T>where
T: RefUnwindSafe,
Blanket Implementations§
Source§impl<T> AssertNotZeroSized for T
impl<T> AssertNotZeroSized for T
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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 moreSource§impl<T> SizedTypeProperties for T
impl<T> SizedTypeProperties for T
Source§#[doc(hidden)] const IS_ZST: bool = _
#[doc(hidden)] const IS_ZST: bool = _
sized_type_properties
)Source§#[doc(hidden)] const LAYOUT: Layout = _
#[doc(hidden)] const LAYOUT: Layout = _
sized_type_properties
)Source§#[doc(hidden)] const MAX_SLICE_LEN: usize = _
#[doc(hidden)] const MAX_SLICE_LEN: usize = _
sized_type_properties
)[Self]
. Read more