Python 装饰器的作用是使函数包装与方法包装（一个函数，接受函数并返回其增强函
数）变得更容易阅读和理解。最初的使用场景是在方法定义的开头能够将其定义为类方法
或静态方法。如果不用装饰器语法的话，定义可能会非常稀疏，并且不断重复：
class WithoutDecorators:
def some_static_method():
print("this is static method")
some_static_method = staticmethod(some_static_method)
def some_class_method(cls):
print("this is class method")
some_class_method = classmethod(some_class_method)
如果用装饰器语法重写的话，代码会更简短，也更容易理解：
class WithDecorators:
@staticmethod
def some_static_method():
print("this is static method")
@classmethod
def some_class_method(cls):
print("this is class method")
1．一般语法和可能的实现
装饰器通常是一个命名的对象（不允许使用 lambda 表达式），在被（装饰函数）调用时接
受单一参数，并返回另一个可调用对象。这里用的是“可调用（callable）”。而不是之前以为的
“函数”。装饰器通常在方法和函数的范围内进行讨论，但它的适用范围并不局限于此。事实上，
任何可调用对象（任何实现了__call__方法的对象都是可调用的）都可以用作装饰器，它们返
回的对象往往也不是简单的函数，而是实现了自己的__call__方法的更复杂的类的实例。
装饰器语法只是语法糖而已。看下面这种装饰器用法：
@some_decorator
def decorated_function():
pass
这种写法总是可以替换为显式的装饰器调用和函数的重新赋值：
def decorated_function():
pass
decorated_function = some_decorator(decorated_function)
但是，如果在一个函数上使用多个装饰器的话，后一种写法的可读性更差，也非常难以理解。
（1）作为一个函数
编写自定义装饰器有许多方法，但最简单的方法就是编写一个函数，返回包装原始函
数调用的一个子函数。
通用模式如下：
def mydecorator(function):
def wrapped(*args, **kwargs):
# 在调用原始函数之前，做点什么
result = function(*args, **kwargs)
# 在函数调用之后，做点什么，
# 并返回结果
return result
# 返回 wrapper 作为装饰函数
return wrapped
（2）作为一个类
虽然装饰器几乎总是可以用函数实现，但在某些情况下，使用用户自定义类可能更好。
如果装饰器需要复杂的参数化或者依赖于特定状态，那么这种说法往往是对的。
非参数化装饰器用作类的通用模式如下：
class DecoratorAsClass:
def __init__(self, function):
self.function = function
def __call__(self, *args, **kwargs):
# 在调用原始函数之前，做点什么
result = self.function(*args, **kwargs)
# 在调用函数之后，做点什么，
# 并返回结果
return result
（3）参数化装饰器
在实际代码中通常需要使用参数化的装饰器。如果用函数作为装饰器的话，那么解决
方法很简单：需要用到第二层包装。下面一个简单的装饰器示例，给定重复次数，每次被
调用时都会重复执行一个装饰函数：
def repeat(number=3):
"""多次重复执行装饰函数。
返回最后一次原始函数调用的值作为结果
:param number: 重复次数，默认值是 3
"""
def actual_decorator(function):
def wrapper(*args, **kwargs):
result = None
for _ in range(number):
result = function(*args, **kwargs)
return result
return wrapper
return actual_decorator
这样定义的装饰器可以接受参数：
>>> @repeat(2)
... def foo():
... print("foo")
...
>>> foo()
foo
foo
注意，即使参数化装饰器的参数有默认值，但名字后面也必须加括号。带默认参数的
装饰器的正确用法如下：
>>> @repeat()
... def bar():
... print("bar")
...
>>> bar()
bar
bar
bar
没加括号的话，在调用装饰函数时会出现以下错误：
>>> @repeat
... def bar():
... pass
...
>>> bar()
Traceback (most recent call last):
File "<input>", line 1, in <module>
TypeError: actual_decorator() missing 1 required positional
argument: 'function'
（4）保存内省的装饰器
使用装饰器的常见错误是在使用装饰器时不保存函数元数据（主要是文档字符串和原始函
数名）。前面所有示例都存在这个问题。装饰器组合创建了一个新函数，并返回一个新对象，
但却完全没有考虑原始函数的标识。这将会使得调试这样装饰过的函数更加困难，也会破坏可
能用到的大多数自动生成文档的工具，因为无法访问原始的文档字符串和函数签名。
但我们来看一下细节。假设我们有一个虚设的（dummy）装饰器，仅有装饰作用，还
有其他一些被装饰的函数：
def dummy_decorator(function):
def wrapped(*args, **kwargs):
"""包装函数内部文档。"""
return function(*args, **kwargs)
return wrapped
@dummy_decorator
def function_with_important_docstring():
"""这是我们想要保存的重要文档字符串。"""
如果我们在 Python 交互式会话中查看 function_with_important_docstring()，
会注意到它已经失去了原始名称和文档字符串：
>>> function_with_important_docstring.__name__
'wrapped'
>>> function_with_important_docstring.__doc__
'包装函数内部文档。'
解决这个问题的正确方法，就是使用 functools 模块内置的 wraps()装饰器：
from functools import wraps
def preserving_decorator(function):
@wraps(function)
def wrapped(*args, **kwargs):
"""包装函数内部文档。"""
return function(*args, **kwargs)
return wrapped
@preserving_decorator
def function_with_important_docstring():
"""这是我们想要保存的重要文档字符串。"""
这样定义的装饰器可以保存重要的函数元数据：
>>> function_with_important_docstring.__name__
'function_with_important_docstring.'
>>> function_with_important_docstring.__doc__
'这是我们想要保存的重要文档字符串。'
2．用法和有用的例子
由于装饰器在模块被首次读取时由解释器来加载，所以它们的使用应受限于通用的包装器（wrapper）。如果装饰器与方法的类或所增强的函数签名绑定，那么应该将其重构为
常规的可调用对象，以避免复杂性。在任何情况下，装饰器在处理 API 时，一个好的做法
是将它们聚集在一个易于维护的模块中。
常见的装饰器模式如下所示。
• 参数检查。
• 缓存。
• 代理。
• 上下文提供者。
（1）参数检查
检查函数接受或返回的参数，在特定上下文中执行时可能有用。举个例子，如果一个
函数要通过 XML-RPC 来调用，那么 Python 无法像静态语言那样直接提供其完整签名。当
XML-RPC 客户端请求函数签名时，就需要用这个功能来提供内省能力。
自定义装饰器可以提供这种类型的签名，并确保输入和输出代表自定义的签名参数：
rpc_info = {}
def xmlrpc(in_=(), out=(type(None),)):
def _xmlrpc(function):
# 注册签名
func_name = function.__name__
rpc_info[func_name] = (in_, out)
def _check_types(elements, types):
"""用来检查类型的子函数。"""
if len(elements) != len(types):
raise TypeError('argument count is wrong')
typed = enumerate(zip(elements, types))
for index, couple in typed:
arg, of_the_right_type = couple
if isinstance(arg, of_the_right_type):
continue
raise TypeError(
'arg #%d should be %s' % (index,
of_the_right_type))
# 包装过的函数
def __xmlrpc(*args): # 没有允许的关键词
# 检查输入的内容
checkable_args = args[1:] # 去掉 self
_check_types(checkable_args, in_)
# 运行函数
res = function(*args)
# 检查输出的内容
if not type(res) in (tuple, list):
checkable_res = (res,)
else:
checkable_res = res
_check_types(checkable_res, out)
# 函数及其类型检查成功
return res
return __xmlrpc
return _xmlrpc
装饰器将函数注册到全局字典中，并将其参数和返回值保存在一个类型列表中。注意，
这个示例做了很大的简化，为的是展示装饰器的参数检查功能。
使用示例如下：
class RPCView:
@xmlrpc((int, int)) # two int -> None
def meth1(self, int1, int2):
print('received %d and %d' % (int1, int2))
@xmlrpc((str,), (int,)) # string -> int
def meth2(self, phrase):
print('received %s' % phrase)
return 12
在实际读取时，这个类定义会填充 rpc_infos 字典，并用于检查参数类型的特定环境中：
>>> rpc_info
{'meth2': ((<class 'str'>,), (<class 'int'>,)), 'meth1': ((<class
'int'>, <class 'int'>), (<class 'NoneType'>,))}
>>> my = RPCView()
>>> my.meth1(1, 2)
received 1 and 2
>>> my.meth2(2)
Traceback (most recent call last):
File "<input>", line 1, in <module>
File "<input>", line 26, in __xmlrpc
File "<input>", line 20, in _check_types
TypeError: arg #0 should be <class 'str'>
（2）缓存
缓存装饰器与参数检查十分相似，不过它重点是关注那些内部状态不会影响输出的函数。
每组参数都可以链接到唯一的结果。这种编程风格是函数式编程（functional programming，参
见 https://en.wikipedia.org/wiki/Functional_programming）的特点，当输入值有限时可以使用。
因此，缓存装饰器可以将输出与计算它所需要的参数放在一起，并在后续的调用中直
接返回它。这种行为被称为 memoizing（参见 https://en.wikipedia.org/wiki/Memoization），
很容易被实现为一个装饰器：
import time
import hashlib
import pickle
cache = {}
def is_obsolete(entry, duration):
return time.time() - entry['time'] > duration
def compute_key(function, args, kw):
key = pickle.dumps((function.__name__, args, kw))
return hashlib.sha1(key).hexdigest()
def memoize(duration=10):
def _memoize(function):
def __memoize(*args, **kw):
key = compute_key(function, args, kw)
# 是否已经拥有它了？
if (key in cache and
not is_obsolete(cache[key], duration)):
print('we got a winner')
return cache[key]['value']
计算
result = function(*args, **kw)
# 保存结果
cache[key] = {
'value': result,
'time': time.time()
}
return result
return __memoize
return _memoize
利用已排序的参数值来构建 SHA 哈希键，并将结果保存在一个全局字典中。利用 pickle
来建立 hash，这是冻结所有作为参数传入的对象状态的快捷方式，以确保所有参数都满足
要求。举个例子，如果用一个线程或套接字作为参数，那么会引发 PicklingError（参
见 https://docs.python.org/3/library/pickle.html）。duration 参数的作用是，如果上一次函数
调用已经过去了太长时间，那么它会使缓存值无效。
下面是一个使用示例：
>>> @memoize()
... def very_very_very_complex_stuff(a, b):
... # 如果在执行这个计算时计算机过热
... # 请考虑中止程序
... return a + b
...
>>> very_very_very_complex_stuff(2, 2)
4
>>> very_very_very_complex_stuff(2, 2)
we got a winner
4
>>> @memoize(1) # 1 秒后令缓存失效
... def very_very_very_complex_stuff(a, b):
... return a + b
...
>>> very_very_very_complex_stuff(2, 2)
4
>>> very_very_very_complex_stuff(2, 2)
we got a winner
4
>>> cache
{'c2727f43c6e39b3694649ee0883234cf': {'value': 4, 'time':
1199734132.7102251)}
>>> time.sleep(2)
>>> very_very_very_complex_stuff(2, 2)
4
缓存代价高昂的函数可以显著提高程序的总体性能，但必须小心使用。缓存值还可以
与函数本身绑定，以管理其作用域和生命周期，代替集中化的字典。但在任何情况下，更
高效的装饰器会使用基于高级缓存算法的专用缓存库。
（3）代理
代理装饰器使用全局机制来标记和注册函数。举个例子，一个根据当前用户来保护代
码访问的安全层可以使用集中式检查器和相关的可调用对象要求的权限来实现：
class User(object):
def __init__(self, roles):
self.roles = roles
class Unauthorized(Exception):
pass
def protect(role):
def _protect(function):
def __protect(*args, **kw):
user = globals().get('user')
if user is None or role not in user.roles:
raise Unauthorized("I won't tell you")
return function(*args, **kw)
return __protect
return _protect
这一模型常用于 Python Web 框架中，用于定义可发布类的安全性。例如，Django 提供
装饰器来保护函数访问的安全。
下面是一个示例，当前用户被保存在一个全局变量中。在方法被访问时装饰器会检查
他/她的角色：
>>> tarek = User(('admin', 'user'))
>>> bill = User(('user',))
>>> class MySecrets(object):
... @protect('admin')
... def waffle_recipe(self):
... print('use tons of butter!')
...
>>> these_are = MySecrets()
user = tarek
>>> these_are.waffle_recipe()
use tons of butter!
>>> user = bill
>>> these_are.waffle_recipe()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 7, in wrap
__main__.Unauthorized: I won't tell you
（4）上下文提供者
上下文装饰器确保函数可以运行在正确的上下文中，或者在函数前后运行一些代码。换
句话说，它设定并复位一个特定的执行环境。举个例子，当一个数据项需要在多个线程之间
共享时，就要用一个锁来保护它避免多次访问。这个锁可以在装饰器中编写，代码如下：
from threading import RLock
lock = RLock()
def synchronized(function):
def _synchronized(*args, **kw):
lock.acquire()
try:
return function(*args, **kw)
finally:
lock.release()
return _synchronized
@synchronized
def thread_safe(): # 确保锁定资源
pass
上下文装饰器通常会被上下文管理器（with 语句）替代，后者将在本章后面介绍。
