How do I document a type alias defined using `type` in Python?

Question

Python 3.12 has the type statement. How do I document the type alias properly?

I tried:

type Number = int | float
"""Represents a scalar number that is either an integer or float"""

But this doesn't seem to associate the docstring with the alias. I tried putting the docstring after the = and before the alias definition, but that generated an error.

Iconology

Could you clarify what you mean by "But this doesn't seem to associate the docstring with the alias"? Are you expecting the string to be added as a attribute somewhere, or are you using some static analysis tool (e.g. Sphinx, IDE hinting, etc.)? – Squeal

I think that question is more for Python to answer than me. I just want to know the way to properly document a type alias. If I add a docstring to a function the normal way, say def test():\n"""This is a test""", one can access it via test.__doc__. I have to assume that this is what the Python tooling uses to grab the docstrings. I want to know how to do that for type aliases defined using the type keyword. – Iconology

I found someone else asking this same question. discuss.python.org/t/… It appears that this just isn't currently possible and this was a poor oversight when adding the type statement. – Iconology

What do you mean by "associate"? Real docstrings only belong to modules, classes, and functions (when a string literal is used as the first line of any of aforementioned definitions). Variables do not have docstrings; though various documentation frameworks may recognize a following string literal as documentation for a given assignment, Python itself does not treat such strings as real attributes. – Scot

@Scot I believe you answered your own question. By associate, I mean that the __doc__ attribute is present. What you state isn't completely correct though, as Python keeps a lot of __doc__ attributes for things other than modules, classes, and functions. It just handles them all differently. For example, NamedTuple fields have a __doc__ attribute at runtime, it's just not what you would expect if you've provided a docstring. So by associate, I mean __doc__ is present and what you'd expect, which is basically what Pylance/Pyright does. – Iconology

Variables don't have attributes; the objects attached to them do, and Python does not assign a __doc__ attribute in the course of an arbitrary assignment statement. It does so for class statements, def statements, and modules. Named-tuple fields are handled specially by the definition of namedtuple itself (i.e., __doc__ attributes are explicitly defined during the creation of the type.) – Scot

Answer 1

I think there is no direct way. For classes, functions and methods, if the first statement is a string, the string is added to the __doc__ attribute of the class/method/function.

So for example:

def foo():
    "Docstring"

is for the runtime the same as:

def foo():
    pass
foo.__doc__ = "Docstring"

Because the TypeAliasType definition lacks the implicit __doc__ setting, I tried to do it explicitly:

type Number = int | float
Number.__doc__ = "Docstring"

which results in the following error:

AttributeError: 'typing.TypeAliasType' object attribute 'doc' is read-only

I think there is no supported way of documentation of TypeAliasType instances. And it depends on your documentation generation tool, e.g. PyCharm or sphinx and their static code analysis, if the docstring is "related" or not.

Hedda