[henryiii]

🤖 AI text below 🤖

Description

On CPython 3.12+, pybind11 now creates its type objects (pybind11_static_property, the pybind11_type metaclass, pybind11_object, and all bound classes) with PyType_FromMetaclass() and a PyType_Spec. It no longer fills in PyHeapTypeObject fields by hand there.

• The PYBIND11_TYPE_CREATION_VIA_SPEC macro (0/1) controls this. It defaults to 1 on CPython 3.12+ and to 0 on older CPython, PyPy, and GraalPy. Define it as 0, or configure with -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF, to keep the legacy path. A new CI job tests the legacy path on 3.12+.
• py::custom_type_setup(), metaclasses with a custom tp_new, and metaclass combinations that PyType_FromMetaclass() rejects still use the legacy path. One example of a rejected combination is a base whose metaclass is not a base or subtype of pybind11_type. Without the fallback, binding a class derived from such a base fails with a metaclass conflict. A new test covers this case.
• If the user defines PYBIND11_BACKWARD_COMPATIBILITY_TP_DICTOFFSET, the legacy path is the default. The spec path uses Py_TPFLAGS_MANAGED_DICT, and all bound classes must have the same __dict__ layout. PYBIND11_TYPE_CREATION_VIA_SPEC=1 together with that macro is a compile error.
• The instance layout and PYBIND11_INTERNALS_ID do not change. The macro is added to the precompiled config check.

This prepares for stable-ABI support (#6104), but it is also useful without it.

Suggested changelog entry:

• On CPython 3.12+, type objects are now created with PyType_FromMetaclass(). Define PYBIND11_TYPE_CREATION_VIA_SPEC=0 (CMake: -DPYBIND11_TYPE_CREATION_VIA_SPEC=OFF) to use the previous PyHeapTypeObject path.

---

📚 Documentation preview 📚: https://pybind11--6231.org.readthedocs.build/

[rwgk]

Initial codex GPT-6.1-Sol ultra review below. Before the review, I locally merged latest master.

I'll use the same codex session to generate a fix.

---

I found one reproducible regression, treating the Python 3.12+ switch as intentional.

[P2] Preserve supplied class names containing dots — class-inl.h:840–841.

For example:

py::class_<T>(m, "Wrapper[pkg.Value]");

The new path changes __name__ and top-level __qualname__ from Wrapper[pkg.Value] to Value]: PyType_FromMetaclass() interprets the last dot as the module/name separator. The module attribute retains the original name, leaving repr and introspection inconsistent.

This reproduces on Python 3.12, 3.14, and free-threaded 3.14. Master and the legacy opt-out preserve the supplied names. Explicitly restoring __name__ and __qualname__ after construction should address it.

Your local merged revision passed:

• Default Python: 1,404 passed, 6 skipped.
• Free-threaded Python: 1,402 passed, 8 skipped.
• Both Catch2 runs: 39 cases, 11,444 assertions passed.

No other introduced actionable issues emerged from the independent reviews.

[rwgk]

In case anyone is looking at the moment: I'm having doubts myself about the direction taken with commit f9eda9d. I'm still working on making up my mind.

[rwgk]

Update: I'm using the CI here to fully characterize the behavior changes introduced by this PR.

I'm uncertain if we should care about them or not. I believe it's best to have complete ground truth, then we can decide.

[rwgk]

PR #6198 introduces a behavior change for supplied class names containing literal dots; that type-creation change is split out into this PR. I reverted f9eda9d and added characterization tests to document the behavior directly.

The CPython legacy path preserves the supplied spelling.

On CPython 3.12+, the new default creation path uses the portion after the last dot as __name__ and, at module scope, __qualname__:

Supplied name	New name / module-scope qualified name
a.b	b
a.b.c	c
a[b]	a[b]
a[b.c]	c]
a.b[c]	b[c]

