Python Jiří Znamenáček Dekorátory 2011-04-28

Dekorátory obecně jsou funkce, které berou jako parametr funkci (a případně nějaké další doplňující parametry) a vrací tuto funkci zadaným způsobem upravenou, „odekorovanou“.

Čistě teoreticky může dekorátor funkci redukovat na libovolnou návratovou hodnotu, ale to by bylo velmi specifické použití.

Většinou se pro jejich zápis používá konstrukce @DEKORÁTOR. Jinými slovy konstrukce..

@dekorátor def moje_funkce(): BLOK

..je vlastně přehlednější náhrada za..

def moje_funkce(): BLOK moje_funkce = dekorátor(moje_funkce)

Funkce dekorátoru se v praxi snad nejčastěji projevuje tak, že návratové hodnoty z dekorované funkce jsou nějakým způsobem omezeny či změněny, proto by člověk mohl být v pokušení napsat dekorovací funkci jako operátor vracející tyto nějak upravené hodnoty. Jenže ve skutečnosti dekorátor dekorovanou funkci vlastně zcela nahrazuje, a proto musí být pochopitelně sám volatelným objektem! Jinak řečeno:

Vstupem dekorátoru je objekt dekorované funkce a výstupem objekt nějaké jiné funkce.

Kvůli tomu je konstrukce dekorátorů kapku složitější, než by člověk na první pohled mohl očekávat.

Zavedeme-li dekorátor..

def dekorátor(funkce): def _dekorátor(): print('START') return funkce() return _dekorátor

..pak volání následujícím způsobem odekorované funkce..

@dekorátor def moje_funkce(): print('moje funkce') Tedy rozepsaně: moje_funkce = dekorátor(moje_funkce)

..vrátí:

>>> moje_funkce() START moje funkce

Celé toto funguje právě proto, že funkce uvnitř funkcí si s sebou nesou celý aktuální (dynamický) kontext, jak jsme viděli už dříve na případě uzávěrů (closures).

Odekorovaná funkce se sice jmenuje stejně, ale pochopitelně je to už úplně jiná funkce:

>>> def dekorátor(funkce): ... def _dekorátor(): ... print('START') ... return funkce() ... return _dekorátor >>> def moje_funkce(): ... print('moje funkce') >>> moje_funkce <function moje_funkce at 0x000001E6B32DB0A0> >>> @dekorátor ... def moje_funkce(): ... print('moje funkce') >>> moje_funkce <function dekorátor.<locals>._dekorátor at 0x000001E6B32DB1C0>

Zpracování návratové hodnoty funkce dekorátorem nebo prostě nějaká další dodatečná činnost ještě po zavolání funkce vyžaduje následující úpravu:

def _dekorátor(): print('START') ret = funkce() print('END') return ret

Dekorovanou funkci je tedy třeba nejdříve vykonat (zavolat), návratovou hodnotu – ať už je jí cokoli – si uschovat pro pozdější použití, vykonat zbývající práci dekorátoru (což tedy může být a často právě bývá úprava návratové hodnoty) a teprve poté vrátit (případně upravenou) spočítanou hodnotu původní funkce.

Následující dekorátor při volání funkce vypíše její jméno a spočítá dobu jejího běhu. Všimněte si však především, že jeden dekorátor použijeme na vícero různých funkcí, aniž bychom změnili jejich výchozí chování, a přitom se dozvíme něco navíc:

Jak jsme viděli u atributu __name__ na předchozím slajdu, funkce je interně také „jenom“ nějaký objekt se složitější strukturou. A jako takovému jí můžeme třeba i nastavovat vlastní atributy:

def dekorátor(funkce): def _dekorátor(): return funkce() _dekorátor.atribut = "Ahoj!" return _dekorátor @dekorátor def moje_funkce(): print( 'moje funkce' ) >>> moje_funkce() moje funkce >>> moje_funkce.atribut 'Ahoj!' >>> moje_funkce.__dict__ {'atribut': 'Ahoj!'} A to pochopitelně nejen v rámci dekorátorů jako zde.

Bude-li dekorovaná funkce očekávat nějaké vstupní parametry, syntaxe se nepatrně změní o vnitřní parametr:

