Add new trait IntoPyObject

pyo3-macros-backend/src/pyclass.rs

@@ -737,6 +737,13 @@ impl<'a> PyClassImplsBuilder<'a> {
                         _pyo3::IntoPy::into_py(_pyo3::Py::new(py, self).unwrap(), py)
                     }
                 }
+
+                impl _pyo3::IntoPyObject for #cls {
+                    type Target = #cls;
+                    fn into_py(self, py: _pyo3::Python) -> _pyo3::Py<#cls> {
+                        _pyo3::Py::new(py, self).unwrap()
+                    }
+                }
             }
         } else {
             quote! {}

src/callback.rs

@@ -6,8 +6,8 @@ use crate::err::{PyErr, PyResult};
 use crate::exceptions::PyOverflowError;
 use crate::ffi::{self, Py_hash_t};
 use crate::panic::PanicException;
-use crate::{GILPool, IntoPyPointer};
-use crate::{IntoPy, PyObject, Python};
+use crate::{GILPool, IntoPyObject, IntoPyPointer};
+use crate::{PyObject, Python};
 use std::any::Any;
 use std::os::raw::c_int;
 use std::panic::UnwindSafe;
@@ -53,7 +53,7 @@ where
 
 impl<T> IntoPyCallbackOutput<*mut ffi::PyObject> for T
 where
-    T: IntoPy<PyObject>,
+    T: IntoPyObject,
 {
     #[inline]
     fn convert(self, py: Python<'_>) -> PyResult<*mut ffi::PyObject> {
@@ -118,11 +118,11 @@ impl IntoPyCallbackOutput<usize> for usize {
 
 impl<T> IntoPyCallbackOutput<PyObject> for T
 where
-    T: IntoPy<PyObject>,
+    T: IntoPyObject,
 {
     #[inline]
     fn convert(self, py: Python<'_>) -> PyResult<PyObject> {
-        Ok(self.into_py(py))
+        Ok(self.into_object(py))
     }
 }
 

src/conversion.rs

@@ -184,6 +184,98 @@ pub trait IntoPy<T>: Sized {
     fn into_py(self, py: Python<'_>) -> T;
 }
 
+/// Defines a conversion from a Rust type to a Python object.
+///
+/// It functions similarly to std's [`Into`](std::convert::Into) trait,
+/// but requires a [GIL token](Python) as an argument.
+/// Many functions and traits internal to PyO3 require this trait as a bound,
+/// so a lack of this trait can manifest itself in different error messages.
+///
+/// # Examples
+/// ## With `#[pyclass]`
+/// The easiest way to implement `IntoPy` is by exposing a struct as a native Python object
+/// by annotating it with [`#[pyclass]`](crate::prelude::pyclass).
+///
+/// ```rust
+/// use pyo3::prelude::*;
+///
+/// #[pyclass]
+/// struct Number {
+///     #[pyo3(get, set)]
+///     value: i32,
+/// }
+/// ```
+/// Python code will see this as an instance of the `Number` class with a `value` attribute.
+///
+/// ## Conversion to a Python object
+///
+/// However, it may not be desirable to expose the existence of `Number` to Python code.
+/// `IntoPy` allows us to define a conversion to an appropriate Python object.
+/// ```rust
+/// use pyo3::prelude::*;
+///
+/// struct Number {
+///     value: i32,
+/// }
+///
+/// impl IntoPy<PyObject> for Number {
+///     fn into_py(self, py: Python<'_>) -> PyObject {
+///         // delegates to i32's IntoPy implementation.
+///         self.value.into_py(py)
+///     }
+/// }
+/// ```
+/// Python code will see this as an `int` object.
+///
+/// ## Dynamic conversion into Python objects.
+/// It is also possible to return a different Python object depending on some condition.
+/// This is useful for types like enums that can carry different types.
+///
+/// ```rust
+/// use pyo3::prelude::*;
+///
+/// enum Value {
+///     Integer(i32),
+///     String(String),
+///     None,
+/// }
+///
+/// impl IntoPy<PyObject> for Value {
+///     fn into_py(self, py: Python<'_>) -> PyObject {
+///         match self {
+///             Self::Integer(val) => val.into_py(py),
+///             Self::String(val) => val.into_py(py),
+///             Self::None => py.None(),
+///         }
+///     }
+/// }
+/// # fn main() {
+/// #     Python::with_gil(|py| {
+/// #         let v = Value::Integer(73).into_py(py);
+/// #         let v = v.extract::<i32>(py).unwrap();
+/// #
+/// #         let v = Value::String("foo".into()).into_py(py);
+/// #         let v = v.extract::<String>(py).unwrap();
+/// #
+/// #         let v = Value::None.into_py(py);
+/// #         let v = v.extract::<Option<Vec<i32>>>(py).unwrap();
+/// #     });
+/// # }
+/// ```
+/// Python code will see this as any of the `int`, `string` or `None` objects.
+#[cfg_attr(docsrs, doc(alias = "IntoPyCallbackOutput"))]
+pub trait IntoPyObject: Sized {
+    type Target;
+
+    /// Performs the conversion.
+    fn into_py(self, py: Python<'_>) -> Py<Self::Target>;
+
+    /// Performs the conversion.
+    fn into_object(self, py: Python<'_>) -> PyObject {
+        unsafe { Py::from_owned_ptr(py, self.into_py(py).into_ptr()) }
+    }
+}
+
 /// `FromPyObject` is implemented by various types that can be extracted from
 /// a Python object reference.
 ///
@@ -244,6 +336,17 @@ where
     }
 }
 
+impl<T> IntoPyObject for Option<T>
+where
+    T: IntoPyObject,
+{
+    type Target = PyAny;
+
+    fn into_py(self, py: Python<'_>) -> PyObject {
+        self.map_or_else(|| py.None(), |val| val.into_object(py))
+    }
+}
+
 /// `()` is converted to Python `None`.
 impl ToPyObject for () {
     fn to_object(&self, py: Python<'_>) -> PyObject {
@@ -431,6 +534,13 @@ impl IntoPy<Py<PyTuple>> for () {
     }
 }
 
+impl IntoPyObject for () {
+    type Target = PyTuple;
+    fn into_py(self, py: Python<'_>) -> Py<PyTuple> {
+        PyTuple::empty(py).into()
+    }
+}
+
 /// Raw level conversion between `*mut ffi::PyObject` and PyO3 types.
 ///
 /// # Safety

src/conversions/array.rs

@@ -3,9 +3,12 @@ use crate::{exceptions, PyErr};
 #[cfg(min_const_generics)]
 mod min_const_generics {
     use super::invalid_sequence_length;
-    use crate::{FromPyObject, IntoPy, PyAny, PyObject, PyResult, PyTryFrom, Python, ToPyObject};
+    use crate::{
+        types::PyList, FromPyObject, IntoPyObject, Py, PyAny, PyObject, PyResult, PyTryFrom,
+        Python, ToPyObject,
+    };
 
-    impl<T, const N: usize> IntoPy<PyObject> for [T; N]
+    impl<T, const N: usize> crate::IntoPy<PyObject> for [T; N]
     where
         T: ToPyObject,
     {
@@ -14,6 +17,16 @@ mod min_const_generics {
         }
     }
 
+    impl<T, const N: usize> IntoPyObject for [T; N]
+    where
+        T: ToPyObject,
+    {
+        type Target = PyList;
+        fn into_py(self, py: Python<'_>) -> Py<PyList> {
+            PyList::new(py, self.as_ref()).into()
+        }
+    }
+
     impl<'a, T, const N: usize> FromPyObject<'a> for [T; N]
     where
         T: FromPyObject<'a>,

src/conversions/hashbrown.rs

@@ -52,6 +52,22 @@ where
     }
 }
 
+impl<K, V, H> IntoPyObject for hashbrown::HashMap<K, V, H>
+where
+    K: hash::Hash + cmp::Eq + IntoPyObject,
+    V: IntoPyObject,
+    H: hash::BuildHasher,
+{
+    type Target = PyDict;
+
+    fn into_py(self, py: Python<'_>) -> Py<PyDict> {
+        let iter = self
+            .into_iter()
+            .map(|(k, v)| (k.into_py(py), v.into_py(py)));
+        IntoPyDict::into_py_dict(iter, py)
+    }
+}
+
 impl<'source, K, V, S> FromPyObject<'source> for hashbrown::HashMap<K, V, S>
 where
     K: FromPyObject<'source> + cmp::Eq + hash::Hash,

src/conversions/indexmap.rs

@@ -121,6 +121,21 @@ where
     }
 }
 
+impl<K, V, H> IntoPyObject for indexmap::IndexMap<K, V, H>
+where
+    K: hash::Hash + cmp::Eq + IntoPyObject,
+    V: IntoPyObject,
+    H: hash::BuildHasher,
+{
+    type Target = PyDict;
+    fn into_py(self, py: Python<'_>) -> PyObject {
+        let iter = self
+            .into_iter()
+            .map(|(k, v)| (k.into_py(py), v.into_py(py)));
+        IntoPyDict::into_py_dict(iter, py).into()
+    }
+}
+
 impl<'source, K, V, S> FromPyObject<'source> for indexmap::IndexMap<K, V, S>
 where
     K: FromPyObject<'source> + cmp::Eq + hash::Hash,