Question Quel est le format standard de Python docstring? [fermé]


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


584
2017-10-10 01:10


origine


Réponses:


Formats

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

Notez que le reST est recommandé par le PEP 287

Voici les principaux formats utilisés pour docstrings.

- Epytext

Historiquement un javadoc comme le style é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 reStructuredText format (reST) utilisé par Sphinx pour générer de la documentation. Note: il est utilisé par défaut dans JetBrains PyCharm (tapez les guillemets 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 c'est souvent utilisé. Il peut également être interprété par Sphinx.

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 à un projet Python pas encore documenté, ou pour convertir des docstrings existants (peut être en train de mélanger plusieurs formats) d'un format à un autre.

Note: Les exemples sont tirés de Documentation de Pyment


617
2018-06-24 11:10



le Guide de style Google contient un excellent guide de style Python. Il comprend conventions pour la syntaxe docstring lisible qui offre une meilleure orientation 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 des 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

295
2017-11-13 03:14



Les conventions de Doctring sont en PEP-257 avec beaucoup plus de détails que PEP-8.

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

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 les choses cohérentes, quelle que soit la longueur de la corde. J'aime comment coder les regards quand 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 des 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

Je trouve que les docstrings qui commencent comme ça sont malpropres.

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

214
2017-10-10 05:36



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

L'extension du sphinx Napolean pour analyser les docstrings de style Google (recommandé dans la réponse de @Nathan) prend également en charge la docstring de style Numpy, et fait un court Comparaison des deux.

Et enfin un 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

42
2018-04-21 00:01



PEP-8 est le standard de codage python officiel. Il contient une section sur docstrings, qui se réfère à PEP-257 - une spécification complète pour docstrings.


12
2017-10-10 01:48



Les styles officiels de Python sont listés dans PEP-8.


3
2017-10-10 01:21



Je suggère d'utiliser Vladimir Keleshev pep257 Programme Python pour vérifier vos docstrings contre PEP-257 et le Norme Docsh de Numpy pour décrire les paramètres, les retours, etc.

pep257 signalera la divergence que vous faites de la norme et s'appelle comme pylint et pep8.


3
2017-09-11 15:34



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

Les gens aiment vraiment parcourir et rechercher de la documentation sur le Web. Pour y parvenir, utilisez l'outil de documentation Sphinx. C'est la norme de facto pour documenter les projets Python. 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.


3
2018-01-11 19:29