Baza znanjaCentar za ispite
HRHrvatski
Odaberi jezik13

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

Izvori