Python でデコレータを使用する方法

関数やクラスはオブジェクトであるため、渡すこともできます。これらは可変オブジェクトであり、変更することができます。関数またはクラス オブジェクトが作成された後、名前にバインドされる前に変更する動作がデコレータです。

「デコレーター」の背後には 2 つの意味が隠されています - 1 つは、関数が装飾的な役割を果たす、たとえば実際の作業を実行するということ、もう 1 つはデコレーター構文に付加された式 (たとえば、at 記号や装飾された関数名。

関数は、関数デコレータ構文を使用して装飾できます:

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

関数は標準的な方法で定義されます。 ①
デコレーター関数②のプレフィックスとして定義した式に@を使用します。 @ の後の部分は単純な式である必要があり、通常は関数またはクラスの名前だけです。この部分が最初に評価され、以下で定義された関数の準備ができた後、新しく定義された関数オブジェクトを単一のパラメーターとしてデコレーターが呼び出されます。デコレーターによって返された値は、装飾された関数名に付加されます。
デコレータは関数とクラスに適用できます。クラスのセマンティクスは明確です。クラス定義はデコレータを呼び出すためのパラメータとして使用され、返されたものはすべて装飾された名前に割り当てられます。

デコレーター構文 (PEP 318) が実装される前は、関数とクラス オブジェクトを一時変数に代入し、明示的にデコレーターを呼び出し、戻り値を関数名に割り当てることで、同じことを実現できました。これには、より多くの入力が必要なように見えますが、デコレータ関数名が 2 回使用され、一時変数が少なくとも 3 回使用されており、間違いが発生しやすいのは事実です。上記の例は次と同等です:

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

デコレーターは積み重ねることができます - 適用の順序は下から上、または内側から外側です。つまり、元の関数は最初のパラメータライザーのパラメーターとして使用され、返されるものはすべて 2 番目のデコレーターのパラメーターとして使用されます。最後のデコレーターが返すものはすべて、元の関数の名前に付加されます。

Decorator 構文は読みやすさを考慮して選択されました。デコレーターは関数ヘッダーの前に指定されており、明らかに関数本体の一部ではないため、関数全体に対してのみ機能します。式の前に @ を付けると、それが無視できないほど明白になります (PEP によると顔で叫びます... :) )。複数のデコレータを適用する場合、それぞれを別の行に配置すると読みやすくなります。

元のオブジェクトを置き換えて適応させます
デコレーターは、同じ関数またはクラス オブジェクト、あるいはまったく異なるオブジェクトを返すことができます。最初のケースでは、デコレーターは、関数またはクラス オブジェクトが変更可能であるという事実を利用して、クラスに docstring を追加するなどのプロパティを追加します。デコレーターは、オブジェクトを変更せずに、グローバルなオブジェクトの登録などの便利な操作を実行することもできます。レジストリ内の装飾されたクラス。 2 番目のケースでは、不可能なことは何もありません。装飾されたクラスまたは関数が別のものに置き換えられると、新しいオブジェクトはまったく異なるものになる可能性があります。ただし、これはデコレータの目的ではありません。デコレータは予期しないことを行うのではなく、装飾されたオブジェクトを変更することを目的としています。したがって、装飾中に関数が別の関数に完全に置き換えられる場合、通常、新しい関数は何らかの準備を行った後に元の関数を呼び出します。同様に、クラスが装飾されて新しいクラスになる場合、通常、新しいクラスは装飾されたクラスから派生します。デコレーターの目的が、デコレーター関数へのすべての呼び出しをログに記録するなど、「毎回」何かを実行することである場合、2 番目のタイプのデコレーターのみが使用可能です。一方、最初のカテゴリで十分な場合は、より簡単なため、それを使用することをお勧めします。

クラスと関数のデコレータを実装する
デコレータの唯一の要件は、単一のパラメータで呼び出せることです。つまり、デコレータは通常の関数または __call__ メソッドを備えたクラスとして実装でき、理論的にはラムダ関数としても実装できます。

関数とクラスメソッドを比較してみましょう。デコレータ式 (@ の後の部分) は名前だけでも構いません。名前のみのアプローチは優れていますが (入力の手間が減り、見た目がすっきりするなど)、パラメーターを使用してデコレータをカスタマイズする必要がない場合にのみ可能です。記述されている関数のデコレータは、次の 2 つの方法で使用できます:

>>> 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

これら 2 つのデコレータは、デコレートされた関数を返すカテゴリに属します。新しい関数を返したい場合は、追加のネストが必要で、最悪の場合は 3 レベルのネストが必要になります。

>>> 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 関数は、すべての位置引数とキーワード引数を受け入れるように定義されています。通常、装飾された関数がどのパラメータを受け入れるかわからないため、ラッパーは装飾された関数に対するすべてを作成します。残念な結果として、明示的なパラメータが混乱を招くことになります。

クラスとして定義された複雑なデコレータは、関数として定義されたデコレータよりも単純です。オブジェクトの作成時、__init__ メソッドは None を返すことのみが許可されており、作成されたオブジェクトの型は変更できません。これは、デコレーターがクラスとして定義されている場合、パラメーターのない形式を使用することに意味がないことを意味します。最終的に装飾されたオブジェクトは、コンストラクター呼び出しによって返される、装飾されたクラスのインスタンスにすぎず、あまり役に立ちません。デコレータ式で引数が指定されるクラスベースのデコレータについて説明すると、デコレータの構築には __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
&#39;a value&#39;

例如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符号，将不可能区分所插入的和源程序中的破折号。

更多Python中装饰器的用法相关文章请关注PHP中文网！