move PyTypeInfo::NAME and ::MODULE into #[pyclass] machinery (#5579)

davidhewitt · web-flow · commit ebf95bd259f1 · 2025-11-08T19:36:29.000Z
* move `PyTypeInfo::NAME` and `::MODULE` into `#[pyclass]` machinery

* newsfragments

* fixup guide code block
diff --git a/guide/src/class.md b/guide/src/class.md
@@ -1409,17 +1409,19 @@ unsafe impl pyo3::type_object::PyTypeInfo for MyClass {
             .unwrap_or_else(|e| pyo3::impl_::pyclass::type_object_init_failed(
                 py,
                 e,
-                <Self as pyo3::type_object::PyTypeInfo>::NAME
+                <Self as pyo3::PyClass>::NAME
             ))
             .as_type_ptr()
     }
 }
 
 impl pyo3::PyClass for MyClass {
+    const NAME: &str = "MyClass";
     type Frozen = pyo3::pyclass::boolean_struct::False;
 }
 
 impl pyo3::impl_::pyclass::PyClassImpl for MyClass {
+    const MODULE: Option<&str> = None;
     const IS_BASETYPE: bool = false;
     const IS_SUBCLASS: bool = false;
     const IS_MAPPING: bool = false;
diff --git a/newsfragments/5579.added.md b/newsfragments/5579.added.md
@@ -0,0 +1 @@
+Add `PyClass::NAME`.
diff --git a/newsfragments/5579.changed.md b/newsfragments/5579.changed.md
@@ -0,0 +1 @@
+Deprecate `PyTypeInfo::NAME` and `PyTypeInfo::MODULE`.
diff --git a/pyo3-macros-backend/src/method.rs b/pyo3-macros-backend/src/method.rs
@@ -709,7 +709,7 @@ impl<'a> FnSpec<'a> {
                 };
                 let python_name = &self.python_name;
                 let qualname_prefix = match cls {
-                    Some(cls) => quote!(Some(<#cls as #pyo3_path::PyTypeInfo>::NAME)),
+                    Some(cls) => quote!(Some(<#cls as #pyo3_path::PyClass>::NAME)),
                     None => quote!(None),
                 };
                 let arg_names = (0..args.len())
diff --git a/pyo3-macros-backend/src/params.rs b/pyo3-macros-backend/src/params.rs
@@ -131,7 +131,7 @@ pub fn impl_arg_params(
     };
 
     let cls_name = if let Some(cls) = self_ {
-        quote! { ::std::option::Option::Some(<#cls as #pyo3_path::type_object::PyTypeInfo>::NAME) }
+        quote! { ::std::option::Option::Some(<#cls as #pyo3_path::PyClass>::NAME) }
     } else {
         quote! { ::std::option::Option::None }
     };
diff --git a/pyo3-macros-backend/src/pyclass.rs b/pyo3-macros-backend/src/pyclass.rs
@@ -1951,13 +1951,6 @@ fn descriptors_to_items(
 
 fn impl_pytypeinfo(cls: &syn::Ident, attr: &PyClassArgs, ctx: &Ctx) -> TokenStream {
     let Ctx { pyo3_path, .. } = ctx;
-    let cls_name = get_class_python_name(cls, attr).to_string();
-
-    let module = if let Some(ModuleAttribute { value, .. }) = &attr.options.module {
-        quote! { ::core::option::Option::Some(#value) }
-    } else {
-        quote! { ::core::option::Option::None }
-    };
 
     #[cfg(feature = "experimental-inspect")]
     let type_hint = {
@@ -1966,11 +1959,14 @@ fn impl_pytypeinfo(cls: &syn::Ident, attr: &PyClassArgs, ctx: &Ctx) -> TokenStre
     };
     #[cfg(not(feature = "experimental-inspect"))]
     let type_hint = quote! {};
+    #[cfg(not(feature = "experimental-inspect"))]
+    let _ = attr;
 
     quote! {
         unsafe impl #pyo3_path::type_object::PyTypeInfo for #cls {
-            const NAME: &'static str = #cls_name;
-            const MODULE: ::std::option::Option<&'static str> = #module;
+
+            const NAME: &str = <Self as #pyo3_path::PyClass>::NAME;
+            const MODULE: ::std::option::Option<&str> = <Self as #pyo3_path::impl_::pyclass::PyClassImpl>::MODULE;
 
             #type_hint
 
@@ -1982,7 +1978,7 @@ fn impl_pytypeinfo(cls: &syn::Ident, attr: &PyClassArgs, ctx: &Ctx) -> TokenStre
                     .unwrap_or_else(|e| #pyo3_path::impl_::pyclass::type_object_init_failed(
                         py,
                         e,
-                        <Self as #pyo3_path::type_object::PyTypeInfo>::NAME
+                        <Self as #pyo3_path::PyClass>::NAME
                     ))
                     .as_type_ptr()
             }
@@ -2328,6 +2324,8 @@ impl<'a> PyClassImplsBuilder<'a> {
         let Ctx { pyo3_path, .. } = ctx;
         let cls = self.cls;
 
+        let cls_name = get_class_python_name(cls, self.attr).to_string();
+
         let frozen = if self.attr.options.frozen.is_some() {
             quote! { #pyo3_path::pyclass::boolean_struct::True }
         } else {
@@ -2336,6 +2334,7 @@ impl<'a> PyClassImplsBuilder<'a> {
 
         quote! {
             impl #pyo3_path::PyClass for #cls {
+                const NAME: &str = #cls_name;
                 type Frozen = #frozen;
             }
         }
@@ -2378,6 +2377,13 @@ impl<'a> PyClassImplsBuilder<'a> {
             .doc
             .as_ref()
             .map_or(c"".to_token_stream(), PythonDoc::to_token_stream);
+
+        let module = if let Some(ModuleAttribute { value, .. }) = &self.attr.options.module {
+            quote! { ::core::option::Option::Some(#value) }
+        } else {
+            quote! { ::core::option::Option::None }
+        };
+
         let is_basetype = self.attr.options.subclass.is_some();
         let base = match &self.attr.options.extends {
             Some(extends_attr) => extends_attr.value.clone(),
@@ -2562,6 +2568,7 @@ impl<'a> PyClassImplsBuilder<'a> {
             #pyclass_base_type_impl
 
             impl #pyo3_path::impl_::pyclass::PyClassImpl for #cls {
+                const MODULE: ::std::option::Option<&str> = #module;
                 const IS_BASETYPE: bool = #is_basetype;
                 const IS_SUBCLASS: bool = #is_subclass;
                 const IS_MAPPING: bool = #is_mapping;
diff --git a/src/impl_/pyclass.rs b/src/impl_/pyclass.rs
@@ -157,6 +157,12 @@ unsafe impl Sync for PyClassItems {}
 /// Users are discouraged from implementing this trait manually; it is a PyO3 implementation detail
 /// and may be changed at any time.
 pub trait PyClassImpl: Sized + 'static {
+    /// Module which the class will be associated with.
+    ///
+    /// (Currently defaults to `builtins` if unset, this will likely be improved in the future, it
+    /// may also be removed when passing module objects in class init.)
+    const MODULE: Option<&'static str>;
+
     /// #[pyclass(subclass)]
     const IS_BASETYPE: bool = false;
 
diff --git a/src/impl_/pyclass/doc.rs b/src/impl_/pyclass/doc.rs
@@ -1,6 +1,6 @@
 use std::{ffi::CStr, marker::PhantomData};
 
-use crate::{impl_::pyclass::PyClassImpl, PyClass, PyTypeInfo};
+use crate::{impl_::pyclass::PyClassImpl, PyClass};
 
 /// Trait implemented by classes with a known text signature for instantiation.
 ///
@@ -26,7 +26,7 @@ pub struct PyClassDocGenerator<
 
 impl<ClassT: PyClass + PyClassNewTextSignature> PyClassDocGenerator<ClassT, true> {
     pub const DOC_PIECES: &'static [&'static [u8]] = &[
-        <ClassT as PyTypeInfo>::NAME.as_bytes(),
+        <ClassT as PyClass>::NAME.as_bytes(),
         ClassT::TEXT_SIGNATURE.as_bytes(),
         b"\n--\n\n",
         <ClassT as PyClassImpl>::RAW_DOC.to_bytes_with_nul(),
diff --git a/src/impl_/pyclass/lazy_type_object.rs b/src/impl_/pyclass/lazy_type_object.rs
@@ -69,8 +69,12 @@ impl<T: PyClass> LazyTypeObject<T> {
 
     #[cold]
     fn try_init<'py>(&self, py: Python<'py>) -> PyResult<&Bound<'py, PyType>> {
-        self.0
-            .get_or_try_init(py, create_type_object::<T>, T::NAME, T::items_iter())
+        self.0.get_or_try_init(
+            py,
+            create_type_object::<T>,
+            <T as PyClass>::NAME,
+            T::items_iter(),
+        )
     }
 }
 
diff --git a/src/pyclass.rs b/src/pyclass.rs
@@ -18,6 +18,11 @@ pub use self::guard::{
 /// The `#[pyclass]` attribute implements this trait for your Rust struct -
 /// you shouldn't implement this trait directly.
 pub trait PyClass: PyTypeInfo + PyClassImpl {
+    /// Name of the class.
+    ///
+    /// This can be set via `#[pyclass(name = "...")]`, otherwise it defaults to the Rust type name.
+    const NAME: &'static str;
+
     /// Whether the pyclass is frozen.
     ///
     /// This can be enabled via `#[pyclass(frozen)]`.
diff --git a/src/pyclass/create_type_object.rs b/src/pyclass/create_type_object.rs
@@ -8,7 +8,7 @@ use crate::{
         pycell::PyClassObject,
         pyclass::{
             assign_sequence_item_from_mapping, get_sequence_item_from_mapping, tp_dealloc,
-            tp_dealloc_with_gc, PyClassItemsIter,
+            tp_dealloc_with_gc, PyClassImpl, PyClassItemsIter,
         },
         pymethods::{Getter, PyGetterDef, PyMethodDefType, PySetterDef, Setter, _call_clear},
         trampoline::trampoline,
@@ -103,8 +103,8 @@ where
             T::weaklist_offset(),
             T::IS_BASETYPE,
             T::items_iter(),
-            T::NAME,
-            T::MODULE,
+            <T as PyClass>::NAME,
+            <T as PyClassImpl>::MODULE,
             std::mem::size_of::<PyClassObject<T>>(),
         )
     }
diff --git a/src/type_object.rs b/src/type_object.rs
@@ -43,9 +43,17 @@ pub trait PySizedLayout<T>: PyLayout<T> + Sized {}
 /// `is_exact_type_of` must only return true for objects whose type is exactly `Self`.
 pub unsafe trait PyTypeInfo: Sized {
     /// Class name.
+    #[deprecated(
+        since = "0.28.0",
+        note = "prefer using `::type_object(py).name()` to get the correct runtime value"
+    )]
     const NAME: &'static str;
 
     /// Module name, if any.
+    #[deprecated(
+        since = "0.28.0",
+        note = "prefer using `::type_object(py).module()` to get the correct runtime value"
+    )]
     const MODULE: Option<&'static str>;
 
     /// Provides the full python type as a type hint.
@@ -124,6 +132,7 @@ unsafe impl<T> PyTypeCheck for T
 where
     T: PyTypeInfo,
 {
+    #[allow(deprecated)]
     const NAME: &'static str = T::NAME;
 
     #[cfg(feature = "experimental-inspect")]
diff --git a/src/types/module.rs b/src/types/module.rs
@@ -496,7 +496,10 @@ impl<'py> PyModuleMethods<'py> for Bound<'py, PyModule> {
         T: PyClass,
     {
         let py = self.py();
-        self.add(T::NAME, T::lazy_type_object().get_or_try_init(py)?)
+        self.add(
+            <T as PyClass>::NAME,
+            T::lazy_type_object().get_or_try_init(py)?,
+        )
     }
 
     fn add_wrapped<T>(&self, wrapper: &impl Fn(Python<'py>) -> T) -> PyResult<()>

Original file line number	Diff line number	Diff line change
`@@ -1409,17 +1409,19 @@ unsafe impl pyo3::type_object::PyTypeInfo for MyClass {`
`1409`	`1409`	`.unwrap_or_else(\|e\| pyo3::impl_::pyclass::type_object_init_failed(`
`1410`	`1410`	`py,`
`1411`	`1411`	`e,`
`1412`		`- <Self as pyo3::type_object::PyTypeInfo>::NAME`
	`1412`	`+ <Self as pyo3::PyClass>::NAME`
`1413`	`1413`	`))`
`1414`	`1414`	`.as_type_ptr()`
`1415`	`1415`	`}`
`1416`	`1416`	`}`
`1417`	`1417`
`1418`	`1418`	`impl pyo3::PyClass for MyClass {`
	`1419`	`+ const NAME: &str = "MyClass";`
`1419`	`1420`	`type Frozen = pyo3::pyclass::boolean_struct::False;`
`1420`	`1421`	`}`
`1421`	`1422`
`1422`	`1423`	`impl pyo3::impl_::pyclass::PyClassImpl for MyClass {`
	`1424`	`+ const MODULE: Option<&str> = None;`
`1423`	`1425`	`const IS_BASETYPE: bool = false;`
`1424`	`1426`	`const IS_SUBCLASS: bool = false;`
`1425`	`1427`	`const IS_MAPPING: bool = false;`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Deprecate `PyTypeInfo::NAME` and `PyTypeInfo::MODULE`.
Original file line number	Diff line number	Diff line change
`@@ -69,8 +69,12 @@ impl<T: PyClass> LazyTypeObject<T> {`
`69`	`69`
`70`	`70`	`#[cold]`
`71`	`71`	`fn try_init<'py>(&self, py: Python<'py>) -> PyResult<&Bound<'py, PyType>> {`
`72`		`- self.0`
`73`		`- .get_or_try_init(py, create_type_object::<T>, T::NAME, T::items_iter())`
	`72`	`+ self.0.get_or_try_init(`
	`73`	`+ py,`
	`74`	`+ create_type_object::<T>,`
	`75`	`+ <T as PyClass>::NAME,`
	`76`	`+ T::items_iter(),`
	`77`	`+ )`
`74`	`78`	`}`
`75`	`79`	`}`
`76`	`80`