Was ist ein Docstring?

Ein Docstring ist ein String-Literal, das als erste Anweisung in einer Modul-, Klassen-, Funktions- oder Methodendefinition vorkommt. Ein solcher Docstring wird zum speziellen Attribut __doc__ dieses Objekts.

Alle Module sollten normalerweise Docstrings haben, und alle von einem Modul exportierten Funktionen und Klassen sollten ebenfalls Docstrings haben. Öffentliche Methoden (einschließlich des Konstruktors __init__) sollten ebenfalls Docstrings haben. Ein Paket kann im Modul-Docstring der Datei __init__.py im Paketverzeichnis dokumentiert werden.

String-Literale, die an anderer Stelle im Python-Code vorkommen, können ebenfalls als Dokumentation dienen. Sie werden vom Python-Bytecode-Compiler nicht erkannt und sind nicht als Laufzeit-Objektattribute zugänglich (d.h. nicht an __doc__ gebunden), aber zwei Arten von zusätzlichen Docstrings können von Software-Tools extrahiert werden.

1. String-Literale, die unmittelbar nach einer einfachen Zuweisung auf der obersten Ebene eines Moduls, einer Klasse oder einer __init__-Methode vorkommen, werden als „Attribut-Docstrings“ bezeichnet.
2. String-Literale, die unmittelbar nach einem anderen Docstring vorkommen, werden als „zusätzliche Docstrings“ bezeichnet.

Weitere Informationen über Attribut- und zusätzliche Docstrings finden Sie in PEP 258, „Docutils Design Specification“.

Verwenden Sie der Konsistenz halber immer """dreifache doppelte Anführungszeichen""" um Docstrings. Verwenden Sie r"""rohe dreifache doppelte Anführungszeichen""", wenn Sie Backslashes in Ihren Docstrings verwenden.

Es gibt zwei Formen von Docstrings: Einzeiler und mehrzeilige Docstrings.

Einzeilige Docstrings

Einzeiler sind für wirklich offensichtliche Fälle. Sie sollten wirklich auf eine Zeile passen. Zum Beispiel:

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

Anmerkungen

• Dreifache Anführungszeichen werden verwendet, auch wenn die Zeichenkette auf eine Zeile passt. Das erleichtert die spätere Erweiterung.
• Die schließenden Anführungszeichen befinden sich auf derselben Zeile wie die öffnenden Anführungszeichen. Das sieht bei Einzeilern besser aus.
• Es gibt weder vor noch nach dem Docstring eine Leerzeile.
• Der Docstring ist ein Satz, der mit einem Punkt endet. Er beschreibt die Auswirkung der Funktion oder Methode als Befehl („Tue dies“, „Gib das zurück“), nicht als Beschreibung; z.B. schreiben Sie nicht „Gibt den Pfadnamen zurück …“.
• Der einzeilige Docstring sollte KEINE „Signatur“ sein, die die Parameter der Funktion/Methode wiederholt (diese können durch Introspektion ermittelt werden). Machen Sie nicht

  def function(a, b):
      """function(a, b) -> list"""
  

  Diese Art von Docstring ist nur für C-Funktionen (wie Built-ins) geeignet, bei denen keine Introspektion möglich ist. Die Art des *Rückgabewerts* kann jedoch nicht durch Introspektion ermittelt werden, daher sollte sie erwähnt werden. Die bevorzugte Form für einen solchen Docstring wäre etwas wie

  def function(a, b):
      """Do X and return a list."""
  

  (Natürlich sollte „Tue X“ durch eine nützliche Beschreibung ersetzt werden!)

Mehrzeilige Docstrings

Mehrzeilige Docstrings bestehen aus einer Zusammenfassungszeile, ähnlich wie ein einzeiliger Docstring, gefolgt von einer Leerzeile und einer ausführlicheren Beschreibung. Die Zusammenfassungszeile kann von automatischen Indexierungswerkzeugen verwendet werden; es ist wichtig, dass sie auf eine Zeile passt und durch eine Leerzeile vom Rest des Docstrings getrennt ist. Die Zusammenfassungszeile kann sich auf derselben Zeile wie die öffnenden Anführungszeichen befinden oder auf der nächsten Zeile. Der gesamte Docstring ist genauso eingerückt wie die Anführungszeichen in seiner ersten Zeile (siehe Beispiel unten).

Fügen Sie nach allen Docstrings (einzeilig oder mehrzeilig), die eine Klasse dokumentieren, eine Leerzeile ein – im Allgemeinen sind die Methoden der Klasse durch eine einzelne Leerzeile getrennt, und der Docstring muss durch eine Leerzeile vom ersten Methode abgesetzt werden.

Der Docstring eines Skripts (ein eigenständiges Programm) sollte als dessen „Usage“-Nachricht verwendet werden können, die ausgegeben wird, wenn das Skript mit falschen oder fehlenden Argumenten (oder vielleicht mit einer Option „-h“ für „Hilfe“) aufgerufen wird. Ein solcher Docstring sollte die Funktion des Skripts und die Syntax der Kommandozeile, Umgebungsvariablen und Dateien dokumentieren. Usage-Nachrichten können ziemlich aufwendig sein (mehrere Bildschirme voll) und sollten ausreichen, damit ein neuer Benutzer den Befehl richtig verwenden kann, sowie eine vollständige schnelle Referenz für alle Optionen und Argumente für den erfahrenen Benutzer.

