裝飾器基礎回顧
# 語法糖等價轉換
@decorator
def func(): pass
# 等同於
def func(): pass
func = decorator(func)
兩種實作模式對比
函式包裝器 (經典)
def wrapper(func):
def inner(*args, **kwargs):
# 前置邏輯
result = func(*args, **kwargs)
# 後置邏輯
return result
return inner
類別包裝器 (更清晰、支援狀態)
class Wrapper:
def __init__(self, func):
self.func = func
self.call_count = 0 # 可保存狀態
def __call__(self, *args, **kwargs):
self.call_count += 1
print(f"第 {self.call_count} 次呼叫 {self.func.__name__}")
return self.func(*args, **kwargs)
核心問題:中繼資料遺失
@wrapper
def add(a, b):
"""相加兩數"""
return a + b
print(add.__name__) # 'inner' (錯誤!)
print(add.__doc__) # None (錯誤!)
print(inspect.signature(add)) # (*args, **kwargs) (錯誤!)
標準庫解決方案:functools.wraps
from functools import wraps
def wrapper(func):
@wraps(func) # 複製 __name__, __doc__, __module__, __annotations__, __qualname__
def inner(*args, **kwargs):
return func(*args, **kwargs)
return inner
進階挑戰:functools.wraps 解決不了的問題
| 需求 | wraps 表現 | 解決方案 |
保留函式簽名 (inspect.signature) | ❌ 顯示 (*args, **kwargs) | functools.WRAPPER_ASSIGNMENTS + ('__signature__',) 或 decorator 套件 |
取得原始碼 (inspect.getsource) | ❌ 顯示包裝器原始碼 | 無標準解,需人工設定 __wrapped__ |
支援 @classmethod/@staticmethod | ❌ Python < 3.10 報錯/失效 | 用 functools.wraps + 正確順序,或 decorator 套件 |
支援描述符協定 (__get__) | ❌ 類別方法綁定失效 | 實作 __get__ 返回 types.MethodType |
完美裝飾器範本 (支援所有場景)
import functools
import types
from typing import Callable, Any, TypeVar, ParamSpec
P = ParamSpec('P')
R = TypeVar('R')
class PerfectDecorator:
"""支援函式、類方法、靜態方法、屬性、描述符的完美裝飾器基類"""
def __init__(self, func: Callable[P, R]):
functools.update_wrapper(self, func)
self._func = func
def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
# 前置邏輯
result = self._func(*args, **kwargs)
# 後置邏輯
return result
# 關鍵:實作描述符協定,支援類方法正確綁定
def __get__(self, instance, owner):
if instance is None:
return self # 類別層級存取
return types.MethodType(self, instance) # 綁定到實例
# 使用範例
def logged(func):
@PerfectDecorator
def wrapper(*args, **kwargs):
print(f"呼叫 {func.__qualname__}")
return func(*args, **kwargs)
return wrapper
class MyClass:
@logged
def instance_method(self, x):
return x * 2
@logged
@classmethod
def class_method(cls, y):
return y + 1
@logged
@staticmethod
def static_method(z):
return z - 1
# 測試
obj = MyClass()
print(obj.instance_method(5)) # 正常綁定 self
print(MyClass.class_method(10)) # 正常綁定 cls
print(MyClass.static_method(20))# 正常呼叫
裝飾器順序陷阱
# ❌ 錯誤順序:classmethod 在外層,裝飾器收到的是 classmethod 物件而非函式
@logged
@classmethod
def method(cls): pass
# ✅ 正確順序:裝飾器在內層,先包裝函式,再轉為 classmethod
@classmethod
@logged
def method(cls): pass
推薦第三方套件
- decorator:
pip install decorator,自動處理簽名、描述符、類方法,API 簡潔
- wrapt:更底層、高效能,適合框架開發
# decorator 套件用法
from decorator import decorator
@decorator
def logged(func, *args, **kwargs):
print(f"呼叫 {func.__name__}")
return func(*args, **kwargs)
@logged
@classmethod
def cm(cls): pass # 直接支援,無須擔心順序
最佳實踐總結
- 永遠使用
@functools.wraps 或 decorator 套件
- 裝飾器順序:功能性裝飾器在內,類型轉換裝飾器在外 (
@classmethod/@staticmethod/@property 在最外層)
- 需保留簽名/原始碼時,引入
decorator 套件
- 類別型裝飾器實作
__get__ 支援描述符協定
- 編寫單元測試驗證
__name__, __doc__, signature, __wrapped__ 正確性