警告警告警告

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

摘要

当前转换函数和方法（例如，将它们声明为类方法或静态方法）的方法很笨拙，可能导致难以理解的代码。理想情况下，这些转换应该在声明本身的代码的同一位置进行。此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在他的第10届Python大会DevDay主题演讲中提到了装饰器的语法支持，尽管他后来表示这只是他“半开玩笑”提出的几个扩展之一。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-decorator”语法，以纪念在装饰器语法同时发生的Pie-thon Parrot枪战，并且因为@看起来有点像一个馅饼。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的动态特性使得它的语法元素与T其他语言中的类似结构永远不会完全相同，并且确实存在显著的重叠。关于对第三方工具的影响：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之前，将重新审查@字符的选择。

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

版权

本文档已置于公共领域。