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

我目前正在使用狮身人面像和AutoDoc插件编写我的Python包文档。
对于函数返回值，我可以写“cc>”，它告诉狮身人面像，int类型的返回值，名为“计数”。
我现在得到了一个函数，它可以为我的数据库中的项目获取前置项：

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

如您所见，它获取原始项，或者根据项目的字段:returns: int: count的内容返回类AlphaRelease、BetaRelease或VRelease的实例。
在docstring中定义具有各种可能类型的返回值的最佳实践是什么？

最佳答案

从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语法和词汇表中，对于多个返回类型没有严格或规范的选择。通常情况下，如果存在一个类型（GenericRelease例如），则会声明可能返回的所有类型的超级类型。但是，在Python3的中后期，Python刚刚定义了一个更丰富的类型表示法。typing module为这些类型定义了一个不断发展的新语法，独立于旧的狮身人面像定义。如果您希望使用这一新兴标准，您可以尝试以下方法：

:rtype: Union[AlphaRelease, BetaRelease, VRelease]

关于python - 如何在python docstring中指定不同的返回类型，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/45004725/