Znalostná bázaCentrum skúšok
SKSlovenčina
Vybrať jazyk13

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

Zdroje