python - 如何在 Sphinx 处理的文档字符串中表示单个参数或返回值的多种类型？

Question

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

我想知道如何使用 Sphinx 文档符号为此类函数编写文档字符串。在下面的示例中，参数可以是 str 或 int。同样，它可能返回 str 或 int。

我已经给出了一个示例文档字符串(包括默认的 Sphinx 表示法以及 Sphinx 的拿破仑扩展所理解的 Google 表示法)。我不知道这是否是记录灵活类型的正确方法。

Sphinx 默认表示法:

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 处理的文档字符串中表达多种类型的参数或返回值的正确方法是什么？

Answer 1

Python 3.5 Union 类型提示

https://docs.python.org/3/library/typing.html#typing.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

我认为它已经支持文档生成，但我还没有测试过:https://github.com/sphinx-doc/sphinx/issues/1968