Eine Funktion dokumentieren

Die vorige Lektion hat die REPL als Ort vorgestellt, an dem du Python Anweisung für Anweisung erkunden kannst. Wir verwenden sie hier weiter, diesmal um Informationen zu untersuchen, die in Funktionen gespeichert sind.

Die Funktionen in diesem Kapitel werden flexibler. Sie haben Standardwerte, benannte Einstellungen und optionale Werte. Mit dieser Flexibilität wächst auch der Bedarf, ihre Regeln zu kennen, ohne jede Zeile des Funktionskörpers zu lesen.

Zum Beispiel braucht eine Prozentfunktion einen positiven Wert für total. Sie gibt eine Zahl zurück und löst einen Fehler aus, wenn diese Regel verletzt wird. Wir können diese Tatsachen als Zusage der Funktion festhalten:

• welche Werte sie erwartet;

• was sie zurückgibt;

• welche wichtigen Regeln oder Fehler es gibt.

Die Umsetzung zeigt, wie die Funktion arbeitet. Python gibt uns einen Weg, eine kurze Erklärung bei der Funktion selbst zu speichern. Bevor wir ihn verwenden, brauchst du eine neue Schreibweise für Strings.

Dreifache Anführungszeichen für Strings

Bisher hast du Strings zwischen einem Paar Anführungszeichen geschrieben, etwa "hello". Ein String kann auch mit drei doppelten Anführungszeichen beginnen und enden:

Der Wert hat weiterhin den Typ str. Die dreifachen Anführungszeichen ändern nur die Schreibweise.

Ein nützlicher Unterschied ist, dass ein String in dreifachen Anführungszeichen auf einer neuen Zeile weitergehen kann:

Python akzeptiert auch drei einfache Anführungszeichen. In diesem Kurs verwenden wir drei doppelte Anführungszeichen für Funktionsdokumentation, weil das dem üblichen Python-Stil entspricht.

Wenn der erste String zur Dokumentation wird

Ein String in dreifachen Anführungszeichen ist nicht automatisch Dokumentation. Seine Position innerhalb der Funktion gibt ihm eine besondere Aufgabe.

Wenn ein String die erste Anweisung in einer Funktion ist, speichert Python ihn als Docstring der Funktion. Ein Docstring erklärt, worauf sich anderer Code beim Verwenden der Funktion verlassen kann.

In Python-Grundlagen I hast du gelernt, dass raise eine Funktion stoppt und meldet, warum sie kein normales Ergebnis zurückgeben konnte. Der Docstring und die Validierung können zusammenstehen:

def percentage(score, total):
    """Return score as a percentage of a positive total."""
    if total <= 0:
        raise ValueError("total must be positive")
    return score / total * 100

Hier ist der String in dreifachen Anführungszeichen die erste Anweisung, deshalb wird er zum Docstring. Er erklärt das Ergebnis und die Regel für eine positive Gesamtzahl in einem Satz.

Pythons Funktion help() kann diese Dokumentation anzeigen:

help(percentage)

Beschreibe die Zusage, nicht jeden Schritt

Dieser Docstring ist schwach:

"""Divide score by total, multiply by 100, and return it."""

Er wiederholt die Umsetzung. Ein stärkerer Docstring benennt die Zusage und die wichtige Einschränkung:

"""Return score as a percentage of a positive total."""

Erkunde Docstrings in der REPL

Das Panel neben dieser Lektion ist eine Python-REPL. Probiere an ihrer Eingabeaufforderung >>> diese Befehle nacheinander aus:

help(len)
help(print)
help("python land".strip)

Diese Funktionen haben bereits Docstrings. Du musst nicht jedes Detail verstehen, das help() zeigt. Suche nach dem Funktionsnamen, den akzeptierten Werten und dem ersten Satz, der das Ergebnis beschreibt.

Der Docstring selbst ist auch über das Attribut __doc__ einer Funktion verfügbar. Vergleiche diese beiden REPL-Anweisungen:

len.__doc__
help(len)

len.__doc__ wird zum gespeicherten String ausgewertet, daher zeigt die REPL diesen Wert an. help(len) stellt dieselbe Dokumentation in einer ausführlicheren Hilfeansicht dar.

Gib jetzt deiner eigenen Funktion einen Docstring. Gib diese Zeilen in die REPL ein und drücke danach in der leeren Zeile mit ... noch einmal Enter, um die Funktion abzuschließen:

def double(number):
    """Return number multiplied by two."""
    return number * 2

Untersuche und verwende sie dann:

double.__doc__
help(double)
double(6)

Ändere versuchsweise den Docstring und definiere die Funktion erneut. Der nächste Aufruf von help(double) zeigt deine neue Beschreibung.