deprecate super class initialization from tuples

Icxolu · Icxolu · commit 43a7cdd117c5 · 2026-01-18T23:06:38.000+01:00
diff --git a/guide/src/class.md b/guide/src/class.md
@@ -447,8 +447,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> {
diff --git a/guide/src/migration.md b/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.
diff --git a/pyo3-macros-backend/src/pymethod.rs b/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)
diff --git a/pytests/src/subclassing.rs b/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 {
diff --git a/src/impl_/pyclass/probes.rs b/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;
 }
 
diff --git a/src/instance.rs b/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());
diff --git a/src/pycell.rs b/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()
diff --git a/src/pyclass/guard.rs b/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()
diff --git a/src/types/pysuper.rs b/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>> {
diff --git a/tests/test_class_basics.rs b/tests/test_class_basics.rs
@@ -282,8 +282,8 @@ struct UnsendableChild {}
 #[pymethods]
 impl UnsendableChild {
     #[new]
-    fn new(value: usize) -> (UnsendableChild, UnsendableBase) {
-        (UnsendableChild {}, UnsendableBase::new(value))
+    fn new(value: usize) -> PyClassInitializer<Self> {
+        PyClassInitializer::from(UnsendableBase::new(value)).add_subclass(UnsendableChild {})
     }
 }
 
@@ -489,16 +489,11 @@ struct InheritDict {
 #[cfg(any(Py_3_9, not(Py_LIMITED_API)))]
 fn inherited_dict() {
     Python::attach(|py| {
-        let inst = Py::new(
-            py,
-            (
-                InheritDict { _value: 0 },
-                DunderDictSupport {
-                    _pad: *b"DEADBEEFDEADBEEFDEADBEEFDEADBEEF",
-                },
-            ),
-        )
-        .unwrap();
+        let initializer = PyClassInitializer::from(DunderDictSupport {
+            _pad: *b"DEADBEEFDEADBEEFDEADBEEFDEADBEEF",
+        })
+        .add_subclass(InheritDict { _value: 0 });
+        let inst = Py::new(py, initializer).unwrap();
         py_run!(
             py,
             inst,
@@ -572,16 +567,11 @@ struct InheritWeakRef {
 #[cfg(any(Py_3_9, not(Py_LIMITED_API)))]
 fn inherited_weakref() {
     Python::attach(|py| {
-        let inst = Py::new(
-            py,
-            (
-                InheritWeakRef { _value: 0 },
-                WeakRefSupport {
-                    _pad: *b"DEADBEEFDEADBEEFDEADBEEFDEADBEEF",
-                },
-            ),
-        )
-        .unwrap();
+        let initializer = PyClassInitializer::from(WeakRefSupport {
+            _pad: *b"DEADBEEFDEADBEEFDEADBEEFDEADBEEF",
+        })
+        .add_subclass(InheritWeakRef { _value: 0 });
+        let inst = Py::new(py, initializer).unwrap();
         py_run!(
             py,
             inst,
diff --git a/tests/test_class_conversion.rs b/tests/test_class_conversion.rs
@@ -122,7 +122,9 @@ fn test_polymorphic_container_does_not_accept_other_types() {
 #[test]
 fn test_pyref_as_base() {
     Python::attach(|py| {
-        let cell = Bound::new(py, (SubClass {}, BaseClass { value: 120 })).unwrap();
+        let initializer =
+            PyClassInitializer::from(BaseClass { value: 120 }).add_subclass(SubClass {});
+        let cell = Bound::new(py, initializer).unwrap();
 
         // First try PyRefMut
         let sub: PyRefMut<'_, SubClass> = cell.borrow_mut();
@@ -142,7 +144,9 @@ fn test_pyref_as_base() {
 #[test]
 fn test_pycell_deref() {
     Python::attach(|py| {
-        let obj = Bound::new(py, (SubClass {}, BaseClass { value: 120 })).unwrap();
+        let initializer =
+            PyClassInitializer::from(BaseClass { value: 120 }).add_subclass(SubClass {});
+        let obj = Bound::new(py, initializer).unwrap();
 
         // Should be able to deref as PyAny
         assert_eq!(
diff --git a/tests/test_class_init.rs b/tests/test_class_init.rs
@@ -35,8 +35,8 @@ struct SubWithoutInit;
 #[pymethods]
 impl SubWithoutInit {
     #[new]
-    fn new() -> (Self, Base) {
-        (Self, Base::new())
+    fn new() -> PyClassInitializer<Self> {
+        PyClassInitializer::from(Base::new()).add_subclass(Self)
     }
 }
 
@@ -60,8 +60,8 @@ struct SubWithInit;
 #[pymethods]
 impl SubWithInit {
     #[new]
-    fn new() -> (Self, Base) {
-        (Self, Base::new())
+    fn new() -> PyClassInitializer<Self> {
+        PyClassInitializer::from(Base::new()).add_subclass(Self)
     }
 
     fn __init__(mut slf: pyo3::PyClassGuardMut<'_, Self>) {
diff --git a/tests/test_compile_error.rs b/tests/test_compile_error.rs
@@ -6,6 +6,7 @@ fn test_compile_errors() {
     let t = trybuild::TestCases::new();
 
     t.compile_fail("tests/ui/deprecated_pyfn.rs");
+    t.compile_fail("tests/ui/deprecated_super_init.rs");
     #[cfg(not(feature = "experimental-inspect"))]
     t.compile_fail("tests/ui/invalid_property_args.rs");
     t.compile_fail("tests/ui/invalid_proto_pymethods.rs");
diff --git a/tests/test_gc.rs b/tests/test_gc.rs
@@ -256,11 +256,9 @@ fn inheritance_with_new_methods_with_drop() {
     #[pymethods]
     impl SubClassWithDrop {
         #[new]
-        fn new() -> (Self, BaseClassWithDrop) {
-            (
-                SubClassWithDrop { guard: None },
-                BaseClassWithDrop { guard: None },
-            )
+        fn new() -> PyClassInitializer<Self> {
+            PyClassInitializer::from(BaseClassWithDrop { guard: None })
+                .add_subclass(SubClassWithDrop { guard: None })
         }
     }
 
diff --git a/tests/test_inheritance.rs b/tests/test_inheritance.rs
@@ -57,8 +57,8 @@ struct SubClass {
 #[pymethods]
 impl SubClass {
     #[new]
-    fn new() -> (Self, BaseClass) {
-        (SubClass { val2: 5 }, BaseClass { val1: 10 })
+    fn new() -> PyClassInitializer<Self> {
+        PyClassInitializer::from(BaseClass { val1: 10 }).add_subclass(SubClass { val2: 5 })
     }
     fn sub_method(&self, x: usize) -> usize {
         x * self.val2
@@ -146,9 +146,9 @@ struct SubClass2 {}
 #[pymethods]
 impl SubClass2 {
     #[new]
-    fn new(value: isize) -> PyResult<(Self, BaseClassWithResult)> {
+    fn new(value: isize) -> PyResult<PyClassInitializer<Self>> {
         let base = BaseClassWithResult::new(value)?;
-        Ok((Self {}, base))
+        Ok(PyClassInitializer::from(base).add_subclass(Self {}))
     }
 }
 
diff --git a/tests/test_super.rs b/tests/test_super.rs
@@ -25,8 +25,8 @@ struct SubClass {}
 #[pymethods]
 impl SubClass {
     #[new]
-    fn new() -> (Self, BaseClass) {
-        (SubClass {}, BaseClass::new())
+    fn new() -> PyClassInitializer<Self> {
+        PyClassInitializer::from(BaseClass::new()).add_subclass(Self {})
     }
 
     fn method<'py>(self_: &Bound<'py, Self>) -> PyResult<Bound<'py, PyAny>> {
diff --git a/tests/ui/deprecated_super_init.rs b/tests/ui/deprecated_super_init.rs
diff --git a/tests/ui/deprecated_super_init.stderr b/tests/ui/deprecated_super_init.stderr

Original file line number	Diff line number	Diff line change
`@@ -114,6 +114,10 @@ where`
`114`	`114`	`B: PyClass + PyClassBaseType<Initializer = PyClassInitializer<B>>,`
`115`	`115`	`B::BaseType: PyClassBaseType<Initializer = PyNativeTypeInitializer<B::BaseType>>,`
`116`	`116`	`{`
	`117`	`+ #[deprecated(`
	`118`	`+ since = "0.28.0",`
	`119`	+ note = "Tuple syntax for super class initialization is phased out. Use `PyClassInitializer` instead."
	`120`	`+ )]`
`117`	`121`	`pub const VALUE: bool = true;`
`118`	`122`	`}`
`119`	`123`	`impl<S, B, E> IsInitializerTuple<Result<(S, B), E>>`
`@@ -122,6 +126,10 @@ where`
`122`	`126`	`B: PyClass + PyClassBaseType<Initializer = PyClassInitializer<B>>,`
`123`	`127`	`B::BaseType: PyClassBaseType<Initializer = PyNativeTypeInitializer<B::BaseType>>,`
`124`	`128`	`{`
	`129`	`+ #[deprecated(`
	`130`	`+ since = "0.28.0",`
	`131`	+ note = "Tuple syntax for super class initialization is phased out. Use `PyClassInitializer` instead."
	`132`	`+ )]`
`125`	`133`	`pub const VALUE: bool = true;`
`126`	`134`	`}`
`127`	`135`