【低門檻 手把手】python 裝飾器(Decorators)原理說明

本文目的是由淺入深地介紹python裝飾器原理

裝飾器(Decorators)是 Python 的一個重要部分
其功能是，在不修改原函式(類)定義程式碼的情況下，增加新的功能
為了理解和實現裝飾器，我們先引入2個核心操作：

1 必要的2個核心操作

1.1 核心操作1， 函式內部可以定義函式

def hi(name='world'):
    print(f"hello, {name}")

    def howdoyoudo(name2=name):
        print(f"how do you do? {name2}")

    howdoyoudo()
    howdoyoudo('world')
    
hi("ytt") 
hi("ycy") 

try:
    howdoyoudo()
except:
    print("function not found")

在這個例子中，函式hi的形參name，預設為'world'
在函式內部，又定義了另一個函式 howdoyoudo，定義這個函式時，將形參name作為新函式的形參name2的預設值。
因此，在函式內部呼叫howdoyoudo()時，將以呼叫hi時的實參為預設值，但也可以給howdoyoudo輸入其他引數。
上面的例子執行後輸出結果為：

hello, ytt
how do you do? ytt
how do you do? world
hello, ycy
how do you do? ycy
how do you do?
worldfunction not found

這裡新定義的howdoyoudo可以稱作一個“閉包”。不少關於裝飾器的blog都提到了這個概念，但其實沒必要給它取一個多專業的名字。我們知道閉包是函式內的函式就可以了

1.2 核心操作2 函式可以作為物件被輸入輸出

1.2.1 核心操作2的前置條件，函式是物件

當我們進行 def 的時候，我們在做什麼？

def hi():
    print("hi")
    return "world"

這時，hi函式，列印一個字串，同時返回一個字串。
但hi函式本身也是一個物件，一個可以執行的物件。執行的方式是hi()。
這裡hi和hi()有本質區別，
hi 代表了這個函式物件本身
hi() 則是執行了函式，得到函式的返回值。

def hi(name='world'):
    print(f"hello, {name}")
    return name
msg = hi()  # 執行函式，返回字串，因此msg是個字串
print(msg)
hello = hi  # 將函式本身賦值給hello，此時hello是另一個函式，即使刪除原函式hi，新函式hello也可以正常呼叫
del hi  # 刪除原函式hi
try:
    hi()
except:
    print("func hi not found")
hello("ycy") # 但是新函式還是存在的。

作為對比，可以想象以下程式碼

a = 'example'
b = a 
del a

此時也是b存在，可以正常使用。

1.2.2函式作為輸入

我們定義2個函式，分別實現自加1， 自乘2，
再定義一個函式double_exec，內容是將某個函式呼叫2次
在呼叫double_exec時，可以將函式作為輸入傳進來

def func1(n):
    return n+1
    
def func2(n):
    return n*2
    
def double_exec(f,x):
    return f(f(x))    
    
rst = double_exec(func1, 5)
print(rst)
rst = double_exec(func2, 3)
print(rst)

輸出結果就是

7
27

1.2.3 函式作為輸出

同樣，也可以將函式作為輸出

def select_func(i):
    def func1(n):
        return n+1

    def func2(n):
        return n*2
    func_list = [func1, func2]    
    return func_list[i]
    
func = select_func(0)  # 第1個函式
print(func(5))
func = select_func(1)  # 第2個函式
print(func(5))

輸出結果為

6
10

2 嘗試構造裝飾器

有了以上兩個核心操作，我們可以嘗試構造裝飾器了。
裝飾器的目的：在不修改原函式(類)定義程式碼的情況下，增加新的功能
試想一下，現在有一個原函式

def original_function:
    print("this is original function")

在不修改原函式定義程式碼的情況下，如果想進行函式內容的新增，可以將這個函式作為一個整體，新增到這樣的包裹中：

def my_decorator(f):
    def wrap_func():
        print(f"before call {f.__name__}")
        f()
        print(f"after call {f.__name__}")
    return wrap_func
new_function = my_decorator(original_function)

我們定義了一個my_decorator函式，這個函式進行了一種操作：
對傳入的f，新增操作(執行前後增加列印)，並把新增操作後的內容連同執行原函式的內容，一起傳出
這個my_decorator，定義了一種增加前後列印內容的行為
呼叫my_decorator時，對這個行為進行了操作。
因此，new_function是一個在original_function上增加了前後列印行為的新函式
這個過程被可以被稱作裝飾。

