Python装饰器的学习笔记

来自：标点符的《Python装饰器的学习笔记》

链接：http://www.biaodianfu.com/python-decorator.html

原文：http://stackoverflow.com/questions/739654/how-to-make-a-chain-of-function-decorators-in-python#answer-1594484

装饰器(decorator)是一种高级Python语法。可以对一个函数、方法或者类进行加工。在Python中，我们有多种方法对函数和类进行加工，相对于其它方式，装饰器语法简单，代码可读性高。因此，装饰器在Python项目中有广泛的应用。修饰器经常被用于有切面需求的场景，较为经典的有插入日志、性能测试、事务处理, Web权限校验, Cache等。很有名的例子，就是咖啡，加糖的咖啡，加牛奶的咖啡。本质上，还是咖啡，只是在原有的东西上，做了“装饰”，使之附加一些功能或特性。

装饰器的优点是能够抽离出大量函数中与函数功能本身无关的雷同代码并继续重用。即，可以将函数“修饰”为完全不同的行为，可以有效的将业务逻辑正交分解。概括的讲，装饰器的作用就是为已经存在的对象添加额外的功能。例如记录日志，需要对某些函数进行记录。笨的办法，每个函数加入代码，如果代码变了，就悲催了。装饰器的办法，定义一个专门日志记录的装饰器，对需要的函数进行装饰。

Python 的 Decorator在使用上和Java/C#的Annotation很相似，都是在方法名前面加一个@XXX注解来为这个方法装饰一些东西。但是，Java/C#的Annotation也很让人望而却步，在使用它之前你需要了解一堆Annotation的类库文档，让人感觉就是在学另外一门语言。而Python使用了一种相对于Decorator Pattern和Annotation来说非常优雅的方法，这种方法不需要你去掌握什么复杂的OO模型或是Annotation的各种类库规定，完全就是语言层面的玩法：一种函数式编程的技巧。

在Python中，装饰器实现是十分方便。原因是：函数可以被扔来扔去。

python的函数就是对象

要理解装饰器，就必须先知道，在python里，函数也是对象（functions are objects）。明白这一点非常重要，让我们通过一个例子来看看为什么。

def shout(word="yes"):          return word.capitalize()+"!"      
print shout()      # outputs : 'Yes!'      
# 作为一个对象，你可以像其他对象一样把函数赋值给其他变量      
scream = shout      # 注意我们没有用括号：我们不是在调用函数，      
# 而是把函数'shout'的值绑定到'scream'这个变量上      
# 这也意味着你可以通过'scream'这个变量来调用'shout'函数      
print scream()      # outputs : 'Yes!'      
# 不仅如此，这也还意味着你可以把原来的名字'shout'删掉，      
# 而这个函数仍然可以通过'scream'来访问      
del shout      try:          print shout()      except NameError, e:          print e          #outputs: "name 'shout' is not defined"     
 print scream()      outputs: 'Yes!'

python 函数的另一个有趣的特性是，它们可以在另一个函数体内定义。

def talk():       # 你可以在 'talk' 里动态的(on the fly)定义一个函数...       def whisper(word="yes"):           return word.lower()+"..."       # ... 然后马上调用它！       print whisper()   # 每当调用'talk'，都会定义一次'whisper'，然后'whisper'在'talk'里被调用   
talk()   # outputs:   
# "yes..."   
# 但是"whisper" 在 "talk"外并不存在:   
try:       print whisper()   except NameError, e:       print e   #outputs : "name 'whisper' is not defined"*

函数引用（Functions references）

你刚刚已经知道了，python的函数也是对象，因此：

• 可以被赋值给变量

• 可以在另一个函数体内定义

那么，这样就意味着一个函数可以返回另一个函数 :-)，来看个例子：

