Python docstringで異なる戻り値の型を指定する方法

Question

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

私は今、私に私のデータベース内の項目の前任者を取得する機能を持って：あなたが見ることができるように、それはに応じて元のアイテムを取得し、いずれかのクラスAlphaReleaseのインスタンスを返し、BetaReleaseまたはVRelease

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 

をアイテムのフィールドnameの内容。

docstringにさまざまな型の戻り値を定義するベストプラクティスは何ですか？ Sphinx documentationから

Answer 1

：一例として、だから、

raises, raise, except, exception: That (and when) a specific exception is raised. 

：

returns, return: Description of the return value. 
rtype: Return type. Creates a link if possible. 

また、恩恵を受ける可能性がある

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 

は残念ながら厳しいまたは標準的な選択はありませんスフィンクスの文法と複数のリターンタイプのボキャブラリで。多くの場合、返される可能性があるすべての型のスーパータイプ（存在する場合はGenericReleaseなど）が記述されます。しかし、PythonはPython 3の中期から後期にかけて、より豊かな型記法を定義しています。 typing moduleは、古いSphinx定義から独立したそのようなタイプの進化する新しい文法を定義します。この新しい標準を使いたい場合は、次のようなものを試してみてください。

:rtype: Union[AlphaRelease, BetaRelease, VRelease]