How can I document type parameters in Python?

Question

I'd like to document what T means in this class

from typing import Generic, TypeVar

T = TypeVar('T')

class A(Generic[T]):
    pass

I could document T with T.__doc__ = "Represents ..." but I might want to use T it in several unrelated classes.

Is there any standard way to document it for a given class/function etc? Ideally using sphinx & reST.

I'm thinking something at the same level as sphinx's :param:, but for types, along the lines of scaladoc's @tparam

@BlueRineS I don't understand your comment. Can you elaborate? — joel, Jul 01 '19 at 13:55
I mean like docstrings or multi-line strings. The regular stuff that people use for documentation. But you probably need something more advanced? — WiseDev, Jul 01 '19 at 14:03
According to the [docs](https://docs.python.org/3/library/typing.html#typing.TypeVar), about all you can say about it is `TypeVar('T') # Can be anything` — i.e. it's a generic. Class `A` is derived from it, but likely requires or assumes that it to have some specific properties. You can document what those are in class `A`'s own documentation. — martineau, Jul 01 '19 at 14:04

score 2 · Answer 1 · answered Jul 01 '19 at 14:09

You could document it through the multiline string as suggested in this way:

from typing import Generic, TypeVar

T = TypeVar('T')

class A(Generic[T]):
"""
Description of the class and his input T

Inputs:
    T : what is T? the type of T

Returns:
    res 

"""

And you could call the documentation as:

A.__doc__

or

help(A)

How can I document type parameters in Python?

1 Answers1