deprecate super class initialization from tuples

Author: Icxolu

guide/src/class.md

@@ -403,17 +403,15 @@ Consult the table below to determine which type your constructor should return:
 |                             | **Cannot fail**           | **May fail**                      |
 |-----------------------------|---------------------------|-----------------------------------|
 |**No inheritance**           | `T`                       | `PyResult<T>`                     |
-|**Inheritance(T Inherits U)**| `(T, U)`                  | `PyResult<(T, U)>`                |
-|**Inheritance(General Case)**| [`PyClassInitializer<T>`] | `PyResult<PyClassInitializer<T>>` |
+|**Inheritance**              | [`PyClassInitializer<T>`] | `PyResult<PyClassInitializer<T>>` |
 
 ## Inheritance
 
 By default, `object`, i.e. `PyAny` is used as the base class.
 To override this default, use the `extends` parameter for `pyclass` with the full path to the base class.
 Currently, only classes defined in Rust and builtins provided by PyO3 can be inherited from; inheriting from other classes defined in Python is not yet supported ([#991](https://github.com/PyO3/pyo3/issues/991)).
 
-For convenience, `(T, U)` implements `Into<PyClassInitializer<T>>` where `U` is the base class of `T`.
-But for a more deeply nested inheritance, you have to return `PyClassInitializer<T>` explicitly.
+To initialize a class, which inherits from another class, use the `PyClassInitializer` API.
 
 To get a parent class from a child, use [`PyRef`] instead of `&self` for methods, or [`PyRefMut`] instead of `&mut self`.
 Then you can access a parent class by `self_.as_super()` as `&PyRef<Self::BaseClass>`, or by `self_.into_super()` as `PyRef<Self::BaseClass>` (and similar for the `PyRefMut` case).
@@ -447,8 +445,9 @@ struct SubClass {
 #[pymethods]
 impl SubClass {
     #[new]
-    fn new() -> (Self, BaseClass) {
-        (SubClass { val2: 15 }, BaseClass::new())
+    fn new() -> PyClassInitializer<Self> {
+        PyClassInitializer::from(BaseClass::new())
+            .add_subclass(SubClass { val2: 15 })
     }
 
     fn method2(self_: PyRef<'_, Self>) -> PyResult<usize> {

guide/src/migration.md

@@ -88,6 +88,52 @@ let obj_2 = existing_bound.clone();
 # })
 ```
 
+### Deprecation of super class initialization from tuples
+
+Performing superclass initialitation from a subclass via a tuple is deprecated and will be removed in a future PyO3 version.
+This also includes the `From<(S, B)> for PyClassInitializer<S>` impl which we can't warn against.
+To migrate use `PyClassInitializer` directly:
+
+Before:
+
+```rust
+# #![allow(deprecated)]
+# use pyo3::prelude::*;
+#[pyclass(subclass)]
+struct Base;
+
+#[pyclass(extends=Base)]
+struct Sub;
+
+#[pymethods]
+impl Sub {
+    #[new]
+    fn new() -> (Self, Base) {
+        (Self, Base)
+    }
+}
+```
+
+After:
+
+```rust
+# use pyo3::prelude::*;
+#[pyclass(subclass)]
+struct Base;
+
+#[pyclass(extends=Base)]
+struct Sub;
+
+#[pymethods]
+impl Sub {
+    #[new]
+    fn new() -> PyClassInitializer<Self> {
+        PyClassInitializer::from(Base)
+            .add_subclass(Self)
+    }
+}
+```
+
 ### Internal change to use multi-phase initialization
 
 [PEP 489](https://peps.python.org/pep-0489/) introduced "multi-phase initialization" for extension modules which provides ways to allocate and clean up per-module state.

newsfragments/5741.changed.md

@@ -0,0 +1 @@
+Super class initialization from tuples is deprecated.

pyo3-macros-backend/src/pymethod.rs

@@ -1465,6 +1465,7 @@ fn generate_method_body(
             } else {
                 &parse_quote!(())
             };
+            let is_initializer_tuple = quote_spanned! { *output_span => #pyo3_path::impl_::pyclass::IsInitializerTuple::<#output>::VALUE };
             let body = quote! {
                 #text_signature_impl
 
@@ -1475,7 +1476,7 @@ fn generate_method_body(
                 #pyo3_path::impl_::pymethods::tp_new_impl::<
                     _,
                     { #pyo3_path::impl_::pyclass::IsPyClass::<#output>::VALUE },
-                    { #pyo3_path::impl_::pyclass::IsInitializerTuple::<#output>::VALUE }
+                    { #is_initializer_tuple }
                 >(py, result, _slf)
             };
             (arg_idents, arg_types, body)

pytests/src/subclassing.rs

@@ -29,8 +29,8 @@ pub mod subclassing {
     #[pymethods]
     impl Subclass {
         #[new]
-        fn new() -> (Self, Subclassable) {
-            (Subclass {}, Subclassable::new())
+        fn new() -> PyClassInitializer<Self> {
+            PyClassInitializer::from(Subclassable::new()).add_subclass(Self {})
         }
 
         fn __str__(&self) -> &'static str {

src/impl_/pyclass/probes.rs

@@ -114,6 +114,10 @@ where
     B: PyClass + PyClassBaseType<Initializer = PyClassInitializer<B>>,
     B::BaseType: PyClassBaseType<Initializer = PyNativeTypeInitializer<B::BaseType>>,
 {
+    #[deprecated(
+        since = "0.28.0",
+        note = "Tuple syntax for super class initialization is phased out. Use `PyClassInitializer` instead."
+    )]
     pub const VALUE: bool = true;
 }
 impl<S, B, E> IsInitializerTuple<Result<(S, B), E>>
@@ -122,6 +126,10 @@ where
     B: PyClass + PyClassBaseType<Initializer = PyClassInitializer<B>>,
     B::BaseType: PyClassBaseType<Initializer = PyNativeTypeInitializer<B::BaseType>>,
 {
+    #[deprecated(
+        since = "0.28.0",
+        note = "Tuple syntax for super class initialization is phased out. Use `PyClassInitializer` instead."
+    )]
     pub const VALUE: bool = true;
 }
 

src/instance.rs

@@ -686,7 +686,8 @@ where
     /// struct SubClass;
     ///
     /// Python::attach(|py| {
-    ///     let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
+    ///     let initializer = PyClassInitializer::from(BaseClass).add_subclass(SubClass);
+    ///     let obj = Bound::new(py, initializer).unwrap();
     ///     assert!(obj.as_super().pyrepr().is_ok());
     /// })
     /// # }
@@ -738,7 +739,8 @@ where
     /// struct SubClass;
     ///
     /// Python::attach(|py| {
-    ///     let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
+    ///     let initializer = PyClassInitializer::from(BaseClass).add_subclass(SubClass);
+    ///     let obj = Bound::new(py, initializer).unwrap();
     ///     assert!(obj.into_super().pyrepr().is_ok());
     /// })
     /// # }
@@ -2865,6 +2867,7 @@ a = A()
     #[cfg(feature = "macros")]
     mod using_macros {
         use super::*;
+        use crate::PyClassInitializer;
 
         #[crate::pyclass(crate = "crate")]
         struct SomeClass(i32);
@@ -2943,7 +2946,8 @@ a = A()
         #[test]
         fn test_as_super() {
             Python::attach(|py| {
-                let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
+                let initializer = PyClassInitializer::from(BaseClass).add_subclass(SubClass);
+                let obj = Bound::new(py, initializer).unwrap();
                 let _: &Bound<'_, BaseClass> = obj.as_super();
                 let _: &Bound<'_, PyAny> = obj.as_super().as_super();
                 assert!(obj.as_super().pyrepr_by_ref().is_ok());
@@ -2953,7 +2957,8 @@ a = A()
         #[test]
         fn test_into_super() {
             Python::attach(|py| {
-                let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
+                let initializer = PyClassInitializer::from(BaseClass).add_subclass(SubClass);
+                let obj = Bound::new(py, initializer).unwrap();
                 let _: Bound<'_, BaseClass> = obj.clone().into_super();
                 let _: Bound<'_, PyAny> = obj.clone().into_super().into_super();
                 assert!(obj.into_super().pyrepr_by_val().is_ok());

src/pycell.rs

@@ -233,8 +233,9 @@ use impl_::{PyClassBorrowChecker, PyClassObjectBaseLayout, PyClassObjectLayout};
 /// #[pymethods]
 /// impl Child {
 ///     #[new]
-///     fn new() -> (Self, Parent) {
-///         (Child { name: "Caterpillar" }, Parent { basename: "Butterfly" })
+///     fn new() -> PyClassInitializer<Self> {
+///         PyClassInitializer::from(Parent { basename: "Butterfly" })
+///             .add_subclass(Child { name: "Caterpillar" })
 ///     }
 ///
 ///     fn format(slf: PyRef<'_, Self>) -> String {
@@ -430,8 +431,9 @@ where
     /// #[pymethods]
     /// impl Sub {
     ///     #[new]
-    ///     fn new() -> (Self, Base) {
-    ///         (Self { sub_name: "sub_name" }, Base { base_name: "base_name" })
+    ///     fn new() -> PyClassInitializer<Self> {
+    ///         PyClassInitializer::from(Base { base_name: "base_name" })
+    ///             .add_subclass(Self { sub_name: "sub_name" })
     ///     }
     ///     fn sub_name_len(&self) -> usize {
     ///         self.sub_name.len()

src/pyclass/guard.rs

@@ -62,8 +62,9 @@ use std::ptr::NonNull;
 /// #[pymethods]
 /// impl Child {
 ///     #[new]
-///     fn new() -> (Self, Parent) {
-///         (Child { name: "Caterpillar" }, Parent { basename: "Butterfly" })
+///     fn new() -> PyClassInitializer<Self> {
+///         PyClassInitializer::from(Parent { basename: "Butterfly" })
+///             .add_subclass(Child { name: "Caterpillar" })
 ///     }
 ///
 ///     fn format(slf: PyClassGuard<'_, Self>) -> String {
@@ -184,8 +185,9 @@ where
     /// #[pymethods]
     /// impl Sub {
     ///     #[new]
-    ///     fn new() -> (Self, Base) {
-    ///         (Self { sub_name: "sub_name" }, Base { base_name: "base_name" })
+    ///     fn new() -> PyClassInitializer<Self> {
+    ///         PyClassInitializer::from(Base { base_name: "base_name" })
+    ///             .add_subclass(Self { sub_name: "sub_name" })
     ///     }
     ///     fn sub_name_len(&self) -> usize {
     ///         self.sub_name.len()

src/types/pysuper.rs

@@ -64,8 +64,8 @@ impl PySuper {
     /// #[pymethods]
     /// impl SubClass {
     ///     #[new]
-    ///     fn new() -> (Self, BaseClass) {
-    ///         (SubClass {}, BaseClass::new())
+    ///     fn new() -> PyClassInitializer<Self> {
+    ///         PyClassInitializer::from(BaseClass::new()).add_subclass(SubClass {})
     ///     }
     ///
     ///     fn method<'py>(self_: &Bound<'py, Self>) -> PyResult<Bound<'py, PyAny>> {