Baza znanjaIzpitno središče
SLSlovenščina
Izberi jezik13

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

Viri