CKTIS / Python
Dokumentacijski nizi funkcij, `__doc__` in `__name__`
Preberi dokumentacijo funkcije brez klica ter pri dekoriranju ohrani njeno ime in dokumentacijski niz, da bodo revizijski zapisi in poročila opisovali pravo funkcijo.
Različica: Python 3.12
Sintaksa
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."V Pythonu 3.12 je dokumentacijski niz funkcije (docstring) nizovni literal, ki je prvi stavek v telesu funkcije. Prazne vrstice in komentarji niso stavki, zato so lahko pred njim. Komentar #, poznejši nizovni literal ali f-niz (tudi brez nadomestnih polj) ne nastavi __doc__. Trojni dvojni narekovaji so dogovor iz PEP 257 in ne slovnična zahteva.
f.__doc__ prebere dokumentacijo, shranjeno v objektu funkcije, ne da bi poklical f. Če dokumentacije ni, je vrednost None, ne prazen niz ''. Pri uporabniško definiranih funkcijah je ta atribut mogoče spremeniti. Za nespremenjeno vrednost v poročilu uporabi f.__doc__, za prikaz dokumentacije z urejenimi zamiki pa inspect.getdoc(f). Možnost -OO v CPythonu odstrani dokumentacijske nize, zato naj obnašanje programa ne bo odvisno od njih.
f.__name__ je ločen atribut: vsebuje ime funkcije, ne njene dokumentacije. alias = f ustvari nov sklic na isti objekt, ne da bi ga preimenoval. Če dekorator vrne novo ovojno funkcijo brez kopiranja metapodatkov, revizija vidi ime in dokumentacijo ovoja. Pri definiciji ovoja uporabi @functools.wraps(f): privzeto med drugim kopira __name__ in __doc__ ter nastavi __wrapped__ tako, da kaže na ovito funkcijo.
Primeri
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)}")Rezultat
Documentation: 'Return gross minus fee.' Audit: compute_net Net: 105
Poročilo najprej prebere dokumentacijski niz brez klica `compute_net`. Ovoj nato zabeleži ohranjeno ime in posreduje argumente; izračun vrne `105`.
Povezane lekcije
- Python · Lekcija 10 · Napredna · Različica: 5