07-05 裝飾器

[TOC]

一 裝飾器介紹

1.1 爲何要用裝飾器

插圖：惡搞圖32

軟件的設計應該遵循開放封閉原則，即對擴展是開放的，而對修改是封閉的。對擴展開放，意味着有新的需求或變化時，可以對現有代碼進行擴展，以適應新的情況。對修改封閉，意味着對象一旦設計完成，就可以獨立完成其工作，而不要對其進行修改。

軟件包含的所有功能的源代碼以及調用方式，都應該避免修改，否則一旦改錯，則極有可能產生連鎖反應，最終導致程序崩潰，而對於上線後的軟件，新需求或者變化又層出不窮，我們必須爲程序提供擴展的可能性，這就用到了裝飾器。

1.2 什麼是裝飾器

插圖：惡搞圖33

’裝飾’代指爲被裝飾對象添加新的功能，’器’代指器具/工具，裝飾器與被裝飾的對象均可以是任意可調用對象。概括地講，裝飾器的作用就是在不修改被裝飾對象源代碼和調用方式的前提下爲被裝飾對象添加額外的功能。裝飾器經常用於有切面需求的場景，比如：插入日誌、性能測試、事務處理、緩存、權限校驗等應用場景，裝飾器是解決這類問題的絕佳設計，有了裝飾器，就可以抽離出大量與函數功能本身無關的雷同代碼並繼續重用。

提示：可調用對象有函數，方法或者類，此處我們單以本章主題函數爲例，來介紹函數裝飾器，並且被裝飾的對象也是函數。

二 裝飾器的實現

函數裝飾器分爲：無參裝飾器和有參裝飾兩種，二者的實現原理一樣，都是’函數嵌套+閉包+函數對象’的組合使用的產物。

插圖：惡搞圖35

2.1 無參裝飾器的實現

如果想爲下述函數添加統計其執行時間的功能

import time

