Struct pyo3::prelude::Bound

source ·

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

Expand description

A GIL-attached equivalent to Py.

Implementations§

source §

impl<'py, T> Bound<'py, T>
where T: PyClass,

source

pub fn new( py: Python<'py>, value: impl Into<PyClassInitializer<T>> ) -> PyResult<Bound<'py, T>>

Creates a new instance Bound<T> of a #[pyclass] on the Python heap.

§Examples

use pyo3::prelude::*;

#[pyclass]
struct Foo {/* fields omitted */}

Python::with_gil(|py| -> PyResult<Py<Foo>> {
    let foo: Bound<'_, Foo> = Bound::new(py, Foo {})?;
    Ok(foo.into())
})?;

source §

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 §

impl<'py, T> Bound<'py, T>

source

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

Returns the GIL token associated with this object.

source

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

Casts this Bound<T> as the corresponding “GIL Ref” type, registering the pointer on the release pool.

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

source §

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

Converts this type into a shared reference of the (usually inferred) input type.

source §

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

source §

fn clone(&self) -> Self

Returns a copy of the value. Read more

Dereferences the value.

source §

fn type_input() -> TypeInfo

Creates an iterator from a value. Read more

source §

impl<'py> IntoIterator for Bound<'py, PySet>

source §

fn into_iter(self) -> Self::IntoIter

Returns an iterator of values in this set.

§Panics

If PyO3 detects that the set is mutated during iteration, it will panic.

§

type Item = Bound<'py, PyAny>

The type of the elements being iterated over.

§

type IntoIter = BoundSetIterator<'py>

Which kind of iterator are we turning this into?

source §

impl<'py> IntoIterator for Bound<'py, PyTuple>

§

type Item = Bound<'py, PyAny>

1.0.0 · source§

fn fuse(self) -> Fuse<Self>
where Self: Sized,

Creates an iterator which ends after the first None. Read more

1.0.0 · source§

fn inspect<F>(self, f: F) -> Inspect<Self, F>
where Self: Sized, F: FnMut(&Self::Item),

Does something with each element of an iterator, passing the value on. Read more

1.0.0 · source§

fn by_ref(&mut self) -> &mut Self
where Self: Sized,

Borrows an iterator, rather than consuming it. Read more

1.0.0 · source§

fn collect(self) -> B
where B: FromIterator<Self::Item>, Self: Sized,

Transforms an iterator into a collection. Read more

source §

fn collect_into<E>(self, collection: &mut E) -> &mut E
where E: Extend<Self::Item>, Self: Sized,

🔬This is a nightly-only experimental API. (iter_collect_into)

Collects all the items from an iterator into a collection. Read more

1.0.0 · source§

fn partition<B, F>(self, f: F) -> (B, B)
where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool,

Consumes an iterator, creating two collections from it. Read more

source §

fn is_partitioned(self, predicate: P) -> bool
where Self: Sized, P: FnMut(Self::Item) -> bool,

🔬This is a nightly-only experimental API. (iter_is_partitioned)

Checks if the elements of this iterator are partitioned according to the given predicate, such that all those that return true precede all those that return false. Read more

1.27.0 · source§

fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R
where Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try<Output = B>,

An iterator method that applies a function as long as it returns successfully, producing a single, final value. Read more

1.27.0 · source§

fn try_for_each<F, R>(&mut self, f: F) -> R
where Self: Sized, F: FnMut(Self::Item) -> R, R: Try<Output = ()>,

An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error. Read more

1.0.0 · source§

fn fold<B, F>(self, init: B, f: F) -> B
where Self: Sized, F: FnMut(B, Self::Item) -> B,

Folds every element into an accumulator by applying an operation, returning the final result. Read more

1.51.0 · source§

fn reduce<F>(self, f: F) -> Option<Self::Item>
where Self: Sized, F: FnMut(Self::Item, Self::Item) -> Self::Item,

Reduces the elements to a single one, by repeatedly applying a reducing operation. Read more

source §

fn try_reduce<F, R>( &mut self, f: F ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
where Self: Sized, F: FnMut(Self::Item, Self::Item) -> R, R: Try<Output = Self::Item>, <R as Try>::Residual: Residual<Option<Self::Item>>,

🔬This is a nightly-only experimental API. (iterator_try_reduce)

Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately. Read more

1.0.0 · source§