装饰器(decorators)
装饰器是这样一种设计模式：如果一个类希望添加其他类的一些功能，而不希望通过继承或是直接修改源代码实现，那么可以使用装饰器模式。简单来说python中的装饰器就是指某些函数或其他可调用对象，以函数或类作为可选输入参数，然后返回函数或类的形式。通过这个在python2.6版本中被新加入的特性可以用来实现装饰器设计模式。
顺便提一句，在继续阅读之前，如果你对python中的闭包(closure)概念不清楚，请查看本文结尾后的附录，如果没有闭包的相关概念，很难恰当的理解python中的装饰器。
在python中，装饰器被用于用@语法糖修辞的函数或类。现在让我们用一个简单的装饰器例子来演示如何做一个函数调用日志记录器。在这个例子中，装饰器将时间格式作为输入参数，在调用被这个装饰器装饰的函数时打印出函数调用的时间。这个装饰器当你需要手动比较两个不同算法或实现的效率时很有用。
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默认可不会这么做。
@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.001s
3
– running ‘add2’ on jul 24 2013 – 13:40:48
– finished ‘add2’, execution time = 2.001s
3
如果你足够细心，你可能会注意到我们对于返回函数的名字__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或是另一个集合的元素。
import time
from 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) = 5
class decorators
在之前的小节中，我们看了一些函数装饰器和一些使用的小技巧，接下来我们来看看类装饰器。类装饰器将一个class作为输入参数(python中的一种类类型对象)，并且返回一个修改过的class。
第一个例子是一个简单的数学问题。当给定一个有序集合p，我们定义pd为p的反序集合p(x,y) pd(x,y)，也就是说两个有序集合的元素顺序互为相反的，这在python中该如何实现？假定一个类定义了__lt__以及__le__或其他方法来实现有序。那么我们可以通过写一个类装饰器来替换这些方法。
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)为其顺序。
@dual_ordering
class rstr(str):
pass
x = rstr(“1”)
y = rstr(“2”)
print x < y
print x y
print x >= y
# output:
false
false
true
true
来看一个更复杂的例子。假定我们希望前面所说的logged装饰器能够被用于某个类的所有方法。一个方案是在每个类方法上都加上装饰器。另一个方案是写一个类装饰器自动完成这些工作。在动手之前，我将把前例中的logged装饰器拿出来做一些小改进。首先，它使用functools提供的wraps装饰器完成固定__name__的工作。第二，一个_logged_decorator属性被引入(设置为true的布尔型变量)，用来指示这个方法是否已经被装饰器装饰过，因为这个类可能会被继承而子类也许会继续使用装饰器。最后，name_prefix参数被加入用来设置打印的日志信息。
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
好的，让我们开始写类装饰器：
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
下面是使用方法，注意被继承的或被重写的方法是如何处理的。
@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:03
test1
– finished ‘a.test1’, execution time = 0.000s
child test1
– finished ‘b.test1’, execution time = 1.001s
– running ‘b.test2’ on jul 24 2013 – 14:15:04
test2
– finished ‘b.test2’, execution time = 2.001s
我们第一个类装饰器的例子是类的反序方法。一个相似的装饰器，可以说是相当有用的，实现__lt__、__le__、__gt__、__ge__和__eq__中的一个，能够实现类的全排序么？这也就是functools.total_ordering装饰器所做的工作。详情请见参考文档。
flask中的一些例子
让我们来看看flask中用到的一些有趣的装饰器。
假定你希望让某些函数在特定的调用时刻输出警告信息，例如仅仅在debug模式下。而你又不希望每个函数都加入控制的代码，那么你就能够使用装饰器来实现。以下就是flask的app.py中定义的装饰器的工作。
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函数来实现的。
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__字段来存储全局引用环境。
来看一个简单的例子：
>>> 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 h
false
>>> h.__closure__
(,)
>>> print [str(c.cell_contents) for c in g.__closure__]
[‘hello’]
>>> print [str(c.cell_contents) for c in h.__closure__]
[‘world’]
一个稍复杂的例子。确保明白为什么会这么执行。
>>> 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方法的定义。
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__