sphinx
sphinx copied to clipboard
sphinx-doc
autodoc: Add support for PEP 613 - Explicit Type Alias
Is your feature request related to a problem? Please describe.
PEP 613 introduces a new type to help with static type checking called TypeAlias. It's expected to be released in the typing module in Python 3.10, and currently available (at least in 3.9, have not verified prior versions) as part of the typing_extensions module.
The intent is to explicitly mark a variable as a type alias. e.g.
OptIntStr: TypeAlias = Optional[int, str]
Currently, the default behaviour of autodoc is to expand type aliases in the output for the signatures it encounters.
To prevent this behaviour we need to explicitly add the type aliases to autodoc_type_aliases. It works, but it's tedious and feels redundant.
One way Sphinx can take advantage of the TypeAlias annotation would be to auto-populate autodoc_type_aliases as autodoc encounters these explicit type aliases. If there's a more straightforward way of doing it, even better.
Describe the solution you'd like
Somehow use TypeAlias to produce the same results that are currently achieved by populating autodoc_type_aliases, without having to redundantly add items to it in config.py.
Describe alternatives you've considered
The alternative already exists (autodoc_type_aliases). TypeAlias is a new feature in Python, and I think this is a useful way for Sphinx to take advantage of it.
Additional context
Large-scale use of TypeAlias is not likely to happen anytime soon because mypy doesn't support it yet (as of 0.812). However, I don't see this as a reason to not implement it. It just means time can be taken to come up with good ideas and implementations.
- https://www.python.org/dev/peps/pep-0613/
As an update to the original issue, since Mypy 0.930 you can also use explicit type aliases, which were introduced in PEP-613.
+1 from me too. I have some pretty complex type aliases for a serialization library and those completely blow up the docs if I don't manually add all of them to the type aliases dict.
+1 from me. A type indication dict[PositionName, MeasurementValue] is way more expressive than dict[str, float].
