Emit complete type information in generated docstrings

[jvansanten]

PEP 484 type stubs are extremely convenient, both for static type checking with e.g. mypy and code completion with e.g. PyLance in VSCode or Jedi in vim. There are various ways to generate these for compiled extensions.

The stubgen that ships with mypy can generate stubs for compiled extensions, but knows nothing about types, so you would still have to complete them by hand. This is not exactly in the spirit of programatically-generated bindings. pybind11-stubgen does a similar thing, but parses the docstrings generated by pybind11 to get argument and return types. While pybind11 can be adapted to parse the signature format that boost-python already uses, the type information in the current generated docstrings is incomplete.

This PR introduces minimal changes such that the generated signatures can be used to create correct stubs. Specifically, these are:

• Set __qualname__ on classes for Python >= 3.3 so that classes bound in scope() can be found again
• Use fully-qualified type names for imported types in signatures
• Emit signatures for property getters/setters
• Ensure that slice and back_reference<T> argument and return types are correctly annotated.

Existing tests were extended to verify the expected docstring contents.

This is a roundabout way of achieving #277, and seemed the most straightforward route given that pybind11 also seems to still rely on external tooling to generate stubs. Along the way, it also fixes #426.

Comments welcome!

[stefanseefeld]

Hi @jvansanten , I unfortunately only now notice that with this PR merged some tests fail when run with Python 2. (See the error message "AttributeError: attribute 'doc' of 'instancemethod' objects is not writable" in https://github.com/boostorg/python/actions/runs/10914059488/job/30291560557#step:5:1122) I don't yet fully understand the cause, i.e. whether the C++ implementation makes assumptions about the internal Python API, or whether it's only the test logic that needs to be conditionalized. Please let me know if you have any suggestions.
(There was also another minor glitch with the new qualname() function definition in class.cpp that returned a str rather than object, which caused an error on Windows. I have a tentative fix for that in 80593fe.)

[jvansanten]

Thanks for taking the time to merge this, @stefanseefeld, I really appreciate it!

Also, sorry for the breakage! I did not test this against Python2; that was sloppy of me. There are fixes in #452.

[stefanseefeld]

Many thanks @jvansanten , I'll review and merge that shortly. (There are also some independent issues with the build logic, i.e. some of our test platforms are outdated and need some work. So not all failures are caused by issues in the code... :-) )