深入理解Python中装饰器的用法

因为函数或类都是对象，它们也能被四处传递。它们又是可变对象，可以被更改。在函数或类对象创建后但绑定到名字前更改之的行为为装饰(decorator)。

"装饰器"后隐藏了两种意思――一是函数起了装饰作用，例如，执行真正的工作，另一个是依附于装饰器语法的表达式，例如，at符号和装饰函数的名称。

函数可以通过函数装饰器语法装饰：

    @decorator       # ②
    def function():    # ①
      pass

函数以标准方式定义。①
以@做为定义为装饰器函数前缀的表达式②。在 @ 后的部分必须是简单的表达式，通常只是函数或类的名字。这一部分先求值，在下面的定义的函数准备好后，装饰器被新定义的函数对象作为单个参数调用。装饰器返回的值附着到被装饰的函数名。
装饰器可以应用到函数和类上。对类语义很明晰――类定义被当作参数来调用装饰器，无论返回什么都赋给被装饰的名字。

在装饰器语法实现前(PEP 318)，通过将函数和类对象赋给临时变量然后显式调用装饰器然后将返回值赋给函数名，可以完成同样的事。这似乎要打更多的字，也确实装饰器函数名用了两次同时临时变量要用至少三次，很容易出错。以上实例相当于：

    def function():         # ①
      pass
    function = decorator(function)  # ②

装饰器可以堆栈(stacked)――应用的顺序是从底到上或从里到外。就是说最初的函数被当作第一次参数器的参数，无论返回什么都被作为第二个装饰器的参数……无论最后一个装饰器返回什么都被依附到最初函数的名下。

装饰器语法因其可读性被选择。因为装饰器在函数头部前被指定，显然不是函数体的一部分，它只能对整个函数起作用。以@为前缀的表达式又让它明显到不容忽视(根据PEP叫在您脸上……：）)。当多个装饰器被应用时，每个放在不同的行非常易于阅读。

代替和调整原始对象
装饰器可以或者返回相同的函数或类对象或者返回完全不同的对象。第一种情况中，装饰器利用函数或类对象是可变的添加属性，例如向类添加文档字符串(docstring).装饰器甚至可以在不改变对象的情况下做有用的事，例如在全局注册表中注册装饰的类。在第二种情况中，简直无所不能：当什么不同的东西取代了被装饰的类或函数，新对象可以完全不同。然而这不是装饰器的目的：它们意在改变装饰对象而非做不可预料的事。因此当一个函数在装饰时被完全替代成不同的函数时，新函数通常在一些准备工作后调用原始函数。同样，当一个类被装饰成一个新类时，新类通常源于被装饰类。当装饰器的目的是"每次都"做什么，像记录每次对被装饰函数的调用，只有第二类装饰器可用。另一方面，如果第一类足够了，最好使用它因为更简单。

实现类和函数装饰器
对装饰器惟一的要求是它能够单参数调用。这意味着装饰器可以作为常规函数或带有call方法的类的实现，理论上，甚至lambda函数也行。

让我们比较函数和类方法。装饰器表达式(@后部分)可以只是名字。只有名字的方法很好(打字少，看起来整洁等)，但是只有当无需用参数定制装饰器时才可能。被写作函数的装饰器可以用以下两种方式：

    >>> def simple_decorator(function):
    ...  print "doing decoration"
    ...  return function
    >>> @simple_decorator
    ... def function():
    ...  print "inside function"
    doing decoration
    >>> function()
    inside function

    >>> def decorator_with_arguments(arg):
    ...  print "defining the decorator"
    ...  def _decorator(function):
    ...    # in this inner function, arg is available too
    ...    print "doing decoration,", arg
    ...    return function
    ...  return _decorator
    >>> @decorator_with_arguments("abc")
    ... def function():
    ...  print "inside function"
    defining the decorator
    doing decoration, abc
    >>> function()
    inside function

