如何在python docstring中指定不同的返回类型 [英] How to specify different return types in python docstring

问题描述

我目前正在使用Sphinx和autodoc插件编写有关python软件包的文档。
对于函数返回值我可以例如编写：returns：int：count 告诉sphinx，有一个int类型的返回值，名为count。

I'm currently writing documentation for my python package using Sphinx and the autodoc plugin. For a function return value I can e.g. write :returns: int: count which tells sphinx that there is a return value of type int, named count.

我现在有了一个使我数据库中的项目前身的函数：

I now got a function which gets me predecessors of items in my database:

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 取决于项目的字段名称。

As you can see, it fetches the original item and either returns an instance of class AlphaRelease, BetaRelease or VRelease depending on the content of the field name of the items.

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

What is best practice to define a return value with various possible types in the docstring?

推荐答案

来自 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中期到后期，定义了更丰富的类型表示法。 分型模块为此类类型定义了不断发展的新语法，而与旧的Sphinx定义无关。如果您希望使用此新兴标准，则可以尝试以下操作：

Unfortunately there is not a strict or canonical choice in the Sphinx grammar and vocabulary for multiple return types. Often one would state a super-type of all the types that might be returned, if one existed (GenericRelease e.g.). But Python is just now, in its mid- to late-Python 3 era, defining a richer type notation. The typing module defines an evolving new grammar for such types independent of the old Sphinx definitions. If you wished to use this emerging standard, you might try something like:

:rtype: Union[AlphaRelease, BetaRelease, VRelease]

这篇关于如何在python docstring中指定不同的返回类型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！