如何在 python docstring 中指定不同的返回类型

Question

我目前正在使用 Sphinx 和 autodoc 插件为我的 python 包编写文档。 对于函数返回值，我可以例如写

:returns: int: count

告诉 sphinx 有一个 int 类型的返回值，名为 count.

我现在有一个函数可以让我获得数据库中项目的前身：

def get_previous_release(release_id):
    """ Holt Vorgängeritem eines Items mit der ID release_id

        :param release_id: ID des items für das Release
        :type release_id: int

    """

    if not isinstance(release_id, int):
        raise ValueError('get_previous_release expects an Integer value for the parameter release_id')

    try:
        release = my_queries.core.get_by_id(release_id)
    except IndexError:
        raise LookupError('The item with id {} could no be found'.format(release_id))

    if 'Alpha-Release' in release.name:
        release = AlphaRelease(release.key, release.name, release.state)
    elif 'Beta-Release' in release.name:
        release = BetaRelease(release.key, release.name, release.state)
    elif '-Release' in release.name:
        release = VRelease(release.key, release.name, release.state)
    else:
        raise TypeError('The item with the id {} does not contain \'-Release\' in the Summary ' + \
                        'and is therefore not considered a Release')

    previous_release = release.get_predecessor()

    if not previous_release:
        raise LookupError('Could not find a predecessor for item with id {}'.format(release_id))

    return previous_release

如您所见，它获取原始项目并返回类

AlphaRelease

、

BetaRelease

或

VRelease

的实例，具体取决于项目的字段

name

的内容。

在文档字符串中定义具有各种可能类型的返回值的最佳实践是什么？

Answer 1

来自Sphinx 文档：

returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.

您可能还会受益于：

raises, raise, except, exception: That (and when) a specific exception is raised.

所以，举个例子：

def get_previous_release(release_id):
    """ 
    Holt Vorgängeritem eines Items mit der ID release_id

    :param release_id: ID des items für das Release
    :type release_id: int
    :returns: appropriate release object
    :rtype: AlphaRelease, BetaRelease, or VRelease
    :raises ValueError: if release_id not an int
    :raises LookupError: if given release_id not found
    :raises TypeError: if id doesn't reference release
    """
    ... # your code here

不幸的是，对于多种返回类型，Sphinx 语法和词汇表中没有严格或规范的选择。通常人们会声明所有可能返回的类型的超类型，如果存在的话（

GenericRelease

例如）。但是 Python 才刚刚开始，在它的 Python 3 中晚期，定义了更丰富的类型表示法。 typing 模块 为此类类型定义了一个不断发展的新语法，独立于旧的 Sphinx 定义。如果你想使用这个新兴标准，你可以尝试这样的事情：

:rtype: Union[AlphaRelease, BetaRelease, VRelease]

Answer 2

Python 3.10

|

（管道，二进制或）

Union

类型提示语法糖

这就是未来的前进方向，好干净：

def f(i: int | str) -> int | str:
    if type(i) is str:
        return int(i) + 1
    else:
        return str(i)

Sphinx 也已经完全支持：

更多详细信息：如何在 Sphinx 处理的文档字符串中表达单个参数或返回值的多种类型？