这两个装饰器属于返回被装饰函数的类别。如果它们想返回新的函数，需要额外的嵌套，最糟的情况下，需要三层嵌套。

    >>> def replacing_decorator_with_args(arg):
    ...  print "defining the decorator"
    ...  def _decorator(function):
    ...    # in this inner function, arg is available too
    ...    print "doing decoration,", arg
    ...    def _wrapper(*args, **kwargs):
    ...      print "inside wrapper,", args, kwargs
    ...      return function(*args, **kwargs)
    ...    return _wrapper
    ...  return _decorator
    >>> @replacing_decorator_with_args("abc")
    ... def function(*args, **kwargs):
    ...   print "inside function,", args, kwargs
    ...   return 14
    defining the decorator
    doing decoration, abc
    >>> function(11, 12)
    inside wrapper, (11, 12) {}
    inside function, (11, 12) {}
    14

_wrapper函数被定义为接受所有位置和关键字参数。通常我们不知道哪些参数被装饰函数会接受，所以wrapper将所有东西都创递给被装饰函数。一个不幸的结果就是显式参数很迷惑人。

相比定义为函数的装饰器，定义为类的复杂装饰器更简单。当对象被创建，init方法仅仅允许返回None，创建的对象类型不能更改。这意味着当装饰器被定义为类时，使用无参数的形式没什么意义：最终被装饰的对象只是装饰类的一个实例而已，被构建器(constructor)调用返回，并不非常有用。讨论在装饰表达式中给出参数的基于类的装饰器，init方法被用来构建装饰器。

    >>> class decorator_class(object):
    ...  def __init__(self, arg):
    ...    # this method is called in the decorator expression
    ...    print "in decorator init,", arg
    ...    self.arg = arg
    ...  def __call__(self, function):
    ...    # this method is called to do the job
    ...    print "in decorator call,", self.arg
    ...    return function
    >>> deco_instance = decorator_class('foo')
    in decorator init, foo
    >>> @deco_instance
    ... def function(*args, **kwargs):
    ...  print "in function,", args, kwargs
    in decorator call, foo
    >>> function()
    in function, () {}

相对于正常规则(PEP 8)由类写成的装饰器表现得更像函数，因此它们的名字以小写字母开始。

事实上，创建一个仅返回被装饰函数的新类没什么意义。对象应该有状态，这种装饰器在装饰器返回新对象时更有用。

    >>> class replacing_decorator_class(object):
    ...  def __init__(self, arg):
    ...    # this method is called in the decorator expression
    ...    print "in decorator init,", arg
    ...    self.arg = arg
    ...  def __call__(self, function):
    ...    # this method is called to do the job
    ...    print "in decorator call,", self.arg
    ...    self.function = function
    ...    return self._wrapper
    ...  def _wrapper(self, *args, **kwargs):
    ...    print "in the wrapper,", args, kwargs
    ...    return self.function(*args, **kwargs)
    >>> deco_instance = replacing_decorator_class('foo')
    in decorator init, foo
    >>> @deco_instance
    ... def function(*args, **kwargs):
    ...  print "in function,", args, kwargs
    in decorator call, foo
    >>> function(11, 12)
    in the wrapper, (11, 12) {}
    in function, (11, 12) {}

像这样的装饰器可以做任何事，因为它能改变被装饰函数对象和参数，调用被装饰函数或不调用，最后改变返回值。

复制原始函数的文档字符串和其它属性
当新函数被返回代替装饰前的函数时，不幸的是原函数的函数名，文档字符串和参数列表都丢失了。这些属性可以部分通过设置doc(文档字符串)，module和name(函数的全称)、annotations(Python 3中关于参数和返回值的额外信息)移植到新函数上，这些工作可通过functools.update_wrapper自动完成。

    >>> import functools
    >>> def better_replacing_decorator_with_args(arg):
    ...  print "defining the decorator"
    ...  def _decorator(function):
    ...    print "doing decoration,", arg
    ...    def _wrapper(*args, **kwargs):
    ...      print "inside wrapper,", args, kwargs
    ...      return function(*args, **kwargs)
    ...    return functools.update_wrapper(_wrapper, function)
    ...  return _decorator
    >>> @better_replacing_decorator_with_args("abc")
    ... def function():
    ...   "extensive documentation"
    ...   print "inside function"
    ...   return 14
    defining the decorator
    doing decoration, abc
    >>> function              
    <function function at 0x...>
    >>> print function.__doc__
    extensive documentation

