Python-Funktionen mit Docstrings dokumentieren

Einleitung

In diesem Lab lernen Sie die Bedeutung der Dokumentation Ihres Python-Codes mithilfe von Docstrings kennen. Wir werden untersuchen, wie Sie auf vorhandene Docstrings für integrierte Funktionen über die Funktion help() und das Attribut __doc__ zugreifen können.

Darüber hinaus sammeln Sie praktische Erfahrungen beim Schreiben eigener Docstrings für benutzerdefinierte Funktionen und beim Überprüfen ihrer Zugänglichkeit mithilfe der Funktion help(), wodurch Ihr Code verständlicher und wartbarer wird.

Docstrings und help() verstehen

In diesem Schritt lernen wir Docstrings in Python kennen und wie wir mit der integrierten Funktion help() darauf zugreifen können. Docstrings sind ein wichtiges Werkzeug, um den Zweck und die Verwendung Ihres Codes zu erklären und ihn so für andere (und Ihr zukünftiges Ich) leichter verständlich zu machen.

Docstrings werden typischerweise mit dreifachen Anführungszeichen ('''...''' oder """...""") als erste Anweisung innerhalb einer Funktion, Klasse, eines Moduls oder einer Methode definiert.

Beginnen wir damit, wie wir die Dokumentation für integrierte Python-Funktionen mithilfe der Funktion help() anzeigen können. Wir verwenden die Funktion print() als Beispiel.

Öffnen Sie das integrierte Terminal in der WebIDE, indem Sie zu Terminal -> New Terminal navigieren.

Geben Sie im Terminal den folgenden Befehl ein und drücken Sie Enter:

python

Dadurch wird die interaktive Python-Shell geöffnet. Verwenden Sie nun innerhalb der Python-Shell die Funktion help(), um die Dokumentation für print anzuzeigen:

help(print)

Sie sehen eine Ausgabe, die dieser ähnelt:

Help on built-in function print in module builtins:

print(...)
    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.

Drücken Sie q, um den Hilfe-Viewer zu verlassen und zur Python-Eingabeaufforderung (>>>) zurückzukehren.

Die Funktion help() bietet eine formatierte Ansicht des Docstrings, was sehr nützlich ist, um zu verstehen, wie eine Funktion verwendet wird.

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

exit()

Docstrings mit doc zugreifen

Im vorherigen Schritt haben wir die Funktion help() verwendet, um die Dokumentation für integrierte Funktionen anzuzeigen. Eine weitere Möglichkeit, auf den Docstring eines Objekts (wie einer Funktion) zuzugreifen, ist die Verwendung seines __doc__-Attributs. Dieses Attribut enthält direkt den Docstring-String.

Sehen wir uns an, wie dies erneut mit der Funktion print() funktioniert.

Öffnen Sie das integrierte Terminal in der WebIDE, falls es noch nicht geöffnet ist (Terminal -> New Terminal).

Stellen Sie sicher, dass Sie sich im Verzeichnis ~/project befinden.

Erstellen Sie eine neue Python-Datei namens access_docstring.py im Verzeichnis ~/project mit dem WebIDE-Editor.

Fügen Sie den folgenden Code in die Datei ein:

print(print.__doc__)

Speichern Sie die Datei.

Führen Sie nun das Python-Skript im Terminal aus:

python access_docstring.py

Sie sehen den Docstring der Funktion print, der direkt auf der Konsole ausgegeben wird:

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.

Diese Methode liefert Ihnen den rohen Docstring-String, was nützlich sein kann, wenn Sie ihn auf eine benutzerdefinierte Weise verarbeiten oder anzeigen möchten.

Versuchen wir ein weiteres Beispiel mit der Funktion str().

Ändern Sie die Datei access_docstring.py so, dass sie den folgenden Code enthält:

print(str.__doc__)

Speichern Sie die Datei.

Führen Sie das Skript erneut aus:

python access_docstring.py

Sie sehen den Docstring der Funktion str:

str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must be a bytes like object. Otherwise,
returns the string representation of the object.
By default, the encoding is 'utf-8', errors is 'strict'.

Die Verwendung von __doc__ ist eine direkte Möglichkeit, auf den Docstring-Inhalt als String zuzugreifen.

Eigene Funktions-Docstrings schreiben

In diesem Schritt schreiben wir unsere eigene Funktion und fügen ihr einen Docstring hinzu. Wie wir bei den integrierten Funktionen gesehen haben, enthält ein guter Docstring typischerweise Informationen darüber, wie die Funktion verwendet wird, ihre Parameter und was sie tut.

Definieren wir eine einfache Funktion, die eine Person begrüßt.

Öffnen Sie das integrierte Terminal in der WebIDE, falls es noch nicht geöffnet ist (Terminal -> New Terminal).

Stellen Sie sicher, dass Sie sich im Verzeichnis ~/project befinden.

Erstellen Sie eine neue Python-Datei namens my_function.py im Verzeichnis ~/project mit dem WebIDE-Editor.

Fügen Sie den folgenden Code in die Datei ein. Dies ist die grundlegende Funktion, noch ohne Docstring:

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

Speichern Sie die Datei.

Fügen wir dieser Funktion nun einen Docstring hinzu. Gemäß den allgemeinen Prinzipien, die wir von integrierten Funktionen beobachtet haben, werden wir die Funktionssignatur und eine Beschreibung aufnehmen.