>>> def dekorátor(funkce): ... def _dekorátor(x): ... print('START') ... ret = funkce(x) ... return ret ... return _dekorátor ... ... @dekorátor ... def moje_funkce(s): ... print( 'Ahoj, ', s, '!', sep='' ) >>> moje_funkce('Láďo') START Ahoj, Láďo! Zatím se nic nezměnilo, vracíme stále stejnou funkci, která prostě jen navíc očekává vstupní parametr: moje_funkce = dekorátor(moje_funkce)

Ukažme si rozumnější příklad – dekorátor, který při volání funkce vypíše všechny její parametry a navíc jeden (debug) nastaví, čímž i změní její chování:

>>> def decorator(target): ... ... def wrapper(*args, **kwargs): ... # Edit the keyword arguments ... # -- here, enable debug mode no matter what ... kwargs.update({'debug': True}) ... print( ... 'Calling function "%s" with arguments %s and keyword arguments %s' ... % (target.__name__, args, kwargs) ... ) ... return target(*args, **kwargs) ... ... wrapper.attribute = 1 ... return wrapper >>> @decorator ... def target(a, b, debug=False): ... if debug: print('[Debug] I am the target function') ... return a + b # volání funkce je nyní odekorované, tzn. 'debug' je nastaven na True.. >>> target(1,2) Calling function "target" with arguments (1, 2) and keyword arguments {'debug': True} [Debug] I am the target function 3 # ..a funkci přibyl nový atribut 'attribute' >>> target.attribute 1 Podle http://www.siafoo.net/article/68 . (Zalámáno pro lepší čitelnost.)

Začněme příkladem. Při zavedení následujícího dekorátoru..

def omez_hodnoty(maximum): # funkce přebírající parametry dekorátoru def _omez_hodnoty(funkce): # funkce přebírající dekorovanou funkci def __omez_hodnoty(xs): # konečná návratová funkce ret = funkce( [x for x in xs if x <= maximum] ) return ret return __omez_hodnoty return _omez_hodnoty

..můžeme provést odekorování např. takto:

@omez_hodnoty(9) def zpracuj_hodnoty(xs): return [x**2 for x in xs] Tohle už je zajímavější: zpracuj_hodnoty = omez_hodnoty(9)(zpracuj_hodnoty) Tedy kód omez_hodnoty(9) vrací vlastně funkci _omez_hodnoty, které jako parametr předhodíme původní funkci, to jest _omez_hodnoty(zpracuj_hodnoty), čímž dostaneme odkaz na funkci __omez_hodnoty, která očekává vstupní parametr xs. A ta pak už volá úplně původní funkci s parametry omezenými podle vstupu dekorátoru.

Volání funkce zpracuj_hodnoty() pak vrátí:

>>> test = zpracuj_hodnoty( [1, 3, 11, 4, 7, 14, 5] ) >>> print(test) [1, 9, 16, 49, 25]

Potřebujeme-li předat parametry nikoli dekorované funkci, ale dekorátoru samotnému, konstrukce se zesložitila o další mezifunkci, která tyto parametry přebírá a posílá dál. Sice už to vypadá kapku nepřehledně, ale v podstatě by se dalo říci, že v tomto případě prostě:

Musíme vyrobit funkci, která z jí zadaných parametrů vyrobí příslušný dekorátor.

Dekorátor sám je tedy stále funkce vrácená z funkce, ale tentokrát je sám navíc vyroben (a tedy vrácen) další funkcí. Která prostě jenom přebírá příslušné parametry, které použije k jeho tvorbě:

původní dekorátor → funkce vyrábějící dekorátor 


def _omez_hodnoty(funkce):
    def __omez_hodnoty(xs):
        ret = funkce(x for x in xs if x <= mx)
        return ret
    return __omez_hodnoty
        
def omez_hodnoty(mx):

    def _omez_hodnoty(funkce):
        def __omez_hodnoty(xs):
            ret = funkce(x for x in xs if x <= mx)
            return ret
        return __omez_hodnoty
    return _omez_hodnoty
Hodnotu mx pro omezení vstupů musí dekorátor nalevo odněkud získat. A obalení další funkcí (která tento dekorátor tedy vlastně vyrobí) je právě ten kontext, odkud se tato hodnota objeví.

Stejně jako funkce můžeme zanořovat do sebe, @dekorátory můžeme přidávat před definici funkce. Aplikují se pak v uvedeném pořadí:

Dává-li to smysl, můžete samozřejmě za sebou řetězit stejný dekorátor ^_~

