python - 列表等数据结构类型的 Sphinx 文档字符串标准是什么？

Question

Sphinx 是否有支持的标准来记录不是简单的单个对象的参数或返回值类型？

例如，在下面，arg1 是一个 str，arg2 是一个 str 列表，arg3 是一个 str 或 int。如何在 Sphinx 中指定集合或复合类型？或者对此没有共同的标准？

def function(arg1, arg2, arg3):
    """
    :param arg1: Argument 1
    :type arg1: str
    :param arg2: Argument 2
    :type arg2: list[str]
    :param arg3: Argument 3
    :type arg3: str or int
    """
    pass

Answer 1

Python 3.5 类型提示

虽然 Sphinx 尚不支持，但有朝一日 Sphinx 类型注释可能会过时。 https://docs.python.org/3/library/typing.html

现在，我建议使用与该模块完全相同的语法，它将:

• 使移植更容易，并可能在以后实现自动化
• 指定了一种独特的定义明确的做事方式

例子:

def f(list_of_int):
    """
    :type list_of_int: List[int]
    :rtype: int
    """
    return list_of_int[0] + list_of_int[1]

然后当你有 3.5 时，你将只写:

def f(list_of_int : List[int]) -> int:
    return list_of_int[0] + list_of_int[1]

str或int部分可以用Union表示:How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?