如何在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项的字段的内容.

在docstring中定义具有各种可能类型的返回值的最佳做法是什么？

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中后期,它定义了一种更丰富的符号.的打字模块定义用于这种类型的独立旧斯芬克斯定义的演进的新的语法.如果您希望使用此新兴标准,您可以尝试以下方法:

:rtype: Union[AlphaRelease, BetaRelease, VRelease]