def getTalk(type="shout"):       # 我们先动态定义一些函数       def shout(word="yes"):           return word.capitalize()+"!"       def whisper(word="yes") :           return word.lower()+"...";       # 然后返回其中一个       if type == "shout":           # 注意：我们是在返回函数对象，而不是调用函数，           # 所以不要用到括号 "()"           return shout        else:           return whisper   # 那你改如何使用这个怪兽呢？(How do you use this strange beast?)   # 先把函数赋值给一个变量   
talk = getTalk()        # 你可以发现 "talk" 其实是一个函数对象:   
print talk   #outputs :    
# 这个对象就是 getTalk 函数返回的:   
print talk()   #outputs : Yes!   
# 你甚至还可以直接这样使用(if you feel wild):   
print getTalk("whisper")()   #outputs : yes...

既然可以返回一个函数，那么也就可以像参数一样传递：

def doSomethingBefore(func):       print "I do something before then I call the function you gave me"       print func()   doSomethingBefore(scream)   #outputs:   
#I do something before then I call the function you gave me   #Yes!

现在已经具备了理解装饰器的所有基础知识了。装饰器也就是一种包装材料，它们可以让你在执行被装饰的函数之前或之后执行其他代码，而且不需要修改函数本身。

手工制作装饰器（Handcrafted decorators）

你可以像这样来定制：

# 一个装饰器是一个需要另一个函数作为参数的函数      
def my_shiny_new_decorator(a_function_to_decorate):          # 在装饰器内部动态定义一个函数：wrapper(原意：包装纸).          # 这个函数将被包装在原始函数的四周          # 因此就可以在原始函数之前和之后执行一些代码.          def the_wrapper_around_the_original_function():              # 把想要在调用原始函数前运行的代码放这里              print "Before the function runs"              # 调用原始函数（需要带括号）              a_function_to_decorate()              # 把想要在调用原始函数后运行的代码放这里              print "After the function runs"          # 直到现在，"a_function_to_decorate"还没有执行过 (HAS NEVER BEEN EXECUTED).          # 我们把刚刚创建的 wrapper 函数返回.          # wrapper 函数包含了这个函数，还有一些需要提前后之后执行的代码，          # 可以直接使用了（It's ready to use!）          return the_wrapper_around_the_original_function      # Now imagine you create a function you don't want to ever touch again.      
def a_stand_alone_function():          print "I am a stand alone function, don't you dare modify me"      a_stand_alone_function()      #outputs: I am a stand alone function, don't you dare modify me      # 现在，你可以装饰一下来修改它的行为.      
# 只要简单的把它传递给装饰器，后者能用任何你想要的代码动态的包装      # 而且返回一个可以直接使用的新函数:      
a_stand_alone_function_decorated = my_shiny_new_decorator(a_stand_alone_function)      a_stand_alone_function_decorated()      #outputs:      
#Before the function runs      
#I am a stand alone function, don't you dare modify me      #After the function runs

现在你大概希望，每次调用 a_stand_alone_function 时，实际调用的是a_stand_alone_function_decorated 。这很容易，只要把 my_shiny_new_decorator 返回的函数覆盖 a_stand_alone_function 就可以了：

a_stand_alone_function = my_shiny_new_decorator(a_stand_alone_function)   a_stand_alone_function()   #outputs:   
#Before the function runs   
#I am a stand alone function, don't you dare modify me   
#After the function runs   
# And guess what? That's EXACTLY what decorators do!

揭秘装饰器(Decorators demystified)

我们用装饰器的语法来重写一下前面的例子：

@my_shiny_new_decorator   
def another_stand_alone_function():       print "Leave me alone"   
another_stand_alone_function()    
#outputs:    
#Before the function runs   
#Leave me alone   
#After the function runs

是的，这就完了，就这么简单。@decorator 只是下面这条语句的简写(shortcut)：

another_stand_alone_function = my_shiny_new_decorator(another_stand_alone_function)

装饰器其实就是装饰器模式的一个python化的变体（pythonic variant）。为了方便开发，python已经内置了好几种经典的设计模式，比如迭代器（iterators）。 当然，你还可以堆积使用装饰器(you can cumulate decorators)：

def bread(func):       def wrapper():           print "''''''>"           func()           print "<______/>"       return wrapper   def ingredients(func):       def wrapper():           print "#tomatoes#"           func()           print "~salad~"       return wrapper   def sandwich(food="--ham--"):       print food   sandwich()   #outputs: --ham--   sandwich = bread(ingredients(sandwich))   sandwich()   #outputs:   
#''''''>   
# #tomatoes#   
# --ham--   
# ~salad~   
#<______/>

