pyo3/
conversion.rs

Help
1//! Defines conversions between Rust and Python types.
2use crate::err::PyResult;
3#[cfg(feature = "experimental-inspect")]
4use crate::inspect::types::TypeInfo;
5use crate::pyclass::boolean_struct::False;
6use crate::types::any::PyAnyMethods;
7use crate::types::PyTuple;
8use crate::{
9    ffi, Borrowed, Bound, BoundObject, Py, PyAny, PyClass, PyErr, PyRef, PyRefMut, Python,
10};
11use std::convert::Infallible;
12
13/// Returns a borrowed pointer to a Python object.
14///
15/// The returned pointer will be valid for as long as `self` is. It may be null depending on the
16/// implementation.
17///
18/// # Examples
19///
20/// ```rust
21/// use pyo3::prelude::*;
22/// use pyo3::ffi;
23///
24/// Python::with_gil(|py| {
25///     let s = "foo".into_pyobject(py)?;
26///     let ptr = s.as_ptr();
27///
28///     let is_really_a_pystring = unsafe { ffi::PyUnicode_CheckExact(ptr) };
29///     assert_eq!(is_really_a_pystring, 1);
30/// #   Ok::<_, PyErr>(())
31/// })
32/// # .unwrap();
33/// ```
34///
35/// # Safety
36///
37/// For callers, it is your responsibility to make sure that the underlying Python object is not dropped too
38/// early. For example, the following code will cause undefined behavior:
39///
40/// ```rust,no_run
41/// # use pyo3::prelude::*;
42/// # use pyo3::ffi;
43/// #
44/// Python::with_gil(|py| {
45///     // ERROR: calling `.as_ptr()` will throw away the temporary object and leave `ptr` dangling.
46///     let ptr: *mut ffi::PyObject = 0xabad1dea_u32.into_pyobject(py)?.as_ptr();
47///
48///     let isnt_a_pystring = unsafe {
49///         // `ptr` is dangling, this is UB
50///         ffi::PyUnicode_CheckExact(ptr)
51///     };
52/// #   assert_eq!(isnt_a_pystring, 0);
53/// #   Ok::<_, PyErr>(())
54/// })
55/// # .unwrap();
56/// ```
57///
58/// This happens because the pointer returned by `as_ptr` does not carry any lifetime information
59/// and the Python object is dropped immediately after the `0xabad1dea_u32.into_pyobject(py).as_ptr()`
60/// expression is evaluated. To fix the problem, bind Python object to a local variable like earlier
61/// to keep the Python object alive until the end of its scope.
62///
63/// Implementors must ensure this returns a valid pointer to a Python object, which borrows a reference count from `&self`.
64pub unsafe trait AsPyPointer {
65    /// Returns the underlying FFI pointer as a borrowed pointer.
66    fn as_ptr(&self) -> *mut ffi::PyObject;
67}
68
69/// Defines a conversion from a Rust type to a Python object, which may fail.
70///
71/// This trait has `#[derive(IntoPyObject)]` to automatically implement it for simple types and
72/// `#[derive(IntoPyObjectRef)]` to implement the same for references.
73///
74/// It functions similarly to std's [`TryInto`] trait, but requires a [GIL token](Python)
75/// as an argument.
76///
77/// The [`into_pyobject`][IntoPyObject::into_pyobject] method is designed for maximum flexibility and efficiency; it
78///  - allows for a concrete Python type to be returned (the [`Target`][IntoPyObject::Target] associated type)
79///  - allows for the smart pointer containing the Python object to be either `Bound<'py, Self::Target>` or `Borrowed<'a, 'py, Self::Target>`
80///    to avoid unnecessary reference counting overhead
81///  - allows for a custom error type to be returned in the event of a conversion error to avoid
82///    unnecessarily creating a Python exception
83///
84/// # See also
85///
86/// - The [`IntoPyObjectExt`] trait, which provides convenience methods for common usages of
87///   `IntoPyObject` which erase type information and convert errors to `PyErr`.
88#[cfg_attr(
89    diagnostic_namespace,
90    diagnostic::on_unimplemented(
91        message = "`{Self}` cannot be converted to a Python object",
92        note = "`IntoPyObject` is automatically implemented by the `#[pyclass]` macro",
93        note = "if you do not wish to have a corresponding Python type, implement it manually",
94        note = "if you do not own `{Self}` you can perform a manual conversion to one of the types in `pyo3::types::*`"
95    )
96)]
97pub trait IntoPyObject<'py>: Sized {
98    /// The Python output type
99    type Target;
100    /// The smart pointer type to use.
101    ///
102    /// This will usually be [`Bound<'py, Target>`], but in special cases [`Borrowed<'a, 'py, Target>`] can be
103    /// used to minimize reference counting overhead.
104    type Output: BoundObject<'py, Self::Target>;
105    /// The type returned in the event of a conversion error.
106    type Error: Into<PyErr>;
107
108    /// Performs the conversion.
109    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error>;
110
111    /// Extracts the type hint information for this type when it appears as a return value.
112    ///
113    /// For example, `Vec<u32>` would return `List[int]`.
114    /// The default implementation returns `Any`, which is correct for any type.
115    ///
116    /// For most types, the return value for this method will be identical to that of [`FromPyObject::type_input`].
117    /// It may be different for some types, such as `Dict`, to allow duck-typing: functions return `Dict` but take `Mapping` as argument.
118    #[cfg(feature = "experimental-inspect")]
119    fn type_output() -> TypeInfo {
120        TypeInfo::Any
121    }
122
123    /// Converts sequence of Self into a Python object. Used to specialize `Vec<u8>`, `[u8; N]`
124    /// and `SmallVec<[u8; N]>` as a sequence of bytes into a `bytes` object.
125    #[doc(hidden)]
126    fn owned_sequence_into_pyobject<I>(
127        iter: I,
128        py: Python<'py>,
129        _: private::Token,
130    ) -> Result<Bound<'py, PyAny>, PyErr>
131    where
132        I: IntoIterator<Item = Self> + AsRef<[Self]>,
133        I::IntoIter: ExactSizeIterator<Item = Self>,
134    {
135        let mut iter = iter.into_iter().map(|e| e.into_bound_py_any(py));
136        let list = crate::types::list::try_new_from_iter(py, &mut iter);
137        list.map(Bound::into_any)
138    }
139
140    /// Converts sequence of Self into a Python object. Used to specialize `&[u8]` and `Cow<[u8]>`
141    /// as a sequence of bytes into a `bytes` object.
142    #[doc(hidden)]
143    fn borrowed_sequence_into_pyobject<I>(
144        iter: I,
145        py: Python<'py>,
146        _: private::Token,
147    ) -> Result<Bound<'py, PyAny>, PyErr>
148    where
149        Self: private::Reference,
150        I: IntoIterator<Item = Self> + AsRef<[<Self as private::Reference>::BaseType]>,
151        I::IntoIter: ExactSizeIterator<Item = Self>,
152    {
153        let mut iter = iter.into_iter().map(|e| e.into_bound_py_any(py));
154        let list = crate::types::list::try_new_from_iter(py, &mut iter);
155        list.map(Bound::into_any)
156    }
157}
158
159pub(crate) mod private {
160    pub struct Token;
161
162    pub trait Reference {
163        type BaseType;
164    }
165
166    impl<T> Reference for &'_ T {
167        type BaseType = T;
168    }
169}
170
171impl<'py, T> IntoPyObject<'py> for Bound<'py, T> {
172    type Target = T;
173    type Output = Bound<'py, Self::Target>;
174    type Error = Infallible;
175
176    fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
177        Ok(self)
178    }
179}
180
181impl<'a, 'py, T> IntoPyObject<'py> for &'a Bound<'py, T> {
182    type Target = T;
183    type Output = Borrowed<'a, 'py, Self::Target>;
184    type Error = Infallible;
185
186    fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
187        Ok(self.as_borrowed())
188    }
189}
190
191impl<'a, 'py, T> IntoPyObject<'py> for Borrowed<'a, 'py, T> {
192    type Target = T;
193    type Output = Borrowed<'a, 'py, Self::Target>;
194    type Error = Infallible;
195
196    fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
197        Ok(self)
198    }
199}
200
201impl<'a, 'py, T> IntoPyObject<'py> for &Borrowed<'a, 'py, T> {
202    type Target = T;
203    type Output = Borrowed<'a, 'py, Self::Target>;
204    type Error = Infallible;
205
206    fn into_pyobject(self, _py: Python<'py>) -> Result<Self::Output, Self::Error> {
207        Ok(*self)
208    }
209}
210
211impl<'py, T> IntoPyObject<'py> for Py<T> {
212    type Target = T;
213    type Output = Bound<'py, Self::Target>;
214    type Error = Infallible;
215
216    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
217        Ok(self.into_bound(py))
218    }
219}
220
221impl<'a, 'py, T> IntoPyObject<'py> for &'a Py<T> {
222    type Target = T;
223    type Output = Borrowed<'a, 'py, Self::Target>;
224    type Error = Infallible;
225
226    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
227        Ok(self.bind_borrowed(py))
228    }
229}
230
231impl<'a, 'py, T> IntoPyObject<'py> for &&'a T
232where
233    &'a T: IntoPyObject<'py>,
234{
235    type Target = <&'a T as IntoPyObject<'py>>::Target;
236    type Output = <&'a T as IntoPyObject<'py>>::Output;
237    type Error = <&'a T as IntoPyObject<'py>>::Error;
238
239    #[inline]
240    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
241        (*self).into_pyobject(py)
242    }
243}
244
245mod into_pyobject_ext {
246    pub trait Sealed {}
247    impl<'py, T> Sealed for T where T: super::IntoPyObject<'py> {}
248}
249
250/// Convenience methods for common usages of [`IntoPyObject`]. Every type that implements
251/// [`IntoPyObject`] also implements this trait.
252///
253/// These methods:
254///   - Drop type information from the output, returning a `PyAny` object.
255///   - Always convert the `Error` type to `PyErr`, which may incur a performance penalty but it
256///     more convenient in contexts where the `?` operator would produce a `PyErr` anyway.
257pub trait IntoPyObjectExt<'py>: IntoPyObject<'py> + into_pyobject_ext::Sealed {
258    /// Converts `self` into an owned Python object, dropping type information.
259    #[inline]
260    fn into_bound_py_any(self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
261        match self.into_pyobject(py) {
262            Ok(obj) => Ok(obj.into_any().into_bound()),
263            Err(err) => Err(err.into()),
264        }
265    }
266
267    /// Converts `self` into an owned Python object, dropping type information and unbinding it
268    /// from the `'py` lifetime.
269    #[inline]
270    fn into_py_any(self, py: Python<'py>) -> PyResult<Py<PyAny>> {
271        match self.into_pyobject(py) {
272            Ok(obj) => Ok(obj.into_any().unbind()),
273            Err(err) => Err(err.into()),
274        }
275    }
276
277    /// Converts `self` into a Python object.
278    ///
279    /// This is equivalent to calling [`into_pyobject`][IntoPyObject::into_pyobject] followed
280    /// with `.map_err(Into::into)` to convert the error type to [`PyErr`]. This is helpful
281    /// for generic code which wants to make use of the `?` operator.
282    #[inline]
283    fn into_pyobject_or_pyerr(self, py: Python<'py>) -> PyResult<Self::Output> {
284        match self.into_pyobject(py) {
285            Ok(obj) => Ok(obj),
286            Err(err) => Err(err.into()),
287        }
288    }
289}
290
291impl<'py, T> IntoPyObjectExt<'py> for T where T: IntoPyObject<'py> {}
292
293/// Extract a type from a Python object.
294///
295///
296/// Normal usage is through the `extract` methods on [`Bound`] and [`Py`], which forward to this trait.
297///
298/// # Examples
299///
300/// ```rust
301/// use pyo3::prelude::*;
302/// use pyo3::types::PyString;
303///
304/// # fn main() -> PyResult<()> {
305/// Python::with_gil(|py| {
306///     // Calling `.extract()` on a `Bound` smart pointer
307///     let obj: Bound<'_, PyString> = PyString::new(py, "blah");
308///     let s: String = obj.extract()?;
309/// #   assert_eq!(s, "blah");
310///
311///     // Calling `.extract(py)` on a `Py` smart pointer
312///     let obj: Py<PyString> = obj.unbind();
313///     let s: String = obj.extract(py)?;
314/// #   assert_eq!(s, "blah");
315/// #   Ok(())
316/// })
317/// # }
318/// ```
319///
320// /// FIXME: until `FromPyObject` can pick up a second lifetime, the below commentary is no longer
321// /// true. Update and restore this documentation at that time.
322// ///
323// /// Note: depending on the implementation, the lifetime of the extracted result may
324// /// depend on the lifetime of the `obj` or the `prepared` variable.
325// ///
326// /// For example, when extracting `&str` from a Python byte string, the resulting string slice will
327// /// point to the existing string data (lifetime: `'py`).
328// /// On the other hand, when extracting `&str` from a Python Unicode string, the preparation step
329// /// will convert the string to UTF-8, and the resulting string slice will have lifetime `'prepared`.
330// /// Since which case applies depends on the runtime type of the Python object,
331// /// both the `obj` and `prepared` variables must outlive the resulting string slice.
332///
333/// During the migration of PyO3 from the "GIL Refs" API to the `Bound<T>` smart pointer, this trait
334/// has two methods `extract` and `extract_bound` which are defaulted to call each other. To avoid
335/// infinite recursion, implementors must implement at least one of these methods. The recommendation
336/// is to implement `extract_bound` and leave `extract` as the default implementation.
337pub trait FromPyObject<'py>: Sized {
338    /// Extracts `Self` from the bound smart pointer `obj`.
339    ///
340    /// Implementors are encouraged to implement this method and leave `extract` defaulted, as
341    /// this will be most compatible with PyO3's future API.
342    fn extract_bound(ob: &Bound<'py, PyAny>) -> PyResult<Self>;
343
344    /// Extracts the type hint information for this type when it appears as an argument.
345    ///
346    /// For example, `Vec<u32>` would return `Sequence[int]`.
347    /// The default implementation returns `Any`, which is correct for any type.
348    ///
349    /// For most types, the return value for this method will be identical to that of
350    /// [`IntoPyObject::type_output`]. It may be different for some types, such as `Dict`,
351    /// to allow duck-typing: functions return `Dict` but take `Mapping` as argument.
352    #[cfg(feature = "experimental-inspect")]
353    fn type_input() -> TypeInfo {
354        TypeInfo::Any
355    }
356}
357
358mod from_py_object_bound_sealed {
359    /// Private seal for the `FromPyObjectBound` trait.
360    ///
361    /// This prevents downstream types from implementing the trait before
362    /// PyO3 is ready to declare the trait as public API.
363    pub trait Sealed {}
364
365    // This generic implementation is why the seal is separate from
366    // `crate::sealed::Sealed`.
367    impl<'py, T> Sealed for T where T: super::FromPyObject<'py> {}
368    impl Sealed for &'_ str {}
369    impl Sealed for std::borrow::Cow<'_, str> {}
370    impl Sealed for &'_ [u8] {}
371    impl Sealed for std::borrow::Cow<'_, [u8]> {}
372}
373
374/// Expected form of [`FromPyObject`] to be used in a future PyO3 release.
375///
376/// The difference between this and `FromPyObject` is that this trait takes an
377/// additional lifetime `'a`, which is the lifetime of the input `Bound`.
378///
379/// This allows implementations for `&'a str` and `&'a [u8]`, which could not
380/// be expressed by the existing `FromPyObject` trait once the GIL Refs API was
381/// removed.
382///
383/// # Usage
384///
385/// Users are prevented from implementing this trait, instead they should implement
386/// the normal `FromPyObject` trait. This trait has a blanket implementation
387/// for `T: FromPyObject`.
388///
389/// The only case where this trait may have a use case to be implemented is when the
390/// lifetime of the extracted value is tied to the lifetime `'a` of the input `Bound`
391/// instead of the GIL lifetime `py`, as is the case for the `&'a str` implementation.
392///
393/// Please contact the PyO3 maintainers if you believe you have a use case for implementing
394/// this trait before PyO3 is ready to change the main `FromPyObject` trait to take an
395/// additional lifetime.
396///
397/// Similarly, users should typically not call these trait methods and should instead
398/// use this via the `extract` method on `Bound` and `Py`.
399pub trait FromPyObjectBound<'a, 'py>: Sized + from_py_object_bound_sealed::Sealed {
400    /// Extracts `Self` from the bound smart pointer `obj`.
401    ///
402    /// Users are advised against calling this method directly: instead, use this via
403    /// [`Bound<'_, PyAny>::extract`] or [`Py::extract`].
404    fn from_py_object_bound(ob: Borrowed<'a, 'py, PyAny>) -> PyResult<Self>;
405
406    /// Extracts the type hint information for this type when it appears as an argument.
407    ///
408    /// For example, `Vec<u32>` would return `Sequence[int]`.
409    /// The default implementation returns `Any`, which is correct for any type.
410    ///
411    /// For most types, the return value for this method will be identical to that of
412    /// [`IntoPyObject::type_output`]. It may be different for some types, such as `Dict`,
413    /// to allow duck-typing: functions return `Dict` but take `Mapping` as argument.
414    #[cfg(feature = "experimental-inspect")]
415    fn type_input() -> TypeInfo {
416        TypeInfo::Any
417    }
418}
419
420impl<'py, T> FromPyObjectBound<'_, 'py> for T
421where
422    T: FromPyObject<'py>,
423{
424    fn from_py_object_bound(ob: Borrowed<'_, 'py, PyAny>) -> PyResult<Self> {
425        Self::extract_bound(&ob)
426    }
427
428    #[cfg(feature = "experimental-inspect")]
429    fn type_input() -> TypeInfo {
430        <T as FromPyObject>::type_input()
431    }
432}
433
434impl<T> FromPyObject<'_> for T
435where
436    T: PyClass + Clone,
437{
438    fn extract_bound(obj: &Bound<'_, PyAny>) -> PyResult<Self> {
439        let bound = obj.downcast::<Self>()?;
440        Ok(bound.try_borrow()?.clone())
441    }
442}
443
444impl<'py, T> FromPyObject<'py> for PyRef<'py, T>
445where
446    T: PyClass,
447{
448    fn extract_bound(obj: &Bound<'py, PyAny>) -> PyResult<Self> {
449        obj.downcast::<T>()?.try_borrow().map_err(Into::into)
450    }
451}
452
453impl<'py, T> FromPyObject<'py> for PyRefMut<'py, T>
454where
455    T: PyClass<Frozen = False>,
456{
457    fn extract_bound(obj: &Bound<'py, PyAny>) -> PyResult<Self> {
458        obj.downcast::<T>()?.try_borrow_mut().map_err(Into::into)
459    }
460}
461
462impl<'py> IntoPyObject<'py> for () {
463    type Target = PyTuple;
464    type Output = Bound<'py, Self::Target>;
465    type Error = Infallible;
466
467    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
468        Ok(PyTuple::empty(py))
469    }
470}
471
472/// ```rust,compile_fail
473/// use pyo3::prelude::*;
474///
475/// #[pyclass]
476/// struct TestClass {
477///     num: u32,
478/// }
479///
480/// let t = TestClass { num: 10 };
481///
482/// Python::with_gil(|py| {
483///     let pyvalue = Py::new(py, t).unwrap().to_object(py);
484///     let t: TestClass = pyvalue.extract(py).unwrap();
485/// })
486/// ```
487mod test_no_clone {}
pyo3/conversion.rs

pyo3/
conversion.rs
