CKTIS / Python
Dokumentační řetězce funkcí, `__doc__` a `__name__`
Přečtěte dokumentaci funkce bez jejího volání a při dekorování zachovejte její název i dokumentační řetězec, aby auditní záznamy a přehledy popisovaly správnou funkci.
Verze: Python 3.12
Syntaxe
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."V Pythonu 3.12 je dokumentační řetězec funkce neboli docstring řetězcový literál, který tvoří první příkaz v těle funkce. Prázdné řádky a komentáře nejsou příkazy, takže mu mohou předcházet. Komentář #, pozdější řetězcový literál ani f-string (i bez dosazování) nenastaví __doc__. Trojité dvojité uvozovky jsou konvencí PEP 257, nikoli požadavkem syntaxe.
f.__doc__ přečte dokumentaci uloženou v objektu funkce, aniž zavolá f. Pokud dokumentace chybí, hodnotou je None, nikoli prázdný řetězec ''. U uživatelsky definovaných funkcí lze tento atribut měnit. Pro nezměněnou hodnotu v přehledu použijte f.__doc__; k zobrazení dokumentace s upraveným odsazením použijte inspect.getdoc(f). Volba -OO v CPythonu dokumentační řetězce odstraňuje, proto na nich nestavte chování programu.
f.__name__ je samostatný atribut: obsahuje název funkce, ne její dokumentaci. Přiřazení alias = f vytvoří další odkaz na stejný objekt, aniž jej přejmenuje. Pokud dekorátor vrátí novou obalovou funkci bez zkopírování metadat, audit přečte název a dokumentaci obalu. Na definici obalu použijte @functools.wraps(f): ve výchozím nastavení kopíruje mimo jiné __name__ a __doc__ a nastaví __wrapped__ na obalenou funkci.
Příklady
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)}")Výsledek
Documentation: 'Return gross minus fee.' Audit: compute_net Net: 105
Přehled nejprve přečte dokumentační řetězec bez volání `compute_net`. Obalová funkce pak zaznamená zachovaný název a předá argumenty; výpočet vrátí `105`.
Související lekce
- Python · Lekce 10 · Pokročilá · Verze: 5