一件重要的东西是从可迁移属性列表中所缺少的：参数列表。参数的默认值可以通过defaults、kwdefaults属性更改，但是不幸的是参数列表本身不能被设置为属性。这意味着help(function)将显式无用的参数列表，使使用者迷惑不已。一个解决此问题有效但是丑陋的方式是使用eval动态创建wrapper。可以使用外部external模块自动实现。它提供了对decorator装饰器的支持，该装饰器接受wrapper并将之转换成保留函数签名的装饰器。

综上，装饰器应该总是使用functools.update_wrapper或者其它方式赋值函数属性。

标准库中的示例
首先要提及的是标准库中有一些实用的装饰器，有三种装饰器：

classmethod让一个方法变成"类方法"，即它能够无需创建实例调用。当一个常规方法被调用时，解释器插入实例对象作为第一个参数self。当类方法被调用时，类本身被给做第一个参数，一般叫cls。
类方法也能通过类命名空间读取，所以它们不必污染模块命名空间。类方法可用来提供替代的构建器(constructor):

    class Array(object):
      def __init__(self, data):
        self.data = data

      @classmethod
      def fromfile(cls, file):
        data = numpy.load(file)
        return cls(data)

这比用一大堆标记的init简单多了。
staticmethod应用到方法上让它们"静态"，例如，本来一个常规函数，但通过类命名空间存取。这在函数仅在类中需要时有用(它的名字应该以_为前缀)，或者当我们想要用户以为方法连接到类时也有用――虽然对实现本身不必要。
property是对getter和setter问题Python风格的答案。通过property装饰的方法变成在属性存取时自动调用的getter。

    >>> class A(object):
    ...  @property
    ...  def a(self):
    ...   "an important attribute"
    ...   return "a value"
    >>> A.a                  
    <property object at 0x...>
    >>> A().a
    'a value'

例如A.a是只读属性，它已经有文档了：help(A)包含从getter方法获取的属性a的文档字符串。将a定义为property使它能够直接被计算，并且产生只读的副作用，因为没有定义任何setter。
为了得到setter和getter，显然需要两个方法。从Python 2.6开始首选以下语法：

    class Rectangle(object):
      def __init__(self, edge):
        self.edge = edge

      @property
      def area(self):
        """Computed area.

        Setting this updates the edge length to the proper value.
        """
        return self.edge**2

      @area.setter
      def area(self, area):
        self.edge = area ** 0.5

通过property装饰器取代带一个属性(property)对象的getter方法，以上代码起作用。这个对象反过来有三个可用于装饰器的方法getter、setter和deleter。它们的作用就是设定属性对象的getter、setter和deleter(被存储为fget、fset和fdel属性(attributes))。当创建对象时，getter可以像上例一样设定。当定义setter时，我们已经在area中有property对象，可以通过setter方法向它添加setter，一切都在创建类时完成。
之后，当类实例创建后，property对象和特殊。当解释器执行属性存取、赋值或删除时，其执行被下放给property对象的方法。
为了让一切一清二楚[^5]，让我们定义一个"调试"例子：

    >>> class D(object):
    ...  @property
    ...  def a(self):
    ...   print "getting", 1
    ...   return 1
    ...  @a.setter
    ...  def a(self, value):
    ...   print "setting", value
    ...  @a.deleter
    ...  def a(self):
    ...   print "deleting"
    >>> D.a                  
    <property object at 0x...>
    >>> D.a.fget                
    <function a at 0x...>
    >>> D.a.fset                
    <function a at 0x...>
    >>> D.a.fdel                
    <function a at 0x...>
    >>> d = D()        # ... varies, this is not the same `a` function
    >>> d.a
    getting 1
    1
    >>> d.a = 2
    setting 2
    >>> del d.a
    deleting
    >>> d.a
    getting 1
    1

