How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?

Question

Sometimes a function in Python may accept an argument of a flexible type. Or it may return a value of a flexible type. Now I can't remember a good example of such a function right now, therefore I am demonstrating what such a function may look like with a toy example below.

I want to know how to write docstrings for such functions using the Sphinx documentation notation. In the example below, the arguments may be either str or int. Similarly it may return either str or int.

I have given an example docstrings (both in the default Sphinx notation as well as the Google notation understood by Sphinx's napoleon extension). I don't know if this is the right way to document the flexible types.

Sphinx default notation:

def add(a, b):
    """Add numbers or concatenate strings.

    :param int/str a: String or integer to be added
    :param int/str b: String or integer to be added
    :return: Result
    :rtype: int/str
    """
    pass

Sphinx napoleon Google notation:

def add2(a, b):
    """Add numbers or concatenate strings.

    Args:
      a (int/str): String or integer to be added
      b (int/str): String or integer to be added

    Returns:
      int/str: Result
    """
    pass

What is the right way to express multiple types for parameters or return values in docstrings that are meant to be processed by Sphinx?

Solution

Python 3.5 Union type hints

https://docs.python.org/3/library/typing.html#typing.Union

For Python 2, I recommend using the exact same syntax as that Python 3 module, which will:

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

Example:

def f(int_or_float):
    """
    :param int_or_float: Description of the parameter
    :type int_or_float: Union[int, float]
    :rtype: float
    """
    return int_or_float + 1.0

Then when you have 3.5, you will write just:

from typing import Union

def f(int_or_float : Union[int, float]) -> float:
    """
    :param int_or_float: Description of the parameter
    """
    return int_or_float + 1.0

I think it already has documentation generation support, but I haven't tested it yet: https://github.com/sphinx-doc/sphinx/issues/1968

Comments

[mzjn]

Similar question: stackoverflow.com/q/33482493/407651

[gihanchanuka]

def add(a: str or int, b: str or int): worked for me. Better to define a typing.TypeVar for reuse.

[Rebs]

Can you update your example to include the description of the parameter.

[Chris Larson]

It's worth noting that, in the case of a return value that may be a single type or None, typing.Optional is the better, intended, solution. Rather than from typing import Union and Union[int, None], for example, one would use from typing import Optional and Optional[int]. See: docs.python.org/3/library/typing.html#typing.Optional