用python的装饰器语法表示：

装饰器放置的顺序 很重要：

给装饰器函数传参（Passing arguments to the decorated function）

含参的装饰器

在上面的装饰器调用中，比如@decorator，该装饰器默认它后面的函数是唯一的参数。装饰器的语法允许我们调用decorator时，提供其它参数，比如@decorator(a)。这样，就为装饰器的编写和使用提供了更大的灵活性。

上面的pre_str是允许参数的装饰器。它实际上是对原有装饰器的一个函数封装，并返回一个装饰器。我们可以将它理解为一个含有环境参量的闭包。当我们使用@pre_str(‘^_^’)调用的时候，Python能够发现这一层的封装，并把参数传递到装饰器的环境中。该调用相当于：

装饰方法（Decorating methods）

Python的一个伟大之处在于：方法和函数几乎是一样的(methods and functions are really the same)，除了方法的第一个参数应该是当前对象的引用(也就是 self)。这也就意味着只要记住把 self 考虑在内，你就可以用同样的方法给方法创建装饰器了：

当然，如果你想编写一个非常通用的装饰器，可以用来装饰任意函数和方法，你就可以无视具体参数了，直接使用 *args, **kwargs 就行：

装饰类

在上面的例子中，装饰器接收一个函数，并返回一个函数，从而起到加工函数的效果。在Python 2.6以后，装饰器被拓展到类。一个装饰器可以接收一个类，并返回一个类，从而起到加工类的效果。

在decorator中，我们返回了一个新类newClass。在新类中，我们记录了原来类生成的对象（self.wrapped），并附加了新的属性total_display，用于记录调用display的次数。我们也同时更改了display方法。通过修改，我们的Bird类可以显示调用display的次数了。

给装饰器传参（Passing arguments to the decorator）

现在对于给装饰器本身传参数，你有什么看法呢？好吧，这样说有点绕，因为装饰器必须接受一个函数作为参数，所以就不能把被装饰的函数的参数，直接传给装饰器（you cannot pass the decorated function arguments directly to the decorator.）

在直奔答案之前，我们先写一个小提示：

这完全一样，都是 my_decorator 被调用。所以当你使用 @my_decorator 时，你在告诉 python 去调用 “被变量 my_decorator 标记的” 函数（the function ‘labeled by the variable “my_decorator”‘）。这很重要，因为你给的这个标签能直接指向装饰器或者其他！

不要感到惊讶，让我们做一件完全一样的事情，只不过跳过了中间变量：

def decorated_function():       print "I am the decorated function."   
decorated_function = decorator_maker()(decorated_function)   #outputs:   
#I make decorators! I am executed only once: when you make me create a decorator.   
#As a decorator maker, I return a decorator   
#I am a decorator! I am executed only when you decorate a function.   
#As the decorator, I return the wrapped function.   
# Finally:   
decorated_function()      #outputs:   
#I am the wrapper around the decorated function. I am called when you call the decorated function.   
#As the wrapper, I return the RESULT of the decorated function.   #I am the decorated function.

再做一次，代码甚至更短：

@decorator_maker()   
def decorated_function():       print "I am the decorated function."   
#outputs:   
#I make decorators! I am executed only once: when you make me create a decorator.   
#As a decorator maker, I return a decorator   
#I am a decorator! I am executed only when you decorate a function.   
#As the decorator, I return the wrapped function.   
#Eventually:   
decorated_function()      #outputs:   
#I am the wrapper around the decorated function. I am called when you call the decorated function.   
#As the wrapper, I return the RESULT of the decorated function.   #I am the decorated function.

我们在用 @ 语法调用了函数 ， 那么回到带参数的装饰器。如果我们能够使用一个函数动态（on the fly）的生成装饰器，那么我们就能把参数传递给那个函数，对吗？

