type Dict<'py> = Bound<'py, PyDict>;
Aliased Type§
struct Dict<'py>(/* private fields */);
Implementations
§impl<'py, T> Bound<'py, T>
impl<'py, T> Bound<'py, T>
pub fn py(&self) -> Python<'py>
pub fn py(&self) -> Python<'py>
Returns the GIL token associated with this object.
pub 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.
pub fn into_ptr(self) -> *mut PyObject
pub fn into_ptr(self) -> *mut PyObject
Returns an owned raw FFI pointer represented by self.
§Safety
The reference is owned; when finished the caller should either transfer ownership
of the pointer or decrease the reference count (e.g. with pyo3::ffi::Py_DecRef
).
pub fn as_any(&self) -> &Bound<'py, PyAny>
pub fn as_any(&self) -> &Bound<'py, PyAny>
Helper to cast to Bound<'py, PyAny>
.
pub fn into_any(self) -> Bound<'py, PyAny>
pub fn into_any(self) -> Bound<'py, PyAny>
Helper to cast to Bound<'py, PyAny>
, transferring ownership.
pub 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.
pub fn unbind(self) -> Py<T>
pub fn unbind(self) -> Py<T>
Removes the connection for this Bound<T>
from the GIL, allowing
it to cross thread boundaries.
pub 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.
§impl<'py, T> Bound<'py, T>where
T: PyClass,
impl<'py, T> Bound<'py, T>where
T: PyClass,
pub 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
][Self::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>,
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>
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
][Self::get] is available.
pub fn try_borrow_mut(&self) -> Result<PyRefMut<'py, T>, PyBorrowMutError>where
T: PyClass<Frozen = False>,
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) -> &Twhere
T: PyClass<Frozen = True> + Sync,
pub fn get(&self) -> &Twhere
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
][macro@crate::pyclass] 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 as PyClassImpl>::BaseType>
pub fn as_super(&self) -> &Bound<'py, <T as PyClassImpl>::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 fn into_super(self) -> Bound<'py, <T as PyClassImpl>::BaseType>
pub fn into_super(self) -> Bound<'py, <T as PyClassImpl>::BaseType>
Upcast this Bound<PyClass>
to its base type by value.
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 into_any
).
This method is particularly useful for calling methods defined in an
extension trait that has been implemented for Bound<BaseType>
.
See also the as_super
method to upcast by reference, and the
[PyRef::into_super
]/[PyRefMut::into_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.into_super().pyrepr().is_ok());
})
§impl<'py, T> Bound<'py, T>where
T: PyClass,
impl<'py, T> Bound<'py, T>where
T: PyClass,
pub fn new(
py: Python<'py>,
value: impl Into<PyClassInitializer<T>>,
) -> Result<Bound<'py, T>, PyErr>
pub fn new( py: Python<'py>, value: impl Into<PyClassInitializer<T>>, ) -> Result<Bound<'py, T>, PyErr>
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())
})?;
Trait Implementations
§impl<T> AsPyPointer for Bound<'_, T>
impl<T> AsPyPointer for Bound<'_, T>
§impl<'py, T> BoundObject<'py, T> for Bound<'py, T>
impl<'py, T> BoundObject<'py, T> for Bound<'py, T>
§fn as_borrowed(&self) -> Borrowed<'_, 'py, T>
fn as_borrowed(&self) -> Borrowed<'_, 'py, T>
§fn into_bound(self) -> Bound<'py, T>
fn into_bound(self) -> Bound<'py, T>
Bound<'py, T>
]§impl<'py, T> FromPyObject<'py> for Bound<'py, T>where
T: PyTypeCheck,
impl<'py, T> FromPyObject<'py> for Bound<'py, T>where
T: PyTypeCheck,
§fn extract_bound(ob: &Bound<'py, PyAny>) -> Result<Bound<'py, T>, PyErr>
fn extract_bound(ob: &Bound<'py, PyAny>) -> Result<Bound<'py, T>, PyErr>
Extracts Self
from the source PyObject
.
§fn type_input() -> TypeInfo
fn type_input() -> TypeInfo
§impl<'py> IntoIterator for Bound<'py, PyDict>
impl<'py> IntoIterator for Bound<'py, PyDict>
§impl<T> IntoPy<Py<PyAny>> for Bound<'_, T>
impl<T> IntoPy<Py<PyAny>> for Bound<'_, T>
§impl<'py, T> IntoPyObject<'py> for Bound<'py, T>
impl<'py, T> IntoPyObject<'py> for Bound<'py, T>
§type Output = Bound<'py, <Bound<'py, T> as IntoPyObject<'py>>::Target>
type Output = Bound<'py, <Bound<'py, T> as IntoPyObject<'py>>::Target>
§type Error = Infallible
type Error = Infallible
§fn into_pyobject(
self,
_py: Python<'py>,
) -> Result<<Bound<'py, T> as IntoPyObject<'py>>::Output, <Bound<'py, T> as IntoPyObject<'py>>::Error>
fn into_pyobject( self, _py: Python<'py>, ) -> Result<<Bound<'py, T> as IntoPyObject<'py>>::Output, <Bound<'py, T> as IntoPyObject<'py>>::Error>
§fn type_output() -> TypeInfo
fn type_output() -> TypeInfo
§#[doc(hidden)] fn owned_sequence_into_pyobject<I>(
iter: I,
py: Python<'py>,
_: Token,
) -> Result<Bound<'py, PyAny>, PyErr>where
I: IntoIterator<Item = Self> + AsRef<[Self]>,
<I as IntoIterator>::IntoIter: ExactSizeIterator<Item = Self>,
#[doc(hidden)] fn owned_sequence_into_pyobject<I>(
iter: I,
py: Python<'py>,
_: Token,
) -> Result<Bound<'py, PyAny>, PyErr>where
I: IntoIterator<Item = Self> + AsRef<[Self]>,
<I as IntoIterator>::IntoIter: ExactSizeIterator<Item = Self>,
Vec<u8>
, [u8; N]
and SmallVec<[u8; N]>
as a sequence of bytes into a bytes
object.§#[doc(hidden)] fn borrowed_sequence_into_pyobject<I>(
iter: I,
py: Python<'py>,
_: Token,
) -> Result<Bound<'py, PyAny>, PyErr>where
Self: Reference,
I: IntoIterator<Item = Self> + AsRef<[Self::BaseType]>,
<I as IntoIterator>::IntoIter: ExactSizeIterator<Item = Self>,
#[doc(hidden)] fn borrowed_sequence_into_pyobject<I>(
iter: I,
py: Python<'py>,
_: Token,
) -> Result<Bound<'py, PyAny>, PyErr>where
Self: Reference,
I: IntoIterator<Item = Self> + AsRef<[Self::BaseType]>,
<I as IntoIterator>::IntoIter: ExactSizeIterator<Item = Self>,
&[u8]
and Cow<[u8]>
as a sequence of bytes into a bytes
object.§impl<'py> PyDictMethods<'py> for Bound<'py, PyDict>
impl<'py> PyDictMethods<'py> for Bound<'py, PyDict>
§fn copy(&self) -> Result<Bound<'py, PyDict>, PyErr>
fn copy(&self) -> Result<Bound<'py, PyDict>, PyErr>
§fn contains<K>(&self, key: K) -> Result<bool, PyErr>where
K: IntoPyObject<'py>,
fn contains<K>(&self, key: K) -> Result<bool, PyErr>where
K: IntoPyObject<'py>,
§fn get_item<K>(&self, key: K) -> Result<Option<Bound<'py, PyAny>>, PyErr>where
K: IntoPyObject<'py>,
fn get_item<K>(&self, key: K) -> Result<Option<Bound<'py, PyAny>>, PyErr>where
K: IntoPyObject<'py>,
§fn set_item<K, V>(&self, key: K, value: V) -> Result<(), PyErr>where
K: IntoPyObject<'py>,
V: IntoPyObject<'py>,
fn set_item<K, V>(&self, key: K, value: V) -> Result<(), PyErr>where
K: IntoPyObject<'py>,
V: IntoPyObject<'py>,
§fn del_item<K>(&self, key: K) -> Result<(), PyErr>where
K: IntoPyObject<'py>,
fn del_item<K>(&self, key: K) -> Result<(), PyErr>where
K: IntoPyObject<'py>,
§fn iter(&self) -> BoundDictIterator<'py>
fn iter(&self) -> BoundDictIterator<'py>
(key, value)
pairs in this dictionary. Read more§fn locked_for_each<F>(&self, f: F) -> Result<(), PyErr>
fn locked_for_each<F>(&self, f: F) -> Result<(), PyErr>
§fn as_mapping(&self) -> &Bound<'py, PyMapping>
fn as_mapping(&self) -> &Bound<'py, PyMapping>
self
cast as a PyMapping
.§fn into_mapping(self) -> Bound<'py, PyMapping>
fn into_mapping(self) -> Bound<'py, PyMapping>
self
cast as a PyMapping
.