feat: create types with PyType_FromMetaclass on CPython 3.12+

.github/workflows/ci.yml

@@ -107,6 +107,34 @@ jobs:
       python-version: ${{ matrix.python-version }}
       cmake-args: -DPYBIND11_TEST_PRECOMPILE=ON
 
+  # The legacy PyHeapTypeObject type-creation path on CPython 3.12+
+  # (PyType_FromMetaclass is the default there).
+  type-creation-legacy:
+    if: github.event.pull_request.draft == false
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runs-on: ubuntu-latest
+            python-version: '3.12'
+            cmake-args: -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF
+          - runs-on: ubuntu-latest
+            python-version: '3.14'
+            cmake-args: -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF -DPYBIND11_TEST_PRECOMPILE=ON
+          - runs-on: macos-latest
+            python-version: '3.13'
+            cmake-args: -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF
+          - runs-on: windows-2022
+            python-version: '3.13'
+            cmake-args: -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF
+
+    name: 📐
+    uses: ./.github/workflows/reusable-standard.yml
+    with:
+      runs-on: ${{ matrix.runs-on }}
+      python-version: ${{ matrix.python-version }}
+      cmake-args: ${{ matrix.cmake-args }}
+
   standard-large:
     if: github.event.pull_request.draft == false
     strategy:

CMakeLists.txt

@@ -99,6 +99,12 @@ option(PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION
        "To enforce that a handle_type_name<> specialization exists" OFF)
 option(PYBIND11_SIMPLE_GIL_MANAGEMENT
        "Use simpler GIL management logic that does not support disassociation" OFF)
+set(PYBIND11_TYPE_CREATION_VIA_SPEC
+    ""
+    CACHE
+      STRING
+      "Create type objects with PyType_FromMetaclass: ON, OFF, or empty for the default (ON on CPython 3.12+)"
+)
 set(PYBIND11_INTERNALS_VERSION
     ""
     CACHE STRING "Override the ABI version, may be used to enable the unstable ABI.")
@@ -323,6 +329,11 @@ if(NOT TARGET pybind11_headers)
   if(PYBIND11_SIMPLE_GIL_MANAGEMENT)
     target_compile_definitions(pybind11_headers INTERFACE PYBIND11_SIMPLE_GIL_MANAGEMENT)
   endif()
+  if(PYBIND11_TYPE_CREATION_VIA_SPEC)
+    target_compile_definitions(pybind11_headers INTERFACE PYBIND11_TYPE_CREATION_VIA_SPEC=1)
+  elseif(NOT "${PYBIND11_TYPE_CREATION_VIA_SPEC}" STREQUAL "")
+    target_compile_definitions(pybind11_headers INTERFACE PYBIND11_TYPE_CREATION_VIA_SPEC=0)
+  endif()
 else()
   # It is invalid to install a target twice, too.
   set(PYBIND11_INSTALL OFF)

docs/compiling.rst

@@ -435,8 +435,9 @@ Requirements and caveats:
   macros ``PYBIND11_INTERNALS_VERSION``, ``Py_GIL_DISABLED``,
   ``PYBIND11_SIMPLE_GIL_MANAGEMENT``,
   ``PYBIND11_DETAILED_ERROR_MESSAGES`` (defaults on in debug builds),
-  ``PYBIND11_HAS_SUBINTERPRETER_SUPPORT``, and
-  ``PYBIND11_BACKWARD_COMPATIBILITY_TP_DICTOFFSET``. A mismatch produces one
+  ``PYBIND11_HAS_SUBINTERPRETER_SUPPORT``,
+  ``PYBIND11_BACKWARD_COMPATIBILITY_TP_DICTOFFSET``, and
+  ``PYBIND11_TYPE_CREATION_VIA_SPEC``. A mismatch produces one
   readable undefined symbol at link time referencing
   ``pybind11_precompiled_config``.
 * Configuration macros that only change code inside the library (for example