The binding remains available through getattr(scope, supplied_name), and the tested constructors and bound methods work. Name-based lookup using cls.__name__ can change, as can generated signatures. Nested classes receive an explicitly assigned __qualname__; a normally named class nested inside a dotted-name class can incorporate the changed spelling of its enclosing class. Explicit legacy mode and existing legacy fallbacks preserve their previous behavior.

The characterization tests cover these cases, nesting, and the custom-setup fallback. All nine cases passed in 41 standard CI configurations (369 individual passes), covering Linux, macOS, Windows, GIL-enabled and free-threaded CPython, explicit legacy mode, PyPy, and GraalPy. The full CI run is green.

The tested PyPy 3.11 builds preserve both name fields; the tested PyPy 3.12 and GraalPy versions already shorten __name__ while retaining __qualname__.

I found

• no documented rule specifically excluding dots,
• no earlier test covering these spellings, and
• no confirmed affected downstream consumer.

The examples above are synthetic characterization inputs.

Options include:

1. Keep the behavior change and describe it in release notes.
2. Reject dotted names when the new path is used, retaining the legacy behavior on the legacy path.
3. Accommodate dotted names in the new path.

Feedback on the intended naming contract, or concrete existing uses, would help decide among these options.

[henryiii]

🤖 AI text below 🤖

Thanks for the characterization. I think the right answer is option 3, implemented as a post-creation fixup rather than a legacy fallback.

The reference is what CPython does for a type created from Python: __name__ is exactly the supplied string, and __qualname__ is the enclosing qualnames joined with dots plus that same string. Dots inside the name are never split:

Case	__name__	__qualname__
type("a.b", (), {})	a.b	a.b
type("Wrapper[pkg.Value]", (), {})	Wrapper[pkg.Value]	Wrapper[pkg.Value]
class Outer: class Inner	Inner	Outer.Inner

The split at the last dot is an artifact of PyType_Spec.name carrying module and name in one string. It is a C API convenience, not a naming rule, and repr of a heap type uses __module__ and __qualname__, so dotted names render correctly. The legacy path already matches CPython here (ht_name, ht_qualname, and tp_name are set explicitly), so it is the behavior to keep.

Plan: after PyType_FromMetaclass() returns, write ht_name, ht_qualname, and tp_name exactly as the legacy path does. On 3.12+ the interpreter keeps its own copy of the spec name in _ht_tpname and frees that pointer, so overwriting tp_name with pybind11's interned string is safe. This also replaces the separate nested-class __qualname__ setattr, so the spec path has one name fixup instead of two special cases. The characterization tests then assert that spec and legacy agree. A follow-up commit is coming.

[henryiii]

🤖 AI text below 🤖

0f15367 implements option 3. After PyType_FromMetaclass() returns, the spec path now sets ht_name, ht_qualname, and tp_name with the same helper the legacy path uses, so __name__ is the supplied string and __qualname__ is <enclosing qualname>.<name>, as with type(). This replaces the separate nested-class __qualname__ setattr. test_class_name_spelling now asserts the preserved names (and tp_name) on both paths; it failed in 6 of 9 cases on the spec path before the fix. PyPy 3.12+ and GraalPy are xfail for dotted names, because those interpreters shorten __name__ themselves.

• Spec path (CPython 3.15, full suite): 1039 passed, 51 skipped, 2 xfailed, 1 xpassed.
• Legacy path (PYBIND11_TYPE_CREATION_VIA_SPEC=OFF; test_class, test_methods_and_attributes, test_custom_type_setup): 89 passed, 2 skipped.

[rwgk]

I agree going with option 3 is a great choice; I find the table under #6231 (comment) very convincing. I asked codex about replacing the characterization tests I added with type(...)-based tests (inspired by that table). Here is the full review:

codex GPT-6.1-Sol ultra:

Fresh PR head is 0f15367. I agree with the chosen naming behavior, but found two issues:

1. [P2] The name replacement is unsafe under free-threading. The new call replaces and decrefs name objects after the type is reachable through its bases’ __subclasses__(). Concurrent __name__ readers can race that replacement. CPython synchronizes the equivalent operation. This is source-supported; my bounded stress run did not reproduce a crash.

