警告警告警告

本文档旨在描述装饰器语法以及导致做出这些决策的过程。它不试图涵盖大量潜在的替代语法，也不是试图详尽列出每种形式的所有优缺点。

摘要

当前转换函数和方法的方法（例如，将它们声明为类或静态方法）很笨拙，并且可能导致难以理解的代码。理想情况下，这些转换应该在代码中声明本身的位置进行。本PEP引入了用于转换函数或方法声明的新语法。

动机

当前将转换应用于函数或方法的方法将实际转换放在函数体之后。对于大型函数，这会将函数行为的关键组成部分与其其余外部接口的定义分开。例如

def foo(self):
    perform method operation
foo = classmethod(foo)

对于较长的方法，这变得不太易读。对于从概念上讲是单个声明的内容，将函数名称重复三次似乎也不够pythonic。解决此问题的一种方法是将方法的转换移到更靠近方法本身的声明处。新语法的目的是替换

def foo(cls):
    pass
foo = synchronized(lock)(foo)
foo = classmethod(foo)

为另一种将装饰放在函数声明中的方法

@classmethod
@synchronized(lock)
def foo(cls):
    pass

以这种方式修改类也是可能的，尽管好处并不那么明显。几乎可以肯定，任何可以使用类装饰器完成的事情都可以使用元类完成，但是使用元类足够模糊，因此有一些吸引力在于有一种更简单的方法来对类进行简单的修改。对于Python 2.4，仅添加函数/方法装饰器。

PEP 3129 提案自Python 2.6开始添加类装饰器。

背景

人们普遍认为，语法支持是当前状态下可取的。Guido在他的DevDay主题演讲中提到了第10届Python大会上的装饰器的语法支持，尽管他后来表示，这只是他在那里“半开玩笑地”提出的几个扩展之一。Michael Hudson在会议后不久在python-dev上提出了这个话题，将最初的括号语法归因于Gareth McCaughan在comp.lang.python上提出的早期提案。

类装饰似乎是显而易见的下一步，因为类定义和函数定义在语法上相似，但是Guido仍然不相信，类装饰器几乎肯定不会出现在Python 2.4中。

从2002年2月到2004年7月，关于此话题的讨论在python-dev上断断续续地进行。人们发表了数百封帖子，提出了许多可能的语法变体。Guido将一份提案带到了EuroPython 2004，在那里进行了一次讨论。随后，他决定采用Java风格的@装饰器语法，这在2.4a2中首次出现。Barry Warsaw将此命名为“派装饰器”语法，以纪念大约在装饰器语法出现的同时发生的Pie-thon Parrot shootout，以及因为@看起来有点像派。Guido在Python-dev上概述了他的论点，包括这部分关于一些（许多）被拒绝的形式。

关于“装饰器”这个名称

人们对为这个特性选择“装饰器”这个名称提出了很多抱怨。主要的一个是，这个名称与其在GoF书中的用法不一致。“装饰器”这个名称可能更多地归因于它在编译器领域的使用——语法树被遍历和注释。很可能会有一个更好的名字出现。

设计目标

新语法应该

• 适用于任意包装器，包括用户定义的可调用对象和现有的内置函数classmethod() 和 staticmethod()。此要求还意味着装饰器语法必须支持将参数传递给包装器构造函数
• 适用于每个定义的多个包装器
• 使正在发生的事情变得显而易见；至少应该让新用户清楚地知道，在编写自己的代码时可以安全地忽略它
• 是一种“一旦解释就容易记住的语法”
• 不会使将来的扩展变得更加困难
• 易于键入；使用它的程序预计会非常频繁地使用它
• 不会使快速浏览代码变得更加困难。仍然应该易于搜索所有定义、特定定义或函数接受的参数
• 不会不必要地使辅助支持工具（例如语言感知编辑器和其他“现有的玩具解析器工具”）复杂化
• 允许将来的编译器针对装饰器进行优化。希望在某个时候为Python创建一个JIT编译器，这往往需要装饰器的语法出现在函数定义之前
• 从函数末尾（它当前隐藏在那里）移动到前面，在那里它更显眼

