I am pleased to present PEP 846, a well-received idea to recognize docstrings of type aliases in Python.
What I like the most about it is that it looks like an easy win for the language.
It’s focused, it has support in most relevant tools, and it’s a well-established practice among many Python programmers.
Abstract
This PEP proposes preserving a string literal immediately following a type statement as the resulting type alias object’s __doc__ attribute, exposing that documentation through ast, and displaying it through pydoc and help(). It follows the placement already supported by source-based documentation tools. The parser stores the docstring in a new optional doc field on ast.TypeAlias instead of creating a separate ast.Expr node for it. ast.get_docstring() retrieves alias docstrings from this field.
I see you chose to put doctest support out of scope.
Please document in rejected ideas including motivation. And perhaps in how to teach, that this is an exception to the rule that docstrings can have doctests.
(Or -my preference- make it in scope )
Docstrings for type aliases are useful and worth supporting
PEP 846 reminded me of an old idea: class-like syntax for union type aliases. With that syntax, instead of attaching the following string to a type statement, a type alias could optionally have a class-like block with the familiar docstring placement:
type Timeout:
"""Maximum wait in seconds."""
float
None
with multiple expressions in the block forming a union.
I posted the idea separately here to avoid derailing this PEP discussion:
Thanks, this seems very useful, and I’d love to be able to apply this to the numpy.typing type aliases .
When reading the “Rejected Ideas” section I had a bit of a déjà vu, which I then realized was the rejected PEP 727 from a while back. It proposed a mechanism for documenting type annotations, and therefore also type aliases, using a new dedicated typing.Doc class as typing.Annotated metadata.
And since PEP 846 already talks about Annotated as a rejected idea, I thought it might also be a good idea to mention PEP 727.
Tools that find alias docstrings by looking at the following statement, or that rely on the alias node’s end position, need adjusting when parsing with Python 3.16.
Yep, confirmed:
# pkg.py
type T = int | None
"""Hello."""
(assuming Griffe is installed in respective envs)
% python -c 'import griffe; print(griffe.load("pkg")["T"].docstring)'
<griffe._internal.models.Docstring object at 0x7f71caae4ad0>
)
.