Python 如何在Sphinx处理的DocString中为单个参数或返回值表示多个类型？

有时Python中的函数可以接受灵活类型的参数。或者它可以返回灵活类型的值。现在我记不起这样一个函数的好例子了，因此我将用下面的一个玩具示例演示这样一个函数的样子

我想知道如何使用Sphinx文档符号为这些函数编写docstring。在下面的示例中，参数可以是

str

或

int

。类似地，它可以返回

str

或

int

我已经给出了一个docstrings示例（使用默认的Sphinx表示法以及Sphinx的napoleon扩展所理解的Google表示法）。我不知道这是否是记录灵活类型的正确方法

斯芬克斯默认符号：

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

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

斯芬克斯拿破仑谷歌符号：

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

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

---

对于要由Sphinx处理的DocString中的参数或返回值，如何正确地表示多种类型？

Python3.5

Union

类型提示

对于Python 2，我建议使用与Python 3模块完全相同的语法，这将：

• 使移植更容易，而且以后可能是自动化的
• 指定一种独特的、定义良好的规范方式

例如：

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

当你有了3.5，你会写下：

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

---

我想它已经有了文档生成支持，但我还没有测试它：

类似的问题：

def-add（a:str或int，b:str或int）：

对我有效。最好定义一个可重用的参数。您是否可以更新示例以包含参数的描述。