萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python 裝飾器進階實戰:正確保留中繼資料、支援類方法與描述符協定

裝飾器基礎回顧


# 語法糖等價轉換
@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  # 直接支援,無須擔心順序

最佳實踐總結

  1. 永遠使用 @functools.wraps 或 decorator 套件
  2. 裝飾器順序:功能性裝飾器在內,類型轉換裝飾器在外 (@classmethod/@staticmethod/@property 在最外層)
  3. 需保留簽名/原始碼時,引入 decorator 套件
  4. 類別型裝飾器實作 __get__ 支援描述符協定
  5. 編寫單元測試驗證 __name__, __doc__, signature, __wrapped__ 正確性
copyright © 萬盛學電腦網 all rights reserved