Qu'est-ce que le format de docstring Python standard? [fermé]


888

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


6
python.org/dev/peps/pep-0008 il y a une section entière consacrée aux chaînes de documentation
mechanical_meat

30
Je pense que cette question n'a pas été assez claire parce que PEP-257 et PEP-8 sont l'établissement que la base pour docstrings, mais que diriez - vous epydoc, doxygen, sphinx? Quelqu'un at-il des statistiques, est-ce que l'un d'entre eux remplacera les autres, dans des cas comme celui-ci, trop d'options peuvent faire mal.
sorin

1
@sorin, j'aimerais également savoir quel balisage, le cas échéant, est le plus courant. Mais je pense que la réponse est qu'aucun d'entre eux n'est vraiment si commun: les gens ont tendance à préférer regarder la source Python directement, plutôt que de le convertir en html. Il est donc très utile d'être juste cohérent, mais d'une manière optimisée pour la lisibilité humaine et sans balisage explicite.
poolie

3
PyCharm s'autocomplète d'une manière plutôt intéressante, ce qui, je pense, est une belle implémentation des instructions nécessaires pour l'exécuter:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Matteo Ferla

1
Laquelle de ces réponses est celle qui fonctionne par défaut avec l'analyseur de documentation VS Code?
William Entriken

Réponses:


1019

Les formats

Les docstrings Python peuvent être écrits en suivant plusieurs formats comme les autres articles l'ont montré. Cependant, le format de docstring Sphinx par défaut n'a pas été mentionné et est basé sur reStructuredText (reST) . Vous pouvez obtenir des informations sur les principaux formats dans cet article de blog .

Notez que le reST est recommandé par le PEP 287

Voici les principaux formats utilisés pour les docstrings.

- Epytext

Historiquement, un style de javadoc était répandu, il a donc été pris comme base pour Epydoc (avec le Epytextformat appelé ) 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
"""

- du repos

De nos jours, le format probablement le plus répandu est le format reStructuredText (reST) utilisé par Sphinx pour générer de la documentation. Remarque: il est utilisé par défaut dans JetBrains PyCharm (tapez des guillemets triples après avoir défini une méthode et appuyez sur Entrée). Il est également utilisé par défaut comme format de sortie dans Pyment.

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 souvent utilisé. Il peut également être interprété par Sphinx (c'est-à-dire en utilisant le plugin Napoléon ).

Exemple:

"""
This is an example of Google style.

Args:
    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.
"""

Même plus d'exemples

- Numpydoc

Notez que Numpy recommande de suivre leur propre 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
"""

Conversion / génération

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

Remarque: Les exemples sont tirés de la documentation Pyment


10
Je pourrais ajouter que reST est ce qui est utilisé par défaut dans JetBrains PyCharm, tapez simplement des guillemets triples après avoir défini votre méthode et appuyez sur Entrée. jetbrains.com/pycharm/help/creating-documentation-comments.html
Felipe Almeida

12
La réponse la plus complète comprend un sens de l'histoire et des meilleures pratiques actuelles. Maintenant, tout ce dont nous avons besoin est d'un certain sens de mouvement communautaire vers un nouveau "meilleur" format et un effort communautaire supplémentaire pour créer des outils de migration de tous les autres vers le nouveau, afin que nous puissions réellement faire évoluer les meilleures pratiques.
BobHy

2
yo @daouzli, le lien de style Google est 404. Je crois que celui-ci est correct. Vous pouvez également ajouter un exemple de style sphinx google . Grande réponse btw. EDIT: J'ai édité votre réponse par moi-même.
voy

4
bonne réponse. J'ose dire où vous pouvez changer le format de docstring par défaut dans PyCharm (JetBrains): Settings -> Tools -> Python Integrated Tools -> Docstring format. Bonne chance!
Jackssn

4
Je suis surpris que personne n'ait commenté la première ligne de texte: actuellement, c'est à proprement parler correct, mais je pense que la façon préférée est de la placer sur la première ligne juste après les triples guillemets. PEP 8 et PEP 257 le font dans presque tous leurs exemples. PEP 287 le fait à votre façon, mais d'après mon expérience, ce n'est pas si courant.
Lapinot

