Decorators in Python

Posted on | In

本文参考之前阅读过的文章Python 函数装饰器 和Python进阶中关于装饰器的内容整理而得。原文中存在一些内容我已经较为熟悉，稍微带过，重点记录不太熟悉的部分。

装饰器(Decorators)是 Python 的一个重要部分。简单地说：他们是修改其他函数的功能的函数。他们有助于让我们的代码更简短，也更Pythonic（Python范儿）。

本文讨论如何写你自己的装饰器。在正式开始之前，先明确几个概念：

  • 在python中一切皆是对象。函数，类对事对象；
  • 一个函数可以是另一个函数的参数、返回值；
  • 函数内部可以定义函数
  • 闭包：python中的装饰器实际上是一个闭包。嵌套定义在非全局作用域里面的函数能够记住它在被定义的时候它所处的封闭命名空间。

第一个装饰器

装饰器函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
def a_decorator(a_func):

    def wrapTheFunction():
        print("I am doing some boring work before executing a_func()")
        a_func()
        print("I am doing some boring work after executing a_func()")
    return wrapTheFunction

def a_function_requiring_decoration():
    print("I am the function which needs some decoration to remove my foul smell")

a_function_requiring_decoration()
#outputs: "I am the function which needs some decoration to remove my foul smell"

a_function_requiring_decoration = a_decorator(a_function_requiring_decoration)

a_function_requiring_decoration()
#outputs:I am doing some boring work before executing a_func()
#        I am the function which needs some decoration to remove my foul smell
#        I am doing some boring work after executing a_func()

上面的代码定义了一个需要装饰的函数a_function_requiring_decoration，用函数a_decorator作为装饰器，对a_function_requiring_decoration的行为进行修饰。

装饰器的作用就是对一个函数进行封装，并且用这样或者那样的方式来对它的行为进行修饰。

使用@符号

现在你也许疑惑，我们在代码里并没有使用@符号？那只是一个简短的方式来生成一个被装饰的函数。这里是我们如何使用@来运行之前的代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
def a_decorator(a_func):

    def wrapTheFunction():
        print("I am doing some boring work before executing a_func()")
        a_func()
        print("I am doing some boring work after executing a_func()")
    return wrapTheFunction

@a_decorator
def a_function_requiring_decoration():
    print("I am the function which needs some decoration to remove my foul smell")
# 等价于 a_function_requiring_decoration = a_decorator(a_function_requiring_decoration)
    
a_function_requiring_decoration()
#outputs: I am doing some boring work before executing a_func()
#         I am the function which needs some decoration to remove my foul smell
#         I am doing some boring work after executing a_func()

可以发现@符号和a_function_requiring_decoration = a_decorator(a_function_requiring_decoration)是等价的。

函数属性

如果我们运行如下代码会存在一个问题：

1
2
print(a_function_requiring_decoration.__name__)
# Output: wrapTheFunction

这并不是我们想要的！Ouput输出应该是“a_function_requiring_decoration”。这里的函数被warpTheFunction替代了。它重写了我们函数的名字和注释文档(docstring)。幸运的是Python提供给我们一个简单的函数来解决这个问题，那就是functools.wraps。我们修改上一个例子来使用functools.wraps：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from functools import wraps

def a_decorator(a_func):

    @wraps(a_func)
    def wrapTheFunction():
        print("I am doing some boring work before executing a_func()")
        a_func()
        print("I am doing some boring work after executing a_func()")
    return wrapTheFunction

@a_decorator
def a_function_requiring_decoration():
    print("I am the function which needs some decoration to remove my foul smell")

print(a_function_requiring_decoration.__name__)
# Output: a_function_requiring_decoration

@wraps接受一个函数来进行装饰，并加入了复制函数名称、注释文档、参数列表等等的功能。这可以让我们在装饰器里面访问在装饰之前的函数的属性。

应用场景

现在我们来看一下装饰器在哪些地方特别耀眼，以及使用它可以让一些事情管理起来变得更简单。

授权

装饰器能有助于检查某个人是否被授权去使用一个web应用的端点(endpoint)。它们被大量使用于Flask和Django web框架中。这里是一个例子来使用基于装饰器的授权：

