浅谈Python装饰器

浅谈Python装饰器

By 马冬亮(凝霜  Loki)

一个人的战争(http://blog.csdn.net/MDL13412)

前置知识

一级对象

Python将一切视为 objec t的子类，即一切都是对象，因此函数可以像变量一样被指向和传递，我们来看下面的例子:

def foo():
    pass
    
print issubclass(foo.__class__, object)

其运行结果如下:

True

上述代码说明了Python 中的函数是 object 的子类，下面让我们看函数被当作参数传递时的效果:

def foo(func):
    func()

def bar():
    print "bar"

foo(bar)

其运行结果如下:

bar

Python中的namespace

Python中通过提供 namespace 来实现重名函数/方法、变量等信息的识别，其一共有三种 namespace，分别为：

• local namespace: 作用范围为当前函数或者类方法
• global namespace: 作用范围为当前模块
• build-in namespace: 作用范围为所有模块

当函数/方法、变量等信息发生重名时，Python会按照 local namespace -> global namespace -> build-in namespace的顺序搜索用户所需元素，并且以第一个找到此元素的 namespace 为准。
下面以系统的 build-in 函数 str 为例进行说明:

def str(s):
    print "global str()"

def foo():
    def str(s):
        print "closure str()"
    str("dummy")

def bar():
    str("dummy")

foo()
bar()

首先定义三个 global namespace 的函数 str、 foo 和 bar，然后在 foo 函数中定义一个内嵌的 local namespace 的函数 str，然后在函数 foo 和 bar 中分别调用  str("dummy")，其运行结果如下所示:

closure str()
global str()

通过编码实验，我们可以看到:

• foo 中调用 str 函数时，首先搜索 local namespace，并且成功找到了所需的函数，停止搜索，使用此namespace 中的定义
• bar 中调用 str 函数时，首先搜索 local namespace，但是没有找到str 方法的定义，因此继续搜索 global namespace，并成功找到了 str 的定义，停止搜索，并使用此定义

下面我们使用Python内置的 `ocals() 和 globals() 函数查看不同 namespace 中的元素定义:

var = "var in global"

def fun():
    var = "var in fun"
    print "fun: " + str(locals())

print "globals: " + str(globals())
fun()

运行结果如下:

globals: {'__builtins__': , '__file__': 'a.py', '__package__': None, 'fun': , 'var': 'var in global', '__name__': '__main__', '__doc__': None}
fun: {'var': 'var in fun'}

通过运行结果，我们看到了 fun 定义了 local namespace 的变量 var，在 global namespace 有一个全局的 var 变量，那么当在 global namespace 中直接访问 var 变量的时候，将会得到 var = "var in global" 的定义，而在 fun 函数的 local namespace 中访问 var 变量，则会得到 fun 私有的 var = "var in fun" 定义。

*args and **kwargs

• *args： 把所有的参数按出现顺序打包成一个 list
• **kwargs：把所有 key-value 形式的参数打包成一个 dict

下面给出一个 *args 的例子:

params_list = (1, 2)
params_tupple = (1, 2)

def add(x, y):
    print x + y

add(*params_list)
add(*params_tupple)

其运行结果如下:

3
3

**kwargs 的例子:

params = {
    'x': 1,
    'y': 2
}

def add(x, y):
    print x + y

add(**params)

其运行结果如下:

3

闭包

闭包在维基百科上的定义如下: 在计算机科学中，闭包（Closure）是词法闭包（Lexical Closure）的简称，是引用了自由变量的函数。这个被引用的自由变量将和这个函数一同存在，即使已经离开了创造它的环境也不例外。所以，有另一种说法认为闭包是由函数和与其相关的引用环境组合而成的实体。

下面给出一个使用闭包实现的 logger factory的例子:

def logger_facroty(prefix="", with_prefix=True):
    if with_prefix:
        def logger(msg):
            print prefix + msg
        return logger
    else:
        def logger(msg):
            print msg
        return logger

logger_with_prefix = logger_facroty("Prefix: ")
logger_without_prefix = logger_facroty(with_prefix=False)
logger_with_prefix("msg")
logger_without_prefix("msg")

其运行结果如下:

Prefix: msg
msg

在上面这个闭包的例子中， prefix 变量时所谓的自由变量，其在 return logger 执行完毕后，便脱离了创建它的环境 logger_factory，但因为其被 logger_factory 中定义的 logger 函数所引用，其生命周期将至少和 logger 函数相同。这样，在 logger 中就可以引用到 logger_factory 作用域内的变量 prefix。
将闭包与 namespace 结合起来:

var = "var in global"

def fun_outer():
    var = "var in fun_outer"
    unused_var = "this var is not used in fun_inner"
    print "fun_outer: " + var
    print "fun_outer: " + str(locals())
    print "fun_outer: " + str(id(var))

    def fun_inner():
        print "fun_inner: " + var
        print "fun_inner: " + str(locals())
        print "fun_inner: " + str(id(var))

    return fun_inner

fun_outer()()

其运行结果如下:

fun_outer: var in fun_outer
fun_outer: {'var': 'var in fun_outer', 'unused_var': 'this var is not used in fun_inner'}
fun_outer: 140228141915584
fun_inner: var in fun_outer
fun_inner: {'var': 'var in fun_outer'}
fun_inner: 140228141915584

在这个例子中，当 fun_outer 被定义时，其内部的定义的 fun_inner 函数对 print "fun_inner: " + var中所引用的 var 变量进行搜索，发现第一个被搜索到的 var 定义在 fun_outer 的 local namespace 中，因此使用此定义，通过 print "fun_outer: " + str(id(var)) 和 print "fun_inner: " + str(id(var))，当 var 超出 fun_outer 的作用域后，依然存活，而 fun_outer 中的 unused_var 变量由于没有被 fun_inner 所引用，因此会被 GC。

探索装饰器

定义

点击打开装饰器在维基百科上的定义链接如下: A decorator is any callable Python object that is used to modify a function, method or class definition. 

基本语法

语法糖

@bar
def foo():
    print "foo"

其等价于:

def foo():
    print "foo"
foo = bar(foo)

无参数装饰器

def foo(func):
    print 'decorator foo'
    return func

@foo
def bar():
    print 'bar'

bar()

foo 函数被用作装饰器，其本身接收一个函数对象作为参数，然后做一些工作后，返回接收的参数，供外界调用。

注意: 时刻牢记 @foo 只是一个语法糖，其本质是 foo = bar(foo)

带参数装饰器

import time

def function_performance_statistics(trace_this=True):
    if trace_this:
       def performace_statistics_delegate(func):
            def counter(*args, **kwargs):
                start = time.clock()
                func(*args, **kwargs)
                end =time.clock()
                print 'used time: %d' % (end - start, )
            return counter
    else:
       def performace_statistics_delegate(func):
            return func
    return performace_statistics_delegate

@function_performance_statistics(True)
def add(x, y):
    time.sleep(3)
    print 'add result: %d' % (x + y,)

@function_performance_statistics(False)
def mul(x, y=1):
    print 'mul result: %d' % (x * y,)

add(1, 1)
mul(10)

上述代码想要实现一个性能分析器，并接收一个参数，来控制性能分析器是否生效，其运行效果如下所示:

add result: 2
used time: 0
mul result: 10

上述代码中装饰器的调用等价于:

add = function_performance_statistics(True)(add(1, 1))
mul = function_performance_statistics(False)(mul(10))

类的装饰器

类的装饰器不常用，因此只简单介绍。

def bar(dummy):
    print 'bar'

def inject(cls):
    cls.bar = bar
    return cls

@inject
class Foo(object):
    pass

foo = Foo()
foo.bar()

上述代码的 inject 装饰器为类动态的添加一个 bar 方法，因为类在调用非静态方法的时候会传进一个 self 指针，因此 bar 的第一个参数我们简单的忽略即可，其运行结果如下:

bar

类装饰器

类装饰器相比函数装饰器，具有灵活度大，高内聚、封装性等优点。其实现起来主要是靠类内部的 __call__ 方法，当使用 @ 形式将装饰器附加到函数上时，就会调用此方法，下面时一个实例:

class Foo(object):
    def __init__(self, func):
        super(Foo, self).__init__()
        self._func = func

    def __call__(self):
        print 'class decorator'
        self._func()

@Foo
def bar():
    print 'bar'

bar()

其运行结果如下:

class decorator
bar

内置装饰器

Python中内置的装饰器有三个: staticmethod、classmethod 和property

staticmethod 是类静态方法，其跟成员方法的区别是没有 self 指针，并且可以在类不进行实例化的情况下调用，下面是一个实例，对比静态方法和成员方法

class Foo(object):
    @staticmethod
    def statc_method(msg):
        print msg

    def member_method(self, msg):
        print msg

foo = Foo()
foo.member_method('some msg')
foo.statc_method('some msg')
Foo.statc_method('some msg')

其运行结果如下:

some msg
some msg
some msg

classmethod 与成员方法的区别在于所接收的第一个参数不是 self 类实例的指针，而是当前类的具体类型，下面是一个实例:

class Foo(object):
    @classmethod
    def class_method(cls):
        print repr(cls)

    def member_method(self):
        print repr(self)

foo = Foo()
foo.class_method()
foo.member_method()

其运行结果如下:

<__main__.Foo object at 0x10a611c50>

property 是属性的意思，即可以通过通过类实例直接访问的信息，下面是具体的例子:

class Foo(object):
    def __init__(self, var):
        super(Foo, self).__init__()
        self._var = var

    @property
    def var(self):
        return self._var

    @var.setter
    def var(self, var):
        self._var = var

foo = Foo('var 1')
print foo.var
foo.var = 'var 2'
print foo.var

注意: 如果将上面的 @var.setter 装饰器所装饰的成员函数去掉，则 Foo.var 属性为只读属性，使用 foo.var = 'var 2' 进行赋值时会抛出异常，其运行结果如下:

var 1
var 2

注意: 如果使用老式的Python类定义，所声明的属性不是 read only的，下面代码说明了这种情况:

class Foo:
    def __init__(self, var):
        self._var = var

    @property
    def var(self):
        return self._var

foo = Foo('var 1')
print foo.var
foo.var = 'var 2'
print foo.var

其运行结果如下:

var 1
var 2

调用顺序

装饰器的调用顺序与使用 @ 语法糖声明的顺序相反，如下所示:

def decorator_a(func):
    print "decorator_a"
    return func

def decorator_b(func):
    print "decorator_b"
    return func

@decorator_a
@decorator_b
def foo():
    print "foo"
    
foo()

其等价于:

def decorator_a(func):
    print "decorator_a"
    return func

def decorator_b(func):
    print "decorator_b"
    return func

def foo():
    print "foo"

foo = decorator_a(decorator_b(foo))
foo()

通过等价的调用形式我们可以看到，按照python的函数求值序列， decorator_b(fun) 会首先被求值，然后将其结果作为输入，传递给 decorator_a，因此其调用顺序与声明顺序相反。其运行结果如下所示:

decorator_b
decorator_a
foo

调用时机

装饰器很好用，那么它什么时候被调用？性能开销怎么样？会不会有副作用？接下来我们就以几个实例来验证我们的猜想。
首先我们验证一下装饰器的性能开销，代码如下所示:

def decorator_a(func):
    print "decorator_a"
    print 'func id: ' + str(id(func))
    return func

def decorator_b(func):
    print "decorator_b"
    print 'func id: ' + str(id(func))
    return func

print 'Begin declare foo with decorators'
@decorator_a
@decorator_b
def foo():
    print "foo"
print 'End declare foo with decorators'

print 'First call foo'
foo()
print 'Second call foo'
foo()
print 'Function infos'
print 'decorator_a id: ' + str(id(decorator_a))
print 'decorator_b id: ' + str(id(decorator_b))
print 'fooid : ' + str(id(foo))

其运行结果如下:

Begin declare foo with decorators
decorator_b
func id: 140124961990488
decorator_a
func id: 140124961990488
End declare foo with decorators
First call foo
foo
Second call foo
foo
Function infos
decorator_a id: 140124961954464
decorator_b id: 140124961988808
fooid : 140124961990488

在运行结果中的:

Begin declare foo with decorators
decorator_b
func id: 140124961990488
decorator_a
func id: 140124961990488
End declare foo with decorators

证实了装饰器的调用时机为: 被装饰对象定义时
而运行结果中的:

First call foo
foo
Second call foo
foo

证实了在相同 .py 文件中，装饰器对所装饰的函数只进行一次装饰，不会每次调用相应函数时都重新装饰，这个很容易理解，因为其本质等价于下面的函数签名重新绑定:

foo = decorator_a(decorator_b(foo))

对于跨模块的调用，我们编写如下结构的测试代码:

.
├── common
│   ├── decorator.py
│   ├── __init__.py
│   ├── mod_a
│   │   ├── fun_a.py
│   │   └── __init__.py
│   └── mod_b
│       ├── fun_b.py
│       └── __init__.py
└── test.py

上述所有模块中的 __init__.py 文件均为: # -*- coding: utf-8 -*-

# -*- coding: utf-8 -*-
# common/mod_a/fun_a.py


from common.decorator import foo


def fun_a():
    print 'in common.mod_a.fun_a.fun_a call foo'
    foo()

# -*- coding: utf-8 -*-
# common/mod_b/fun_b.py

from common.decorator import foo

def fun_b():
    print 'in common.mod_b.fun_b.fun_b call foo'
    foo()

# -*- coding: utf-8 -*-
# common/decorator.py

def decorator_a(func):
    print 'init decorator_a'
    return func

@decorator_a
def foo():
    print 'function foo'

# -*- coding: utf-8 -*-
# test.py

from common.mod_a.fun_a import fun_a
from common.mod_b.fun_b import fun_b

fun_a()
fun_b()

上述代码通过创建 common.mod_a 和 common.mod_b 两个子模块，并调用 common.decorator 中的 foo 函数，来测试跨模块时装饰器的工作情况，运行 test.py 的结果如下所示:

init decorator_a
in common.mod_a.fun_a.fun_a call foo
function foo
in common.mod_b.fun_b.fun_b call foo
function foo

经过上面的验证，可以看出，对于跨模块的调用，装饰器也只会初始化一次，不过这要归功于 *.pyc，这与本文主题无关，故不详述。
关于装饰器副作用的话题比较大，这不仅仅是装饰器本身的问题，更多的时候是我们设计上的问题，下面给出一个初学装饰器时大家都会遇到的一个问题——丢失函数元信息:

def decorator_a(func):
    def inner(*args, **kwargs):
        res = func(*args, **kwargs)
        return res
    return inner

@decorator_a
def foo():
    '''foo doc'''
    return 'foo result'

print 'foo.__module__: ' + str(foo.__module__)
print 'foo.__name__: ' + str(foo.__name__)
print 'foo.__doc__: ' + str(foo.__doc__)
print foo()

其运行结果如下所示:

foo.__module__: __main__
foo.__name__: inner
foo.__doc__: None
foo result

我们可以看到，在使用 decorator_a 对 foo 函数进行装饰后，foo 的元信息会丢失，解决方案参见:  functools.wraps

多个装饰器运行期行为

前面已经讲解过装饰器的调用顺序和调用时机，但是被多个装饰器装饰的函数，其运行期行为还是有一些细节需要说明的，而且很可能其行为会让你感到惊讶，下面时一个实例:

def tracer(msg):
    print "[TRACE] %s" % msg

def logger(func):
    tracer("logger")
    def inner(username, password):
        tracer("inner")
        print "call %s" % func.__name__
        return func(username, password)
    return inner

def login_debug_helper(show_debug_info=False):
    tracer("login_debug_helper")
    def proxy_fun(func):
        tracer("proxy_fun")
        def delegate_fun(username, password):
            tracer("delegate_fun")
            if show_debug_info:
                print "username: %s\npassword: %s" % (username, password)
            return func(username, password)
        return delegate_fun
    return proxy_fun

print 'Declaring login_a'

@logger
@login_debug_helper(show_debug_info=True)
def login_a(username, password):
    tracer("login_a")
    print "do some login authentication"
    return True

print 'Call login_a'
login_a("mdl", "pwd")

大家先来看一下运行结果，看看是不是跟自己想象中的一致:

Declaring login_a
[TRACE] login_debug_helper
[TRACE] proxy_fun
[TRACE] logger
Call login_a
[TRACE] inner
call delegate_fun
[TRACE] delegate_fun
username: mdl
password: pwd
[TRACE] login_a
do some login authentication

首先，装饰器初始化时的调用顺序与我们前面讲解的一致，如下:

Declaring login_a
[TRACE] login_debug_helper
[TRACE] proxy_fun
[TRACE] logger

然而，接下来，来自 logger 装饰器中的 inner 函数首先被执行，然后才是 login_debug_helper 返回的 proxy_fun 中的 delegate_fun 函数。各位读者发现了吗，运行期执行 login_a 函数的时候，装饰器中返回的函数的执行顺序是相反的，难道是我们前面讲解的例子有错误吗？其实，如果大家的认为运行期调用顺序应该与装饰器初始化阶段的顺序一致的话，那说明大家没有看透这段代码的调用流程，下面我来为大家分析一下。

def login_debug_helper(show_debug_info=False):
    tracer("login_debug_helper")
    def proxy_fun(func):
        tracer("proxy_fun")
        def delegate_fun(username, password):
            tracer("delegate_fun")
            if show_debug_info:
                print "username: %s\npassword: %s" % (username, password)
            return func(username, password)
        return delegate_fun
    return proxy_fun

当装饰器 login_debug_helper 被调用时，其等价于:

login_debug_helper(show_debug_info=True)(login_a)('mdl', 'pwd')

对于只有 login_debug_helper 的情况，现在就应该是执行玩 login_a输出结果的时刻了，但是如果现在在加上 logger 装饰器的话，那么这个 login_debug_helper(show_debug_info=True)(login_a)('mdl', 'pwd')就被延迟执行，而将 login_debug_helper(show_debug_info=True)(login_a) 作为参数传递给 logger，我们令 login_tmp = login_debug_helper(show_debug_info=True)(login_a)，则调用过程等价于:

login_tmp = login_debug_helper(show_debug_info=True)(login_a)
login_a = logger(login_tmp)
login_a('mdl', 'pwd')

相信大家看过上面的等价变换后，已经明白问题出在哪里了，如果你还没有明白，我强烈建议你把这个例子自己敲一遍，并尝试用自己的方式进行化简，逐步得出结论。

一些实例参考

本文主要讲解原理性的东西，具体的实例可以参考下面的链接:
Python装饰器实例：调用参数合法性验证

Python装饰器与面向切面编程

Python装饰器小结

Python tips: 超时装饰器, @timeout decorator

python中判断一个运行时间过长的函数

python利用装饰器和threading实现异步调用

python输出指定函数运行时间的装饰器

python通过装饰器和线程限制函数的执行时间

python装饰器的一个妙用

通过 Python 装饰器实现DRY(不重复代码)原则

参考资料

Understanding Python Decorators in 12 Easy Steps

Decorators and Functional Python

Python Wiki: PythonDecorators

Meta-matters: Using decorators for better Python programming

Python装饰器入门（译）

Python装饰器与面向切面编程

Python 的闭包和装饰器

Python装饰器学习（九步入门）

python 装饰器和 functools 模块