deprecate ToPyObject in favor or IntoPyObject

guide/src/class.md

@@ -412,10 +412,10 @@ impl SubSubClass {
         let base = PyClassInitializer::from(BaseClass::new());
         let sub = base.add_subclass(SubClass { val2: val });
         if val % 2 == 0 {
-            Ok(Py::new(py, sub)?.to_object(py))
+            Ok(Py::new(py, sub)?.into_any())
         } else {
             let sub_sub = sub.add_subclass(SubSubClass { val3: val });
-            Ok(Py::new(py, sub_sub)?.to_object(py))
+            Ok(Py::new(py, sub_sub)?.into_any())
         }
     }
 }

guide/src/conversions/traits.md

@@ -294,8 +294,8 @@ enum RustyEnum<'py> {
 # fn main() -> PyResult<()> {
 #     Python::with_gil(|py| -> PyResult<()> {
 #         {
-#             let thing = 42_u8.to_object(py);
-#             let rust_thing: RustyEnum<'_> = thing.extract(py)?;
+#             let thing = 42_u8.into_pyobject(py)?;
+#             let rust_thing: RustyEnum<'_> = thing.extract()?;
 #
 #             assert_eq!(
 #                 42,
@@ -318,8 +318,8 @@ enum RustyEnum<'py> {
 #             );
 #         }
 #         {
-#             let thing = (32_u8, 73_u8).to_object(py);
-#             let rust_thing: RustyEnum<'_> = thing.extract(py)?;
+#             let thing = (32_u8, 73_u8).into_pyobject(py)?;
+#             let rust_thing: RustyEnum<'_> = thing.extract()?;
 #
 #             assert_eq!(
 #                 (32, 73),
@@ -330,8 +330,8 @@ enum RustyEnum<'py> {
 #             );
 #         }
 #         {
-#             let thing = ("foo", 73_u8).to_object(py);
-#             let rust_thing: RustyEnum<'_> = thing.extract(py)?;
+#             let thing = ("foo", 73_u8).into_pyobject(py)?;
+#             let rust_thing: RustyEnum<'_> = thing.extract()?;
 #
 #             assert_eq!(
 #                 (String::from("foo"), 73),
@@ -427,8 +427,8 @@ enum RustyEnum {
 # fn main() -> PyResult<()> {
 #     Python::with_gil(|py| -> PyResult<()> {
 #         {
-#             let thing = 42_u8.to_object(py);
-#             let rust_thing: RustyEnum = thing.extract(py)?;
+#             let thing = 42_u8.into_pyobject(py)?;
+#             let rust_thing: RustyEnum = thing.extract()?;
 #
 #             assert_eq!(
 #                 42,
@@ -440,8 +440,8 @@ enum RustyEnum {
 #         }
 #
 #         {
-#             let thing = "foo".to_object(py);
-#             let rust_thing: RustyEnum = thing.extract(py)?;
+#             let thing = "foo".into_pyobject(py)?;
+#             let rust_thing: RustyEnum = thing.extract()?;
 #
 #             assert_eq!(
 #                 "foo",
@@ -453,8 +453,8 @@ enum RustyEnum {
 #         }
 #
 #         {
-#             let thing = b"foo".to_object(py);
-#             let error = thing.extract::<RustyEnum>(py).unwrap_err();
+#             let thing = b"foo".into_pyobject(py)?;
+#             let error = thing.extract::<RustyEnum>().unwrap_err();
 #             assert!(error.is_instance_of::<pyo3::exceptions::PyTypeError>(py));
 #         }
 #

guide/src/migration.md

@@ -155,9 +155,12 @@ Notable features of this new trait:
 All PyO3 provided types as well as `#[pyclass]`es already implement `IntoPyObject`. Other types will
 need to adapt an implementation of `IntoPyObject` to stay compatible with the Python APIs.
 
+Together with the introduction of `IntoPyObject` the old conversion traits `ToPyObject` and `IntoPy`
+are deprecated and will be removed in a future PyO3 version.
+
 
 Before:
-```rust
+```rust,ignore
 # use pyo3::prelude::*;
 # #[allow(dead_code)]
 struct MyPyObjectWrapper(PyObject);

newsfragments/4595.changed.md

@@ -0,0 +1,2 @@
+- `PyErr::matches` is now fallible due to `IntoPyObject` migration.
+- deprecate `ToPyObject` in favor of `IntoPyObject`

pytests/src/objstore.rs

@@ -13,8 +13,8 @@ impl ObjStore {
         ObjStore::default()
     }
 
-    fn push(&mut self, py: Python<'_>, obj: &Bound<'_, PyAny>) {
-        self.obj.push(obj.to_object(py));
+    fn push(&mut self, obj: &Bound<'_, PyAny>) {
+        self.obj.push(obj.clone().unbind());
     }
 }
 

src/conversion.rs

@@ -64,6 +64,10 @@ pub unsafe trait AsPyPointer {
 }
 
 /// Conversion trait that allows various objects to be converted into `PyObject`.
+#[deprecated(
+    since = "0.23.0",
+    note = "`ToPyObject` is going to be replaced by `IntoPyObject`. See the migration guide (https://pyo3.rs/v0.23/migration) for more information."
+)]
 pub trait ToPyObject {
     /// Converts self into a Python object.
     fn to_object(&self, py: Python<'_>) -> PyObject;
@@ -548,6 +552,7 @@ where
 
 /// Identity conversion: allows using existing `PyObject` instances where
 /// `T: ToPyObject` is expected.
+#[allow(deprecated)]
 impl<T: ?Sized + ToPyObject> ToPyObject for &'_ T {
     #[inline]
     fn to_object(&self, py: Python<'_>) -> PyObject {