323

Le guide de style Google contient un excellent guide de style Python. Il comprend des conventions pour la syntaxe de docstring lisible qui offre un meilleur guidage que 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 les informations de type dans les arguments, comme décrit dans ce tutoriel de documentation Sphinx . Par exemple:

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

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

37
Je trouve le style "signature dans docstrings" terriblement redondant et verbeux. Pour Python 3+, les annotations de fonction sont un moyen beaucoup plus propre de le faire. Pire encore s'il utilise des pseudo-types forts: Python est bien meilleur avec le typage canard.
Evpok

27
oui, mais au moins cela donne une idée du type de canard attendu, et la majorité des développeurs ne sont pas encore sur Python 3
Anentropic

3
@Evpok personnellement, je n'aime pas les annotations de fonction. Pour y utiliser des classes, vous devrez peut-être effectuer des importations inutiles, pour y utiliser des chaînes, vous risquez de manquer d'espace horizontal très rapidement en les décrivant. Jusqu'à présent, je n'ai pas vu l'intérêt de les utiliser pour quoi que ce soit.
OdraEncoded

5
@Nathan, le guide de style de Google recommande des commentaires descriptifs plutôt que déclaratifs, par exemple "Récupère les lignes d'une Bigtable" sur "Récupère les lignes d'une Bigtable". Ainsi, changer "Calculer ..." en "Calculer ..." rendrait votre exemple plus cohérent avec le reste du commentaire, c'est-à-dire "Renvoie" et "Augmente".
gwg

2
nit: suivant le style de Google, utilisez une forme descriptive plutôt qu'impérative, c'est-à-dire "Calcule ..." et "Ajoute ..."
sbeliakov

228

Les conventions de 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 standard.

J'ai tendance à toujours inclure des docstrings, car ils ont tendance à 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 chaîne. J'aime coder l'apparence lorsque l'indentation et l'espacement sont cohérents. Cela signifie que j'utilise:

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

Plus de:

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

Et ont tendance à laisser les commentaires sur la première ligne dans des docstrings plus longs:

def sq(n):
    """
    Return 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 signifie que je trouve que les docstrings qui commencent comme ça sont en désordre.

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

90
Notez que PEP-8 dit spécifiquement que les docstrings doivent être écrites sous forme de commandes / instructions, plutôt que de descriptions, par exemple. """Return the squared result"""plutôt que """Returns the squared result""". Bien que personnellement, j'écris le mien comment Tim est ici, malgré ce que dit le PEP.
Cam Jackson

63
Je ne suis pas non plus d'accord avec ce conseil (en utilisant le temps impératif) car il commence à sembler maladroit pendant plus d'une phrase. De plus, vous décrivez une fonction, sans dire au lecteur quoi faire.
mk12

14
Remarque: La spécification pour les docstrings prescriptifs plutôt que descriptifs apparaît en fait dans PEP-257 , pas PEP-8. Je viens d'une tradition de Java, où je décrivais des fonctions, mais j'ai finalement commencé à utiliser le temps impératif lorsque mon paradigme de programmation est passé de orienté objet à procédural. Et quand j'ai commencé à utiliser pycco pour générer une documentation de style programmation alphabétisée, il est devenu très évident pourquoi le temps impératif était suggéré. Vous devez choisir en fonction de votre paradigme.
karan.dodia

26
L'impératif est une humeur grammaticale . (Désolé.)
Denis Drescher

5
Les messages de commit @ Mk12 Git doivent également être écrits sous forme de commandes au lieu de descriptions. Et ils " décrivent " également un changement de code, "ne disent pas au lecteur quoi faire". Je pense donc que c'est juste une convention d'écrire des descriptions sous forme de commandes.
pièce le

58

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

L'extension du sphinx napoléon pour analyser les docstrings de style Google (recommandée dans la réponse de @Nathan) prend également en charge la docstring de style Numpy et fait une courte comparaison des deux.

Et dernier exemple de base pour donner une idée à 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

2
Le format NumPy à mon humble avis prend trop d'espace vertical, ce qui est rare sur les moniteurs à écran large (sauf que vous en utilisez un tourné de 90 degrés, mais je suppose que la plupart des gens ne le font pas).
Semanino

3
Je suppose que c'est quelque peu subjectif. Une fois que vous avez une docstring plus complexe (avec différentes sections, avec des exemples, etc., donc prenant beaucoup d'espace vertical de toute façon quel que soit le format), je trouve le format numpydoc plus facile à lire / mieux structuré.
joris

2
Personnellement, je pense qu'une si longue docstring est mieux située dans la documentation, pas dans le code source, si elle est si longue, cela finit par nuire à la lisibilité du module.
Jonathan Hartley

12

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


8
Mentionner PEP-257 dans le contexte de "comment dois-je documenter correctement les paramètres, les valeurs de retour, les exceptions levées, etc." est un JOKE - il ne dit pas un seul mot à leur sujet (bien qu'un exemple de code en montre). IMHO Google Format est un bon choix en termes de lisibilité et de fonctionnalités.
Semanino

9

C'est Python; tout se passe . Considérez comment publier votre documentation . Les docstrings sont invisibles sauf pour les lecteurs de votre code source.

Les gens aiment vraiment parcourir et rechercher de la documentation sur le Web. Pour ce faire, utilisez l'outil de documentation Sphinx . C'est la norme de facto pour la documentation des projets Python. Le produit est beau - jetez un œil à https://python-guide.readthedocs.org/en/latest/ . Le site Web Read the Docs hébergera vos documents gratuitement.


22
J'utilise régulièrement ipythonpour tester une bibliothèque, et cela rend la lecture des docstrings très simple - tout ce que j'ai à taper est your_module.some_method_im_curious_about?et j'obtiens une impression agréable, y compris docstring.
Thanatos

8
Les utilisateurs d'une bibliothèque ou d'une API ou qui écrivent un plugin sont tous susceptibles de regarder le code et doivent le comprendre. Je trouve les commentaires beaucoup plus cruciaux en Python qu'en Java ou C # car les types ne sont pas déclarés. Cela aide beaucoup si les commentaires donnent une idée de quels types de canards sont passés et retournés. (Sinon, vous devez parcourir tout le code et déterminer qu'un paramètre donné doit ... être itérable ici ... prendre en charge l'indexation là-bas ... prendre en charge la soustraction numérique à la fin ... Aha! C'est fondamentalement un int array. Un commentaire aurait aidé!)
Jon Coombs

Eh non. Les docstrings ne sont pas invisibles et c'est un peu le point. Vous pouvez voir la docstring si vous exécutez la helpfonction sur la fonction / méthode / classe documentée (et que vous pouvez le faire même si vous n'avez accès qu'au module compilé). Personnellement, je pense qu'il faut garder cela à l'esprit lors du choix de la convention docstring (c'est-à-dire qu'elle est destinée à être lue telle quelle).
skyking

7

Je suggère d'utiliser le programme Pep257 Python de Vladimir Keleshev pour vérifier vos docstrings par rapport à PEP-257 et à la norme Numpy Docstring pour décrire les paramètres, les retours, etc.

pep257 signalera la divergence que vous faites par rapport à la norme et est appelé comme pylint et pep8.


Mentionner PEP-257 dans le contexte de "comment dois-je documenter correctement les paramètres, les valeurs de retour, les exceptions levées, etc." est un JOKE - il ne dit pas un seul mot à leur sujet (bien qu'un exemple de code en montre). Le format NumPy à mon humble avis prend trop d'espace vertical, ce qui est rare sur les moniteurs à écran large (sauf que vous en utilisez un tourné de 90 degrés, mais je suppose que la plupart des gens ne le font pas).
Semanino

1
@Semanino Je mentionne la norme Numpy Docstring dans le contexte du programme pep257, et non PEP-257. Ce programme est maintenant appelé pydocstyle. pydocstyle vous permet de faire quelques vérifications numpydoc, par exemple, pydocstyle --select=D4 tmp.pyvérifie une gamme de problèmes de contenu de docstring, y compris le nommage des sections.
Finn Årup Nielsen
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.