属性(property)是对装饰器语法的一点扩展。使用装饰器的一大前提――命名不重复――被违反了，但是目前没什么更好的发明。为getter，setter和deleter方法使用相同的名字还是个好的风格。
一些其它更新的例子包括：

functools.lru_cache记忆任意维持有限 参数：结果 对的缓存函数(Python
3.2)
functools.total_ordering是一个基于单个比较方法而填充丢失的比较(ordering)方法(lt,gt，le等等)的类装饰器。
函数的废弃
比如说我们想在第一次调用我们不希望被调用的函数时在标准错误打印一个废弃函数警告。如果我们不想更改函数，我们可用装饰器

    class deprecated(object):
      """Print a deprecation warning once on first use of the function.

      >>> @deprecated()          # doctest: +SKIP
      ... def f():
      ...   pass
      >>> f()               # doctest: +SKIP
      f is deprecated
      """
      def __call__(self, func):
        self.func = func
        self.count = 0
        return self._wrapper
      def _wrapper(self, *args, **kwargs):
        self.count += 1
        if self.count == 1:
          print self.func.__name__, 'is deprecated'
        return self.func(*args, **kwargs)

也可以实现成函数：

    def deprecated(func):
      """Print a deprecation warning once on first use of the function.

      >>> @deprecated           # doctest: +SKIP
      ... def f():
      ...   pass
      >>> f()               # doctest: +SKIP
      f is deprecated
      """
      count = [0]
      def wrapper(*args, **kwargs):
        count[0] += 1
        if count[0] == 1:
          print func.__name__, 'is deprecated'
        return func(*args, **kwargs)
      return wrapper

while-loop移除装饰器
例如我们有个返回列表的函数，这个列表由循环创建。如果我们不知道需要多少对象，实现这个的标准方法如下：

    def find_answers():
      answers = []
      while True:
        ans = look_for_next_answer()
        if ans is None:
          break
        answers.append(ans)
      return answers

只要循环体很紧凑，这很好。一旦事情变得更复杂，正如真实的代码中发生的那样，这就很难读懂了。我们可以通过yield语句简化它，但之后用户不得不显式调用嗯list(find_answers())。

我们可以创建一个为我们构建列表的装饰器：

    def vectorized(generator_func):
      def wrapper(*args, **kwargs):
        return list(generator_func(*args, **kwargs))
      return functools.update_wrapper(wrapper, generator_func)

然后函数变成这样：

    @vectorized
    def find_answers():
      while True:
        ans = look_for_next_answer()
        if ans is None:
          break
        yield ans

插件注册系统
这是一个仅仅把它放进全局注册表中而不更改类的类装饰器，它属于返回被装饰对象的装饰器。

    class WordProcessor(object):
      PLUGINS = []
      def process(self, text):
        for plugin in self.PLUGINS:
          text = plugin().cleanup(text)
        return text

      @classmethod
      def plugin(cls, plugin):
        cls.PLUGINS.append(plugin)

    @WordProcessor.plugin
    class CleanMdashesExtension(object):
      def cleanup(self, text):
        return text.replace('--', u'\N{em dash}')

这里我们使用装饰器完成插件注册。我们通过一个名词调用装饰器而不是一个动词，因为我们用它来声明我们的类是WordProcessor的一个插件。plugin方法仅仅将类添加进插件列表。

关于插件自身说下：它用真正的Unicode中的破折号符号替代HTML中的破折号。它利用unicode literal notation通过它在unicode数据库中的名称("EM DASH")插入一个符号。如果直接插入Unicode符号，将不可能区分所插入的和源程序中的破折号。