1
2
3
4
5
6
7
8
9
10
from functools import wraps

def requires_auth(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        auth = request.authorization
        if not auth or not check_auth(auth.username, auth.password):
            authenticate()
        return f(*args, **kwargs)
    return decorated

日志

日志是装饰器运用的另一个亮点。这是个例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from functools import wraps

def logit(func):
    @wraps(func)
    def with_logging(*args, **kwargs):
        print(func.__name__ + " was called")
        return func(*args, **kwargs)
    return with_logging

@logit
def addition_func(x):
   """Do some math."""
   return x + x


result = addition_func(4)
# Output: addition_func was called

带参数的装饰器

来想想这个问题，难道@wraps不也是个装饰器吗？但是，它接收一个参数，就像任何普通的函数能做的那样。那么，为什么我们不也那样做呢？

我们回到日志的例子，并创建一个包裹函数，能让我们指定一个用于输出的日志文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
from functools import wraps

def logit(logfile='out.log'):  # 此时是三层函数嵌套
    def logging_decorator(func):
        @wraps(func)
        def wrapped_function(*args, **kwargs):
            log_string = func.__name__ + " was called"
            print(log_string)
            # 打开logfile，并写入内容
            with open(logfile, 'a') as opened_file:
                # 现在将日志打到指定的logfile
                opened_file.write(log_string + '\n')
            return func(*args, **kwargs)
        return wrapped_function
    return logging_decorator

@logit()  # 等价于 myfunc1=logit()(myfunc1)
def myfunc1():
    pass
# 等价于 myfunc1=logit()(myfunc1)

myfunc1()
# Output: myfunc1 was called
# 现在一个叫做 out.log 的文件出现了，里面的内容就是上面的字符串

@logit(logfile='func2.log')  # 等价于 myfunc1=logit(logfile='func2.log')(myfunc1)
def myfunc2():
    pass

myfunc2()
# Output: myfunc2 was called
# 现在一个叫做 func2.log 的文件出现了，里面的内容就是上面的字符串

装饰器类

现在我们有了能用于正式环境的logit装饰器，但当我们的应用的某些部分还比较脆弱时，异常也许是需要更紧急关注的事情。比方说有时你只想打日志到一个文件。而有时你想把引起你注意的问题发送到一个email，同时也保留日志，留个记录。这是一个使用继承的场景，但目前为止我们只看到过用来构建装饰器的函数。

幸运的是，类也可以用来构建装饰器。那我们现在以一个类而不是一个函数的方式，来重新构建logit。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from functools import wraps
 
class logit(object):
    def __init__(self, logfile='out.log'):
        self.logfile = logfile
 
    def __call__(self, func):
        @wraps(func)
        def wrapped_function(*args, **kwargs):
            log_string = func.__name__ + " was called"
            print(log_string)
            # 打开logfile并写入
            with open(self.logfile, 'a') as opened_file:
                # 现在将日志打到指定的文件
                opened_file.write(log_string + '\n')
            # 现在，发送一个通知
            self.notify()
            return func(*args, **kwargs)
        return wrapped_function
 
    def notify(self):
        # logit只打日志，不做别的
        pass

这个实现有一个附加优势，在于比嵌套函数的方式更加整洁，而且包裹一个函数还是使用跟以前一样的语法：

1
2
3
@logit(logfile='out.log')  # 等价于 myfunc1=logit(logfile='out.log')(myfunc1)
def myfunc1():
    pass

现在，我们给logit创建子类，来添加email的功能(虽然email这个话题不会在这里展开)。

1
2
3
4
5
6
7
8
9
10
11
12
class email_logit(logit):
    '''
    一个logit的实现版本，可以在函数调用时发送email给管理员
    '''
    def __init__(self, email='admin@myproject.com', *args, **kwargs):
        self.email = email
        super(email_logit, self).__init__(*args, **kwargs)

    def notify(self):
        # 发送一封email到self.email
        # 这里就不做实现了
        pass

从现在起，@email_logit将会和@logit产生同样的效果，但是在打日志的基础上，还会多发送一封邮件给管理员。

参考资料

https://eastlakeside.gitbooks.io/interpy-zh/content/decorators/