Python-Funktionen mit Docstrings dokumentieren

Einführung

In diesem Lab lernen Sie die Bedeutung der Dokumentation Ihres Python-Codes mithilfe von Docstrings kennen. Wir werden untersuchen, wie man auf vorhandene Docstrings für eingebaute Funktionen mit der Funktion help() und dem Attribut __doc__ zugreift.

Darüber hinaus sammeln Sie praktische Erfahrungen beim Schreiben eigener Docstrings für benutzerdefinierte Funktionen und beim Überprüfen deren Zugänglichkeit, wodurch Ihr Code für Sie und andere verständlicher und wartbarer wird.

Dokumentation mit help() abrufen

Ein Docstring ist eine String-Literal, die als erste Anweisung in einer Modul-, Funktions-, Klassen- oder Methoden-Definition vorkommt. Er dient dazu, zu dokumentieren, was der Code tut. Die eingebaute Python-Funktion help() ist ein ausgezeichnetes Werkzeug, um diese Dokumentation in einem sauberen, lesbaren Format anzuzeigen. Die Funktion help() ist für die interaktive Nutzung konzipiert.

Beginnen wir damit, die Dokumentation für die eingebaute Funktion print() anzuzeigen.

Öffnen Sie zunächst ein Terminal in der WebIDE. Dies können Sie tun, indem Sie oben auf dem Bildschirm auf das Menü Terminal klicken und New Terminal auswählen.

Geben Sie im Terminal die folgende Befehl ein und drücken Sie die Eingabetaste, um die interaktive Python-Shell zu starten:

python

Sie sehen den Python-Prompt (>>>). Verwenden Sie nun die Funktion help(), um Informationen über print() zu erhalten:

help(print)

Das Terminal zeigt die Dokumentation für die print-Funktion an.

Help on built-in function print in module builtins:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    Prints the values to a stream, or to sys.stdout by default.

    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

(END)

Diese Ausgabe erklärt, was die Funktion tut, welche Parameter sie akzeptiert und welche Standardwerte diese haben. Drücken Sie die Taste q, um den Hilfe-Viewer zu verlassen und zum Python-Prompt zurückzukehren.

Beenden Sie nun die interaktive Python-Shell, indem Sie Folgendes eingeben:

exit()

Direkter Zugriff auf Docstrings mit __doc__

Während help() hervorragend für die interaktive Nutzung ist, können Sie den rohen Docstring eines Objekts auch programmatisch über sein spezielles Attribut __doc__ abrufen. Dieses Attribut speichert den Docstring als einfachen String.

Sehen wir uns das in Aktion an. Suchen Sie im Dateiexplorer der WebIDE auf der linken Seite die Datei mit dem Namen access_docstring.py und öffnen Sie diese.

Fügen Sie den folgenden Python-Code in die Datei ein. Dieser Code gibt den Docstring der eingebauten Funktion len() aus.

## This script prints the docstring of the len() function.
print(len.__doc__)

Speichern Sie die Datei (Sie können die Tastenkombination Strg+S verwenden).

Kehren Sie nun zum Terminal zurück und führen Sie das Skript mit dem folgenden Befehl aus:

python access_docstring.py

Die Ausgabe wird der rohe Docstring für die len-Funktion sein.

Return the number of items in a container.

Wie Sie sehen, liefert __doc__ den direkten String-Inhalt der Dokumentation, was für benutzerdefinierte Tools oder Skripte, die Dokumentation verarbeiten, nützlich sein kann.

Einen benutzerdefinierten Funktions-Docstring schreiben

Die Dokumentation eigener Funktionen ist eine grundlegende Praxis für das Schreiben von sauberem und wartbarem Code. Ein guter Docstring erklärt den Zweck der Funktion, ihre Parameter und was sie zurückgibt.

Schreiben wir eine Funktion und dokumentieren sie. Öffnen Sie die Datei my_function.py aus dem Dateiexplorer.

Fügen Sie zuerst die folgende Funktionsdefinition in die Datei ein:

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

Fügen wir nun einen Docstring hinzu. Der Docstring sollte unmittelbar nach der def-Zeile platziert und auf derselben Ebene wie der Code der Funktion eingerückt werden. Wir verwenden dreifache Anführungszeichen ("""...""") für einen mehrzeiligen Docstring.

Ändern Sie my_function.py, um den Docstring einzufügen. Wir fügen auch eine Zeile hinzu, um den Docstring auszugeben und zu überprüfen, ob es funktioniert.

def greet(name, greeting="Hello"):
    """Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".
    """
    print(f"{greeting}, {name}!")

## Print the docstring of our greet function
print(greet.__doc__)

Speichern Sie die Datei. Führen Sie nun das Skript in Ihrem Terminal aus:

python my_function.py

Sie sehen Ihren benutzerdefinierten Docstring in der Konsole ausgegeben.

Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

Dies bestätigt, dass Sie Ihre Funktion erfolgreich dokumentiert haben und über das Attribut __doc__ auf ihren Docstring zugreifen können.

Verwendung von help() mit Ihrer benutzerdefinierten Funktion

Im vorherigen Schritt haben wir über __doc__ auf unseren benutzerdefinierten Docstring zugegriffen. Nun verwenden wir die Funktion help(), um eine poliertere und benutzerfreundlichere Ansicht unserer Dokumentation zu erhalten, genau wie wir es bei der eingebauten Funktion print() getan haben.

Wir werden unsere greet-Funktion in die interaktive Python-Shell importieren, um help() zu verwenden.

Starten Sie in Ihrem Terminal erneut die Python-Shell:

python

Sobald Sie die Eingabeaufforderung >>> sehen, importieren Sie die Funktion greet aus Ihrem Modul my_function (der Dateiname my_function.py wird als Modul namens my_function behandelt).

from my_function import greet

Verwenden Sie nun help(), um die Dokumentation Ihrer greet-Funktion anzuzeigen:

help(greet)

Sie sehen eine schön formatierte Ausgabe, die aus Ihrem Docstring generiert wurde.

Help on function greet in module my_function:

greet(name, greeting='Hello')
    Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

(END)

Beachten Sie, wie help() automatisch die Signatur der Funktion (greet(name, greeting='Hello')) einfügt und den Docstring zur besseren Lesbarkeit formatiert. Deshalb ist das Schreiben guter Docstrings so wertvoll – er integriert sich direkt in das eingebaute Hilfesystem von Python.

Drücken Sie q, um den Hilfe-Viewer zu verlassen, und geben Sie dann exit() ein, um die Python-Shell zu beenden.

Zusammenfassung

In diesem Lab haben Sie die Grundlagen der Dokumentation von Python-Code mit Docstrings erlernt. Sie haben geübt, auf die Dokumentation eingebauter Funktionen mithilfe der interaktiven help()-Funktion und des Attributs __doc__ zuzugreifen. Anschließend haben Sie dieses Wissen angewendet, indem Sie Ihre eigenen einzeiligen und mehrzeiligen Docstrings für eine benutzerdefinierte Funktion gemäß den Standardkonventionen geschrieben haben. Schließlich haben Sie überprüft, ob Ihre benutzerdefinierte Dokumentation sowohl über __doc__ als auch über das help()-System von Python zugänglich ist – eine Schlüsselkompetenz für die Erstellung von lesbarem, wiederverwendbarem und wartbarem Code.