Der Docstring eines Moduls sollte im Allgemeinen die von ihm exportierten Klassen, Ausnahmen und Funktionen (und alle anderen Objekte) mit einer einzeiligen Zusammenfassung jeder einzelnen auflisten. (Diese Zusammenfassungen geben im Allgemeinen weniger Details als die Zusammenfassungszeile im Docstring des Objekts.) Der Docstring eines Pakets (d.h. der Docstring des __init__.py-Moduls des Pakets) sollte auch die vom Paket exportierten Module und Unterpakete auflisten.

Der Docstring einer Funktion oder Methode sollte ihr Verhalten zusammenfassen und ihre Argumente, Rückgabewerte, Seiteneffekte, ausgelösten Ausnahmen und Einschränkungen für ihre Aufrufbarkeit (sofern zutreffend) dokumentieren. Optionale Argumente sollten angegeben werden. Es sollte dokumentiert werden, ob Schlüsselwortargumente Teil der Schnittstelle sind.

Der Docstring einer Klasse sollte ihr Verhalten zusammenfassen und die öffentlichen Methoden und Instanzvariablen auflisten. Wenn die Klasse dazu bestimmt ist, Unterklassen zu bilden, und eine zusätzliche Schnittstelle für Unterklassen hat, sollte diese Schnittstelle separat (im Docstring) aufgeführt werden. Der Klassenkonstruktor sollte im Docstring seiner __init__-Methode dokumentiert werden. Einzelne Methoden sollten durch ihren eigenen Docstring dokumentiert werden.

Wenn eine Klasse eine andere Klasse unterclassifiziert und ihr Verhalten größtenteils von dieser Klasse geerbt wird, sollte ihr Docstring dies erwähnen und die Unterschiede zusammenfassen. Verwenden Sie das Verb „überschreiben“, um anzuzeigen, dass eine Unterklassenmethode eine Oberklassenmethode ersetzt und die Oberklassenmethode nicht aufruft; verwenden Sie das Verb „erweitern“, um anzuzeigen, dass eine Unterklassenmethode die Oberklassenmethode aufruft (zusätzlich zu ihrem eigenen Verhalten).

*Verwenden Sie nicht* die Emacs-Konvention, die Argumente von Funktionen oder Methoden in Großbuchstaben im Fließtext zu erwähnen. Python ist case-sensitive und die Argumentnamen können für Schlüsselwortargumente verwendet werden, daher sollte der Docstring die korrekten Argumentnamen dokumentieren. Am besten ist es, jedes Argument auf einer separaten Zeile aufzuführen. Zum Beispiel:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

Wenn der gesamte Docstring nicht auf eine Zeile passt, platzieren Sie die schließenden Anführungszeichen auf einer eigenen Zeile. Auf diese Weise kann der fill-paragraph-Befehl von Emacs darauf angewendet werden.

Verarbeitung von Docstring-Einrückungen

Docstring-Verarbeitungswerkzeuge entfernen von der zweiten und weiteren Zeilen des Docstrings einen gleichmäßigen Einzug, der der minimalen Einrückung aller nicht-leeren Zeilen nach der ersten Zeile entspricht. Jeder Einzug in der ersten Zeile des Docstrings (d.h. bis zum ersten Zeilenumbruch) ist unerheblich und wird entfernt. Die relative Einrückung späterer Zeilen im Docstring bleibt erhalten. Leerzeilen sollten vom Anfang und Ende des Docstrings entfernt werden.

Da Code viel präziser ist als Worte, hier ist eine Implementierung des Algorithmus

def trim(docstring):
    if not docstring:
        return ''
    # Convert tabs to spaces (following the normal Python rules)
    # and split into a list of lines:
    lines = docstring.expandtabs().splitlines()
    # Determine minimum indentation (first line doesn't count):
    indent = sys.maxsize
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    # Remove indentation (first line is special):
    trimmed = [lines[0].strip()]
    if indent < sys.maxsize:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    # Strip off trailing and leading blank lines:
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    # Return a single string:
    return '\n'.join(trimmed)

Der Docstring in diesem Beispiel enthält zwei Zeilenumbruchzeichen und ist daher 3 Zeilen lang. Die erste und die letzte Zeile sind leer.

def foo():
    """
    This is the second line of the docstring.
    """

Zur Veranschaulichung:

>>> print repr(foo.__doc__)
'\n    This is the second line of the docstring.\n    '
>>> foo.__doc__.splitlines()
['', '    This is the second line of the docstring.', '    ']
>>> trim(foo.__doc__)
'This is the second line of the docstring.'

Nach dem Zuschneiden sind diese Docstrings äquivalent:

def foo():
    """A multi-line
    docstring.
    """

def bar():
    """
    A multi-line
    docstring.
    """