CKTIS / Python
Dokumentacijski nizovi funkcija, `__doc__` i `__name__`
Pročitaj dokumentaciju funkcije bez pozivanja te pri dekoriranju očuvaj njezino ime i dokumentacijski niz kako bi revizijski zapisi i izvještaji opisivali pravu funkciju.
Verzija: Python 3.12
Sintaksa
def f():
"""Describe what the function does."""
...
f.__doc__
f.__name__
f.__doc__ = "Updated documentation."U Pythonu 3.12 dokumentacijski niz funkcije (docstring) jest literal znakovnog niza koji je prva naredba u tijelu funkcije. Prazni redci i komentari nisu naredbe pa mu mogu prethoditi. Ni komentar #, ni kasniji literal znakovnog niza, ni f-string (čak i bez zamjena) ne postavlja __doc__. Trostruki dvostruki navodnici konvencija su iz PEP-a 257, a ne sintaktički zahtjev.
f.__doc__ čita dokumentaciju spremljenu u objektu funkcije bez pozivanja f. Ako dokumentacija nedostaje, vrijednost je None, a ne prazan niz ''. Taj se atribut može mijenjati kod korisnički definiranih funkcija. Za neizmijenjenu vrijednost u izvještaju upotrijebi f.__doc__, a za prikaz dokumentacije s uređenim uvlakama inspect.getdoc(f). Opcija -OO u CPythonu uklanja dokumentacijske nizove, pa ponašanje programa ne bi smjelo ovisiti o njima.
f.__name__ zaseban je atribut: sadrži ime funkcije, a ne njezinu dokumentaciju. Dodjela alias = f stvara još jednu referencu na isti objekt bez promjene njegova imena. Ako dekorator vrati novu omotnu funkciju bez kopiranja metapodataka, revizija vidi ime i dokumentaciju omotača. Primijeni @functools.wraps(f) na definiciju omotača: prema zadanim postavkama kopira, među ostalim, __name__ i __doc__ te postavlja __wrapped__ tako da upućuje na omotanu funkciju.
Primjeri
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
Izvještaj prvo čita dokumentacijski niz bez pozivanja `compute_net`. Omotač zatim bilježi očuvano ime i prosljeđuje argumente; izračun vraća `105`.
Povezane lekcije
- Python · Lekcija 10 · Napredno · Verzija: 5