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

pyo3/types/
mod.rs
