警告警告警告

本文件旨在描述裝飾器語法以及導致這些決策的流程。它不試圖涵蓋大量潛在的替代語法，也不試圖詳盡列出每種形式的所有優缺點。

摘要

當前轉換函式和方法（例如，將它們宣告為類方法或靜態方法）的方法很笨拙，可能導致難以理解的程式碼。理想情況下，這些轉換應該在宣告本身的程式碼的同一位置進行。此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之前，將重新審查@字元的選擇。

   最終，@字元被保留了下來。

版權

本文件已置於公共領域。