Andrew Kuchling在他的博客中链接了大量关于动机和用例的讨论。特别值得注意的是Jim Huginin的用例列表。

当前语法

Python 2.4a2中实现的函数装饰器的当前语法是

@dec2
@dec1
def func(arg1, arg2, ...):
    pass

这等价于

def func(arg1, arg2, ...):
    pass
func = dec2(dec1(func))

无需将中间赋值给变量func。装饰器靠近函数声明。@符号清楚地表明这里发生了一些新事情。

应用顺序（从下到上）的基本原理是，它与函数应用的通常顺序相匹配。在数学中，函数的复合（g o f)(x)转换为g(f(x))。在Python中，@g @f def foo() 转换为 foo=g(f(foo)。

装饰器语句在其可以接受的内容方面受到限制——任意表达式将不起作用。Guido更喜欢这个，因为他有一种直觉。

当前语法还允许装饰器声明调用返回装饰器的函数

@decomaker(argA, argB, ...)
def func(arg1, arg2, ...):
    pass

这等价于

func = decomaker(argA, argB, ...)(func)

拥有返回装饰器的函数的基本原理是，@符号后面的部分可以被认为是一个表达式（尽管在语法上仅限于函数），并且调用该表达式返回的任何内容。请参阅声明参数。

语法替代方案

已经提出了大量不同的语法——与其尝试遍历这些单独的语法，不如将语法讨论分解为几个方面。尝试单独讨论每个可能的语法将是一件疯狂的事情，并且会产生一个完全笨拙的PEP。

@classmethod
def foo(arg1,arg2):
    pass

@accepts(int,int)
@returns(float)
def bar(low,high):
    pass

def @classmethod foo(arg1,arg2):
    pass

def @accepts(int,int),@returns(float) bar(low,high):
    pass

def foo @classmethod (arg1,arg2):
    pass

def bar @accepts(int,int),@returns(float) (low,high):
    pass

def foo(arg1,arg2) @classmethod:
    pass

def bar(low,high) @accepts(int,int),@returns(float):
    pass

def foo(arg1,arg2):
    @classmethod
    pass

def bar(low,high):
    @accepts(int,int)
    @returns(float)
    pass

decorate:
    classmethod
    def foo(arg1,arg2):
        pass

decorate:
    accepts(int,int)
    returns(float)
    def bar(low,high):
        pass

当前实现，历史

Guido 要求志愿者实现他喜欢的语法，Mark Russell 挺身而出，并在 SF 上发布了一个补丁。这种新语法在 2.4a2 中可用。

@dec2
@dec1
def func(arg1, arg2, ...):
    pass

这等价于

def func(arg1, arg2, ...):
    pass
func = dec2(dec1(func))

尽管没有中间创建名为 func 的变量。

在 2.4a2 中实现的版本允许在同一行上使用多个 @decorator 子句。在 2.4a3 中，这一点得到了改进，只允许每行一个装饰器。

Michael Hudson 的一个以前的补丁实现了 def 后列表语法，也仍在使用。

在发布 2.4a2 之后，为了回应社区的反应，Guido 表示如果社区能够达成共识，提出一个合理的提案并实现它，他将重新审查社区的提案。经过大量帖子，在Python wiki中收集了大量备选方案之后，社区达成了一致意见（如下所示）。Guido 随后拒绝了这种替代形式，但补充道：

在 Python 2.4a3（将于本周四发布）中，所有内容都保持与 CVS 中当前相同。对于 2.4b1，我将考虑将 @ 更改为其他一些单字符，即使我认为 @ 具有与 Java 中类似功能使用相同字符的优势。有人认为它并不完全相同，因为 Java 中的 @ 用于不更改语义的属性。但是 Python 的动态特性使得其语法元素与其他语言中的类似构造永远不会完全相同，并且肯定存在明显的重叠。关于对第三方工具的影响：IPython 的作者认为不会有太大影响；Leo 的作者表示 Leo 将继续存在（尽管这会给他和他的用户带来一些过渡期的痛苦）。我实际上预计，在 Python 的语法中选择一个已经在其他地方使用的字符可能会使外部工具更难适应，因为在这种情况下，解析将不得不更加微妙。但我坦率地说还没有决定，所以这里有一些回旋余地。此时我不想考虑进一步的语法替代方案：必须在某个时间点停止，每个人都已表达了自己的意见，并且节目必须继续进行。

using:
    classmethod
    synchronized(lock)
def func(cls):
    pass

示例

在comp.lang.python和python-dev邮件列表上的许多讨论都集中在使用装饰器作为更简洁的方式来使用staticmethod()和classmethod()内置函数。这种能力远不止于此。本节提供了一些使用示例。

1. 定义一个在退出时执行的函数。请注意，该函数实际上并没有以通常的意义被“包装”。

   def onexit(f):
       import atexit
       atexit.register(f)
       return f
   
   @onexit
   def func():
       ...
   

   请注意，此示例可能不适用于实际使用，仅供示例说明。

2. 定义一个具有单例实例的类。请注意，一旦类消失，有进取心的程序员将不得不更具创造力才能创建更多实例。（来自Shane Hathaway在python-dev上的帖子。）

   def singleton(cls):
       instances = {}
       def getinstance():
           if cls not in instances:
               instances[cls] = cls()
           return instances[cls]
       return getinstance
   
   @singleton
   class MyClass:
       ...
   

3. 向函数添加属性。（基于Anders Munch在python-dev上发布的示例。）

   def attrs(**kwds):
       def decorate(f):
           for k in kwds:
               setattr(f, k, kwds[k])
           return f
       return decorate
   
   @attrs(versionadded="2.2",
          author="Guido van Rossum")
   def mymethod(f):
       ...
   

4. 强制执行函数参数和返回值类型。请注意，这会将func_name属性从旧函数复制到新函数。func_name在Python 2.4a3中被设为可写。

   def accepts(*types):
       def check_accepts(f):
           assert len(types) == f.func_code.co_argcount
           def new_f(*args, **kwds):
               for (a, t) in zip(args, types):
                   assert isinstance(a, t), \
                          "arg %r does not match %s" % (a,t)
               return f(*args, **kwds)
           new_f.func_name = f.func_name
           return new_f
       return check_accepts
   
   def returns(rtype):
       def check_returns(f):
           def new_f(*args, **kwds):
               result = f(*args, **kwds)
               assert isinstance(result, rtype), \
                      "return value %r does not match %s" % (result,rtype)
               return result
           new_f.func_name = f.func_name
           return new_f
       return check_returns
   
   @accepts(int, (int,float))
   @returns((int,float))
   def func(arg1, arg2):
       return arg1 * arg2
   

5. 声明一个类实现了特定（组）接口。这来自Bob Ippolito在python-dev上的帖子，基于使用PyProtocols的经验。

   def provides(*interfaces):
        """
        An actual, working, implementation of provides for
        the current implementation of PyProtocols.  Not
        particularly important for the PEP text.
        """
        def provides(typ):
            declareImplementation(typ, instancesProvide=interfaces)
            return typ
        return provides
   
   class IBar(Interface):
        """Declare something about IBar here"""
   
   @provides(IBar)
   class Foo(object):
           """Implement something here..."""
   

当然，所有这些示例在今天都是可能的，尽管没有语法支持。

（不再是）开放问题

1. 目前尚不确定类装饰器是否会在将来的某个时间点被纳入语言中。Guido对这个概念表示怀疑，但一些人在python-dev上提出了一些强有力的论点（搜索PEP 318 -- posting draft）来支持它们。类装饰器极不可能出现在Python 2.4中。

   PEP 3129 提案自Python 2.6开始添加类装饰器。

2. 在Python 2.4b1之前，将重新审查@字符的选择。

   最终，@字符被保留了下来。

版权

本文档已进入公有领域。