def decorator_maker_with_arguments(decorator_arg1, decorator_arg2):       print "I make decorators! And I accept arguments:", decorator_arg1, decorator_arg2       def my_decorator(func):           # 在这里能传参数是一个来自闭包的馈赠.           # 如果你对闭包感到不舒服，你可以直接忽略（you can assume it's ok）,           # 或者看看这里: http://stackoverflow.com/questions/13857/can-you-explain-closures-as-they-relate-to-python           print "I am the decorator. Somehow you passed me arguments:", decorator_arg1, decorator_arg2           # 不要把装饰器参数和函数参数搞混了！           def wrapped(function_arg1, function_arg2) :               print ("I am the wrapper around the decorated function.
"                     "I can access all the variables
"                     "	- from the decorator: {0} {1}
"                     "	- from the function call: {2} {3}
"                     "Then I can pass them to the decorated function"                     .format(decorator_arg1, decorator_arg2,                             function_arg1, function_arg2))               return func(function_arg1, function_arg2)           return wrapped       return my_decorator   @decorator_maker_with_arguments("Leonard", "Sheldon")   def decorated_function_with_arguments(function_arg1, function_arg2):       print ("I am the decorated function and only knows about my arguments: {0}"              " {1}".format(function_arg1, function_arg2))   decorated_function_with_arguments("Rajesh", "Howard")   #outputs:   
#I make decorators! And I accept arguments: Leonard Sheldon   
#I am the decorator. Somehow you passed me arguments: Leonard Sheldon   
#I am the wrapper around the decorated function.   
#I can access all the variables   
#   - from the decorator: Leonard Sheldon   
#   - from the function call: Rajesh Howard   
#Then I can pass them to the decorated function   
#I am the decorated function and only knows about my arguments: Rajesh Howard

这就是了，带参数的装饰器。参数也可以设置为变量：

如你所见，你可以给装饰器传递参数，就好像其他任意一个使用了这种把戏的函数一样（。如果你愿意，甚至可以使用 *args, **kwargs。但是，记住，装置器只调用一次，仅当python导入这个脚本时。你不能在之后动态的设置参数。当你执行 import x 时，这个函数已经被装饰了，因此你不能修改任何东西。

实践：装饰器装饰一个装饰器（Let’s practice: a decorator to decorate a decorator）

我将展示一段能用来创建能接受通用的任意参数的装饰器的代码。毕竟，为了能接受参数，我们用了另一个函数来创建我们的装饰器。我们包装了装饰器。在我们刚刚看到的东西里，还有用来包装函数的吗？是的，就是装饰器。让我们给装饰器写一个装饰器来玩玩：

def decorator_with_args(decorator_to_enhance):       """       This function is supposed to be used as a decorator.       It must decorate an other function, that is intended to be used as a decorator.       Take a cup of coffee.       It will allow any decorator to accept an arbitrary number of arguments,       saving you the headache to remember how to do that every time.       """       # We use the same trick we did to pass arguments       def decorator_maker(*args, **kwargs):           # We create on the fly a decorator that accepts only a function           # but keeps the passed arguments from the maker.           def decorator_wrapper(func):               # We return the result of the original decorator, which, after all,               # IS JUST AN ORDINARY FUNCTION (which returns a function).               # Only pitfall: the decorator must have this specific signature or it won't work:               return decorator_to_enhance(func, *args, **kwargs)          return decorator_wrapper   return decorator_maker

它可以像这样使用：

# You create the function you will use as a decorator. And stick a decorator on it :-)   
# Don't forget, the signature is "decorator(func, *args, **kwargs)"   
@decorator_with_args   
def decorated_decorator(func, *args, **kwargs):       def wrapper(function_arg1, function_arg2):           print "Decorated with", args, kwargs           return func(function_arg1, function_arg2)       return wrapper   # Then you decorate the functions you wish with your brand new decorated decorator.   
@decorated_decorator(42, 404, 1024)   
def decorated_function(function_arg1, function_arg2):       print "Hello", function_arg1, function_arg2   decorated_function("Universe and", "everything")   #outputs:   
#Decorated with (42, 404, 1024) {}   
#Hello Universe and everything   
# Whoooot!