Ändern Sie die Datei my_function.py, um den Docstring einzufügen. Platzieren Sie den Docstring unmittelbar nach der Zeile mit der Funktionsdefinition, korrekt eingerückt.

def hello(name, greet="Hello"):
    '''\
hello(name)
hello(name, greet="Hello")

This function greets a person.
The 'name' parameter is the person to greet.
The optional 'greet' parameter is the greeting word, defaulting to "Hello".'''
    print(f'{greet} {name}!')

Beachten Sie das '''\ am Anfang des Docstrings. Der Backslash ermöglicht es dem Docstring, in der nächsten Zeile zu beginnen, ohne das Zeilenumbruchzeichen in den Docstring selbst aufzunehmen. Dies ist eine gängige Konvention.

Speichern Sie die Datei.

Verwenden wir nun das Attribut __doc__, um auf den Docstring unserer hello-Funktion zuzugreifen.

Fügen Sie die folgende Zeile am Ende der Datei my_function.py hinzu:

print(hello.__doc__)

Speichern Sie die Datei.

Führen Sie das Skript im Terminal aus:

python my_function.py

Sie sollten den Docstring als Ausgabe sehen:

hello(name)
hello(name, greet="Hello")

This function greets a person.
The 'name' parameter is the person to greet.
The optional 'greet' parameter is the greeting word, defaulting to "Hello".

Dies bestätigt, dass wir erfolgreich einen Docstring zu unserer Funktion hinzugefügt haben und darauf über __doc__ zugreifen können.

Benutzerdefinierte Docstrings mit Help() anzeigen

Im vorherigen Schritt haben wir unserer hello-Funktion einen Docstring hinzugefügt und über das __doc__-Attribut darauf zugegriffen. Während __doc__ Ihnen den rohen String liefert, bietet die Funktion help() eine formatiertere und besser lesbare Ansicht, ähnlich wie sie die Dokumentation für integrierte Funktionen anzeigt.

In diesem Schritt verwenden wir die Funktion help(), um den Docstring unserer benutzerdefinierten hello-Funktion anzuzeigen.

Öffnen Sie das integrierte Terminal in der WebIDE, falls es noch nicht geöffnet ist (Terminal -> New Terminal).

Stellen Sie sicher, dass Sie sich im Verzeichnis ~/project befinden.

Wir verwenden die Datei my_function.py, die wir im vorherigen Schritt erstellt haben. Stellen Sie sicher, dass die Datei die hello-Funktion mit ihrem Docstring enthält.

def hello(name, greet="Hello"):
    '''\
hello(name)
hello(name, greet="Hello")

This function greets a person.
The 'name' parameter is the person to greet.
The optional 'greet' parameter is the greeting word, defaulting to "Hello".'''
    print(f'{greet} {name}!')

## Wir können die Zeile print(hello.__doc__) aus dem vorherigen Schritt entfernen
## oder beibehalten, sie beeinträchtigt den help()-Aufruf nicht.
## print(hello.__doc__)

Nun müssen wir diese Funktion in eine interaktive Python-Sitzung oder ein anderes Skript importieren, um help() verwenden zu können. Der Einfachheit halber verwenden wir die interaktive Sitzung.

Starten Sie die interaktive Python-Shell im Terminal:

python

Importieren Sie nun die hello-Funktion aus unserem my_function-Modul:

from my_function import hello

Wenn der Import erfolgreich ist, sehen Sie keine Ausgabe. Wenn ein Fehler auftritt, überprüfen Sie den Dateinamen und den Funktionsnamen.

Verwenden Sie nun die Funktion help() mit unserer importierten hello-Funktion:

help(hello)

Sie sehen die formatierte Docstring-Ausgabe, ähnlich der, die Sie für integrierte Funktionen gesehen haben:

Help on function hello in module my_function:

hello(name, greet='Hello')
    hello(name)
    hello(name,greet="Hello")

    This function greets a person.
    The 'name' parameter is the person to greet.
    The optional 'greet' parameter is the greeting word, defaulting to "Hello".

Drücken Sie q, um den Hilfe-Viewer zu verlassen.

Dies zeigt, wie help() verwendet werden kann, um die Dokumentation für Ihre eigenen Funktionen anzuzeigen und so Ihren Code für andere Benutzer zugänglicher und verständlicher zu machen.

Beenden Sie die interaktive Python-Shell:

exit()

Zusammenfassung

In diesem Lab haben wir uns mit Docstrings in Python und ihrer Bedeutung für die Code-Dokumentation beschäftigt. Wir haben untersucht, wie man mit der Funktion help() in der interaktiven Python-Shell auf Docstrings für integrierte Funktionen zugreift, die eine formatierte und detaillierte Ansicht des Zwecks und der Parameter der Funktion bietet.

Wir haben auch eine alternative Methode entdeckt, um direkt über das __doc__-Attribut eines Objekts auf Docstrings zuzugreifen. Dies ermöglicht den programmatischen Zugriff auf den rohen Docstring-String. Schließlich haben wir geübt, eigene Docstrings für benutzerdefinierte Funktionen mit dreifachen Anführungszeichen zu schreiben und gelernt, wie man diese benutzerdefinierten Docstrings mit der Funktion help() anzeigt, was zeigt, wie man eigenen Code effektiv für Klarheit und Benutzerfreundlichkeit dokumentiert.