例子中的物件	角色	說明
wrap	閉包函式	重新定義了一種格式，這個格式可以任意的，是裝飾器的真正內容
my_decorator	裝飾器	定義了按warp這種格式進行操作的函式
f	待裝飾函式(形參)	在定義裝飾器時，待裝飾函式只是一個引數
original_function	實際進行裝飾的函式	一個具體的需要裝飾的函式
new_function	裝飾後的函式	一個具體的裝飾完成的函式

這裡已經可以發現，裝飾器本身對於被裝飾的函式是什麼，是不需要考慮的。裝飾器本身只定義了一種裝飾行為，這個行為是通過裝飾器內部的閉包函式()進行定義的。
執行裝飾前後的函式，可以清晰看到裝飾的效果

def original_function():
    print("this is original function")
    
def my_decorator(f):
    def wrap_func():
        print(f"before calling {f.__name__}")
        f()
        print(f"after calling {f.__name__}")
    return wrap_func


new_function = my_decorator(original_function)
original_function()
print("#########")
new_function()

3裝飾器定義的簡寫

我們復現一下實際要用裝飾器的情況，我們往往有一種裝飾器，想應用於很多個函式，比如

def my_decorator(f):
    def wrap_func():
        print(f"before calling {f.__name__}")
        f()
        print(f"after calling {f.__name__}")
    return wrap_func

def print1():
    print("num=1")
def print2():
    print("num=2")
def print3():
    print("num=3")

此時，如果我們想給3個print函式都加上裝飾器，需要這麼做

new_print1 = my_decorator(print1)
new_print2 = my_decorator(print2)
new_print3 = my_decorator(print3)

實際呼叫的時候，就需要呼叫新增裝飾器的函式名了

new_print1()
new_print2()
new_print3()

當然，也可以賦值給原函式名

print1 = my_decorator(print1)
print1 = my_decorator(print2)
print3 = my_decorator(print3)

這樣至少不需要管理一系列裝飾前後的函式。
同時，在不需要進行裝飾的時候，需要把

print1 = my_decorator(print1)
print1 = my_decorator(print2)
print3 = my_decorator(print3)

全部刪掉。

事實上，這樣並不方便，尤其對於更復雜的裝飾器來說
為此，python提供了一種簡寫方式

def my_decorator(f):
    def wrap_func():
        print(f"before calling {f.__name__}")
        f()
        print(f"after calling {f.__name__}")
    return wrap_func

@my_decorator
def print1():
    print("num=1") 

這個定義print1函式前的@my_decorator，相當於在定義完print1後，自動直接執行了

print1 = my_decorator(print1)

一個新的麻煩及解決辦法

不論採用@my_decorator放在新函式前，還是顯示地重寫print1 = my_decorator(print1)，都會存在一個問題：
裝飾後的函式，名字改變了(其實不止名字，一系列的索引都改變了)

def print1():
    print("num=1") 
    
print(f"before decorate, function name: {print1.__name__}")
print1 = my_decorator(print1)
print(f"after decorate, function name: {print1.__name__}")

輸出結果為:

before decorate, function name: print1
after decorate, function name: wrap_func

這個現象的原因是，裝飾行為本身，是通過構造了一個新的函式（例子中是wrap_func函式）來實現裝飾這個行為的，然後把這個修改後的函式賦給了原函式名。
這樣，會導致我們預期的被裝飾函式的一些系統變數（比如__name__）發生了變化。
對此，python提供瞭解決方案：

from functools import wraps  # 匯入一個系統工具
def my_decorator(f):
    @wraps(f)  # 在定義裝飾行為函式的時候，增加一個新的裝飾器
    def wrap_func():
        print(f"before calling {f.__name__}")
        f()
        print(f"after calling {f.__name__}")
    return wrap_func

經過這個行為後，被裝飾函式的系統變數問題被解決了

def print1():
    print("num=1") 
    
print(f"before decorate, function name: {print1.__name__}")
print1 = my_decorator(print1)
print(f"after decorate, function name: {print1.__name__}")

輸出結果為

before decorate, function name: print1
after decorate, function name: print1

當然，如果你不需要使用一些系統變數，也可以不關注這個問題。

複雜一點的情況1 被裝飾函式有輸入輸出

