CKTIS / Python
Dokumentačné reťazce funkcií, `__doc__` a `__name__`
Prečítajte dokumentáciu funkcie bez jej volania a pri dekorovaní zachovajte jej názov aj dokumentačný reťazec, aby auditné záznamy a prehľady opisovali správnu funkciu.
Verzia: Python 3.12
Syntax
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."V Pythone 3.12 je dokumentačný reťazec funkcie, čiže docstring, reťazcový literál, ktorý tvorí prvý príkaz v tele funkcie. Prázdne riadky a komentáre nie sú príkazy, preto mu môžu predchádzať. Komentár #, neskorší reťazcový literál ani f-string (aj bez dosadzovania) nenastavia __doc__. Trojité dvojité úvodzovky sú konvenciou PEP 257, nie požiadavkou syntaxe.
f.__doc__ prečíta dokumentáciu uloženú v objekte funkcie bez volania f. Ak dokumentácia chýba, hodnotou je None, nie prázdny reťazec ''. Pri funkciách definovaných používateľom možno tento atribút meniť. Na uvedenie nezmenenej hodnoty v prehľade použite f.__doc__; na zobrazenie dokumentácie s upraveným odsadením použite inspect.getdoc(f). Voľba -OO v CPythone dokumentačné reťazce odstraňuje, preto od nich nesmie závisieť správanie programu.
f.__name__ je samostatný atribút: obsahuje názov funkcie, nie jej dokumentáciu. Priradenie alias = f vytvorí ďalší odkaz na ten istý objekt bez premenovania. Ak dekorátor vráti novú obaľovaciu funkciu bez skopírovania metadát, audit prečíta názov a dokumentáciu obalu. Na definíciu obaľovacej funkcie použite @functools.wraps(f): predvolene kopíruje okrem iného __name__ a __doc__ a nastaví __wrapped__ tak, aby odkazoval na obalenú funkciu.
Prí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ýsledok
Documentation: 'Return gross minus fee.' Audit: compute_net Net: 105
Prehľad najprv prečíta dokumentačný reťazec bez volania `compute_net`. Obaľovacia funkcia potom zaznamená zachovaný názov a odovzdá argumenty; výpočet vráti `105`.
Súvisiace lekcie
- Python · Lekcia 10 · Pokročilá · Verzia: 5