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?

Answer 1

Python 3.5 Union type hints

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

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 canonical way to do things

Example:

def f(int_or_float):
    """
    :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:

def f(list_of_int : Union[int, float]) -> float:
    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