In a tl;dr fashion:
Looking at the documentation in the beginning of function module_level_function that you linked, one can see that:
def module_level_function(param1, param2=None, *args, **kwargs):
"""This is an example of a module level function.
Function parameters should be documented in the ``Args`` section. The name
of each parameter is required. The type and description of each parameter
is optional, but should be included if not obvious.
Parameter types -- if given -- should be specified according to
`PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
# ^^^^^ this! ^^^^
The final line contains a hint. Apparently, the notation introduced in PEP 484 assisted by the typing module is what you're seeing.
A small intro on the notation:
PEP 484 is based on function annotations as described in PEP 3107; essentially each function parameter can have an optional type specifier after its name. So, for a function like:
def foo(a, b):
pass
You could annotate their types in the following way:
def foo(a: int, b: str) -> None:
pass
The introduction of type hinting brought with it a need to formalize the way types will be indicated; this is where the typing module comes in.
The typing module contains a good set of abstract types (and, generally, type theory mumbo-jumbo) for you to specify additional types other than standard built-ins like int, str et al. For example, the Optional[str] notation indicates that the parameter can take either a str type or a 'type' of None i.e it's optionally a string.
So in a nutshell, they're using the notation defined with the introduction of type hints for documenting the type of the parameters. This means that if you have a function that takes an argument that is a List of integers:
def func(param1)
The documentation for it should look something like this:
param1 (List[int]): The first parameter containing a list of ints
Where List[int] comes from the notation in the typing module.
Some more examples:
Some examples where this specific notation is defined and furthe explained can be found in the documentation of mypy (a static checker that inspired PEP 484). Common cases that one might need to document in their code are contained in the table of built-in types:
Type Description
---- -----------
int integer of arbitrary size
float floating point number
bool boolean value
str unicode string
bytes 8-bit string
object an arbitrary object (object is the common base class)
List[str] list of str objects
Dict[str, int] dictionary from str keys to int values
Iterable[int] iterable object containing ints
Sequence[bool] sequence of booleans
Any dynamically typed value with an arbitrary type
Others, like Any, Union are defined here while generic notation described here.
