it-swarm.com.de

Was ist das standardmäßige Python Docstring-Format?

Ich habe in Python einige verschiedene Stile zum Schreiben von Dokumenten gesehen. Gibt es einen offiziellen oder "vereinbarten" Stil?

785
Noah McIlraith

Formate

Python-Docstrings können in verschiedenen Formaten geschrieben werden, wie die anderen Posts gezeigt haben. Das Standard-Sphinx-Docstring-Format wurde jedoch nicht erwähnt und basiert auf reStructuredText (reST) . Informationen zu den wichtigsten Formaten erhalten Sie in that tuto .

Beachten Sie, dass der reST vom PEP 287 empfohlen wird

Es folgen die wichtigsten verwendeten Formate für Dokumentzeichenfolgen.

- Epytext

Historisch gesehen war ein javadoc ähnlicher Stil vorherrschend, daher wurde er als Basis für Epydoc (mit dem aufgerufenen Epytext-Format) genommen Dokumentation erstellen.

Beispiel:

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

- sich ausruhen

Heutzutage ist das wahrscheinlich am weitesten verbreitete Format das Format reStructuredText (reST), das von Sphinx zum Generieren von Dokumentation verwendet wird. Hinweis: Wird standardmäßig in JetBrains PyCharm verwendet (geben Sie nach dem Definieren einer Methode dreifache Anführungszeichen ein und drücken Sie die Eingabetaste). Es wird auch standardmäßig als Ausgabeformat in Pyment verwendet.

Beispiel:

"""
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 ein eigenes Format , das häufig verwendet wird. Es kann auch von Sphinx interpretiert werden (dh mit Napoleon-Plugin ).

Beispiel:

"""
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, ihrem eigenen numpydoc zu folgen, das auf dem Google-Format basiert und von Sphinx verwendet werden kann.

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

Konvertieren/Generieren

Es ist möglich, ein Tool wie Pyment zu verwenden, um automatisch Dokumentfolgen in ein Python -Projekt zu generieren, das noch nicht dokumentiert ist, oder vorhandene Dokumentfolgen (können mehrere Formate mischen) von einem Format in zu konvertieren noch einer.

Hinweis: Die Beispiele stammen aus der Pyment-Dokumentation

866
daouzli

Das Google Style Guide enthält einen hervorragenden Python Style Guide. Es enthält Konventionen für lesbare Docstring-Syntax , das eine bessere Anleitung 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 diesem Tutorial zur Sphinx-Dokumentation beschrieben. Zum Beispiel:

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

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

Docstring-Konventionen sind in PEP-257 ausführlicher als in 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 einzuschließen, weil sie zeigen, wie man die Funktion benutzt und was sie sehr schnell macht.

Ich ziehe es vor, die Dinge unabhängig von der Länge der Zeichenfolge konsistent zu halten. Ich mag es, wie Code aussieht, wenn Einrückung und Abstand konsistent sind. Das heißt, ich benutze:

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

Über:

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

Und neigen dazu, das Kommentieren der ersten Zeile in längeren Dokumentenstrings zu unterlassen:

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 Docstrings, die so beginnen, unordentlich.

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

Wie anscheinend niemand erwähnt: Sie können auch den Numpy Docstring Standard verwenden. Es ist in der wissenschaftlichen Gemeinschaft weit verbreitet.

Die napoleonische Sphinx-Erweiterung zum Parsen von Docstrings im Google-Stil (empfohlen in der Antwort von @Nathan) unterstützt auch Docstring im Numpy-Stil und macht aus beiden ein kurzes Vergleich .

Und als letztes ein einfaches Beispiel, um eine Vorstellung davon zu bekommen, 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
50
joris

PEP-8 ist der offizielle python Kodierungsstandard. Es enthält einen Abschnitt zu Dokumentzeichenfolgen, der auf PEP-257 - eine vollständige Spezifikation für Dokumentzeichenfolgen verweist.

12
bstpierre

Es ist Python; alles geht . Überlegen Sie, wie Sie Ihre Dokumentation veröffentlichen . Docstrings sind nur für Leser Ihres Quellcodes sichtbar.

Die Leute stöbern und suchen wirklich gerne im Web nach Dokumentationen. Verwenden Sie dazu das Dokumentationswerkzeug Sphinx . Dies 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 Read the Docs hostet Ihre Dokumente kostenlos.

7
Colonel Panic

Ich schlage vor, Vladimir Keleshevs pep257 Python-Programm zu verwenden, um Ihre Docstrings mit PEP-257 und dem Numpy Docstring Standard zu vergleichen Parameter, Rückgaben usw.

pep257 meldet Abweichungen vom Standard und heißt wie pylint und pep8.

6

Die offiziellen Stile von Python sind in PEP-8 aufgelistet.

0
Amber