剛才的例子都比較簡單，被裝飾的函式是沒有引數的。如果被裝飾的函式有引數，只需要在定義裝飾行為時（事實上，這個才更通用），增加(*args, **kwargs)描述即可

from functools import wraps  
def my_decorator(f):
    @wraps(f)  
    def wrap_func(*args, **kwargs):  # 增加了輸入引數
        print(f"before calling {f.__name__}")
        ret = f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出
        print(f"after calling {f.__name__}") # line-after
        return ret  # 執行 "line-after" 後，將f的輸出返回
    return wrap_func

之前的描述中可以感受到，對於例子中的裝飾行為(前後加列印)，函式被裝飾後，本質上是呼叫了新的裝飾函式wrap_func。
因此，如果原函式需要有輸入引數傳遞，只需要在wrap_func（或其他任意名字的裝飾函式）定義時，也增加引數輸入(*args, **kwargs)，並將這些引數，原封不動地傳給待裝飾函式f。
這種定義裝飾行為的方式更具有普遍性，忘記之前的定義方式吧
我們試一下

@my_decorator
def my_add(x, y):
    return x + y
    
n = my_add(1, 3)
print(n)

輸出

before calling my_add
after calling my_add
4

這裡需要注意的是，如果按照以下的方式定義裝飾器

from functools import wraps  
def my_decorator(f):
    @wraps(f)  
    def wrap_func(*args, **kwargs):  # 增加了輸入引數
        print(f"before calling {f.__name__}")
        return f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出
        print(f"after calling {f.__name__}") # line-after        
    return wrap_func

那麼以下語句將不會執行

 print(f"after calling {f.__name__}") # line-after        

因為裝飾後實際的函式wrap_func(雖然名字被改成了原函式，系統引數也改成了原函式)，執行到return f(*args, **kwargs) 的時候已經結束了

複雜一點的情況2 裝飾器有輸入

因為裝飾器my_decorator本身也是可以輸入的，因此，只需要在定義裝飾器時，增加引數，並在後續函式中使用就可以了，比如

from functools import wraps  
def my_decorator(f, msg=""):
    @wraps(f)  
    def wrap_func(*args, **kwargs):  # 增加了輸入引數
        print(f"{msg}, before calling {f.__name__}")
        return f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出
        print(f"{msg}, after calling {f.__name__}") # line-after        
    return wrap_func

此時裝飾器已經可以有輸入引數了

def my_add(x, y):
    return x + y

my_add = my_decorator(my_add, 'yusheng')
    
n = my_add(1, 3)
print(n)

輸出

yusheng, before calling my_add
yusheng, after calling my_add
4

你可能發現，為什麼不用簡寫版的方法了

@my_decorator(msg='yusheng')
def my_add(x, y):
    return x + y
    
n = my_add(1, 3)
print(n)

因為以上程式碼會報錯！！
究其原因，雖然

@my_decorator
def my_add(x, y):
    return x + y

等價於

def my_add(x, y):
    return x + y
my_add = my_decorator(my_add)

但是，

@my_decorator(msg='yusheng')
def my_add(x, y):
    return x + y

並不等價於

def my_add(x, y):
    return x + y
my_add = my_decorator(my_add, msg='yusheng')

這本身和@語法有關，使用@my_decorator時，是系統在應用一個以單個函式作為引數的閉包函式。即，@是不能帶引數的。
但是你應該發現了，之前的@wraps(f)不是帶引數了嗎？請仔細觀察以下程式碼

def my_decorator_with_parma(msg='')
    def my_decorator(f):
        @wraps(f)  
        def wrap_func(*args, **kwargs):  # 增加了輸入引數
            print(f"{msg}, before calling {f.__name__}")
            return f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出
            print(f"{msg}, after calling {f.__name__}") # line-after        
        return wrap_func
    return my_decorator    

通過一層巢狀，my_decorator_with_parma本質上是返回了一個引數僅為一個函式的函式(my_decorator)，但因為my_decorator對my_decorator_with_parma來說是一個閉包，my_decorator_with_parma是可以帶引數的。（這句話真繞）
通過以上的定義，我們再來看

@my_decorator_with_parma(msg='yusheng')
def my_add(x, y):
    return x + y

可以這麼理解，my_decorator_with_parma(msg='yusheng')的結果是原來的my_decorator函式，同時，因為my_decorator_with_parma可以傳參，引數實際上是參與了my_decorator的（因為my_decorator對my_decorator_with_parma是閉包），my_decorator_with_parma(msg='yusheng')全等於一個有引數參加的my_decorator
因此，以上程式碼等價於有引數msg傳遞的

