What is the Sphinx docstring standard for data structure types such as lists?

Question

Does Sphinx have a supported standard for documenting the arguments or return value types that are not a simple, single object?

For instance, in the following, arg1 is a str, arg2 is a list of str, and arg3 is either a str or int. How can you specify collection or composite types in Sphinx? Or is there no common standard for this?

def function(arg1, arg2, arg3):
    """
    :param arg1: Argument 1
    :type arg1: str
    :param arg2: Argument 2
    :type arg2: list[str]
    :param arg3: Argument 3
    :type arg3: str or int
    """
    pass

Answer 1

Python 3.5 type hints

While not yet supported by Sphinx, will likely make Sphinx type annotations obsolete one day. https://docs.python.org/3/library/typing.html

For now, I recommend using the exact same syntax as that module, which will:

• make porting easier, and possibly automatable, later on
• specifies a unique well defined way to do things

Example:

def f(list_of_int):
    """
    :type list_of_int: List[int]
    :rtype: int
    """
    return list_of_int[0] + list_of_int[1]

Then when you have 3.5, you will write just:

def f(list_of_int : List[int]) -> int:
    return list_of_int[0] + list_of_int[1]

The str or int part can be expressed with Union: How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?