def index():
    time.sleep(3)
    print('Welcome to the index page’)
    return 200

index() #函數執行

遵循不修改被裝飾對象源代碼的原則，我們想到的解決方法可能是這樣

start_time=time.time()
index() #函數執行
stop_time=time.time()
print('run time is %s' %(stop_time-start_time))

插圖：惡搞圖36

考慮到還有可能要統計其他函數的執行時間，於是我們將其做成一個單獨的工具，函數體需要外部傳入被裝飾的函數從而進行調用，我們可以使用參數的形式傳入

def wrapper(func): # 通過參數接收外部的值
    start_time=time.time()
    res=func()
    stop_time=time.time()
    print('run time is %s' %(stop_time-start_time))
    return res

但之後函數的調用方式都需要統一改成

wrapper(index)
wrapper(其他函數)

這便違反了不能修改被裝飾對象調用方式的原則，於是我們換一種爲函數體傳值的方式，即將值包給函數，如下

def timer(func):
    def wrapper(): # 引用外部作用域的變量func
        start_time=time.time()
        res=func()
        stop_time=time.time()
        print('run time is %s' %(stop_time-start_time))
        return res
    return wrapper

這樣我們便可以在不修改被裝飾函數源代碼和調用方式的前提下爲其加上統計時間的功能，只不過需要事先執行一次timer將被裝飾的函數傳入，返回一個閉包函數wrapper重新賦值給變量名 /函數名index，如下

index=timer(index)  #得到index=wrapper，wrapper攜帶對外作用域的引用：func=原始的index
index() # 執行的是wrapper()，在wrapper的函數體內再執行最原始的index

插圖：惡搞圖39

至此我們便實現了一個無參裝飾器timer，可以在不修改被裝飾對象index源代碼和調用方式的前提下爲其加上新功能。但我們忽略了若被裝飾的函數是一個有參函數，便會拋出異常

def home(name):
    time.sleep(5)
    print('Welcome to the home page',name)

home=timer(home)
home('egon')
#拋出異常
TypeError: wrapper() takes 0 positional arguments but 1 was given 

之所以會拋出異常，是因爲home(‘egon’)調用的其實是wrapper(‘egon’)，而函數wrapper沒有參數。wrapper函數接收的參數其實是給最原始的func用的，爲了能滿足被裝飾函數參數的所有情況，便用上*args+**kwargs組合（見4.3小節）,於是修正裝飾器timer如下

def timer(func):
    def wrapper(*args,**kwargs):
        start_time=time.time()
        res=func(*args,**kwargs)
        stop_time=time.time()
        print('run time is %s' %(stop_time-start_time))
        return res
    return wrapper

插圖：惡搞圖37

此時我們就可以用timer來裝飾帶參數或不帶參數的函數了，但是爲了簡潔而優雅地使用裝飾器，Python提供了專門的裝飾器語法來取代index=timer(index)的形式，需要在被裝飾對象的正上方單獨一行添加@timer,當解釋器解釋到@timer時就會調用timer函數，且把它正下方的函數名當做實參傳入，然後將返回的結果重新賦值給原函數名

@timer # index=timer(index)
def index():
    time.sleep(3)
    print('Welcome to the index page')
    return 200
@timer # index=timer(home)
          def home(name):
    time.sleep(5)
    print('Welcome to the home page’,name)

如果我們有多個裝飾器，可以疊加多個

@deco3
@deco2
@deco1
def index():
    pass

疊加多個裝飾器也無特殊之處，上述代碼語義如下：

index=deco3(deco2(deco1(index)))

插圖：惡搞圖38

2.2 有參裝飾器的實現

瞭解無參裝飾器的實現原理後，我們可以再實現一個用來爲被裝飾對象添加認證功能的裝飾器，實現的基本形式如下

def deco(func):
    def wrapper(*args,**kwargs):
        編寫基於文件的認證,認證通過則執行res=func(*args,**kwargs),並返回res
    return wrapper

如果我們想提供多種不同的認證方式以供選擇，單從wrapper函數的實現角度改寫如下

  def deco(func):
        def wrapper(*args,**kwargs):
            if driver == 'file':
                編寫基於文件的認證,認證通過則執行res=func(*args,**kwargs),並返回res
            elif driver == 'mysql':
                編寫基於mysql認證,認證通過則執行res=func(*args,**kwargs),並返回res
        return wrapper

插圖：惡搞圖40

函數wrapper需要一個driver參數，而函數deco與wrapper的參數都有其特定的功能，不能用來接受其他類別的參數，可以在deco的外部再包一層函數auth，用來專門接受額外的參數，這樣便保證了在auth函數內無論多少層都可以引用到

def auth(driver):
    def deco(func):
        ……
    return deco

此時我們就實現了一個有參裝飾器，使用方式如下

#先調用auth_type(driver='file')，得到@deco，deco是一個閉包函數，包含了對外部作用域名字driver的引用，@deco的語法意義與無參裝飾器一樣
@auth(driver='file')
def index():
    pass

@auth(driver='mysql')
def home():
    pass

可以使用help(函數名)來查看函數的文檔註釋，本質就是查看函數的doc屬性，但對於被裝飾之後的函數，查看文檔註釋

@timer
def home(name):
    '''
    home page function
    :param name: str
    :return: None
    '''
    time.sleep(5)
    print('Welcome to the home page',name)

print(help(home))
'''
打印結果：

Help on function wrapper in module __main__:

wrapper(*args, **kwargs)

None
'''

插圖：惡搞圖41

在被裝飾之後home=wrapper,查看home.name也可以發現home的函數名確實是wrapper，想要保留原函數的文檔和函數名屬性，需要修正裝飾器

def timer(func):
    def wrapper(*args,**kwargs):
        start_time=time.time()
        res=func(*args,**kwargs)
        stop_time=time.time()
        print('run time is %s' %(stop_time-start_time))
        return res
    wrapper.__doc__=func.__doc__
    wrapper.__name__=func.__name__
    return wrapper

按照上述方式來實現保留原函數屬性過於麻煩，functools模塊下提供一個裝飾器wraps專門用來幫我們實現這件事，用法如下

from functools import wraps

def timer(func):
    @wraps(func)
    def wrapper(*args,**kwargs):
        start_time=time.time()
        res=func(*args,**kwargs)
        stop_time=time.time()
        print('run time is %s' %(stop_time-start_time))
        return res
    return wrapper

插圖：惡搞圖42