feat: create types with PyType_FromMetaclass on CPython 3.12+ (#6231)

* feat: create types with PyType_FromMetaclass on CPython 3.12+

pybind11_static_property, the pybind11_type metaclass, pybind11_object
and the classes from make_new_python_type() are now created from a
PyType_Spec on CPython 3.12+ instead of by filling in PyHeapTypeObject
fields. PYBIND11_TYPE_CREATION_VIA_SPEC (0/1) controls this; define it
as 0, or configure with -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF, to keep
the legacy path. PyPy, GraalPy and Python < 3.12 keep the legacy path.

py::custom_type_setup(), metaclasses with a custom tp_new, and metaclass
combinations that PyType_FromMetaclass() rejects (such as a base whose
metaclass is not related to pybind11_type) still use the legacy path. A
user-defined PYBIND11_BACKWARD_COMPATIBILITY_TP_DICTOFFSET also selects
the legacy path, so all bound classes share one __dict__ layout.

The instance layout and the internals ID do not change. The macro is
encoded in the precompiled config check. A new CI job tests the legacy
path on CPython 3.12+.

See https://github.com/pybind/pybind11/discussions/6104.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix: preserve bound class names containing dots

— codex GPT-6 on behalf of Ralf —

Use the existing legacy type-creation fallback when a bound name contains
a dot. PyType_FromMetaclass() treats the last dot as the module separator,
truncating names such as Wrapper[pkg.Value].

Preserve both the public __name__/__qualname__ and the fully qualified C
tp_name. Assigning __name__ after creation would also overwrite tp_name.

Add top-level and nested regression cases; both fail without the fix.

* Revert "fix: preserve bound class names containing dots"

— codex GPT-6 on behalf of Ralf —

Revert f9eda9d4d63782b7ac3d00ad9d6ea069e3509075 so the naming behavior
introduced by spec-based type creation can be characterized across CI.
The naming policy will be discussed separately after collecting results.

* test: characterize supplied class-name spelling

— codex GPT-6 on behalf of Ralf —

Record name, qualified name, literal lookup, construction, reference-return
identity and generated signatures for dotted and bracketed class names.
Include nested scopes, a child of a dotted class, and custom type setup.

Keep expectations specific to the current creation path and Python runtime.
These tests collect evidence for the naming-policy discussion without
choosing whether to retain, reject or accommodate the changed behavior.

* test: use boolean literals for type-creation config

— codex GPT-6 on behalf of Ralf —

Select true/false with the preprocessor instead of casting the numeric
configuration macro to bool. This satisfies modernize-use-bool-literals
in Clang-Tidy, including the Python3.11 macro-zero branch.

* fix: preserve supplied class names in the spec type-creation path

PyType_FromMetaclass() splits the spec name at the last dot, so a class
named "a[b.c]" got __name__ "c]". After creation, set ht_name,
ht_qualname, and tp_name the same way as the legacy path, through a
helper that both paths share. This matches type(), which never splits
dots in a name. The characterization tests now assert the preserved
names on both paths.

Assisted-by: ClaudeCode:claude-opus-5-5

* fix: silence unused module_ parameter on PyPy

Assisted-by: ClaudeCode:claude-fable-5-1

* fix: set spec-path type names through the __name__/__qualname__ setters

After PyType_FromMetaclass() the type is reachable through its bases'
__subclasses__(), so replacing ht_name/ht_qualname directly races with
concurrent readers on free-threaded builds (CPython's own setters use a
stop-the-world pause for this, gh-133467). Go through the setters, and
only when the spec did not already produce the right strings. tp_name
only ever points at buffers that outlive the type, so that pointer swap
stays direct. The legacy path keeps the direct writes: it runs before
PyType_Ready(), when nothing else can see the type.

Assisted-by: ClaudeCode:claude-fable-5-1

* fix: initialize names without metaclass rename hooks

— codex GPT-6 on behalf of Ralf —

Call the builtin type name descriptors directly so metaclasses that reject
later renaming still work during class creation. Preserve the interpreter's
setter implementation and the existing conditional updates.

Cover dotted module names and ordinary nested names with a metaclass that
rejects renaming. The regression fails before the fix and passes afterward
on default and free-threaded CPython 3.14.4. All-files pre-commit passes.

* test: compare bound class names with Python type()

— codex GPT-6 on behalf of Ralf —

Derive naming expectations from independently created Python types,
including reference parents for nested classes. Retain construction,
identity, lookup, signature, and custom-setup coverage.

Keep raw C type spelling separate through the existing obj_class_name
helper. Apply known interpreter name xfails only after unaffected checks.

Validation: full default/free-threaded suites pass (1416/1414 tests),
plus 39 Catch2 cases and 11444 assertions each. Focused CPython 3.11,
3.12, legacy, PyPy 3.11/3.12, and GraalPy checks pass with expected
skips/xfails. A qualname mutation is XFAIL in the old test and FAIL in
the new test. All-files pre-commit passes.

* test: return class_ objects as py::object in bind_with_metaclass

py::make_tuple of a py::class_ needs handle_type_name, which the
PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION CI job turns off.

Assisted-by: ClaudeCode:claude-fable-5-1

---------

Co-authored-by: Ralf W. Grosse-Kunstleve <rgrossekunst@nvidia.com>
14 files changed