装饰器(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
</div>
来看一个例子，在这里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
</div>
如果你足够细心，你可能会注意到我们对于返回函数的名字__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
</div>
在之前的小节中，我们看了一些函数装饰器和一些使用的小技巧，接下来我们来看看类装饰器。类装饰器将一个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
</div>
下面是将这个装饰器用以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
print x >= y
# Output:
False
False
True
True
</div>
来看一个更复杂的例子。假定我们希望前面所说的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.__