Initial support for PEP 695 type aliases by mmatous · Pull Request #13508 · sphinx-doc/sphinx (original) (raw)

There is still one issue remaining with how type alias objects are stringified in stringify_annotation that I need to look into.

I think it is okay as is actually.

The issue is that you can define a type alias as a class member, e.g.:

However, the resultant TypeAliasType object has a __module__ and __name__ but does not have a __qualname__ so stringify_annotation just outputs modulename.X rather than modulename.Foo.X.

In principle, inside of stringify_annotation we could attempt to figure out a qualified path to X, by first checking if it is defined at the top level of the module, and if not, attempt to build a (cached) dict mapping TypeAliasType objects within the module to their corresponding qualified names, by attempting to iterate over all nested classes defined within the module and then iterating over their class variables.

However, the same issue also applies to NewType objects (which are already supported by Sphinx) and this would add significant additional complexity to stringify_annotation just to handle this edge case.

It might be nice to add a note about these caveats to the autodoc documentation, though.