pyo3/types/
mod.rs

1//! Various types defined by the Python interpreter such as `int`, `str` and `tuple`.
2
3pub use self::any::{PyAny, PyAnyMethods};
4pub use self::boolobject::{PyBool, PyBoolMethods};
5pub use self::bytearray::{PyByteArray, PyByteArrayMethods};
6pub use self::bytes::{PyBytes, PyBytesMethods};
7pub use self::capsule::{PyCapsule, PyCapsuleMethods};
8pub use self::code::{PyCode, PyCodeInput, PyCodeMethods};
9pub use self::complex::{PyComplex, PyComplexMethods};
10#[allow(deprecated)]
11pub use self::datetime::{
12    timezone_utc, PyDate, PyDateTime, PyDelta, PyTime, PyTzInfo, PyTzInfoAccess,
13};
14#[cfg(not(Py_LIMITED_API))]
15pub use self::datetime::{PyDateAccess, PyDeltaAccess, PyTimeAccess};
16pub use self::dict::{IntoPyDict, PyDict, PyDictMethods};
17#[cfg(not(any(PyPy, GraalPy)))]
18pub use self::dict::{PyDictItems, PyDictKeys, PyDictValues};
19pub use self::ellipsis::PyEllipsis;
20pub use self::float::{PyFloat, PyFloatMethods};
21#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
22pub use self::frame::PyFrame;
23pub use self::frozenset::{PyFrozenSet, PyFrozenSetBuilder, PyFrozenSetMethods};
24pub use self::function::PyCFunction;
25#[cfg(all(not(Py_LIMITED_API), not(all(PyPy, not(Py_3_8)))))]
26pub use self::function::PyFunction;
27#[cfg(Py_3_9)]
28pub use self::genericalias::PyGenericAlias;
29pub use self::iterator::PyIterator;
30pub use self::list::{PyList, PyListMethods};
31pub use self::mapping::{PyMapping, PyMappingMethods};
32pub use self::mappingproxy::PyMappingProxy;
33pub use self::memoryview::PyMemoryView;
34pub use self::module::{PyModule, PyModuleMethods};
35#[cfg(all(not(Py_LIMITED_API), Py_3_13))]
36pub use self::mutex::{PyMutex, PyMutexGuard};
37pub use self::none::PyNone;
38pub use self::notimplemented::PyNotImplemented;
39pub use self::num::PyInt;
40#[cfg(not(any(PyPy, GraalPy)))]
41pub use self::pysuper::PySuper;
42pub use self::range::{PyRange, PyRangeMethods};
43pub use self::sequence::{PySequence, PySequenceMethods};
44pub use self::set::{PySet, PySetMethods};
45pub use self::slice::{PySlice, PySliceIndices, PySliceMethods};
46#[cfg(not(Py_LIMITED_API))]
47pub use self::string::PyStringData;
48pub use self::string::{PyString, PyStringMethods};
49pub use self::traceback::{PyTraceback, PyTracebackMethods};
50pub use self::tuple::{PyTuple, PyTupleMethods};
51pub use self::typeobject::{PyType, PyTypeMethods};
52pub use self::weakref::{PyWeakref, PyWeakrefMethods, PyWeakrefProxy, PyWeakrefReference};
53
54/// Iteration over Python collections.
55///
56/// When working with a Python collection, one approach is to convert it to a Rust collection such
57/// as `Vec` or `HashMap`. However this is a relatively expensive operation. If you just want to
58/// visit all their items, consider iterating over the collections directly:
59///
60/// # Examples
61///
62/// ```rust
63/// use pyo3::prelude::*;
64/// use pyo3::types::PyDict;
65/// use pyo3::ffi::c_str;
66///
67/// # pub fn main() -> PyResult<()> {
68/// Python::attach(|py| {
69///     let dict = py.eval(c_str!("{'a':'b', 'c':'d'}"), None, None)?.cast_into::<PyDict>()?;
70///
71///     for (key, value) in &dict {
72///         println!("key: {}, value: {}", key, value);
73///     }
74///
75///     Ok(())
76/// })
77/// # }
78///  ```
79///
80/// If PyO3 detects that the collection is mutated during iteration, it will panic.
81///
82/// These iterators use Python's C-API directly. However in certain cases, like when compiling for
83/// the Limited API and PyPy, the underlying structures are opaque and that may not be possible.
84/// In these cases the iterators are implemented by forwarding to [`PyIterator`].
85pub mod iter {
86    pub use super::dict::BoundDictIterator;
87    pub use super::frozenset::BoundFrozenSetIterator;
88    pub use super::list::BoundListIterator;
89    pub use super::set::BoundSetIterator;
90    pub use super::tuple::{BorrowedTupleIterator, BoundTupleIterator};
91}
92
93/// Python objects that have a base type.
94///
95/// This marks types that can be upcast into a [`PyAny`] and used in its place.
96/// This essentially includes every Python object except [`PyAny`] itself.
97///
98/// This is used to provide the [`Deref<Target = Bound<'_, PyAny>>`](std::ops::Deref)
99/// implementations for [`Bound<'_, T>`](crate::Bound).
100///
101/// Users should not need to implement this trait directly. It's implementation
102/// is provided by the [`#[pyclass]`](macro@crate::pyclass) attribute.
103///
104/// ## Note
105/// This is needed because the compiler currently tries to figure out all the
106/// types in a deref-chain before starting to look for applicable method calls.
107/// So we need to prevent [`Bound<'_, PyAny`](crate::Bound) dereferencing to
108/// itself in order to avoid running into the recursion limit. This trait is
109/// used to exclude this from our blanket implementation. See [this Rust
110/// issue][1] for more details. If the compiler limitation gets resolved, this
111/// trait will be removed.
112///
113/// [1]: https://github.com/rust-lang/rust/issues/19509
114pub trait DerefToPyAny {
115    // Empty.
116}
117
118// Implementations core to all native types except for PyAny (because they don't
119// make sense on PyAny / have different implementations).
120#[doc(hidden)]
121#[macro_export]
122macro_rules! pyobject_native_type_named (
123    ($name:ty $(;$generics:ident)*) => {
124        impl $crate::types::DerefToPyAny for $name {}
125    };
126);
127
128#[doc(hidden)]
129#[macro_export]
130macro_rules! pyobject_native_static_type_object(
131    ($typeobject:expr) => {
132        |_py| {
133            #[allow(unused_unsafe)] // https://github.com/rust-lang/rust/pull/125834
134            unsafe { ::std::ptr::addr_of_mut!($typeobject) }
135        }
136    };
137);
138
139#[doc(hidden)]
140#[macro_export]
141macro_rules! pyobject_native_type_info(
142    ($name:ty, $typeobject:expr, $module:expr $(, #checkfunction=$checkfunction:path)? $(;$generics:ident)*) => {
143        unsafe impl<$($generics,)*> $crate::type_object::PyTypeInfo for $name {
144            const NAME: &'static str = stringify!($name);
145            const MODULE: ::std::option::Option<&'static str> = $module;
146
147            #[inline]
148            #[allow(clippy::redundant_closure_call)]
149            fn type_object_raw(py: $crate::Python<'_>) -> *mut $crate::ffi::PyTypeObject {
150                $typeobject(py)
151            }
152
153            $(
154                #[inline]
155                fn is_type_of(obj: &$crate::Bound<'_, $crate::PyAny>) -> bool {
156                    #[allow(unused_unsafe)]
157                    unsafe { $checkfunction(obj.as_ptr()) > 0 }
158                }
159            )?
160        }
161
162        impl $name {
163            #[doc(hidden)]
164            pub const _PYO3_DEF: $crate::impl_::pymodule::AddTypeToModule<Self> = $crate::impl_::pymodule::AddTypeToModule::new();
165
166            #[allow(dead_code)]
167            #[doc(hidden)]
168            pub const _PYO3_INTROSPECTION_ID: &'static str = concat!(stringify!($module), stringify!($name));
169        }
170    };
171);
172
173/// Declares all of the boilerplate for Python types.
174#[doc(hidden)]
175#[macro_export]
176macro_rules! pyobject_native_type_core {
177    ($name:ty, $typeobject:expr, #module=$module:expr $(, #checkfunction=$checkfunction:path)? $(;$generics:ident)*) => {
178        $crate::pyobject_native_type_named!($name $(;$generics)*);
179        $crate::pyobject_native_type_info!($name, $typeobject, $module $(, #checkfunction=$checkfunction)? $(;$generics)*);
180    };
181    ($name:ty, $typeobject:expr $(, #checkfunction=$checkfunction:path)? $(;$generics:ident)*) => {
182        $crate::pyobject_native_type_core!($name, $typeobject, #module=::std::option::Option::Some("builtins") $(, #checkfunction=$checkfunction)? $(;$generics)*);
183    };
184}
185
186#[doc(hidden)]
187#[macro_export]
188macro_rules! pyobject_subclassable_native_type {
189    ($name:ty, $layout:path $(;$generics:ident)*) => {
190        #[cfg(not(Py_LIMITED_API))]
191        impl<$($generics,)*> $crate::impl_::pyclass::PyClassBaseType for $name {
192            type LayoutAsBase = $crate::impl_::pycell::PyClassObjectBase<$layout>;
193            type BaseNativeType = $name;
194            type Initializer = $crate::impl_::pyclass_init::PyNativeTypeInitializer<Self>;
195            type PyClassMutability = $crate::pycell::impl_::ImmutableClass;
196        }
197    }
198}
199
200#[doc(hidden)]
201#[macro_export]
202macro_rules! pyobject_native_type_sized {
203    ($name:ty, $layout:path $(;$generics:ident)*) => {
204        unsafe impl $crate::type_object::PyLayout<$name> for $layout {}
205        impl $crate::type_object::PySizedLayout<$name> for $layout {}
206    };
207}
208
209/// Declares all of the boilerplate for Python types which can be inherited from (because the exact
210/// Python layout is known).
211#[doc(hidden)]
212#[macro_export]
213macro_rules! pyobject_native_type {
214    ($name:ty, $layout:path, $typeobject:expr $(, #module=$module:expr)? $(, #checkfunction=$checkfunction:path)? $(;$generics:ident)*) => {
215        $crate::pyobject_native_type_core!($name, $typeobject $(, #module=$module)? $(, #checkfunction=$checkfunction)? $(;$generics)*);
216        // To prevent inheriting native types with ABI3
217        #[cfg(not(Py_LIMITED_API))]
218        $crate::pyobject_native_type_sized!($name, $layout $(;$generics)*);
219    };
220}
221
222pub(crate) mod any;
223pub(crate) mod boolobject;
224pub(crate) mod bytearray;
225pub(crate) mod bytes;
226pub(crate) mod capsule;
227mod code;
228pub(crate) mod complex;
229pub(crate) mod datetime;
230pub(crate) mod dict;
231mod ellipsis;
232pub(crate) mod float;
233#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
234mod frame;
235pub(crate) mod frozenset;
236mod function;
237#[cfg(Py_3_9)]
238pub(crate) mod genericalias;
239pub(crate) mod iterator;
240pub(crate) mod list;
241pub(crate) mod mapping;
242pub(crate) mod mappingproxy;
243mod memoryview;
244pub(crate) mod module;
245#[cfg(all(not(Py_LIMITED_API), Py_3_13))]
246mod mutex;
247mod none;
248mod notimplemented;
249mod num;
250#[cfg(not(any(PyPy, GraalPy)))]
251mod pysuper;
252pub(crate) mod range;
253pub(crate) mod sequence;
254pub(crate) mod set;
255pub(crate) mod slice;
256pub(crate) mod string;
257pub(crate) mod traceback;
258pub(crate) mod tuple;
259pub(crate) mod typeobject;
260pub(crate) mod weakref;
pyo3/types/mod.rs

pyo3/types/
mod.rs