2. [P2] The helper breaks PyPy builds with warnings treated as errors. module_ becomes unused under PYPY_VERSION. This reproduces locally and explains the PyPy CI failures. The sampled older Linux failures are unrelated Debian download errors.

There is no direct type() comparison yet. The current test mentions type() in its docstring but asserts literal expectations. Henry has already removed the old path-dependent expectations.

I’d convert this test into comparisons against Python reference classes, keeping the small C++ fixtures and meaningful coverage: dotted names, nesting, custom-setup fallback, lookup, construction, and signatures. Nested references need an explicitly assigned qualified name derived from an independent Python parent.

Two details deserve care:

• Raw tp_name differs from Python-created types, so keep any legacy-compatibility assertion separate.
• Narrow the early xfail; currently it can hide failures in unrelated assertions.

[henryiii]

🤖 AI text below 🤖

Both review points are addressed.

Free-threading race (P2): agreed. CPython reads ht_name/ht_qualname without a lock, and its own setters need a stop-the-world pause to be safe (gh-133467, in 3.15 and 3.14.1), which an extension cannot do. The spec path now goes through the __name__/__qualname__ setters via a new set_published_type_names(), so it inherits CPython's synchronization wherever CPython has it, and is never worse than cls.__name__ = x from Python. It only does so when the spec did not already produce the right strings, so the common case (no dot, module scope) touches no name object at all. tp_name is still swapped directly: every buffer it can point at outlives the type (CPython's _ht_tpname copy, the ht_name UTF-8 cache, or pybind11's interned full name). The legacy path keeps the direct field writes, since it runs before PyType_Ready() when nothing else can see the type.

Unused module_ on PyPy (P2): fixed in e76ef78.

Verified locally (test_class, test_methods_and_attributes, test_custom_type_setup): spec path on CPython 3.15, legacy path (PYBIND11_TYPE_CREATION_VIA_SPEC=OFF), and free-threaded CPython 3.14t all pass (89 passed, 2 skipped each).

On the test suggestion: comparing against type()-created reference classes is a good idea and independent of the above. Happy to take it as a follow-up commit here, or leave it to codex, whichever you prefer.

[rwgk]

or leave it to codex

Working on it.

[rwgk]

— codex GPT-6 on behalf of Ralf —

c49e296e fixes a compatibility issue with custom metaclasses that allow class creation but prohibit later renaming.

The ordinary setattr() calls in the name fixup dispatch to the metaclass’s __setattr__. A metaclass that rejects assignments to __name__ or __qualname__ therefore made binding Frozen[pkg.Value] raise TypeError, although Python creation and the legacy path succeeded. Ordinary nested classes can hit the same issue when restoring their qualified name.

The fix invokes the built-in type descriptor setters directly. This preserves the interpreter’s setter implementation, including its available free-threading synchronization, while bypassing custom renaming hooks. The existing name-comparison guards still avoid unnecessary setter calls.

The regression test covers a dotted module-level class and an ordinary nested class, verifies usable C++ instances, and checks that later renaming is still rejected. It fails before the fix and passes afterward on both default and free-threaded CPython 3.14.4.

[rwgk]

@henryiii done, could you please re-review from your end?

[henryiii]

🤖 AI text below 🤖

CI on 4af4aa7 was green except the PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION job: py::make_tuple of two py::class_ objects in bind_with_metaclass needs a handle_type_name for class_, which that job disables. Fixed by wrapping them in py::object first. Verified locally with that define on CPython 3.15: test_class 57 passed.

[henryiii]

Once you give the okay to have it commit on a PR, it comments on everything. :)

The change is fine. This was (the thing I fixed) a really, really minor edge case; to get a race condition, you'd have to be actively scanning for new modules from a different thread and you'd just have a few cycles to cause an issue before it was changed. But the fix wasn't too bad, and this isn't performance critical code, so I went with it.

Pushed a fix for a test (as it was happy to comment on).

[rwgk]

Looks great!