CKTIS / Python
Funktions-Docstrings, `__doc__` und `__name__`
Lies die Dokumentation einer Funktion ohne Aufruf und erhalte beim Dekorieren ihren Namen und Docstring, damit Auditprotokolle und Berichte die richtige Funktion beschreiben.
Version: Python 3.12
Syntax
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."In Python 3.12 ist der Docstring einer Funktion ein Zeichenkettenliteral, das die erste Anweisung im Funktionsrumpf bildet. Leerzeilen und Kommentare sind keine Anweisungen und dürfen davor stehen. Ein #-Kommentar, ein späteres Zeichenkettenliteral oder ein f-String (auch ohne Ersetzungsfelder) setzt __doc__ nicht. Dreifache doppelte Anführungszeichen sind eine Konvention aus PEP 257, keine Syntaxvorgabe.
f.__doc__ liest die im Funktionsobjekt gespeicherte Dokumentation, ohne f aufzurufen. Fehlende Dokumentation ergibt None, nicht die leere Zeichenkette ''. Bei benutzerdefinierten Funktionen ist dieses Attribut beschreibbar. Verwende f.__doc__ für den unveränderten Wert im Bericht oder inspect.getdoc(f) zur Anzeige mit bereinigter Einrückung. Die CPython-Option -OO entfernt Docstrings; das Programmverhalten sollte daher nicht von ihnen abhängen.
f.__name__ ist ein eigenes Attribut: Es enthält den Namen der Funktion, nicht ihre Dokumentation. alias = f erzeugt eine weitere Referenz auf dasselbe Objekt, ohne es umzubenennen. Gibt ein Dekorator eine neue Wrapper-Funktion zurück, ohne Metadaten zu kopieren, erfasst das Audit den Namen und die Dokumentation des Wrappers. Setze @functools.wraps(f) an die Wrapper-Definition: Standardmäßig kopiert es unter anderem __name__ und __doc__ und setzt __wrapped__ auf die umschlossene Funktion.
Beispiele
from functools import wraps
def audit(func):
@wraps(func)
def wrapper(*args, **kwargs):
print(f"Audit: {wrapper.__name__}")
return func(*args, **kwargs)
return wrapper
@audit
def compute_net(gross, fee):
"""Return gross minus fee."""
return gross - fee
print(f"Documentation: {compute_net.__doc__!r}")
print(f"Net: {compute_net(120, fee=15)}")Ergebnis
Documentation: 'Return gross minus fee.' Audit: compute_net Net: 105
Der Bericht liest zuerst den Docstring, ohne `compute_net` aufzurufen. Danach protokolliert der Wrapper den erhaltenen Namen und leitet die Argumente weiter; die Berechnung ergibt `105`.
Zugehörige Lektionen
- Python · Lektion 10 · Fortgeschritten · Version: 5