Quel est le format standard de la docstring Python ?

Question

J'ai vu quelques styles différents d'écriture de docstrings en Python, y a-t-il un style officiel ou "convenu" ?

Answer 1

Formats

Les docstrings Python peuvent être écrites suivant plusieurs formats comme les autres posts l'ont montré. Cependant, le format par défaut de la docstring de Sphinx n'a pas été mentionné et est basé sur reStructuredText (reST) . Vous pouvez trouver des informations sur les principaux formats dans ce tuto .

Notez que le reST est recommandé par le PEP 287

Voici les principaux formats utilisés pour les docstrings.

- Epytext

Historiquement, un javadoc était prédominant, il a donc été pris comme base pour la création de Epydoc (avec l'appelé Epytext ) pour générer de la documentation.

Exemple :

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- ReST

Aujourd'hui, le format probablement le plus répandu est le reStructuredText (reST) qui est utilisé par Sphinx pour générer de la documentation.

Exemple :

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google a son propre format qui est assez utilisé. Il peut également être interprété par Sphinx.

Exemple :

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

- Numpydoc

Notez que Numpy recommande de suivre ses propres numpydoc basé sur le format Google et utilisable par Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Convertir/Générer

Il est possible d'utiliser un outil comme Pyment pour générer automatiquement les docstrings d'un projet Python non encore documenté, ou pour convertir des docstrings existants (pouvant mélanger plusieurs formats) d'un format à un autre.

Remarque : Les exemples sont tirés du Documentation sur le paiement

Answer 2

Le site Guide de style Google contient un excellent guide de style Python. Il comprend conventions pour une syntaxe lisible de la docstring qui offre de meilleures orientations que le PEP-257. Par exemple :

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

J'aime étendre cela pour inclure également des informations sur le type dans les arguments, comme décrit dans cet article. Tutoriel de documentation Sphinx . Par exemple :

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Answer 3

Les conventions de la docstring sont dans PEP-257 avec beaucoup plus de détails que PEP-8.

Cependant, les docstrings semblent être beaucoup plus personnels que les autres domaines du code. Différents projets auront leur propre norme.

J'ai tendance à toujours inclure les docstrings, car ils ont tendance à démontrer comment utiliser la fonction et ce qu'elle fait très rapidement.

Je préfère garder les choses cohérentes, quelle que soit la longueur de la corde. J'aime l'aspect du code lorsque l'indentation et l'espacement sont cohérents. Cela signifie que j'utilise :

def sq(n):
    """
    Returns the square of n. 
    """
    return n * n

Terminé :

def sq(n):
    """Returns the square of n."""
    return n * n

Et j'ai tendance à ne pas commenter la première ligne dans les longues docstrings :

def sq(n):
    """
    Returns the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Ce qui veut dire que je trouve que les docstrings qui commencent comme ça sont désordonnés.

def sq(n):
    """Returns the squared result. 
    ...

Answer 4

Comme apparemment personne ne l'a mentionné : vous pouvez également utiliser la fonction Numpy Docstring Standard . Il est largement utilisé dans la communauté scientifique.

• Le site spécification du format de numpy avec un exemple
• Vous avez une extension sphinx pour le rendre : numpydoc
• Et un exemple de ce à quoi peut ressembler une docstring rendue : http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

L'extension Napolean sphinx pour analyser les docstrings de style Google (recommandée dans la réponse de @Nathan) supporte également les docstrings de style Numpy, et fait une courte comparaison des deux.

Et enfin un exemple de base pour donner une idée de ce à quoi cela ressemble :

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

Answer 5

PEP-8 est la norme de codage officielle de Python. Elle contient une section sur les docstrings, qui fait référence à PEP-257 -- une spécification complète pour les docstrings.