pydoc — Dokumentationserzeuger und Online-Hilfesystem¶
Quellcode: Lib/pydoc.py
Das Modul pydoc erzeugt automatisch Dokumentation aus Python-Modulen. Die Dokumentation kann als Textseiten auf der Konsole dargestellt, an einen Webbrowser ausgeliefert oder in HTML-Dateien gespeichert werden.
Bei Modulen, Klassen, Funktionen und Methoden wird die angezeigte Dokumentation aus dem Docstring (also dem Attribut __doc__) des Objekts und rekursiv aus dem seiner dokumentierbaren Member abgeleitet. Gibt es keinen Docstring, versucht pydoc, eine Beschreibung aus dem Block von Kommentarzeilen direkt über der Definition der Klasse, Funktion oder Methode in der Quelldatei oder am Anfang des Moduls zu bekommen (siehe inspect.getcomments()).
Die integrierte Funktion help() ruft im interaktiven Interpreter das Online-Hilfesystem auf, das pydoc verwendet, um seine Dokumentation als Text auf der Konsole zu erzeugen. Dieselbe Textdokumentation lässt sich auch außerhalb des Python-Interpreters ansehen, indem du pydoc an der Eingabeaufforderung des Betriebssystems als Skript ausführst. Führst du zum Beispiel
python -m pydoc sys
an einer Shell-Eingabeaufforderung aus, wird die Dokumentation zum Modul sys angezeigt, in einem Stil, der den Man-Pages ähnelt, die der Unix-Befehl man anzeigt. Das Argument für pydoc kann der Name einer Funktion, eines Moduls oder eines Pakets sein oder ein mit Punkten geschriebener Verweis auf eine Klasse, Methode oder Funktion innerhalb eines Moduls oder eines Moduls in einem Paket. Sieht das Argument für pydoc wie ein Pfad aus (es enthält also das Pfadtrennzeichen deines Betriebssystems, unter Unix etwa einen Schrägstrich) und bezeichnet eine vorhandene Python-Quelldatei, wird die Dokumentation für diese Datei erzeugt.
Bemerkung
Um Objekte und ihre Dokumentation zu finden, importiert pydoc das oder die zu dokumentierenden Module. Deshalb wird bei dieser Gelegenheit jeder Code auf Modulebene ausgeführt. Verwende eine Absicherung if __name__ == '__main__':, damit Code nur dann ausgeführt wird, wenn eine Datei als Skript aufgerufen und nicht bloß importiert wird.
Gibt pydoc Ausgabe auf der Konsole aus, versucht es, die Ausgabe seitenweise umzubrechen, damit sie leichter zu lesen ist. Ist eine der Umgebungsvariablen MANPAGER oder PAGER gesetzt, verwendet pydoc ihren Wert als Programm zum Blättern. Sind beide gesetzt, wird MANPAGER verwendet.
Gibst du vor dem Argument das Flag -w an, wird die HTML-Dokumentation in eine Datei im aktuellen Verzeichnis geschrieben, statt Text auf der Konsole anzuzeigen.
Gibst du vor dem Argument das Flag -k an, werden die Kurzbeschreibungszeilen aller verfügbaren Module nach dem als Argument angegebenen Schlüsselwort durchsucht, wiederum ähnlich wie beim Unix-Befehl man. Die Kurzbeschreibungszeile eines Moduls ist die erste Zeile seines Dokumentationsstrings.
Du kannst pydoc auch verwenden, um auf der lokalen Maschine einen HTTP-Server zu starten, der Dokumentation an Webbrowser ausliefert, die ihn besuchen. python -m pydoc -p 1234 startet einen HTTP-Server auf Port 1234, sodass du die Dokumentation in deinem bevorzugten Webbrowser unter http://localhost:1234/ durchsehen kannst. Gibst du 0 als Portnummer an, wird ein beliebiger unbenutzter Port gewählt.
Warnung
Der HTTP-Server von pydoc ist für die lokale Verwendung während der Entwicklung gedacht und für den Produktivbetrieb nicht geeignet.
python -m pydoc -n <hostname> startet den Server so, dass er auf dem angegebenen Hostnamen lauscht. Voreingestellt ist der Hostname „localhost“. Soll der Server aber von anderen Maschinen aus erreichbar sein, möchtest du vielleicht den Hostnamen ändern, auf den der Server antwortet. Während der Entwicklung ist das besonders nützlich, wenn du pydoc innerhalb eines Containers ausführen willst.
python -m pydoc -b startet den Server und öffnet außerdem einen Webbrowser mit einer Modulindexseite. Jede ausgelieferte Seite hat oben eine Navigationsleiste, über die du mit Get Hilfe zu einem einzelnen Eintrag bekommst, mit Search alle Module nach einem Schlüsselwort in ihrer Kurzbeschreibungszeile durchsuchst und zu den Seiten Module index, Topics und Keywords gelangst.
Erzeugt pydoc Dokumentation, verwendet es die aktuelle Umgebung und den aktuellen Pfad, um Module zu finden. pydoc spam aufzurufen dokumentiert also genau die Fassung des Moduls, die du bekämst, wenn du den Python-Interpreter startest und import spam eingibst.
Es wird angenommen, dass die Moduldokumentation der Kernmodule unter https://docs.python.org/X.Y/library/ liegt, wobei X und Y die Haupt- und Nebenversionsnummer des Python-Interpreters sind. Das lässt sich übergehen, indem die Umgebungsvariable PYTHONDOCS auf eine andere URL oder auf ein lokales Verzeichnis mit den Seiten des Bibliotheksreferenzhandbuchs gesetzt wird.
Geändert in Version 3.2: Die Option -b wurde hinzugefügt.
Geändert in Version 3.3: Die Befehlszeilenoption -g wurde entfernt.
Geändert in Version 3.4: pydoc verwendet jetzt inspect.signature() statt inspect.getfullargspec(), um Signaturinformationen aus aufrufbaren Objekten zu gewinnen.
Geändert in Version 3.7: Die Option -n wurde hinzugefügt.