Comment spécifier différents types de retour dans docstring python

Question

Je suis en train d'écrire la documentation de mon paquet python en utilisant Sphinx et le plugin autodoc. Pour une valeur de retour de fonction, je peux par ex. écrire :returns: int: count qui indique au sphinx qu'il existe une valeur de retour de type int, dénommé count.

maintenant je suis une fonction qui me fait prédécesseurs d'articles dans ma base de données:

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 

Comme vous pouvez le voir, il récupère l'élément d'origine et renvoie soit une instance de fonction de la classe AlphaRelease, BetaRelease ou VRelease le contenu du champ name des articles.

Quelle est la meilleure pratique pour définir une valeur de retour avec différents types possibles dans la docstring?

Answer 1

De l'Sphinx documentation:

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

Vous pouvez également bénéficier de:

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

Ainsi, à titre d'exemple:

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 

Malheureusement il n'y a pas un choix strict ou canonique dans la grammaire Sphinx et le vocabulaire pour plusieurs types de retour. Souvent, on pourrait indiquer un super-type de tous les types qui pourraient être retournés, s'il en existait un (GenericRelease par exemple). Mais Python est juste maintenant, dans son milieu à la fin de Python 3 ère, définissant une notation de type plus riche. Le typing module définit une nouvelle grammaire évolutive pour ces types indépendamment des anciennes définitions de Sphinx. Si vous souhaitez utiliser cette nouvelle norme, vous pouvez essayer quelque chose comme:

:rtype: Union[AlphaRelease, BetaRelease, VRelease]