From 3975c85e6b7af76b25dd4756500478c0b76cfc75 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Mon, 26 Jan 2026 14:15:03 -0700
Subject: [PATCH 01/15] Use PyModExport and PyABIInfo APIs in pymodule
 implementation

---
 pyo3-macros-backend/src/module.rs |   2 +-
 src/impl_/pymodule.rs             | 198 ++++++++++++++++++++++--------
 2 files changed, 146 insertions(+), 54 deletions(-)

diff --git a/pyo3-macros-backend/src/module.rs b/pyo3-macros-backend/src/module.rs
index a5642a8905e..9a4279ff060 100644
--- a/pyo3-macros-backend/src/module.rs
+++ b/pyo3-macros-backend/src/module.rs
@@ -531,7 +531,7 @@ fn module_initialization(
                 #pyo3_path::impl_::trampoline::module_exec(module, #module_exec)
             }
 
-            static SLOTS: impl_::PyModuleSlots<4> = impl_::PyModuleSlotsBuilder::new()
+            static SLOTS: impl_::PyModuleSlots = impl_::PyModuleSlotsBuilder::new()
                 .with_mod_exec(__pyo3_module_exec)
                 .with_gil_used(#gil_used)
                 .build();
diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index b1bf6fb8878..dcbad95d9c7 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -37,7 +37,14 @@ use crate::{ffi_ptr_ext::FfiPtrExt, PyErr};
 /// `Sync` wrapper of `ffi::PyModuleDef`.
 pub struct ModuleDef {
     // wrapped in UnsafeCell so that Rust compiler treats this as interior mutability
+    #[cfg(not(Py_3_15))]
     ffi_def: UnsafeCell<ffi::PyModuleDef>,
+    #[cfg(Py_3_15)]
+    name: &'static CStr,
+    #[cfg(Py_3_15)]
+    doc: &'static CStr,
+    #[cfg(Py_3_15)]
+    slots: &'static PyModuleSlots,
     /// Interpreter ID where module was initialized (not applicable on PyPy).
     #[cfg(all(
         not(any(PyPy, GraalPy)),
@@ -53,14 +60,12 @@ unsafe impl Sync for ModuleDef {}
 
 impl ModuleDef {
     /// Make new module definition with given module name.
-    pub const fn new<const N: usize>(
+    pub const fn new(
         name: &'static CStr,
         doc: &'static CStr,
-        // TODO: it might be nice to make this unsized and not need the
-        // const N generic parameter, however that might need unsized return values
-        // or other messy hacks.
-        slots: &'static PyModuleSlots<N>,
+        slots: &'static PyModuleSlots,
     ) -> Self {
+        #[cfg(not(Py_3_15))]
         #[allow(clippy::declare_interior_mutable_const)]
         const INIT: ffi::PyModuleDef = ffi::PyModuleDef {
             m_base: ffi::PyModuleDef_HEAD_INIT,
@@ -74,6 +79,7 @@ impl ModuleDef {
             m_free: None,
         };
 
+        #[cfg(not(Py_3_15))]
         let ffi_def = UnsafeCell::new(ffi::PyModuleDef {
             m_name: name.as_ptr(),
             m_doc: doc.as_ptr(),
@@ -84,7 +90,14 @@ impl ModuleDef {
         });
 
         ModuleDef {
+            #[cfg(not(Py_3_15))]
             ffi_def,
+            #[cfg(Py_3_15)]
+            name,
+            #[cfg(Py_3_15)]
+            doc,
+            #[cfg(Py_3_15)]
+            slots,
             // -1 is never expected to be a valid interpreter ID
             #[cfg(all(
                 not(any(PyPy, GraalPy)),
@@ -98,7 +111,14 @@ impl ModuleDef {
 
     pub fn init_multi_phase(&'static self) -> *mut ffi::PyObject {
         // SAFETY: `ffi_def` is correctly initialized in `new()`
-        unsafe { ffi::PyModuleDef_Init(self.ffi_def.get()) }
+        #[cfg(not(Py_3_15))]
+        unsafe {
+            ffi::PyModuleDef_Init(self.ffi_def.get())
+        }
+        #[cfg(Py_3_15)]
+        unreachable!(
+            "Python shouldn't be calling an intialization function in Python 3.15 or newer"
+        )
     }
 
     /// Builds a module object directly. Used for [`#[pymodule]`][crate::pymodule] submodules.
@@ -150,47 +170,88 @@ impl ModuleDef {
         static SIMPLE_NAMESPACE: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
         let simple_ns = SIMPLE_NAMESPACE.import(py, "types", "SimpleNamespace")?;
 
-        let ffi_def = self.ffi_def.get();
-
-        let name = unsafe { CStr::from_ptr((*ffi_def).m_name).to_str()? }.to_string();
-        let kwargs = PyDict::new(py);
-        kwargs.set_item("name", name)?;
-        let spec = simple_ns.call((), Some(&kwargs))?;
+        #[cfg(not(Py_3_15))]
+        {
+            let ffi_def = self.ffi_def.get();
+
+            let name = unsafe { CStr::from_ptr((*ffi_def).m_name).to_str()? }.to_string();
+            let kwargs = PyDict::new(py);
+            kwargs.set_item("name", name)?;
+            let spec = simple_ns.call((), Some(&kwargs))?;
+
+            self.module
+                .get_or_try_init(py, || {
+                    let def = self.ffi_def.get();
+                    let module = unsafe {
+                        ffi::PyModule_FromDefAndSpec(def, spec.as_ptr()).assume_owned_or_err(py)?
+                    }
+                    .cast_into()?;
+                    if unsafe { ffi::PyModule_ExecDef(module.as_ptr(), def) } != 0 {
+                        return Err(PyErr::fetch(py));
+                    }
+                    Ok(module.unbind())
+                })
+                .map(|py_module| py_module.clone_ref(py))
+        }
 
-        self.module
-            .get_or_try_init(py, || {
-                let def = self.ffi_def.get();
-                let module = unsafe {
-                    ffi::PyModule_FromDefAndSpec(def, spec.as_ptr()).assume_owned_or_err(py)?
-                }
-                .cast_into()?;
-                if unsafe { ffi::PyModule_ExecDef(module.as_ptr(), def) } != 0 {
-                    return Err(PyErr::fetch(py));
-                }
-                Ok(module.unbind())
-            })
-            .map(|py_module| py_module.clone_ref(py))
+        #[cfg(Py_3_15)]
+        {
+            let name = self.name;
+            let doc = self.doc;
+            let kwargs = PyDict::new(py);
+            kwargs.set_item("name", name)?;
+            let spec = simple_ns.call((), Some(&kwargs))?;
+
+            self.module
+                .get_or_try_init(py, || {
+                    let slots = self.slots.0.get() as *const ffi::PyModuleDef_Slot;
+                    let module = unsafe { ffi::PyModule_FromSlotsAndSpec(slots, spec.as_ptr()) };
+                    if unsafe { ffi::PyModule_SetDocString(module, doc.as_ptr()) } != 0 {
+                        return Err(PyErr::fetch(py));
+                    }
+                    let module = unsafe { module.assume_owned_or_err(py)? }.cast_into()?;
+                    if unsafe { ffi::PyModule_Exec(module.as_ptr()) } != 0 {
+                        return Err(PyErr::fetch(py));
+                    }
+                    Ok(module.unbind())
+                })
+                .map(|py_module| py_module.clone_ref(py))
+        }
     }
 }
 
 /// Type of the exec slot used to initialise module contents
 pub type ModuleExecSlot = unsafe extern "C" fn(*mut ffi::PyObject) -> c_int;
 
+const MAX_SLOTS: usize =
+    // Py_mod_exec and a trailing null entry
+    2 +
+    // Py_mod_gil
+    cfg!(Py_3_13) as usize +
+    // Py_mod_name and Py_mod_abi
+    2 * (cfg!(Py_3_15) as usize);
+
 /// Builder to create `PyModuleSlots`. The size of the number of slots desired must
 /// be known up front, and N needs to be at least one greater than the number of
 /// actual slots pushed due to the need to have a zeroed element on the end.
-pub struct PyModuleSlotsBuilder<const N: usize> {
+pub struct PyModuleSlotsBuilder {
     // values (initially all zeroed)
-    values: [ffi::PyModuleDef_Slot; N],
+    values: [ffi::PyModuleDef_Slot; MAX_SLOTS],
     // current length
     len: usize,
 }
 
-impl<const N: usize> PyModuleSlotsBuilder<N> {
+// note that macros cannot use conditional compilation,
+// so all implementations below must be available in all
+// Python versions
+// By handling it here we can avoid conditional
+// compilation within the macros; they can always emit
+// e.g. a `.with_gil_used()` call.
+impl PyModuleSlotsBuilder {
     #[allow(clippy::new_without_default)]
     pub const fn new() -> Self {
         Self {
-            values: [unsafe { std::mem::zeroed() }; N],
+            values: [unsafe { std::mem::zeroed() }; MAX_SLOTS],
             len: 0,
         }
     }
@@ -216,22 +277,44 @@ impl<const N: usize> PyModuleSlotsBuilder<N> {
         {
             // Silence unused variable warning
             let _ = gil_used;
+            self
+        }
+    }
+
+    pub const fn with_name(self, name: &'static CStr) -> Self {
+        #[cfg(Py_3_15)]
+        {
+            self.push(ffi::Py_mod_name, name.as_ptr() as *mut c_void)
+        }
+
+        #[cfg(not(Py_3_15))]
+        {
+            // Silence unused variable warning
+            let _ = name;
+            self
+        }
+    }
 
-            // Py_mod_gil didn't exist before 3.13, can just make
-            // this function a noop.
-            //
-            // By handling it here we can avoid conditional
-            // compilation within the macros; they can always emit
-            // a `.with_gil_used()` call.
+    pub const fn with_abi_info(self) -> Self {
+        #[cfg(Py_3_15)]
+        {
+            ffi::PyABIInfo_VAR!(ABI_INFO);
+            self.push(ffi::Py_mod_abi, std::ptr::addr_of_mut!(ABI_INFO).cast())
+        }
+
+        #[cfg(not(Py_3_15))]
+        {
+            // Silence unused variable warning
+            let _ = abi_info;
             self
         }
     }
 
-    pub const fn build(self) -> PyModuleSlots<N> {
+    pub const fn build(self) -> PyModuleSlots {
         // Required to guarantee there's still a zeroed element
         // at the end
         assert!(
-            self.len < N,
+            self.len < MAX_SLOTS,
             "N must be greater than the number of slots pushed"
         );
         PyModuleSlots(UnsafeCell::new(self.values))
@@ -245,13 +328,13 @@ impl<const N: usize> PyModuleSlotsBuilder<N> {
 }
 
 /// Wrapper to safely store module slots, to be used in a `ModuleDef`.
-pub struct PyModuleSlots<const N: usize>(UnsafeCell<[ffi::PyModuleDef_Slot; N]>);
+pub struct PyModuleSlots(UnsafeCell<[ffi::PyModuleDef_Slot; MAX_SLOTS]>);
 
 // It might be possible to avoid this with SyncUnsafeCell in the future
 //
 // SAFETY: the inner values are only accessed within a `ModuleDef`,
 // which only uses them to build the `ffi::ModuleDef`.
-unsafe impl<const N: usize> Sync for PyModuleSlots<N> {}
+unsafe impl Sync for PyModuleSlots {}
 
 /// Trait to add an element (class, function...) to a module.
 ///
@@ -335,10 +418,17 @@ mod tests {
             }
         }
 
-        static SLOTS: PyModuleSlots<2> = PyModuleSlotsBuilder::new()
+        static NAME: &CStr = c"test_module";
+        static DOC: &CStr = c"some doc";
+
+        static SLOTS: PyModuleSlots = PyModuleSlotsBuilder::new()
             .with_mod_exec(module_exec)
+            .with_gil_used(false)
+            .with_abi_info()
+            .with_name(NAME)
             .build();
-        static MODULE_DEF: ModuleDef = ModuleDef::new(c"test_module", c"some doc", &SLOTS);
+
+        static MODULE_DEF: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS);
 
         Python::attach(|py| {
             let module = MODULE_DEF.make_module(py).unwrap().into_bound(py);
@@ -376,24 +466,22 @@ mod tests {
         static NAME: &CStr = c"test_module";
         static DOC: &CStr = c"some doc";
 
-        static SLOTS: PyModuleSlots<2> = PyModuleSlotsBuilder::new().build();
+        static SLOTS: PyModuleSlots = PyModuleSlotsBuilder::new().build();
+
+        let module_def: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS);
 
+        #[cfg(not(Py_3_15))]
         unsafe {
-            let module_def: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS);
             assert_eq!((*module_def.ffi_def.get()).m_name, NAME.as_ptr() as _);
             assert_eq!((*module_def.ffi_def.get()).m_doc, DOC.as_ptr() as _);
             assert_eq!((*module_def.ffi_def.get()).m_slots, SLOTS.0.get().cast());
         }
-    }
-
-    #[test]
-    #[should_panic]
-    fn test_module_slots_builder_overflow() {
-        unsafe extern "C" fn module_exec(_module: *mut ffi::PyObject) -> c_int {
-            0
+        #[cfg(Py_3_15)]
+        {
+            assert_eq!(module_def.name, NAME);
+            assert_eq!(module_def.doc, DOC);
+            assert_eq!(module_def.slots.0.get(), SLOTS.0.get());
         }
-
-        PyModuleSlotsBuilder::<0>::new().with_mod_exec(module_exec);
     }
 
     #[test]
@@ -403,7 +491,11 @@ mod tests {
             0
         }
 
-        PyModuleSlotsBuilder::<2>::new()
+        PyModuleSlotsBuilder::new()
+            .with_mod_exec(module_exec)
+            .with_mod_exec(module_exec)
+            .with_mod_exec(module_exec)
+            .with_mod_exec(module_exec)
             .with_mod_exec(module_exec)
             .with_mod_exec(module_exec)
             .build();

From 7b032a20585f292fffc46ae5b0e7cb7adf973379 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Mon, 26 Jan 2026 14:26:35 -0700
Subject: [PATCH 02/15] Add PyModExport function

---
 pyo3-macros-backend/src/module.rs | 12 +++++++++++-
 src/impl_/pymodule.rs             | 21 ++++++++++++++++-----
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/pyo3-macros-backend/src/module.rs b/pyo3-macros-backend/src/module.rs
index 9a4279ff060..afd16746d2e 100644
--- a/pyo3-macros-backend/src/module.rs
+++ b/pyo3-macros-backend/src/module.rs
@@ -511,6 +511,7 @@ fn module_initialization(
 ) -> TokenStream {
     let Ctx { pyo3_path, .. } = ctx;
     let pyinit_symbol = format!("PyInit_{name}");
+    let pymodexport_symbol = format!("PyModExport_{name}");
     let pyo3_name = LitCStr::new(&CString::new(full_name).unwrap(), Span::call_site());
 
     let mut result = quote! {
@@ -542,13 +543,22 @@ fn module_initialization(
     if !is_submodule {
         result.extend(quote! {
             /// This autogenerated function is called by the python interpreter when importing
-            /// the module.
+            /// the module on Python 3.14 and older.
             #[doc(hidden)]
             #[export_name = #pyinit_symbol]
             pub unsafe extern "C" fn __pyo3_init() -> *mut #pyo3_path::ffi::PyObject {
                 _PYO3_DEF.init_multi_phase()
             }
         });
+        result.extend(quote! {
+            /// This autogenerated function is called by the python interpreter when importing
+            /// the module on Python 3.15 and newer.
+            #[doc(hidden)]
+            #[export_name = #pymodexport_symbol]
+            pub unsafe extern "C" fn __pyo3_export() -> *mut #pyo3_path::ffi::PyModuleDef_Slot {
+                _PYO3_DEF.get_slots()
+            }
+        });
     }
     result
 }
diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index dcbad95d9c7..0f099cd20a5 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -43,8 +43,7 @@ pub struct ModuleDef {
     name: &'static CStr,
     #[cfg(Py_3_15)]
     doc: &'static CStr,
-    #[cfg(Py_3_15)]
-    slots: &'static PyModuleSlots,
+    slots: Option<&'static PyModuleSlots>,
     /// Interpreter ID where module was initialized (not applicable on PyPy).
     #[cfg(all(
         not(any(PyPy, GraalPy)),
@@ -97,7 +96,9 @@ impl ModuleDef {
             #[cfg(Py_3_15)]
             doc,
             #[cfg(Py_3_15)]
-            slots,
+            slots: Some(slots),
+            #[cfg(not(Py_3_15))]
+            slots: None,
             // -1 is never expected to be a valid interpreter ID
             #[cfg(all(
                 not(any(PyPy, GraalPy)),
@@ -204,7 +205,7 @@ impl ModuleDef {
 
             self.module
                 .get_or_try_init(py, || {
-                    let slots = self.slots.0.get() as *const ffi::PyModuleDef_Slot;
+                    let slots = self.get_slots();
                     let module = unsafe { ffi::PyModule_FromSlotsAndSpec(slots, spec.as_ptr()) };
                     if unsafe { ffi::PyModule_SetDocString(module, doc.as_ptr()) } != 0 {
                         return Err(PyErr::fetch(py));
@@ -218,6 +219,16 @@ impl ModuleDef {
                 .map(|py_module| py_module.clone_ref(py))
         }
     }
+    pub fn get_slots(&'static self) -> *mut ffi::PyModuleDef_Slot {
+        #[cfg(Py_3_15)]
+        {
+            self.slots.unwrap().0.get() as *mut ffi::PyModuleDef_Slot
+        }
+        #[cfg(not(Py_3_15))]
+        {
+            unsafe { *self.ffi_def.get() }.m_slots
+        }
+    }
 }
 
 /// Type of the exec slot used to initialise module contents
@@ -480,7 +491,7 @@ mod tests {
         {
             assert_eq!(module_def.name, NAME);
             assert_eq!(module_def.doc, DOC);
-            assert_eq!(module_def.slots.0.get(), SLOTS.0.get());
+            assert_eq!(module_def.slots.unwrap().0.get(), SLOTS.0.get());
         }
     }
 

From a7375d165a1def45b79ec2ade343c965b8731864 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Mon, 26 Jan 2026 14:27:52 -0700
Subject: [PATCH 03/15] DNM: temporarily disable append_to_inittab doctest

---
 guide/src/python-from-rust/calling-existing-code.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/guide/src/python-from-rust/calling-existing-code.md b/guide/src/python-from-rust/calling-existing-code.md
index ecc4167179d..fd38cfe0e95 100644
--- a/guide/src/python-from-rust/calling-existing-code.md
+++ b/guide/src/python-from-rust/calling-existing-code.md
@@ -140,7 +140,7 @@ The macro **must** be invoked _before_ initializing Python.
 
 As an example, the below adds the module `foo` to the embedded interpreter:
 
-```rust
+```rust,no_run
 use pyo3::prelude::*;
 
 #[pymodule]

From 6816e2ffddb932ea3fd851246510dc209160440e Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Mon, 26 Jan 2026 15:04:18 -0700
Subject: [PATCH 04/15] fix issues seen on older pythons in CI

---
 src/impl_/pymodule.rs | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index 0f099cd20a5..e4ee02490cc 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -43,7 +43,8 @@ pub struct ModuleDef {
     name: &'static CStr,
     #[cfg(Py_3_15)]
     doc: &'static CStr,
-    slots: Option<&'static PyModuleSlots>,
+    #[cfg(Py_3_15)]
+    slots: &'static PyModuleSlots,
     /// Interpreter ID where module was initialized (not applicable on PyPy).
     #[cfg(all(
         not(any(PyPy, GraalPy)),
@@ -97,8 +98,6 @@ impl ModuleDef {
             doc,
             #[cfg(Py_3_15)]
             slots: Some(slots),
-            #[cfg(not(Py_3_15))]
-            slots: None,
             // -1 is never expected to be a valid interpreter ID
             #[cfg(all(
                 not(any(PyPy, GraalPy)),
@@ -222,11 +221,11 @@ impl ModuleDef {
     pub fn get_slots(&'static self) -> *mut ffi::PyModuleDef_Slot {
         #[cfg(Py_3_15)]
         {
-            self.slots.unwrap().0.get() as *mut ffi::PyModuleDef_Slot
+            self.slots.0.get() as *mut ffi::PyModuleDef_Slot
         }
         #[cfg(not(Py_3_15))]
         {
-            unsafe { *self.ffi_def.get() }.m_slots
+            unsafe { (*self.ffi_def.get()).m_slots }
         }
     }
 }
@@ -315,8 +314,6 @@ impl PyModuleSlotsBuilder {
 
         #[cfg(not(Py_3_15))]
         {
-            // Silence unused variable warning
-            let _ = abi_info;
             self
         }
     }
@@ -491,7 +488,7 @@ mod tests {
         {
             assert_eq!(module_def.name, NAME);
             assert_eq!(module_def.doc, DOC);
-            assert_eq!(module_def.slots.unwrap().0.get(), SLOTS.0.get());
+            assert_eq!(module_def.slots.0.get(), SLOTS.0.get());
         }
     }
 

From c289ea5e14e5a154892f6897429972c53faeafbf Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Mon, 26 Jan 2026 15:35:19 -0700
Subject: [PATCH 05/15] fix incorrect ModuleDef setup on 3.15

---
 src/impl_/pymodule.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index e4ee02490cc..657cf9de524 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -97,7 +97,7 @@ impl ModuleDef {
             #[cfg(Py_3_15)]
             doc,
             #[cfg(Py_3_15)]
-            slots: Some(slots),
+            slots,
             // -1 is never expected to be a valid interpreter ID
             #[cfg(all(
                 not(any(PyPy, GraalPy)),

From 2392337c8cf829aa72bd96b9842a3470a20d067d Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Tue, 27 Jan 2026 09:39:11 -0700
Subject: [PATCH 06/15] Expose both the PyInit and PyModExport initialization
 hooks

---
 .../python-from-rust/calling-existing-code.md |  2 +-
 pyo3-macros-backend/src/module.rs             | 16 ++++++-
 src/impl_/pymodule.rs                         | 47 ++++++++++++-------
 3 files changed, 45 insertions(+), 20 deletions(-)

diff --git a/guide/src/python-from-rust/calling-existing-code.md b/guide/src/python-from-rust/calling-existing-code.md
index fd38cfe0e95..ecc4167179d 100644
--- a/guide/src/python-from-rust/calling-existing-code.md
+++ b/guide/src/python-from-rust/calling-existing-code.md
@@ -140,7 +140,7 @@ The macro **must** be invoked _before_ initializing Python.
 
 As an example, the below adds the module `foo` to the embedded interpreter:
 
-```rust,no_run
+```rust
 use pyo3::prelude::*;
 
 #[pymodule]
diff --git a/pyo3-macros-backend/src/module.rs b/pyo3-macros-backend/src/module.rs
index afd16746d2e..87ae8ffa68c 100644
--- a/pyo3-macros-backend/src/module.rs
+++ b/pyo3-macros-backend/src/module.rs
@@ -532,12 +532,26 @@ fn module_initialization(
                 #pyo3_path::impl_::trampoline::module_exec(module, #module_exec)
             }
 
+            // The full slots, used for the PyModExport initializaiton
             static SLOTS: impl_::PyModuleSlots = impl_::PyModuleSlotsBuilder::new()
                 .with_mod_exec(__pyo3_module_exec)
                 .with_gil_used(#gil_used)
+                .with_name(__PYO3_NAME)
+                .with_doc(#doc)
                 .build();
 
-            impl_::ModuleDef::new(__PYO3_NAME, #doc, &SLOTS)
+            // Used for old-style PyModuleDef initialization
+            // CPython doesn't allow specifying slots like the name and docstring that
+            // can be defined in PyModuleDef, so we skip those slots
+            static SLOTS_MINIMAL: impl_::PyModuleSlots = impl_::PyModuleSlotsBuilder::new()
+                .with_mod_exec(__pyo3_module_exec)
+                .with_gil_used(#gil_used)
+                .build();
+
+            // Since the macros need to be written agnostic to the Python version
+            // we need to explicitly pass the name and docstring for PyModuleDef
+            // initializaiton.
+            impl_::ModuleDef::new(__PYO3_NAME, #doc, &SLOTS, &SLOTS_MINIMAL)
         };
     };
     if !is_submodule {
diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index 657cf9de524..f26686aff9b 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -37,7 +37,6 @@ use crate::{ffi_ptr_ext::FfiPtrExt, PyErr};
 /// `Sync` wrapper of `ffi::PyModuleDef`.
 pub struct ModuleDef {
     // wrapped in UnsafeCell so that Rust compiler treats this as interior mutability
-    #[cfg(not(Py_3_15))]
     ffi_def: UnsafeCell<ffi::PyModuleDef>,
     #[cfg(Py_3_15)]
     name: &'static CStr,
@@ -64,8 +63,11 @@ impl ModuleDef {
         name: &'static CStr,
         doc: &'static CStr,
         slots: &'static PyModuleSlots,
+        slots_with_no_name_or_doc: &'static PyModuleSlots,
     ) -> Self {
-        #[cfg(not(Py_3_15))]
+        // This is only used in PyO3 for append_to_inittab on Python 3.15 and newer.
+        // There could also be other tools that need the legacy init hook.
+        // Opaque PyObject builds won't be able to use this.
         #[allow(clippy::declare_interior_mutable_const)]
         const INIT: ffi::PyModuleDef = ffi::PyModuleDef {
             m_base: ffi::PyModuleDef_HEAD_INIT,
@@ -79,18 +81,16 @@ impl ModuleDef {
             m_free: None,
         };
 
-        #[cfg(not(Py_3_15))]
         let ffi_def = UnsafeCell::new(ffi::PyModuleDef {
             m_name: name.as_ptr(),
             m_doc: doc.as_ptr(),
             // TODO: would be slightly nicer to use `[T]::as_mut_ptr()` here,
             // but that requires mut ptr deref on MSRV.
-            m_slots: slots.0.get() as _,
+            m_slots: slots_with_no_name_or_doc.0.get() as _,
             ..INIT
         });
 
         ModuleDef {
-            #[cfg(not(Py_3_15))]
             ffi_def,
             #[cfg(Py_3_15)]
             name,
@@ -110,15 +110,7 @@ impl ModuleDef {
     }
 
     pub fn init_multi_phase(&'static self) -> *mut ffi::PyObject {
-        // SAFETY: `ffi_def` is correctly initialized in `new()`
-        #[cfg(not(Py_3_15))]
-        unsafe {
-            ffi::PyModuleDef_Init(self.ffi_def.get())
-        }
-        #[cfg(Py_3_15)]
-        unreachable!(
-            "Python shouldn't be calling an intialization function in Python 3.15 or newer"
-        )
+        unsafe { ffi::PyModuleDef_Init(self.ffi_def.get()) }
     }
 
     /// Builds a module object directly. Used for [`#[pymodule]`][crate::pymodule] submodules.
@@ -238,8 +230,8 @@ const MAX_SLOTS: usize =
     2 +
     // Py_mod_gil
     cfg!(Py_3_13) as usize +
-    // Py_mod_name and Py_mod_abi
-    2 * (cfg!(Py_3_15) as usize);
+    // Py_mod_name, Py_mod_doc, and Py_mod_abi
+    3 * (cfg!(Py_3_15) as usize);
 
 /// Builder to create `PyModuleSlots`. The size of the number of slots desired must
 /// be known up front, and N needs to be at least one greater than the number of
@@ -318,6 +310,18 @@ impl PyModuleSlotsBuilder {
         }
     }
 
+    pub const fn with_doc(self, doc: &'static CStr) -> Self {
+        #[cfg(Py_3_15)]
+        {
+            self.push(ffi::Py_mod_doc, doc.as_ptr() as *mut c_void)
+        }
+
+        #[cfg(not(Py_3_15))]
+        {
+            self
+        }
+    }
+
     pub const fn build(self) -> PyModuleSlots {
         // Required to guarantee there's still a zeroed element
         // at the end
@@ -434,9 +438,16 @@ mod tests {
             .with_gil_used(false)
             .with_abi_info()
             .with_name(NAME)
+            .with_doc(DOC)
+            .build();
+
+        static SLOTS_MINIMAL: PyModuleSlots = PyModuleSlotsBuilder::new()
+            .with_mod_exec(module_exec)
+            .with_gil_used(false)
+            .with_abi_info()
             .build();
 
-        static MODULE_DEF: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS);
+        static MODULE_DEF: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS, &SLOTS_MINIMAL);
 
         Python::attach(|py| {
             let module = MODULE_DEF.make_module(py).unwrap().into_bound(py);
@@ -476,7 +487,7 @@ mod tests {
 
         static SLOTS: PyModuleSlots = PyModuleSlotsBuilder::new().build();
 
-        let module_def: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS);
+        let module_def: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS, &SLOTS);
 
         #[cfg(not(Py_3_15))]
         unsafe {

From 957d8d358e21839f01cfc7fcf080069161421782 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Tue, 27 Jan 2026 09:49:29 -0700
Subject: [PATCH 07/15] fix clippy

---
 src/impl_/pymodule.rs | 29 ++++++++---------------------
 1 file changed, 8 insertions(+), 21 deletions(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index f26686aff9b..dbf88ba3b00 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -38,11 +38,10 @@ use crate::{ffi_ptr_ext::FfiPtrExt, PyErr};
 pub struct ModuleDef {
     // wrapped in UnsafeCell so that Rust compiler treats this as interior mutability
     ffi_def: UnsafeCell<ffi::PyModuleDef>,
-    #[cfg(Py_3_15)]
+    #[cfg_attr(not(Py_3_15), allow(dead_code))]
     name: &'static CStr,
-    #[cfg(Py_3_15)]
+    #[cfg_attr(not(Py_3_15), allow(dead_code))]
     doc: &'static CStr,
-    #[cfg(Py_3_15)]
     slots: &'static PyModuleSlots,
     /// Interpreter ID where module was initialized (not applicable on PyPy).
     #[cfg(all(
@@ -92,11 +91,8 @@ impl ModuleDef {
 
         ModuleDef {
             ffi_def,
-            #[cfg(Py_3_15)]
             name,
-            #[cfg(Py_3_15)]
             doc,
-            #[cfg(Py_3_15)]
             slots,
             // -1 is never expected to be a valid interpreter ID
             #[cfg(all(
@@ -211,14 +207,7 @@ impl ModuleDef {
         }
     }
     pub fn get_slots(&'static self) -> *mut ffi::PyModuleDef_Slot {
-        #[cfg(Py_3_15)]
-        {
-            self.slots.0.get() as *mut ffi::PyModuleDef_Slot
-        }
-        #[cfg(not(Py_3_15))]
-        {
-            unsafe { (*self.ffi_def.get()).m_slots }
-        }
+        self.slots.0.get() as *mut ffi::PyModuleDef_Slot
     }
 }
 
@@ -318,6 +307,8 @@ impl PyModuleSlotsBuilder {
 
         #[cfg(not(Py_3_15))]
         {
+            // Silence unused variable warning
+            let _ = doc;
             self
         }
     }
@@ -489,18 +480,14 @@ mod tests {
 
         let module_def: ModuleDef = ModuleDef::new(NAME, DOC, &SLOTS, &SLOTS);
 
-        #[cfg(not(Py_3_15))]
         unsafe {
             assert_eq!((*module_def.ffi_def.get()).m_name, NAME.as_ptr() as _);
             assert_eq!((*module_def.ffi_def.get()).m_doc, DOC.as_ptr() as _);
             assert_eq!((*module_def.ffi_def.get()).m_slots, SLOTS.0.get().cast());
         }
-        #[cfg(Py_3_15)]
-        {
-            assert_eq!(module_def.name, NAME);
-            assert_eq!(module_def.doc, DOC);
-            assert_eq!(module_def.slots.0.get(), SLOTS.0.get());
-        }
+        assert_eq!(module_def.name, NAME);
+        assert_eq!(module_def.doc, DOC);
+        assert_eq!(module_def.slots.0.get(), SLOTS.0.get());
     }
 
     #[test]

From add822c7812537f1a0359ebf790483fc8ac14de7 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Tue, 27 Jan 2026 10:31:03 -0700
Subject: [PATCH 08/15] add changelog entry

---
 newsfragments/5753.changed.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 newsfragments/5753.changed.md

diff --git a/newsfragments/5753.changed.md b/newsfragments/5753.changed.md
new file mode 100644
index 00000000000..5f22cf42516
--- /dev/null
+++ b/newsfragments/5753.changed.md
@@ -0,0 +1 @@
+Module initialization uses the PyModExport and PyABIInfo APIs on python 3.15 and newer.
\ No newline at end of file

From b9138e7ae0f7bfb1f786e1d2a70680bbf59464bd Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 13:37:31 -0700
Subject: [PATCH 09/15] avoid unnecessary extra quote! use

---
 pyo3-macros-backend/src/module.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/pyo3-macros-backend/src/module.rs b/pyo3-macros-backend/src/module.rs
index 87ae8ffa68c..512329f4d80 100644
--- a/pyo3-macros-backend/src/module.rs
+++ b/pyo3-macros-backend/src/module.rs
@@ -563,8 +563,7 @@ fn module_initialization(
             pub unsafe extern "C" fn __pyo3_init() -> *mut #pyo3_path::ffi::PyObject {
                 _PYO3_DEF.init_multi_phase()
             }
-        });
-        result.extend(quote! {
+
             /// This autogenerated function is called by the python interpreter when importing
             /// the module on Python 3.15 and newer.
             #[doc(hidden)]

From 29e1791476a52edda2d959a1ee4bc209464539a9 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 13:39:30 -0700
Subject: [PATCH 10/15] rename MAX_SLOTS as MAX_SLOTS_WITH_TRAILING_NULL

---
 src/impl_/pymodule.rs | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index dbf88ba3b00..f4bfc7d9f2f 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -215,19 +215,20 @@ impl ModuleDef {
 pub type ModuleExecSlot = unsafe extern "C" fn(*mut ffi::PyObject) -> c_int;
 
 const MAX_SLOTS: usize =
-    // Py_mod_exec and a trailing null entry
-    2 +
+    // Py_mod_exec
+    1 +
     // Py_mod_gil
     cfg!(Py_3_13) as usize +
     // Py_mod_name, Py_mod_doc, and Py_mod_abi
     3 * (cfg!(Py_3_15) as usize);
+const MAX_SLOTS_WITH_TRAILING_NULL: usize = MAX_SLOTS + 1;
 
 /// Builder to create `PyModuleSlots`. The size of the number of slots desired must
 /// be known up front, and N needs to be at least one greater than the number of
 /// actual slots pushed due to the need to have a zeroed element on the end.
 pub struct PyModuleSlotsBuilder {
     // values (initially all zeroed)
-    values: [ffi::PyModuleDef_Slot; MAX_SLOTS],
+    values: [ffi::PyModuleDef_Slot; MAX_SLOTS_WITH_TRAILING_NULL],
     // current length
     len: usize,
 }
@@ -242,7 +243,7 @@ impl PyModuleSlotsBuilder {
     #[allow(clippy::new_without_default)]
     pub const fn new() -> Self {
         Self {
-            values: [unsafe { std::mem::zeroed() }; MAX_SLOTS],
+            values: [unsafe { std::mem::zeroed() }; MAX_SLOTS_WITH_TRAILING_NULL],
             len: 0,
         }
     }
@@ -317,7 +318,7 @@ impl PyModuleSlotsBuilder {
         // Required to guarantee there's still a zeroed element
         // at the end
         assert!(
-            self.len < MAX_SLOTS,
+            self.len < MAX_SLOTS_WITH_TRAILING_NULL,
             "N must be greater than the number of slots pushed"
         );
         PyModuleSlots(UnsafeCell::new(self.values))
@@ -331,7 +332,7 @@ impl PyModuleSlotsBuilder {
 }
 
 /// Wrapper to safely store module slots, to be used in a `ModuleDef`.
-pub struct PyModuleSlots(UnsafeCell<[ffi::PyModuleDef_Slot; MAX_SLOTS]>);
+pub struct PyModuleSlots(UnsafeCell<[ffi::PyModuleDef_Slot; MAX_SLOTS_WITH_TRAILING_NULL]>);
 
 // It might be possible to avoid this with SyncUnsafeCell in the future
 //

From 9e3d495a63d47d71c5f14091287d8907c7d91f38 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 13:53:16 -0700
Subject: [PATCH 11/15] Move MAX_SLOTS check to push

---
 src/impl_/pymodule.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index f4bfc7d9f2f..b4b01e389fb 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -317,14 +317,14 @@ impl PyModuleSlotsBuilder {
     pub const fn build(self) -> PyModuleSlots {
         // Required to guarantee there's still a zeroed element
         // at the end
-        assert!(
-            self.len < MAX_SLOTS_WITH_TRAILING_NULL,
-            "N must be greater than the number of slots pushed"
-        );
         PyModuleSlots(UnsafeCell::new(self.values))
     }
 
     const fn push(mut self, slot: c_int, value: *mut c_void) -> Self {
+        assert!(
+            self.len <= MAX_SLOTS,
+            "Cannot add more than MAX_SLOTS slots to a PyModuleSlots",
+        );
         self.values[self.len] = ffi::PyModuleDef_Slot { slot, value };
         self.len += 1;
         self

From 35fd97505740a9e09390190627185d904215fb99 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 14:32:06 -0700
Subject: [PATCH 12/15] Apply David's suggestions for tests

---
 src/impl_/pymodule.rs | 42 ++++++++++++++++++++++++++++--------------
 1 file changed, 28 insertions(+), 14 deletions(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index b4b01e389fb..aea7e0db581 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -322,7 +322,7 @@ impl PyModuleSlotsBuilder {
 
     const fn push(mut self, slot: c_int, value: *mut c_void) -> Self {
         assert!(
-            self.len <= MAX_SLOTS,
+            self.len + 1 <= MAX_SLOTS,
             "Cannot add more than MAX_SLOTS slots to a PyModuleSlots",
         );
         self.values[self.len] = ffi::PyModuleDef_Slot { slot, value };
@@ -409,7 +409,11 @@ mod tests {
         Python,
     };
 
-    use super::ModuleDef;
+    use super::{ModuleDef, MAX_SLOTS};
+
+    unsafe extern "C" fn module_exec(_module: *mut ffi::PyObject) -> c_int {
+        0
+    }
 
     #[test]
     fn module_init() {
@@ -491,20 +495,30 @@ mod tests {
         assert_eq!(module_def.slots.0.get(), SLOTS.0.get());
     }
 
+    #[test]
+    fn test_build_maximal_slots() {
+        let builder = PyModuleSlotsBuilder::new()
+            .with_mod_exec(module_exec)
+            .with_name(c"test_module")
+            .with_doc(c"some doc")
+            .with_gil_used(false)
+            .with_abi_info();
+
+        assert!(builder.values[builder.len] == unsafe { std::mem::zeroed() });
+        assert!(builder.values[builder.len - 1] != unsafe { std::mem::zeroed() });
+        assert!(builder.len == MAX_SLOTS);
+
+        let result = std::panic::catch_unwind(|| builder.with_mod_exec(module_exec).build());
+
+        assert!(result.is_err());
+    }
+
     #[test]
     #[should_panic]
-    fn test_module_slots_builder_overflow_2() {
-        unsafe extern "C" fn module_exec(_module: *mut ffi::PyObject) -> c_int {
-            0
+    fn test_module_slots_builder_overflow() {
+        let mut builder = PyModuleSlotsBuilder::new();
+        for _ in 0..MAX_SLOTS + 1 {
+            builder = builder.with_mod_exec(module_exec);
         }
-
-        PyModuleSlotsBuilder::new()
-            .with_mod_exec(module_exec)
-            .with_mod_exec(module_exec)
-            .with_mod_exec(module_exec)
-            .with_mod_exec(module_exec)
-            .with_mod_exec(module_exec)
-            .with_mod_exec(module_exec)
-            .build();
     }
 }

From 3bd805a12a3d3ff0b538d25b51bafcfdf0d5f8d1 Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 14:32:25 -0700
Subject: [PATCH 13/15] Always include abi info slot in PyModule initialization

---
 pyo3-macros-backend/src/module.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pyo3-macros-backend/src/module.rs b/pyo3-macros-backend/src/module.rs
index 512329f4d80..a594adf6063 100644
--- a/pyo3-macros-backend/src/module.rs
+++ b/pyo3-macros-backend/src/module.rs
@@ -535,6 +535,7 @@ fn module_initialization(
             // The full slots, used for the PyModExport initializaiton
             static SLOTS: impl_::PyModuleSlots = impl_::PyModuleSlotsBuilder::new()
                 .with_mod_exec(__pyo3_module_exec)
+                .with_abi_info()
                 .with_gil_used(#gil_used)
                 .with_name(__PYO3_NAME)
                 .with_doc(#doc)
@@ -545,6 +546,7 @@ fn module_initialization(
             // can be defined in PyModuleDef, so we skip those slots
             static SLOTS_MINIMAL: impl_::PyModuleSlots = impl_::PyModuleSlotsBuilder::new()
                 .with_mod_exec(__pyo3_module_exec)
+                .with_abi_info()
                 .with_gil_used(#gil_used)
                 .build();
 

From b8d2191f6ea8c498841dbc96c4c8425b9ccd4b2d Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 14:43:53 -0700
Subject: [PATCH 14/15] only unwind panics if panic = "unwind"

---
 src/impl_/pymodule.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index aea7e0db581..8ca8420d92e 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -496,6 +496,7 @@ mod tests {
     }
 
     #[test]
+    #[cfg(panic = "unwind")]
     fn test_build_maximal_slots() {
         let builder = PyModuleSlotsBuilder::new()
             .with_mod_exec(module_exec)

From 9b62a4e8a0062d1119b38f84262020e91aeba7aa Mon Sep 17 00:00:00 2001
From: Nathan Goldbaum <nathan.goldbaum@gmail.com>
Date: Fri, 6 Feb 2026 14:59:00 -0700
Subject: [PATCH 15/15] appease clippy

---
 src/impl_/pymodule.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/impl_/pymodule.rs b/src/impl_/pymodule.rs
index 8ca8420d92e..8a1cf8249cc 100644
--- a/src/impl_/pymodule.rs
+++ b/src/impl_/pymodule.rs
@@ -315,14 +315,14 @@ impl PyModuleSlotsBuilder {
     }
 
     pub const fn build(self) -> PyModuleSlots {
-        // Required to guarantee there's still a zeroed element
-        // at the end
         PyModuleSlots(UnsafeCell::new(self.values))
     }
 
     const fn push(mut self, slot: c_int, value: *mut c_void) -> Self {
+        // Required to guarantee there's still a zeroed element
+        // at the end
         assert!(
-            self.len + 1 <= MAX_SLOTS,
+            self.len < MAX_SLOTS,
             "Cannot add more than MAX_SLOTS slots to a PyModuleSlots",
         );
         self.values[self.len] = ffi::PyModuleDef_Slot { slot, value };