web-dev-qa-db-ja.com

python docstringに異なる戻り値の型を指定する方法

私は現在、Sphinxとautodocプラグインを使用して、pythonパッケージのドキュメントを書いています。関数の戻り値については、たとえば:returns: int: countこれは、countという名前のint型の戻り値があることをsphinxに伝えます。

データベース内のアイテムの前任者を取得する関数を取得しました。

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で考えられるさまざまな型で戻り値を定義するためのベストプラクティスは何ですか？

pythonpython-sphinxdocstringautodoc
9
Igle

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 module は、そのような型の進化する新しい文法を定義します古いSphinxの定義とは関係なく、この新しい標準を使用したい場合は、次のようにしてみてください。

:rtype: Union[AlphaRelease, BetaRelease, VRelease]
13
Jonathan Eunice