Pro komplikovanější řetězení dekorátorů pak volání vypadá tak, jak jsme už viděli u předávání parametrů dekorátoru. Například (bez invence přímo podle dokumentace)..

@f1(arg) @f2 def func(): pass

je ekvivalentní tomutu kódu:

func(): pass func = f1(arg)(f2(func))

Volání komplikovanějších případů je snad z této ukázky a hlavně předchozího příkladu již celkem zřejmé: Parametrem dekorátoru je vždy funkce, tudíž čeká-li sám dekorátor nějaké řídicí parametry, musí vrátit funkci, jejímž parametrem teprve bude funkce následující.

V tomto příkladu tedy volání f1(arg) vrátí funkci, která teprve slouží jako vlastní dekorátor funkce f2 (která je zase vlastním dekorátorem původní funkce func).

Python sám nabízí několik připravených dekorátorů. Asi nejviditelnější jsou dekorátory @classmethod a @staticmethod u tříd, které zajišťují, že příslušné metody třídy se nechovají jako instanční, ale jako třídní nebo statické.

Odhaduji na kontrolu a případnou eliminaci či nahrazení implicitního prvního parametru.

Z předchozích příkladů je vidět, že častého použití by se mohly dekorátory dočkat např. u logovacích nebo debugovacích funkcí:

Zcela typicky se s dekorátory setkáte v různých webových frameworcích, kde slouží k zajištění vybraných podmínek pro vstupní nebo návratové hodnoty funkcí. Typické příklady:

Kupříkladu v kontextu anotací funkcí je možno dekorátory použít pro tak nepythoní věc jako je ověřování vstupních a výstupních typů.

Když se podíváte na seznam vestavěných funkcí Python'u (třeba přes dir(__builtins__)), zjistíte kupříkladu, že známé třídní dekorátory @classmethod a @staticmethod jsou prostě jenom funkce v globálním jmenném prostoru. Další dekorátory se schovávají v různých modulech, např. @contextlib.contextmanager. Vzhledem k tomu, že dekorátory jsou vlastně „jenom“ funkce, není se moc čemu divit.

Pokud by vás ale zajímal nějaký ultimativnější přehled dekorátorů (převážně externích), podívejte se na oficiální Python Decorator Library. Najdete tam spoustu zajímavého, mimo jiné i podstatně rozumnější dekorátory pro deskriptory, než je oficiální verze.

Při použití dekorátorů je třeba pamatovat na to, že „obalovací“ mezifunkce zcela nahradí dekorovanou funkci. Což mimo jiné znamená, že pokud budeme dekorované funkci pomocí introspekce klást nějaké otázky o její identitě, dostaneme úplně jiné odpovědi – budou se totiž týkat identity dekorátoru!

Jinými slovy – pokud se nebudete (hodně) snažit, použití dekorátoru zcela změní tzv. otisk funkce (call signature), tj. přibližně jméno funkce a seznam jejích argumentů.

Přepsat úplně celý otisk je dosti komplikované (pro jeho definici viz PEP 362). Ale pro začátek se můžete podívat třeba na kopírování dokumentačního řetězce __doc__ nebo jména funkce __name__. A možná postačí dekorátor (sic :-) functools.wraps: from functools import wraps def dekorátor(funkce): @wraps(funkce) def _dekorátor(*args, **kwargs): ... return _dekorátor

Kromě běžného zápisu, který jsme celou dobu používali..

def dekorátor(funkce): def _dekorátor(*args, **kwargs): ... return _dekorátor

..můžete tu vnitřní funkci klidně zapsat i bokem..

def _dekorátor(*args, **kwargs): ... def dekorátor(funkce): return _dekorátor

..ale je vidět, že to je spíš pro zmatení nepřítele než k běžnému užitku.

Jelikož generátory se v Python'u zavádějí pomocí funkcí, dají se také odekorovat. Mezi generátory a funkcemi je však několik významných rozdílů, především:

Z toho vyplývá, že ne všechno, co jsme si ukázali na předchozích slajdech půjde aplikovat úplně přímočaře i pro generátory – zatímco dekorátor funkce je sám funkcí, dekorátor generátoru musí být sám generátorem.

Především tedy jedno konkrétní volání dekorované funkce se musí nahradit nějakou složitější konstrukcí, která generátor projde yield po yieldu, až ho celý vyčerpá.