我知道，你上一次有这种感觉，是在听一个人说“在理解递归之前，你必须先理解递归”之后。但是现在，掌握之后，你不觉得很爽吗？

装饰器最佳实践（Best practices while using decorators）

装饰器是在 python 2.4 之后才有的，所以先确定你的代码运行时；

记住这点：装饰器降低了函数调用效率；

你不能“解装饰”一个函数。有一些能用来创建可以移除的装饰器的方法，但没人用它们。所以一个函数一旦被装饰了，就结束了（不能改变了）。

装饰器包装了函数，这使得会难以调试。

Python 2.5 通过提供了一个 functools 模块解决了最后一个问题。functools.wraps 把任意被包装函数的函数名、模块名和 docstring 拷贝给了 wrapper. 有趣的事是，functools.wraps 也是一个装饰器：-）

装饰器如何才能有用（How can the decorators be useful?）

现在问题来了：我能用装饰器来干嘛？看起来很酷也很强大，但是来一个实际例子才更好。一个典型的用途是，用来扩展一个外部导入的函数（你不能修改）的行为，或者为了调试（你不想修改这个函数，因为只是暂时的）。你也可以用装饰器实现只用一段相同的代码来扩展成几个不同的函数，而且你不需要每次都重写这段代码。这样就是常说的 DRY。比如：

def benchmark(func):       """       A decorator that prints the time a function takes       to execute.       """       import time       def wrapper(*args, **kwargs):           t = time.clock()           res = func(*args, **kwargs)           print func.__name__, time.clock()-t           return res       return wrapper   def logging(func):       """       A decorator that logs the activity of the script.       (it actually just prints it, but it could be logging!)       """       def wrapper(*args, **kwargs):           res = func(*args, **kwargs)           print func.__name__, args, kwargs           return res       return wrapper   def counter(func):       """       A decorator that counts and prints the number of times a function has been executed       """       def wrapper(*args, **kwargs):           wrapper.count = wrapper.count + 1           res = func(*args, **kwargs)           print "{0} has been used: {1}x".format(func.__name__, wrapper.count)           return res       wrapper.count = 0       return wrapper   @counter   

@benchmark   
logging   

def reverse_string(string):       return str(reversed(string))   print reverse_string("Able was I ere I saw Elba")   print reverse_string("A man, a plan, a canoe, pasta, heros, rajahs, a coloratura, maps, snipe, percale, macaroni, a gag, a banana bag, a tan, a tag, a banana bag again (or a camel), a crepe, pins, Spam, a rut, a Rolo, cash, a jar, sore hats, a peon, a canal: Panama!")   #outputs:   
#reverse_string ('Able was I ere I saw Elba',) {}   
#wrapper 0.0   
#wrapper has been used: 1x   
#ablE was I ere I saw elbA   
#reverse_string ('A man, a plan, a canoe, pasta, heros, rajahs, a coloratura, maps, snipe, percale, macaroni, a gag, a banana bag, a tan, a tag, a banana bag again (or a camel), a crepe, pins, Spam, a rut, a Rolo, cash, a jar, sore hats, a peon, a canal: Panama!',) {}   
#wrapper 0.0   
#wrapper has been used: 2x   
#!amanaP :lanac a ,noep a ,stah eros ,raj a ,hsac ,oloR a ,tur a ,mapS ,snip ,eperc a ,)lemac a ro( niaga gab ananab a ,gat a ,nat a ,gab ananab a ,gag a ,inoracam ,elacrep ,epins ,spam ,arutaroloc a ,shajar ,soreh ,atsap ,eonac a ,nalp a ,nam A

当然，装饰器的好处就是你可以几乎用来装饰所有东西，而且不要重写。也就是我说的 DRY：

Python 语言本身也提供了一些装饰器：property、staticmethod 等。Django 用装饰器来管理换成和视图权限。Twisted 用来伪装 内联异步函数调用。

总结

装饰器的核心作用是name binding。这种语法是Python多编程范式的又一个体现。大部分Python用户都不怎么需要定义装饰器，但有可能会使用装饰器。鉴于装饰器在Python项目中的广泛使用，了解这一语法是非常有益的。