Lidsky řečeno
Lékař ordinuje pořád stejně. Před jeho dveře ale posadíš sestru: zapíše příchozího, změří mu tlak a po vyšetření vydá recept. Lékař se kvůli tomu nemusel nic přeučit a pacienti pořád chodí na stejnou adresu. Dekorátor je taková sestra před funkcí. Přidá něco před voláním a po něm a samotnou funkci nechá být.
Funkce v obalu
Dekorátor stojí na dvou věcech z modulu Funkce: funkci můžeš předat jako hodnotu a vnitřní funkce si pamatuje proměnné z té vnější (closure). Dekorátor je funkce, která dostane funkci a vrátí jinou funkci.
def hlasite(funkce):
def obal():
vysledek = funkce()
return vysledek.upper() + "!"
return obal
def pozdrav():
return "ahoj"
pozdrav = hlasite(pozdrav)
print(pozdrav())
AHOJ!
Jméno pozdrav teď ukazuje na obal a ten si v closure drží původní funkci. Řádek pozdrav = hlasite(pozdrav) je tak častý, že pro něj existuje zkratka se zavináčem. Nic jiného @ nedělá.
def hlasite(funkce):
def obal():
return funkce().upper() + "!"
return obal
@hlasite
def pozdrav():
return "ahoj"
@hlasite
def rozlouceni():
return "měj se"
print(pozdrav())
print(rozlouceni())
AHOJ! MĚJ SE!
Obal pro jakoukoli funkci
Náš obal nebere žádné argumenty, takže by rozbil každou funkci, která nějaké má. Univerzální obal přijme cokoli přes *args, **kwargs, předá to dál a vrátí výsledek.
def loguj(funkce):
def obal(*args, **kwargs):
print(f"volám {funkce.__name__}, args={args}, kwargs={kwargs}")
vysledek = funkce(*args, **kwargs)
print(f"{funkce.__name__} vrátila {vysledek!r}")
return vysledek
return obal
@loguj
def secti(a, b=0):
return a + b
celkem = secti(2, b=3)
print("celkem:", celkem)
volám secti, args=(2,), kwargs={'b': 3}
secti vrátila 5
celkem: 5Stejný vzor měří čas, kontroluje oprávnění nebo zachytává chyby. Tady je měření. Výsledné číslo se pokaždé liší.
import time
def stopuj(funkce):
def obal(*args, **kwargs):
start = time.perf_counter()
try:
return funkce(*args, **kwargs)
finally:
ms = (time.perf_counter() - start) * 1000
print(f"{funkce.__name__}: {ms:.2f} ms")
return obal
@stopuj
def soucet_ctvercu(n):
return sum(i * i for i in range(n))
print(soucet_ctvercu(100_000))
Díky finally se čas vypíše i tehdy, když funkce skončí výjimkou.
Co přesně znamená @d nad def f(): ...?
Dekorátor se zavolá jednou, hned při vytvoření funkce. Při dalších voláních běží to, co dekorátor vrátil.
Výsledek velkými písmeny
Napiš dekorátor velka. Ozdobená funkce přijme stejné argumenty jako původní a vrátí její textový výsledek velkými písmeny.
def velka(funkce):
# doplň
return funkce
functools.wraps: neztrať identitu
Obal má jednu nepříjemnou vlastnost. Navenek se místo tvé funkce objeví funkce jménem obal, bez dokumentace. To rozbíjí logy, nápovědu i nástroje. Opravuje to dekorátor wraps, který na obal přenese údaje z původní funkce.
from functools import wraps
def bez_wraps(funkce):
def obal(*args, **kwargs):
return funkce(*args, **kwargs)
return obal
def s_wraps(funkce):
@wraps(funkce)
def obal(*args, **kwargs):
return funkce(*args, **kwargs)
return obal
@bez_wraps
def prvni():
"""Dokumentace první funkce."""
@s_wraps
def druha():
"""Dokumentace druhé funkce."""
print(prvni.__name__, "|", prvni.__doc__)
print(druha.__name__, "|", druha.__doc__)
obal | None druha | Dokumentace druhé funkce.
Ber to jako povinnost: @wraps patří do každého dekorátoru. Stojí to jeden řádek.
Počítadlo volání
Napiš dekorátor pocitej. Ozdobená funkce má atribut volani, který začíná na 0 a při každém volání vzroste o 1. Každá funkce má vlastní počítadlo. Výsledek a jméno původní funkce musí zůstat zachované.
def pocitej(funkce):
# doplň
return funkce
Dekorátor s parametry
Co když chceš psát @opakuj(3)? Výraz za zavináčem se nejdřív vyhodnotí a jeho výsledek musí být dekorátor. Přibude tedy jedna úroveň: funkce, která dekorátor vyrobí.
opakuj(3) vrátí dekorator (pamatuje si kolikrat)
dekorator(funkce) vrátí obal (pamatuje si funkce)
obal(...) běží při každém volánífrom functools import wraps
def opakuj(kolikrat):
def dekorator(funkce):
@wraps(funkce)
def obal(*args, **kwargs):
return [funkce(*args, **kwargs) for _ in range(kolikrat)]
return obal
return dekorator
@opakuj(3)
def pozdrav(jmeno):
return f"Ahoj, {jmeno}"
print(pozdrav("Eva"))
['Ahoj, Eva', 'Ahoj, Eva', 'Ahoj, Eva']
Zkus to znovu
Napiš dekorátor zkus_znovu(pokusy, vyjimka=Exception). Když funkce vyhodí výjimku typu vyjimka, zavolá se znovu, celkem nejvýš tolikrát, kolik říká pokusy. Při úspěchu vrátí výsledek. Když selže i poslední pokus, výjimka se pustí ven. Jiné typy výjimek se neopakují a projdou ven hned.
def zkus_znovu(pokusy, vyjimka=Exception):
def dekorator(funkce):
# doplň
return funkce
return dekorator
Kdy co běží a v jakém pořadí
Dekorátory můžeš vrstvit. Vyhodnocují se shora dolů, ale aplikují zdola nahoru: nejblíž funkci sedí ten spodní. A všechno se to děje při definici, ještě než funkci kdokoli zavolá.
from functools import wraps
def znacka(nazev):
print("vyhodnocuji", nazev)
def dekorator(funkce):
print("aplikuji", nazev)
@wraps(funkce)
def obal():
return f"<{nazev}>{funkce()}</{nazev}>"
return obal
return dekorator
@znacka("b")
@znacka("i")
def text():
return "ahoj"
print("teď teprve volám")
print(text())
vyhodnocuji b vyhodnocuji i aplikuji i aplikuji b teď teprve volám <b><i>ahoj</i></b>
Protože dekorátor běží při definici, nemusí funkci vůbec obalovat. Může si ji jen někam zapsat a vrátit beze změny. Takhle fungují registrace v mnoha frameworcích, například cesty ve webovém API.
PRIKAZY = {}
def prikaz(nazev):
def dekorator(funkce):
PRIKAZY[nazev] = funkce
return funkce
return dekorator
@prikaz("ahoj")
def pozdrav():
return "Nazdar!"
@prikaz("verze")
def verze():
return "1.0"
print(sorted(PRIKAZY))
print(PRIKAZY["verze"]())
['ahoj', 'verze'] 1.0
Hotových dekorátorů máš v Pythonu spoustu. @property, @classmethod a @staticmethod už znáš z objektů, @dataclass je příklad dekorátoru třídy. Velmi užitečný je functools.cache, který si pamatuje výsledky podle argumentů.
from functools import cache
@cache
def fibonacci(n):
if n < 2:
return n
return fibonacci(n - 1) + fibonacci(n - 2)
print(fibonacci(80))
print(fibonacci.cache_info())
23416728348467685 CacheInfo(hits=78, misses=81, maxsize=None, currsize=81)
Bez cache by tohle volání znamenalo desítky biliard rekurzivních kroků. S ní se každá hodnota spočítá jednou.
Co vrátí f() pro tento kód? @a je nad @b a def f(): return "x", přičemž a výsledek obalí do [...] a b do (...).
Spodní dekorátor b sedí nejblíž funkci, takže se jeho závorky přidají první. a je obal na povrchu a přidá své jako poslední. Platí f = a(b(f)).
Pod kapotou · wraps a __wrapped__
wraps je zkratka pro update_wrapper. Kopíruje __module__, __name__, __qualname__, __doc__, __annotations__ a od 3.12 i __type_params__, aktualizuje __dict__ a nastaví __wrapped__, odkaz na původní funkci. inspect.signature po něm jde, takže nápověda a nástroje vidí skutečné parametry.
import inspect
from functools import wraps
def prihlaseny(funkce):
@wraps(funkce)
def obal(*args, **kwargs):
raise PermissionError("nejdřív se přihlas")
return obal
@prihlaseny
def smaz_ucet(id_uctu: int, navzdy: bool = False):
return f"smazáno {id_uctu}"
print(inspect.signature(smaz_ucet))
print(smaz_ucet.__wrapped__(7))
print(inspect.unwrap(smaz_ucet).__name__)
(id_uctu: int, navzdy: bool = False) smazáno 7 smaz_ucet
Pro testy je __wrapped__ požehnání, pro bezpečnost připomínka: dekorátor není sandbox. Kdo se k objektu dostane, ochranu obejde. Přes @wraps se také kopíruje obsah __dict__, takže atributy z vnitřního dekorátoru se objeví i na vnějším obalu, kde už ale nemusejí znamenat totéž.
Pod kapotou · dekorátor jako třída a metody
Obyčejná funkce je deskriptor, a proto se při přístupu přes instanci naváže a doplní self. Objekt s __call__ tohle sám neumí a na metodě selže. Oprava je __get__.
import types
from functools import update_wrapper
class Pocitadlo:
def __init__(self, funkce):
update_wrapper(self, funkce)
self.funkce = funkce
self.volani = 0
def __call__(self, *args, **kwargs):
self.volani += 1
return self.funkce(*args, **kwargs)
class Opravene(Pocitadlo):
def __get__(self, instance, owner=None):
if instance is None:
return self
return types.MethodType(self, instance)
class Kosik:
@Pocitadlo
def spatne(self):
return "ok"
@Opravene
def dobre(self):
return "ok"
kosik = Kosik()
try:
kosik.spatne()
except TypeError as chyba:
print("TypeError:", chyba)
print(kosik.dobre(), Kosik.dobre.volani)
TypeError: Kosik.spatne() missing 1 required positional argument: 'self' ok 1
Všimni si, že volani je tady společné pro všechny instance. Stejná věc kouše lru_cache na metodě: self je součástí klíče, takže cache drží instance naživu až do vypršení záznamu (pravidlo B019 v Ruffu). Pro hodnotu vázanou na objekt je lepší cached_property.
Pod kapotou · cache a typy
lru_cache skládá klíč ze zápisu volání, ne z jeho významu, takže f(1) a f(a=1) jsou dva záznamy. V ukázce dole se s f(1) nepotká ani f(1.0), přestože 1 == 1.0: CPython má pro jediný argument typu int nebo str zkratku a klíčem je přímo hodnota, jinak n-tice. Na shodu mezi typy proto nespoléhej a když je chceš rozlišit zaručeně, nastav typed=True. Argumenty musí být hashovatelné. Vrácený objekt se sdílí, takže když volající změní vrácený seznam, změní ho všem. Cache je vláknově bezpečná v tom smyslu, že se nerozbije, ale funkce se při souběhu může zavolat víckrát.
Správné typování dává ParamSpec (PEP 612), v zápisu z 3.12 (PEP 695) je to krátké. Typová kontrola pak u ozdobené funkce vidí původní parametry.
from collections.abc import Callable
from functools import lru_cache, wraps
def loguj[**P, R](funkce: Callable[P, R]) -> Callable[P, R]:
@wraps(funkce)
def obal(*args: P.args, **kwargs: P.kwargs) -> R:
print("volám", funkce.__name__)
return funkce(*args, **kwargs)
return obal
@loguj
def secti(a: int, b: int) -> int:
return a + b
print(secti(1, 2))
@lru_cache
def f(a):
return a * 2
f(1)
f(a=1)
f(1.0)
print(f.cache_info())
volám secti 3 CacheInfo(hits=0, misses=3, maxsize=128, currsize=3)
Synchronní obal nad async def funkcí jen vrátí nespuštěnou korutinu, takže měření času nebo try kolem ní nic nezachytí. Obal musí být také async a výsledek si počkat přes await, viz lekce asyncio.
Vyzkoušej si: Pořadí dekorátorů
Skládej a přeskládávej dekorátory na funkci a sleduj, v jakém pořadí se při volání spustí.