Skip to content

fix: correct __qualname__ for bound functions - #6272

Draft
henryiii wants to merge 5 commits into
pybind:masterfrom
henryiii:qualname
Draft

henryiii wants to merge 5 commits into
pybind:masterfrom
henryiii:qualname

Conversation

@henryiii

@henryiii henryiii commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Experiment.

🤖 AI text below 🤖

Description

Fixes #5774 and #2059. Includes the tests from #5775.

CPython computes the __qualname__ of a builtin function from its __self__, which pybind11 sets to the function record. The result was pybind11_detail_function_record_v1_....name. This PR changes the type of the record object:

  • Module-level and scope-less functions: the record is a module subclass. CPython adds no prefix if __self__ is a module, so the result is module_func.
  • Functions in a class: each class has its own record type, with the __qualname__ of the class. The result is NestBase.Nested.fn. The type is in the class __dict__ as __pybind11_function_record_type__, so that all extension modules use the same one.
  • PyPy and GraalPy: no change.

The dispatcher has two entry points, one for each record layout, so there is no type check for each call.

Trade-offs to review:

  • __pybind11_function_record_type__ shows in vars(cls). A map in local_internals with a weakref cleanup would hide it, with more code.
  • There is one more heap type for each bound class, and the record of a module-level function is larger.
  • Older pybind11 versions do not recognise the module-subclass record. Overload chains of module-level functions across pybind11 versions do not work, and a stateless function passed to their std::function caster uses the Python round trip. The class-level records keep the old name and layout.
  • __self__ of a module-level function is an empty module-like object without a __dict__. Pickle of this object continues to work.
  • local_internals has one more pointer.

An alternative that does not work: the record in the PyCMethod class slot, with the scope as __self__. builtin_method.__doc__ is always None on CPython 3.12 to 3.15.

Tested locally on CPython 3.11 (subset), 3.13, the stable ABI (3.14), abi3t (3.15t), and the precompiled mode. Not tested locally on GraalPy.

Suggested changelog entry:

  • The __qualname__ of bound functions and methods is now correct on CPython (for example Class.method, not pybind11_detail_function_record_v1_....method).

gentlegiantJGC and others added 4 commits November 21, 2026 00:51
Add tests for function and method __qualname__ attributes.
I believe these tests will fail with the current implementation but they should pass.
These are tests for the correct behaviour of pybind#2059 and pybind#5774
CPython computes the __qualname__ of a builtin function from its
__self__, which is the function record. The record of a function that is
not in a class is now a module subclass, which gives no prefix. The
record type for the functions in a class has the __qualname__ of that
class.

Assisted-by: ClaudeCode:claude-fable-5-2
PyType_FromSpecWithBases accepts a single class only from Python 3.10.
Also discard the release() result explicitly for clang-tidy.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEA]: change function __qualname__ prefix

2 participants