Struct pyo3 :: prelude :: Bound Copy item path

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

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 */}

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

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

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

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

Returns the GIL token associated with this object.

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

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

Available on crate feature gil-refs only.

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.

Available on crate feature gil-refs only.

Extracts Self from the source GIL Ref obj. Read more

fn type_input() -> TypeInfo

Creates an iterator from a value. Read more

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

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?

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

type Item = Bound<'py, PyAny>

The type of the elements being iterated over.

type IntoIter = BoundTupleIterator<'py>

Which kind of iterator are we turning this into?

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as a return value. Read more

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

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

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

fn try_reduce<R>( &mut self, f: impl FnMut(Self::Item, Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
where Self: Sized, 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§

fn all<F>(&mut self, f: F) -> bool
where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if every element of the iterator matches a predicate. Read more

1.0.0 · source§

fn any<F>(&mut self, f: F) -> bool
where Self: Sized, F: FnMut(Self::Item) -> bool,

Tests if any element of the iterator matches a predicate. Read more

1.0.0 · source§

fn find(&mut self, predicate: P) -> Option<Self::Item>
where Self: Sized, P: FnMut(&Self::Item) -> bool,

Searches for an element of an iterator that satisfies a predicate. Read more

1.30.0 · source§

fn find_map<B, F>(&mut self, f: F) -> Option
where Self: Sized, F: FnMut(Self::Item) -> Option,

Applies function to the elements of iterator and returns the first non-none result. Read more

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

fn cycle(self) -> Cycle<Self>
where Self: Sized + Clone,

Repeats an iterator endlessly. Read more

fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N>
where Self: Sized,

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

Returns an iterator over N elements of the iterator at a time. Read more

1.11.0 · source§

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

Checks if the elements of this iterator are sorted using the given comparator function. Read more

fn is_sorted_by_key<F, K>(self, f: F) -> bool
where Self: Sized, F: FnMut(Self::Item) -> K, K: PartialOrd,

Determines if self contains value. Read more

fn py_super(&self) -> PyResult<Bound<'py, PySuper>>

Available on neither PyPy nor GraalPy.

fn data(&self) -> *mut u8

Gets the start of the buffer containing the contents of the bytearray. Read more

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

Extracts a slice of the ByteArray’s entire buffer. Read more

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

Extracts a mutable slice of the ByteArray’s entire buffer. Read more

fn to_vec(&self) -> Vec<u8> ⓘ

Copies the contents of the bytearray to a Rust vector. Read more

Gets the current context stored in the capsule. If there is no context, the pointer will be null. Read more

unsafe fn reference<T>(&self) -> &'py T

Obtains a reference to the value of this capsule. Read more

fn pointer(&self) -> *mut c_void

Gets the raw c_void pointer to the value in this capsule. Read more

fn is_valid(&self) -> bool

Checks if this is a valid capsule. Read more

fn name(&self) -> PyResult<Option<&'py CStr>>

Retrieves the name of this capsule, if set. Read more

impl<'py> PyComplexMethods<'py> for Bound<'py, PyComplex>

fn real(&self) -> c_double

Returns the real part of the complex number.

Determines if the set contains the specified key. Read more

fn iter(&self) -> BoundFrozenSetIterator<'py> ⓘ

Returns an iterator of values in this set.

fn is_empty(&self) -> bool

Checks if set is empty.

impl<'py> PyListMethods<'py> for Bound<'py, PyList>

fn len(&self) -> usize

Returns the length of the list.

fn is_empty(&self) -> bool

Checks if the list is empty.

fn as_sequence(&self) -> &Bound<'py, PySequence>

Returns self cast as a PySequence.

fn into_sequence(self) -> Bound<'py, PySequence>

Returns self cast as a PySequence.

fn get_item(&self, index: usize) -> PyResult<Bound<'py, PyAny>>

Gets the list item at the specified index.

§Example

use pyo3::{prelude::*, types::PyList};
Python::with_gil(|py| {
    let list = PyList::new_bound(py, [2, 3, 5, 7]);
    let obj = list.get_item(0);
    assert_eq!(obj.unwrap().extract::<i32>().unwrap(), 2);
});

unsafe fn get_item_unchecked(&self, index: usize) -> Bound<'py, PyAny>

Available on non-Py_LIMITED_API only.

Gets the list item at the specified index. Undefined behavior on bad index. Use with caution.

Appends an item to the list.

fn insert(&self, index: usize, item: I) -> PyResult<()>
where I: ToPyObject,

Inserts an item at the specified index.

If index >= self.len(), inserts at the end.

fn contains<V>(&self, value: V) -> PyResult<bool>
where V: ToPyObject,

Determines if self contains value.

This is equivalent to the Python expression value in self.

fn index<V>(&self, value: V) -> PyResult<usize>
where V: ToPyObject,

Returns the first index i for which self[i] == value.

This is equivalent to the Python expression self.index(value).

fn iter(&self) -> BoundListIterator<'py> ⓘ

fn count<V>(&self, value: V) -> PyResult<usize>
where V: ToPyObject,

Available on non-PyPy only.

Returns the number of occurrences of value in self, that is, return the number of keys for which self[key] == value.

fn contains<V>(&self, value: V) -> PyResult<bool>
where V: ToPyObject,

Determines if self contains value. Read more

fn index<V>(&self, value: V) -> PyResult<usize>
where V: ToPyObject,

Returns the first index i for which self[i] == value. Read more

fn to_list(&self) -> PyResult<Bound<'py, PyList>>

Returns a fresh list based on the Sequence.

fn to_tuple(&self) -> PyResult<Bound<'py, PyTuple>>

Returns a fresh tuple based on the Sequence.

fn to_cow(&self) -> PyResult<Cow<'_, str>>

Converts the PyString into a Rust string, avoiding copying when possible. Read more

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

Converts the PyString into a Rust string. Read more

fn encode_utf8(&self) -> PyResult<Bound<'py, PyBytes>>

Encodes this string as a Python bytes object, using UTF-8 encoding.

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

Available on neither Py_LIMITED_API nor GraalPy nor PyPy.

Determines if self contains value. Read more

fn index<V>(&self, value: V) -> PyResult<usize>
where V: ToPyObject,

Returns the first index i for which self[i] == value. Read more

fn iter(&self) -> BoundTupleIterator<'py> ⓘ

Returns an iterator over the tuple items.

fn iter_borrowed<'a>(&'a self) -> BorrowedTupleIterator<'a, 'py> ⓘ

Like iter, but produces an iterator which returns borrowed objects, which is a slight performance optimization by avoiding a reference count change.

fn to_list(&self) -> Bound<'py, PyList>

Return a new list containing the contents of this tuple; equivalent to the Python expression list(tuple). Read more

Return the method resolution order for this type. Read more

fn bases(&self) -> Bound<'py, PyTuple>

Return Python bases Read more

impl<'py> PyTzInfoAccess<'py> for Bound<'py, PyDateTime>

Available on non-Py_LIMITED_API only.

fn get_tzinfo_bound(&self) -> Option<Bound<'py, PyTzInfo>>

Returns the tzinfo (which may be None). Read more

fn get_tzinfo(&self) -> Option<&'py PyTzInfo>

👎Deprecated since 0.21.0: get_tzinfo will be replaced by get_tzinfo_bound in a future PyO3 version

Available on crate feature gil-refs only.

Deprecated form of get_tzinfo_bound.

impl<'py> PyTzInfoAccess<'py> for Bound<'py, PyTime>

Available on non-Py_LIMITED_API only.

Retrieve to a Bound object pointed to by the weakref. Read more

Retrieve to a Bound object pointed to by the weakref. Read more

The type returned in the event of a conversion error.

impl<'py> TryFrom<&Bound<'py, PyAny>> for Bound<'py, PyMemoryView>

fn try_from(value: &Bound<'py, PyAny>) -> Result<Self, Self::Error>

Creates a new Python memoryview object from another Python object that implements the buffer protocol.

impl<'py, T> FromPyObjectBound<'_, 'py> for T
where T: FromPyObject<'py>,

fn from_py_object_bound(ob: Borrowed<'_, 'py, PyAny>) -> Result<T, PyErr>

Extracts Self from the bound smart pointer obj. Read more

fn type_input() -> TypeInfo

Available on crate feature experimental-inspect only.

Extracts the type hint information for this type when it appears as an argument. Read more

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

impl IntoIterator for I
where I: Iterator,

type Item = ::Item

The type of the elements being iterated over.

type IntoIter = I

Which kind of iterator are we turning this into?

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

Performs the conversion.

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

type Error = >::Error

The type returned in the event of a conversion error.