@my_decorator
def my_add(x, y):
    return x + y

比較繞，需要理解一下，或者乾脆強記這種正規化：

from functools import wraps  
def my_decorator(msg=''):  # 名字改一下
    def inner_decorator(f):  # 名字改一下
        @wraps(f)  
        def wrap_func(*args, **kwargs):  # 增加了輸入引數
            print(f"{msg}, before calling {f.__name__}")
            ret = f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出
            print(f"{msg}, after calling {f.__name__}") # line-after        
            return ret
        return wrap_func
    return inner_decorator

以上正規化包含函式的輸入輸出、裝飾器的輸入，可以應對大部分情況了。
實驗一下：

@my_decorator(msg='yusheng')
def my_add(x, y):
    return x + y

my_add(1, 2)

輸出

yusheng, before calling my_add
yusheng, after calling my_add

有用的函式裝飾器例子

統計耗時的日誌

from functools import wraps
import datetime

def log(output_path=None):  # 名字改一下
    def decorator(f):  # 名字改一下
        @wraps(f)  
        def wrap_func(*args, **kwargs):  # 增加了輸入引數
            now = datetime.datetime.now()
            msg = now.strftime("%Y-%m-%d %H:%M:%S")  # 執行時刻
            msg += f" {f.__name__}()\n"  # 執行的函式名            

            ret = f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出

            aft = datetime.datetime.now()
            time_cost = aft - now
            ms = time_cost.total_seconds() * 10**3  # 毫秒
            msg += now.strftime("%Y-%m-%d %H:%M:%S")
            msg += f" {f.__name__}() return, cost {ms} ms"
            if output_path is None:
                print(msg)
            else:
                print(f"print logs into {output_path}")
                with open(output_path, 'a+') as fp:
                    fp.write(msg + '\n')
        return wrap_func
    return decorator

以上是一個log裝飾器，利用datetime統計了函式的耗時，
並且，裝飾器可以進行輸出檔案操作，如果給出了檔案路徑，則輸出檔案，否則就列印。
利用這個裝飾器，可以靈活地進行耗時統計

@log()
def my_sum(x, y):
    s = 0
    for i in range(x, y+1):
        s += i
    return s
    
my_sum(1, 9999999)

不設定輸出檔案地址，則列印。執行結果為：

2021-12-03 10:01:52 my_sum()
2021-12-03 10:01:52 my_sum() return, cost 506.3299999999999 ms

也可以輸出到檔案

@log('test.log')
def my_sum(x, y):
    s = 0
    for i in range(x, y+1):
        s += i
    return s   

my_sum(1, 9999999)

輸出結果為

print logs into test.log

同時在當前目錄生成了一個test.log 檔案，內容為：

2021-12-03 10:03:17 my_sum()
2021-12-03 10:03:17 my_sum() return, cost 461.813 ms

從裝飾函式到裝飾類

以上的裝飾器都是以函式形式出現的，但我們可以稍做改寫，將裝飾器以類的形式實現。

from functools import wraps
import datetime
class Log:
    def __init__(self, path=None):
        self._output = path
        
    def __call__(self, f):  # 相當於原來的 inner_decorator
        @wraps(f)  
        def wrap_func(*args, **kwargs):  # 增加了輸入引數
            now = datetime.datetime.now()
            msg = now.strftime("%Y-%m-%d %H:%M:%S")  # 執行時刻
            msg += f" {f.__name__}()\n"  # 執行的函式名            

            ret = f(*args, **kwargs)  # 透傳了輸入引數，並記錄了輸出

            aft = datetime.datetime.now()
            time_cost = aft - now
            ms = time_cost.total_seconds() * 10**3  # 毫秒
            msg += now.strftime("%Y-%m-%d %H:%M:%S")
            msg += f" {f.__name__}() return, cost {ms} ms"
            if self._output is None:
                print(msg)
            else:
                print(f"print logs into {self._output}")
                with open(self._output, 'a+') as fp:
                    fp.write(msg + '\n')
        return wrap_func

這個裝飾器類Log 上個例子裡的裝飾器函式log功能是一樣的，同時，這個裝飾器類還可以作為基類被其他繼承，進一步增加功能。