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

• 2021 年 12 月 3 日
• 筆記
• 低門檻 手把手

本文目的是由淺入深地介紹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上增加了前後列印行為的新函數
這個過程被可以被稱作裝飾。

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

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功能是一樣的，同時，這個裝飾器類還可以作為基類被其他繼承，進一步增加功能。