Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / Python

Dokumentační řetězce funkcí, `__doc__` a `__name__`

Přečtěte dokumentaci funkce bez jejího volání a při dekorování zachovejte její název i dokumentační řetězec, aby auditní záznamy a přehledy popisovaly správnou funkci.

Verze: Python 3.12

Syntaxe

def f():
    """Describe what the function does."""
    ...

f.__doc__
f.__name__
f.__doc__ = "Updated documentation."

V Pythonu 3.12 je dokumentační řetězec funkce neboli docstring řetězcový literál, který tvoří první příkaz v těle funkce. Prázdné řádky a komentáře nejsou příkazy, takže mu mohou předcházet. Komentář #, pozdější řetězcový literál ani f-string (i bez dosazování) nenastaví __doc__. Trojité dvojité uvozovky jsou konvencí PEP 257, nikoli požadavkem syntaxe.

f.__doc__ přečte dokumentaci uloženou v objektu funkce, aniž zavolá f. Pokud dokumentace chybí, hodnotou je None, nikoli prázdný řetězec ''. U uživatelsky definovaných funkcí lze tento atribut měnit. Pro nezměněnou hodnotu v přehledu použijte f.__doc__; k zobrazení dokumentace s upraveným odsazením použijte inspect.getdoc(f). Volba -OO v CPythonu dokumentační řetězce odstraňuje, proto na nich nestavte chování programu.

f.__name__ je samostatný atribut: obsahuje název funkce, ne její dokumentaci. Přiřazení alias = f vytvoří další odkaz na stejný objekt, aniž jej přejmenuje. Pokud dekorátor vrátí novou obalovou funkci bez zkopírování metadat, audit přečte název a dokumentaci obalu. Na definici obalu použijte @functools.wraps(f): ve výchozím nastavení kopíruje mimo jiné __name__ a __doc__ a nastaví __wrapped__ na obalenou funkci.

Pří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ýsledek

Documentation: 'Return gross minus fee.'
Audit: compute_net
Net: 105

Přehled nejprve přečte dokumentační řetězec bez volání `compute_net`. Obalová funkce pak zaznamená zachovaný název a předá argumenty; výpočet vrátí `105`.

Související lekce

  • Python · Lekce 10 · Pokročilá · Verze: 5

Zdroje