Was sind die gängigsten Python-Docstring-Formate?

Question

Ich habe ein paar verschiedene Stile des Schreibens docstrings in Python gesehen, was sind die beliebtesten Stile?

Answer 1

Formate

Python-Docstrings können in verschiedenen Formaten geschrieben werden, wie die anderen Beiträge gezeigt haben. Das Standardformat von Sphinx docstring wurde jedoch nicht erwähnt und basiert auf reStrukturierterText (reST) . Einige Informationen über die wichtigsten Formate finden Sie unter dieser Blogbeitrag .

Beachten Sie, dass die reST von der Europäischen Kommission empfohlen wird. PEP 287

Es folgen die wichtigsten Formate für Docstrings.

- Epytext

Historisch gesehen ein javadoc Stil vorherrschend war, wurde er als Grundlage für die Epydoc (mit der Bezeichnung Epytext Format), um Dokumentation zu erstellen.

Ejemplo:

"""
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

Heutzutage ist das wahrscheinlich am meisten verbreitete Format das reStructuredText (reST)-Format, das verwendet wird von Sphinx um Dokumentation zu erstellen. Hinweis: Es wird standardmäßig in JetBrains PyCharm verwendet (geben Sie dreifache Anführungszeichen nach der Definition einer Methode ein und drücken Sie Enter). Es wird auch standardmäßig als Ausgabeformat in Pyment verwendet.

Ejemplo:

"""
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 hat seine eigene Format die oft verwendet wird. Sie kann auch von Sphinx interpretiert werden (z. B. mit Napoleon-Stecker ).

Ejemplo:

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

Sogar weitere Beispiele

- Numpydoc

Beachten Sie, dass Numpy empfiehlt, die eigene numpydoc die auf dem Google-Format basieren und von Sphinx verwendet werden können.

"""
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
"""

Umwandlung/Erzeugung

Es ist möglich, ein Werkzeug wie Pyment um automatisch Docstrings für ein noch nicht dokumentiertes Python-Projekt zu erzeugen oder um bestehende Docstrings (es können mehrere Formate gemischt werden) von einem Format in ein anderes zu konvertieren.

Hinweis: Die Beispiele stammen aus der Dokumentation zur Zahlung

Answer 2

Le site Google Style Guide enthält einen hervorragenden Python-Style-Guide. Er umfasst Konventionen für lesbare Docstring-Syntax die eine bessere Orientierung bietet als PEP-257. Zum Beispiel:

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

Ich möchte dies erweitern, um auch Typinformationen in die Argumente aufzunehmen, wie in dieser Tutorial zur Sphinx-Dokumentation . Zum Beispiel:

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

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

Answer 3

Die Docstring-Konventionen sind in PEP-257 mit viel mehr Details als PEP-8.

Docstrings scheinen jedoch viel persönlicher zu sein als andere Bereiche des Codes. Verschiedene Projekte werden ihren eigenen Standard haben.

Ich neige dazu, immer Docstrings mit einzubeziehen, weil sie in der Regel sehr schnell zeigen, wie man die Funktion benutzt und was sie tut.

Ich ziehe es vor, die Dinge einheitlich zu halten, unabhängig von der Länge der Saite. Mir gefällt, wie der Code aussieht, wenn Einrückung und Abstände einheitlich sind. Das heißt, ich verwende:

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

Ende:

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

Und ich neige dazu, die erste Zeile in längeren Dokumentationsstrings nicht zu kommentieren:

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

Das heißt, ich finde Doku-Strings, die so beginnen, unübersichtlich.

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

Answer 4

Da es anscheinend niemand erwähnt hat: Sie können auch die Numpy Docstring Standard . Es ist in der wissenschaftlichen Gemeinschaft weit verbreitet.

• Le site Spezifikation des Formats von numpy zusammen mit einer Beispiel
• Sie haben eine Sphinx-Erweiterung, um sie zu rendern: numpydoc
• Und ein Beispiel dafür, wie schön ein gerenderter Docstring aussehen kann: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Die Napolean-Sphinx-Erweiterung zum Parsen von Docstrings im Google-Stil (empfohlen in der Antwort von @Nathan) unterstützt auch Docstrings im Numpy-Stil, und macht eine kurze Vergleich von beidem.

Und schließlich ein einfaches Beispiel, um eine Vorstellung davon zu vermitteln, wie es aussieht:

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

Das ist Python; alles ist erlaubt . Überlegen Sie, wie Sie Ihre Dokumentation veröffentlichen . Docstrings sind unsichtbar, außer für die Leser Ihres Quellcodes.

Die Menschen lieben es, im Internet zu stöbern und Dokumentationen zu suchen. Verwenden Sie dazu das Dokumentationswerkzeug Sphinx . Es ist der De-facto-Standard für die Dokumentation von Python-Projekten. Das Produkt ist wunderschön - werfen Sie einen Blick auf https://python-guide.readthedocs.org/en/latest/ . Die Website Lesen Sie die Dokumente wird Ihre Dokumente kostenlos hosten.