裝飾器(Decorators)
裝飾器是這樣一種設計模式：如果一個類希望添加其他類的一些功能，而不希望通過繼承或是直接修改源代碼實現，那么可以使用裝飾器模式。簡單來說Python中的裝飾器就是指某些函數或其他可調用對象，以函數或類作為可選輸入參數，然后返回函數或類的形式。通過這個在Python2.6版本中被新加入的特性可以用來實現裝飾器設計模式。
順便提一句，在繼續閱讀之前，如果你對Python中的閉包(Closure)概念不清楚，請查看本文結尾后的附錄，如果沒有閉包的相關概念，很難恰當的理解Python中的裝飾器。
在Python中，裝飾器被用于用@語法糖修辭的函數或類。現在讓我們用一個簡單的裝飾器例子來演示如何做一個函數調用日志記錄器。在這個例子中，裝飾器將時間格式作為輸入參數，在調用被這個裝飾器裝飾的函數時打印出函數調用的時間。這個裝飾器當你需要手動比較兩個不同算法或實現的效率時很有用。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
def logged(time_format): def decorator(func): def decorated_func(*args, **kwargs): print "- Running '%s' on %s " % ( func.__name__, time.strftime(time_format) ) start_time = time.time() result = func(*args, **kwargs) end_time = time.time() print "- Finished '%s', execution time = %0.3fs " % ( func.__name__, end_time - start_time ) return result decorated_func.__name__ = func.__name__ return decorated_func return decorator |
來看一個例子，在這里add1和add2函數被logged修飾，下面給出了一個輸出示例。請注意在這里時間格式參數是存儲在被返回的裝飾器函數中(decorated_func)。這就是為什么理解閉包對于理解裝飾器來說很重要的原因。同樣也請注意返回函數的名字是如何被替換為原函數名的，以防萬一如果它還要被使用到，這是為了防止混淆。Python默認可不會這么做。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
@logged("%b %d %Y - %H:%M:%S")def add1(x, y): time.sleep(1) return x + y @logged("%b %d %Y - %H:%M:%S")def add2(x, y): time.sleep(2) return x + y print add1(1, 2)print add2(1, 2) # Output:- Running 'add1' on Jul 24 2013 - 13:40:47- Finished 'add1', execution time = 1.001s3- Running 'add2' on Jul 24 2013 - 13:40:48- Finished 'add2', execution time = 2.001s3 |
如果你足夠細心，你可能會注意到我們對于返回函數的名字__name__有著特別的處理，但對其他的注入__doc__或是__module__則沒有如此。所以如果，在這個例子中add函數有一個doc字符串的話，它就會被丟棄。那么該如何處理呢？我們當然可以像處理__name__那樣對待所有的字段，不過如果在每個裝飾器內都這么做的話未免太繁冗了。這就是為何functools模塊提供了一個名為wraps的裝飾器的原因，那正是為了處理這種情況。可能在理解裝飾器的過程中會被迷惑，不過當你把裝飾器看成是一個接收函數名作為輸入參數并且返回一個函數，這樣就很好理解了。我們將在下個例子中使用wraps裝飾器而不是手動去處理__name__或其他屬性。
下個例子會有點復雜，我們的任務是將一個函數調用的返回結果緩存一段時間，輸入參數決定緩存時間。傳遞給函數的輸入參數必須是可哈希的對象，因為我們使用包含調用輸入參數的tuple作為第一個參數，第二個參數則為一個frozenset對象，它包含了關鍵詞項kwargs，并且作為cache key。每個函數都會有一個唯一的cache字典存儲在函數的閉包內。
【譯注】set和frozenset為Python的兩種內建集合，其中前者為可變對象(mutable)，其元素可以使用add()或remove()進行變更，而后者為不可變對象(imutable)并且是可哈希的(hashable)，在建立之后元素不可變，他可以作為字典的key或是另一個集合的元素。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
import timefrom functools import wraps def cached(timeout, logged=False): """Decorator to cache the result of a function call. Cache expires after timeout seconds. """ def decorator(func): if logged: print "-- Initializing cache for", func.__name__ cache = {} @wraps(func) def decorated_function(*args, **kwargs): if logged: print "-- Called function", func.__name__ key = (args, frozenset(kwargs.items())) result = None if key in cache: if logged: print "-- Cache hit for", func.__name__, key (cache_hit, expiry) = cache[key] if time.time() - expiry < timeout: result = cache_hit elif logged: print "-- Cache expired for", func.__name__, key elif logged: print "-- Cache miss for", func.__name__, key # No cache hit, or expired if result is None: result = func(*args, **kwargs) cache[key] = (result, time.time()) return result return decorated_function return decorator來看看它的用法。我們使用裝飾器裝飾一個很基本的斐波拉契數生成器。這個cache裝飾器將對代碼使用備忘錄模式(Memoize Pattern)。請注意fib函數的閉包是如何存放cache字典、一個指向原fib函數的引用、logged參數的值以及timeout參數的最后值的。dump_closure將在文末定義。>>> @cached(10, True)... def fib(n):... """Returns the n'th Fibonacci number."""... if n == 0 or n == 1:... return 1... return fib(n - 1) + fib(n - 2)...-- Initializing cache for fib>>> dump_closure(fib)1. Dumping function closure for fib:-- cell 0 = {}-- cell 1 =-- cell 2 = True-- cell 3 = 10>>>>>> print "Testing - F(4) = %d" % fib(4)-- Called function fib-- Cache miss for fib ((4,), frozenset([]))-- Called function fib-- Cache miss for fib ((3,), frozenset([]))-- Called function fib-- Cache miss for fib ((2,), frozenset([]))-- Called function fib-- Cache miss for fib ((1,), frozenset([]))-- Called function fib-- Cache miss for fib ((0,), frozenset([]))-- Called function fib-- Cache hit for fib ((1,), frozenset([]))-- Called function fib-- Cache hit for fib ((2,), frozenset([]))Testing - F(4) = 5Class Decorators |
在之前的小節中，我們看了一些函數裝飾器和一些使用的小技巧，接下來我們來看看類裝飾器。類裝飾器將一個class作為輸入參數(Python中的一種類類型對象)，并且返回一個修改過的class。
第一個例子是一個簡單的數學問題。當給定一個有序集合P，我們定義Pd為P的反序集合P(x,y) <-> Pd(x,y)，也就是說兩個有序集合的元素順序互為相反的，這在Python中該如何實現？假定一個類定義了__lt__以及__le__或其他方法來實現有序。那么我們可以通過寫一個類裝飾器來替換這些方法。
|
1
2
3
4
5
6
7
8
9
10
11
12
|
def make_dual(relation): @wraps(relation, ['__name__', '__doc__']) def dual(x, y): return relation(y, x) return dual def dual_ordering(cls): """Class decorator that reverses all the orderings""" for func in ['__lt__', '__gt__', '__ge__', '__le__']: if hasattr(cls, func): setattr(cls, func, make_dual(getattr(cls, func))) return cls |
下面是將這個裝飾器用以str類型的例子，創建一個名為rstr的新類，使用反字典序(opposite lexicographic)為其順序。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
@dual_orderingclass rstr(str): pass x = rstr("1")y = rstr("2") print x < yprint x <= yprint x > yprint x >= y # Output:FalseFalseTrueTrue |
來看一個更復雜的例子。假定我們希望前面所說的logged裝飾器能夠被用于某個類的所有方法。一個方案是在每個類方法上都加上裝飾器。另一個方案是寫一個類裝飾器自動完成這些工作。在動手之前，我將把前例中的logged裝飾器拿出來做一些小改進。首先，它使用functools提供的wraps裝飾器完成固定__name__的工作。第二，一個_logged_decorator屬性被引入(設置為True的布爾型變量)，用來指示這個方法是否已經被裝飾器裝飾過，因為這個類可能會被繼承而子類也許會繼續使用裝飾器。最后，name_prefix參數被加入用來設置打印的日志信息。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
def logged(time_format, name_prefix=""): def decorator(func): if hasattr(func, '_logged_decorator') and func._logged_decorator: return func @wraps(func) def decorated_func(*args, **kwargs): start_time = time.time() print "- Running '%s' on %s " % ( name_prefix + func.__name__, time.strftime(time_format) ) result = func(*args, **kwargs) end_time = time.time() print "- Finished '%s', execution time = %0.3fs " % ( name_prefix + func.__name__, end_time - start_time ) return result decorated_func._logged_decorator = True return decorated_func return decorator |
好的，讓我們開始寫類裝飾器：
|
1
2
3
4
5
6
7
8
9
10
11
|
def log_method_calls(time_format): def decorator(cls): for o in dir(cls): if o.startswith('__'): continue a = getattr(cls, o) if hasattr(a, '__call__'): decorated_a = logged(time_format, cls.__name__ + ".")(a) setattr(cls, o, decorated_a) return cls return decorator |
下面是使用方法，注意被繼承的或被重寫的方法是如何處理的。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
@log_method_calls("%b %d %Y - %H:%M:%S")class A(object): def test1(self): print "test1" @log_method_calls("%b %d %Y - %H:%M:%S")class B(A): def test1(self): super(B, self).test1() print "child test1" def test2(self): print "test2" b = B()b.test1()b.test2() # Output:- Running 'B.test1' on Jul 24 2013 - 14:15:03- Running 'A.test1' on Jul 24 2013 - 14:15:03test1- Finished 'A.test1', execution time = 0.000schild test1- Finished 'B.test1', execution time = 1.001s- Running 'B.test2' on Jul 24 2013 - 14:15:04test2- Finished 'B.test2', execution time = 2.001s |
我們第一個類裝飾器的例子是類的反序方法。一個相似的裝飾器，可以說是相當有用的，實現__lt__、__le__、__gt__、__ge__和__eq__中的一個，能夠實現類的全排序么？這也就是functools.total_ordering裝飾器所做的工作。詳情請見參考文檔。
Flask中的一些例子
讓我們來看看Flask中用到的一些有趣的裝飾器。
假定你希望讓某些函數在特定的調用時刻輸出警告信息，例如僅僅在debug模式下。而你又不希望每個函數都加入控制的代碼，那么你就能夠使用裝飾器來實現。以下就是Flask的app.py中定義的裝飾器的工作。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
def setupmethod(f): """Wraps a method so that it performs a check in debug mode if the first request was already handled. """ def wrapper_func(self, *args, **kwargs): if self.debug and self._got_first_request: raise AssertionError('A setup function was called after the ' 'first request was handled. This usually indicates a bug ' 'in the application where a module was not imported ' 'and decorators or other functionality was called too late.\n' 'To fix this make sure to import all your view modules, ' 'database models and everything related at a central place ' 'before the application starts serving requests.') return f(self, *args, **kwargs) return update_wrapper(wrapper_func, f) |
來看一個更有趣的例子，這個例子是Flask的route裝飾器，在Flask類中定義。注意到裝飾器可以是類中的一個方法，將self作為第一個參數。完整的代碼在app.py中。請注意裝飾器簡單的將被裝飾過的函數注冊成為一個URL句柄，這是通過調用add_url_rule函數來實現的。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
def route(self, rule, **options): """A decorator that is used to register a view function for a given URL rule. This does the same thing as :meth:`add_url_rule` but is intended for decorator usage:: @app.route('/') def index(): return 'Hello World' For more information refer to :ref:`url-route-registrations`. :param rule: the URL rule as string :param endpoint: the endpoint for the registered URL rule. Flask itself assumes the name of the view function as endpoint :param options: the options to be forwarded to the underlying :class:`~werkzeug.routing.Rule` object. A change to Werkzeug is handling of method options. methods is a list of methods this rule should be limited to (`GET`, `POST` etc.). By default a rule just listens for `GET` (and implicitly `HEAD`). Starting with Flask 0.6, `OPTIONS` is implicitly added and handled by the standard request handling. """ def decorator(f): endpoint = options.pop('endpoint', None) self.add_url_rule(rule, endpoint, f, **options) return f return decorator |
擴展閱讀
1. official Python Wiki
2. metaprogramming in Python 3
附錄：閉包
一個函數閉包是一個函數和一個引用集合的組合，這個引用集合指向這個函數被定義的作用域的變量。后者通常指向一個引用環境(referencing environment)，這使得函數能夠在它被定義的區域之外執行。在Python中，這個引用環境被存儲在一個cell的tuple中。你能夠通過func_closure或Python 3中的__closure__屬性訪問它。要銘記的一點是引用及是引用，而不是對象的深度拷貝。當然了，對于不可變對象而言，這并不是問題，然而對可變對象(list)這點就必須注意，隨后會有一個例子說明。請注意函數在定義的地方也有__globals__字段來存儲全局引用環境。
來看一個簡單的例子：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
>>> def return_func_that_prints_s(s):... def f():... print s... return f...>>> g = return_func_that_prints_s("Hello")>>> h = return_func_that_prints_s("World")>>> g()Hello>>> h()World>>> g is hFalse>>> h.__closure__(,)>>> print [str(c.cell_contents) for c in g.__closure__]['Hello']>>> print [str(c.cell_contents) for c in h.__closure__]['World'] |
一個稍復雜的例子。確保明白為什么會這么執行。
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
>>> def return_func_that_prints_list(z):... def f():... print z... return f...>>> z = [1, 2]>>> g = return_func_that_prints_list(z)>>> g()[1, 2]>>> z.append(3)>>> g()[1, 2, 3]>>> z = [1]>>> g()[1, 2, 3] |
【譯者】：z.append(3)時，g()內部的引用和z仍然指向一個變量，而z=[1]之后，兩者就不再指向一個變量了。
最后，來看看代碼中使用到的dump_closure方法的定義。
|
1
2
3
4
5
6
7
|
def dump_closure(f): if hasattr(f, "__closure__") and f.__closure__ is not None: print "- Dumping function closure for %s:" % f.__name__ for i, c in enumerate(f.__closure__): print "-- cell %d = %s" % (i, c.cell_contents) else: print " - %s has no closure!" % f.__name__ |
