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

目前，我建议使用与该模块完全相同的语法，它将：

稍后在
指定了一种独特的定义规范的做事方式

示例：

def f(int_or_float):
    """
    :type int_or_float: Union[int, float]
    :rtype: float
    """
    return int_or_float + 1.0

然后当你有3.5时，你只会写：

def f(list_of_int : Union[int, float]) -> float:
    return int_or_float + 1.0

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

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

1 个答案: