Qu'est-ce que le format standard Python docstring?
J'ai vu différents styles d'écriture de docstrings en Python. Existe-t-il un style officiel ou "convenu"?
Les formats
Les docstrings Python peuvent être écrits en plusieurs formats, comme le montrent les autres articles. Cependant, le format Sphinx docstring par défaut n’est pas mentionné et est basé sur reStructuredText (reST) . Vous pouvez obtenir des informations sur les principaux formats dans this tuto .
Notez que le reST est recommandé par le PEP 287
Voici les principaux formats utilisés pour docstrings.
- Epytext
Historiquement, un style javadoc était répandu, il a donc été pris comme base pour Epydoc (avec l'appelé Epytext format) 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 (saisissez les 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 a son propre format qui est souvent utilisé. Il peut aussi être interprété par Sphinx (c'est-à-dire en utilisant plugin Napoleon ).
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 dans un projet Python non encore documenté, ou pour convertir des docstrings existants (pouvant mélanger plusieurs formats) d’un format à un autre. un autre.
Remarque: Les exemples sont tirés de la documentation Pyment
Le guide de style de Google contient un excellent guide de style Python. Il inclut conventions pour la syntaxe lisible de docstring qui offre de meilleurs conseils 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
Je souhaite également inclure des informations de type dans les arguments, comme décrit dans le présent tutoriel sur la documentation Sphinx . Par exemple:
def add_value(self, value):
"""Add a new value.
Args:
value (str): the value to add.
"""
pass
Les conventions de docstring sont en 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 les docstrings, car ils ont tendance à montrer comment utiliser la fonction et ce qu'elle fait très rapidement.
Je préfère garder la cohérence, 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 de commentaire sur la première ligne dans 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
Cela signifie que les documents qui commencent comme ça sont en désordre.
def sq(n):
"""Return the squared result.
...
Apparemment, personne ne l'a mentionné: vous pouvez également utiliser le Numpy Docstring Standard . Il est largement utilisé dans la communauté scientifique.
- Le spécification du format de numpy avec un exemple
- Vous avez une extension sphinx pour le rendre: numpydoc
- Et un exemple de la beauté d'une docstring rendue peut ressembler à: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html
L'extension Napolean sphinx permettant d'analyser les docstrings de style Google (recommandé dans la réponse de @Nathan) prend également en charge les docstring de style Numpy et en fait un court comparaison des deux.
Et enfin un exemple de base pour donner une idée de ce à quoi il 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
C'est du python; tout est permis . 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 de Python projets. Le produit est beau - jetez un oeil à https://python-guide.readthedocs.org/en/latest/ . Le site Web Lire les documents hébergera vos documents gratuitement.
Je suggère d'utiliser le programme pep257 Python de Vladimir Keleshev pour vérifier votre docstrings contre PEP-257 et le Numpy Docstring Standard pour décrire paramètres, retours, etc.
pep257 signalera votre divergence par rapport à la norme et s'appelle pylint et pep8.
Les styles officiels de Python sont listés dans PEP-8 .