如何在 python 文档字符串中指定不同的 return 类型

Question

我目前正在使用 Sphinx 和 autodoc 插件为我的 python 包编写文档。对于函数 return 值，我可以例如写 :returns: int: count 告诉 sphinx 有一个 return 类型的值，名为 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

如您所见，它会获取原始项目，并且 return 是 class AlphaRelease、BetaRelease 或 VRelease 的一个实例，具体取决于name 项的字段内容。

在文档字符串中定义具有各种可能类型的 return 值的最佳做法是什么？

Answer 1

来自 Sphinx documentation：

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 语法和词汇表中没有针对多种 return 类型的严格或规范的选择。通常人们会声明所有可能被 returned 的类型的超类型，如果存在的话（GenericRelease 例如）。但是 Python 只是现在，在它的中后期-Python 3 时代，定义了更丰富的类型表示法。 typing module 为此类类型定义了一种独立于旧 Sphinx 定义的不断发展的新语法。如果你想使用这个新兴标准，你可以尝试这样的事情：

:rtype: Union[AlphaRelease, BetaRelease, VRelease]

如何在 python 文档字符串中指定不同的 return 类型

How to specify different return types in python docstring

python

docstring

python-sphinx

autodoc