WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / Python

docstring — Dokumentationszeichenfolge

Ein Docstring ist ein gewöhnliches Zeichenfolgenliteral (kein f-String und kein t-String), das als erste Anweisung eines Moduls, einer Klasse oder einer Funktion steht. Er dokumentiert den Zweck des Objekts und ist über __doc__ verfügbar; er ist kein Kommentar, der mit # beginnt.

Version: Python 3.14; repository image, production runtime not attested

Syntax

def function_name():
    """Describe the function's purpose."""
    pass

Ein docstring ist ein gewöhnliches Zeichenfolgenliteral (kein f-String und kein t-String), das als erste Anweisung eines Moduls, einer Klasse oder einer Funktion (auch einer Methode) steht. Python stellt ihn als Attribut __doc__ des Objekts bereit. Werkzeuge können diesen Inhalt zur Anzeige von Dokumentation verwenden.

Weder ein formatiertes Zeichenfolgenliteral (f-String) noch ein Vorlagenliteral (t-String) erzeugt einen Docstring, auch wenn das Literal keine Ersetzungsfelder enthält und als erste Anweisung steht. Lautet die erste Anweisung einer Funktion f"""Description.""", hat ihr Attribut __doc__ den Wert None.

Ein Kommentar, der mit # beginnt, erzeugt keinen docstring. Auch ein alleinstehendes Zeichenfolgenliteral nach einer anderen Anweisung wird nicht zum Haupt-docstring des Objekts. Dreifache Anführungszeichen """...""" sind besonders bei mehreren Zeilen praktisch, reichen aber allein nicht aus: Sowohl die Art des Literals als auch seine Position sind entscheidend.

Der Konvention nach sollte die erste Zeile den Zweck des Objekts kurz beschreiben, mit einem Großbuchstaben beginnen und mit einem Punkt enden. Weitere Erläuterungen werden durch eine Leerzeile abgetrennt; bei Bedarf können Argumente, Ergebnisse und Nebenwirkungen erklärt werden. Dies sind Empfehlungen zum Inhalt, keine Syntaxanforderungen.

Im Beispiel stellt square.__doc__ die Beschreibung bereit, während square(5) unabhängig von der Dokumentation das Ergebnis berechnet. Die Option -OO entfernt Docstrings. Anwendungscode sollte daher nicht davon abhängen, dass sie vorhanden sind.

Beispiele

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

print(square.__doc__)
print(square(5))

Ergebnis

Return the square of number.
25

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen