Tekst źródłowy strony TI/Dekoratory


Dekoratory są w miarę ezoteryczną cechą Pythona — w przeciwieństwie do funkcji, klas czy iteratorów
nie są powszechną cechą języków programowania. Niemniej, warto je omówić mimo wszystko, gdyż są niezwykle
eleganckie i użyteczne.

Krótko mówiąc, dekorator to obiekt (np. funkcja), który można wywołać przekazując mu jako argument dekorowany obiekt. Tym dekorowanym obiektem może być funkcja lub klasa. Wartość zwrócona przez to wywołanie zostaje użyta zamiast dekorowanego obiektu.

== Składnia ==

Dekoratora używa się wstawiając linijkę zaczynającą się od @ przed definicją dekorowanego obiektu (klasy czy funkcji).

Popatrzmy na przykład:
<source lang="python">
>>> def ustaw_atrybut_xxx(funkcja):  # definicja naszego dekoratora
...     funkcja.xxx = True
...     return funkcja
>>> @ustaw_atrybut_xxx               # wywołanie dekoratora
... def f():                         # dekorowany obiekt
...     print "ciao"
>>> f()                              # wywołanie obiektu zwróconego przez dekorator
ciao
>>> f.xxx                            # dodatkowy atrybut ustawiony przez dekorator
True
</source>

Definicja funkcji (zaczynająca się od <tt>def</tt>) tworzy funkcję, czyli obiekt typu <tt>function</tt>).
Ten obiekt jest przepuszczany przez funkcję <tt>ustaw_atrybut_xxx</tt>, która dodaje dodatkowe pole.
W rezultacie zastosowanie dekoratora powoduje, że pod nazwą <tt>f</tt> zostaje zachowana oryginalna funkcja,
ale z dodatkowym atrybutem.

Składnia wywołania dekoratorów jest pomyślana tak, by trudno było przeoczyć fakt, że definiowany obiekt został dekorowany. Niemniej, zanim pojawiła się składnia z <tt>@</tt>, możliwe było użycie dekoratorów poprzez jawne wywołanie:
<source lang="python">
>>> def f():
...     print "ciao"
>>> f = ustaw_atrybut_xxx(f)   # równoważne użyciu @ustaw_atrybut_xxx w poprzednim przykładzie
>>> f()
ciao
>>> f.xxx
True
</source>

Ten przykład pokazuje też, co dokładnie powoduje wstawienie dekoratora — zachowanie pod nazwą definiowanej funkcji wartości zwracanej przez wywołanie dekoratora z oryginalną funkcja jako argumentem.

== Klasyczne zastosowanie dekoratorów: metody statyczne i klasowe ==
Funkcje zdefiniowane w klasie tworzą metody. Ich pierwszy argument to zawsze <tt>self</tt>, magiczny parametr
za który Python podstawia obiekt na którym wywoływana jest metoda. Niemniej, czasami wygodnie jest zdefiniować
w klasie funkcję, którą można wywołać bez dostępu do instancji. Aby mieć taką możliwość, definiuje się metodę
klasową (używając dekoratora <tt>classmethod</tt>) lub statyczną (używając dekoratora <tt>staticmethod</tt>).
Różnica między nimi jest taka, że metoda klasowa ma pierwszy magiczny parametr tak samo jak zwykłe metody, tylko że Python wstawia za niego samą klasę, a nie jedną z jej instancji. Metoda statyczna zachowuje się jak zwykła funkcja,
i lista argumentów jest przekazywana bez zmian.

<source lang="python">
>>> class T(object):
...     def a(self, x):
...         print self, x
...
...     @classmethod
...     def b(cls, x):
...         print cls, x
...
...     @staticmethod:
...     def c(x):
...         print x
>>> t = T()
>>> t.a(1)
<__main__.T object at ...> 1
>>> t.b(2)
<class '__main__.Test'> 2
>>> t.c(3)
3
>>> # nie możemy wywołać T.a()
>>> T.b(4)
<class '__main__.Test'> 4
>>> T.c(5)
5

</source>

Istotna różnica między metodą <tt>a</tt> i metodami <tt>b</tt> oraz <tt>c</tt> jest to, że te drugie można wywołać
poprzez klasę, bez tworzenia instancji.

Nazwy pierwszego parametru metod <tt>a</tt> i <tt>b</tt>, czyli <tt>self</tt> i <tt>cls</tt>
powinny być właśnie takie. Użycie nazwy <tt>self</tt> dla parametru nie będącego pierwszym parametrem
zwykłej metody prowadzi do konfuzji osoby czytającej kod. Podobnie nazwanie takiego parametru jakkolwiek inaczej jest złamaniem reguł stylu. W przypadku parametru <tt>cls</tt> reguły nie są aż takie ścisłe, gdyż czasem nazywa się go <tt>klass</tt>, niemniej użycie słowa nie kojarzącego się od razu z klasą jest również błędem.

== Dekoratory definiowane jako funkcje czy klasy ==
Zdefiniowany na początku dekorator <tt>ustaw_atrybut_xxx</tt>, mimo że wystarczający do zademonstrowania składni,
raczej nie nie ma zastosowania praktycznego. Zanim przejdziemy do definiowania użytecznych dekoratorów,
omówmy w jaki sposób można to zrobić. Na wstępnie zaznaczyliśmy, że dekorator to obiekt który można wywołać jak funkcję. Jako funkcja był też napisany nasz przykładowy dekorator <tt>ustaw_atrybut_xxx</tt>. Inny sposób na otrzymanie wywoływalnych obiektów to zdefiniowanie klasy z metodą <tt>__call__</tt>. Przewaga klasowego podejścia do dekoratorów nad funkcyjnym jest taka, że są one w ten sposób czytelniejsze. Definiowanie dekoratorów przy użyciu funkcji wymaga zastosowania dwu- lub trzykrotnie zagnieżdzonych funkcji. Przy definicji przez klasę analogiczna definicja zawiera po prostu dwie lub trzy metody. Dlatego też, w niniejszym omówieniu, dalsze dekoratory będziemy definiować jako klasy.

Na początek przypomnijmy, jak działa dodanie specjalnej metody <tt>__call__</tt>. Mianowicie, jeśli mamy obiekt, którego klasa definiuje <tt>__call__</tt>, to można go użyć jak funkcji i wywoła (dostawiając listę argumentów w nawiasach okrągłych).

<source lang="python">
>>> class T(object):
...     def __init__(self):
...         print "w __init__"
...     def __call__(self):
...         print "w __call__"
>>> t = T()
w __init__
>>> t()
w __call__
</source>

Przypomnijmy też, jak działa dodanie metody <tt>__init__</tt>. Mianowicie, zostaje ona wywołana automatycznie po tym, jak stworzymy nowy obiekt. Tworzenie obiektów w Pythonie przypomina zwykłe wywołanie funkcji, tyle tylko, że zamiast funkcji używa się klasy. Metoda <tt>__init__</tt> nie zwraca nic.

Reasumując, operacja wywołania dokonana na klasie powoduje stworzenie nowego obiektu i wywołanie <tt>__init__</tt>, natomiast operacja wywołania dokonana na obiekcie powoduje wywołanie <tt>__call__</tt>.

Dla przykładu zdefiniujmy <tt>ustaw_atrybut_xxx</tt> na nowo, tym razem jako klasę.
<source lang="python">
>>> class ustaw_atrybut_xxx(object):
...     def __init__(self):
...         pass
...     def __call__(self, funkcja):
...         funkcja.xxx = True
...         return funkcja
>>> @ustaw_atrybut_xxx()
... def f():
...     return 'bonjour'
>>> f()
'bonjour'
>>> f.xxx
True
</source>

Nieco inny jest sposób wykorzystania dekoratora — o ile wcześniej po znaku <tt>@</tt> następowała tylko nazwa funkcji,
to teraz dostawiliśmy nawiasy, tak by skonstruować obiekt <tt>ustaw_atrybut_xxx</tt>.o

== Dekorator typu ''trace'' ==
Zdefiniujmy użyteczny dekorator, który wypisze nazwę wykonywanej funkcji przed i po jej wykonaniu. 

<source lang="pycon">
>>> class logged(object):
...     def __init__(self, funkcja):
...         self.funkcja = funkcja
...     def __call__(self, *args, **kwargs):
...         print "wywołanie", self.funkcja.__name__
...         x = self.funkcja(*args, **kwargs)
...         print self.funkcja.__name__, "zwróciła", x
...         return x
>>> @logged
... def f():
...     return g() + g()
>>> @logged
... def g():
...     return 1
>>> f()
wywołanie f
wywołanie g
g zwróciła 1
wywołanie g
g zwróciła 1
f zwróciła 2
2
</source>

Tutaj mamy taką sytuację, że nasz obiekt klasy dekorującej podstawiamy za dekorowany obiekt, i wywołanie <tt>f()</tt> czy <tt>g()</tt>, wywołuje naprawdę <tt>logged.__call__</tt>, a dopiero pośrednio oryginalną funkcję.

== Dekoratora zwracające oryginalną funkcję i dekoratory zwracające inny obiekt ==

Dwa poprzednie przykłady różnią się w istotny sposób. Pierwszy dekorator, <tt>ustaw_atrybut_xxx</tt>, zwraca
przekazany mu obiekt, lekko tylko go zmieniając. Natomiast drugi dekorator, <tt>logged</tt>, zwraca inny
wywoływalny obiekt — instancję <tt>logged</tt> — który zostaje dowiązany pod nazwą oryginalnej funkcji.

Obie wersje są dozwolone, i obie wersje są użyteczne, w zależności od sytuacji. W pierwszej wersji działanie dekoratora ogranicza się do momentu definicji funkcji i wywołania dekoratora. Oznacza to, że dekorator może ustawić atrybut na funkcji, wypisać komunikat, czy dopisać funkcję do jakiegoś rejestru, ale nie może wpływać na sposób działania
funkcji. Bardziej interesująca jest druga wersja, gdzie możliwe są nie tylko operacje w trakcie definicji funkcji,
ale możliwe jest w zasadzie nieograniczone oddziaływanie na każde wywołanie funkcji. Przewagą pierwszej wersji nad drugą jest prostota i wydajność — nie tylko definicja dekoratora jest prostsza, ale również
* lista funkcji widoczna w komunikacie o wyjątku nie zawiera funkcji dekorującej, której obecność może być niespodzianką dla użytkownika, zwłaszcza że często jest to anonimowa funkcja tworzona przy każdym wywołaniu dekoratora
* działanie programu jest minimalnie szybsze, bo unikamy niewielkiego narzutu na każde wywołanie.

== Do czego (i czy wogóle) warto używać dekoratorów? ==
Ponieważ już mniej więcej wiemy jak się definiuje dekoratory, pora odpowiedzieć na pytanie, czy i dlaczego warto je wykorzystywać. W przypadku <tt>logged</tt>, z całą pewnością moglibyśmy wstawić odpowiednie wyrażenia <tt>print</tt> na początek i koniec każdej z definiowanych funkcji. Wykorzystanie dekoratorów pozwala na rozdzielenie sfer odpowiedzialności pomiędzy właściwe funkcje (dokonujące "obliczeń") oraz funkcję wypisującą komunikaty. W przypadku mniej trywialnych funkcji powoduje to uproszczenie kodu i ułatwia jego zrozumienie. Zaletą jest też to, że unikamy duplikacji — zamiast identycznych poleceń <tt>print</tt> w każdej funkcji, piszemy je tylko raz, a następnie "wstawiamy", dodając jedną linijkę wywołującą dekorator.

Przykłady funkcjonalności jaką można zaimplementować w formie dekoratorów obejmuje
* przechowywanie wykonanych wcześniej obliczeń w celu przyspieszenia działania programu,
* oznaczanie funkcji jako "przestarzałych" {{ang|deprecated}} i wypisywania ostrzeżenia przy pierwszym wywołaniu,
* pomiar czasu działania funkcji
* i oczywiście wiele innych&hellip;

==Przydatne linki==
*[http://wiki.python.org/moin/PythonDecoratorLibrary Python Decorator Library]
*moduł [http://docs.python.org/dev/library/functools.html functools]
*[https://portal.g-node.org/python-autumnschool/_media/materials/advanced_python/advanced_python.s5.html Prezentacja o dekoratorach, wyjątkach i context managers]
*moduł [http://pypi.python.org/pypi/decorator decorator]