模組二：元編程 on Tarragon

2.1 Descriptor Protocol 完整指南

Tue, 20 Jan 2026 00:00:00 +0000

Descriptor 是 Python 中最強大但也最容易被忽略的機制之一。理解 Descriptor 是深入 Python 物件模型的關鍵。

先備知識

入門系列 4.4 單例與快取（@property 的使用）

本章目標

學完本章後，你將能夠：

理解 @property 實際上是一個 Descriptor
區分 Data Descriptor 和 Non-data Descriptor
理解屬性查找順序
實作自訂的 Descriptor

【原理層】@property 的真相

property 是一個 Descriptor

當你使用 @property 時，實際上是建立了一個 Descriptor：

 1class Circle:
 2    def __init__(self, radius):
 3        self._radius = radius
 4
 5    @property
 6    def radius(self):
 7        return self._radius
 8
 9    @radius.setter
10    def radius(self, value):
11        if value < 0:
12            raise ValueError("半徑不能為負")
13        self._radius = value
14
15# 等價於
16class Circle:
17    def __init__(self, radius):
18        self._radius = radius
19
20    def get_radius(self):
21        return self._radius
22
23    def set_radius(self, value):
24        if value < 0:
25            raise ValueError("半徑不能為負")
26        self._radius = value
27
28    radius = property(get_radius, set_radius)

property 是 Python 內建的 Descriptor 類別。

Descriptor Protocol

Descriptor 是實現了以下方法之一的物件：

 1class Descriptor:
 2    def __get__(self, obj, objtype=None):
 3        """讀取屬性時呼叫"""
 4        pass
 5
 6    def __set__(self, obj, value):
 7        """設定屬性時呼叫"""
 8        pass
 9
10    def __delete__(self, obj):
11        """刪除屬性時呼叫"""
12        pass
13
14    def __set_name__(self, owner, name):
15        """Python 3.6+：設定屬性名時呼叫"""
16        pass

簡單範例

 1class Verbose:
 2    """一個會報告存取情況的 Descriptor"""
 3
 4    def __set_name__(self, owner, name):
 5        self.name = name
 6
 7    def __get__(self, obj, objtype=None):
 8        if obj is None:
 9            return self
10        print(f"讀取 {self.name}")
11        return obj.__dict__.get(self.name)
12
13    def __set__(self, obj, value):
14        print(f"設定 {self.name} = {value}")
15        obj.__dict__[self.name] = value
16
17class MyClass:
18    x = Verbose()
19
20m = MyClass()
21m.x = 10  # 輸出：設定 x = 10
22print(m.x)  # 輸出：讀取 x，然後 10

【設計層】Data vs Non-data Descriptor

兩種 Descriptor

 1# Data Descriptor：有 __set__ 或 __delete__
 2class DataDescriptor:
 3    def __get__(self, obj, objtype=None):
 4        return "data descriptor"
 5
 6    def __set__(self, obj, value):
 7        pass
 8
 9# Non-data Descriptor：只有 __get__
10class NonDataDescriptor:
11    def __get__(self, obj, objtype=None):
12        return "non-data descriptor"

屬性查找順序

這是理解 Descriptor 的關鍵：

1obj.attr 的查找順序：
2
31. Data Descriptor（在類別或父類別中）
42. Instance __dict__
53. Non-data Descriptor（在類別或父類別中）
64. Class __dict__
75. __getattr__（如果定義了）

 1class DataDesc:
 2    def __get__(self, obj, objtype=None):
 3        return "data descriptor"
 4    def __set__(self, obj, value):
 5        pass
 6
 7class NonDataDesc:
 8    def __get__(self, obj, objtype=None):
 9        return "non-data descriptor"
10
11class MyClass:
12    data = DataDesc()
13    nondata = NonDataDesc()
14
15m = MyClass()
16m.__dict__['data'] = "instance value"
17m.__dict__['nondata'] = "instance value"
18
19print(m.data)     # data descriptor（Data Descriptor 優先）
20print(m.nondata)  # instance value（Instance 優先於 Non-data）

為什麼 method 是 Non-data Descriptor？

1class MyClass:
2    def method(self):
3        return "method"
4
5# 可以在實例上覆蓋方法
6m = MyClass()
7m.method = lambda: "overridden"
8print(m.method())  # overridden

如果 method 是 Data Descriptor，就無法這樣覆蓋了。

【實作層】實用的 Descriptor

延遲計算屬性

 1class LazyProperty:
 2    def __init__(self, func):
 3        self.func = func
 4
 5    def __set_name__(self, owner, name):
 6        self.name = name
 7
 8    def __get__(self, obj, objtype=None):
 9        if obj is None:
10            return self
11        value = self.func(obj)
12        obj.__dict__[self.name] = value  # 快取到實例
13        return value
14
15class Data:
16    def __init__(self, values):
17        self.values = values
18
19    @LazyProperty
20    def average(self):
21        print("計算平均值...")
22        return sum(self.values) / len(self.values)
23
24d = Data([1, 2, 3, 4, 5])
25print(d.average)  # 計算平均值... 3.0
26print(d.average)  # 3.0（從快取讀取）

型別驗證器

 1class Typed:
 2    def __init__(self, expected_type):
 3        self.expected_type = expected_type
 4
 5    def __set_name__(self, owner, name):
 6        self.name = name
 7
 8    def __get__(self, obj, objtype=None):
 9        if obj is None:
10            return self
11        return obj.__dict__.get(self.name)
12
13    def __set__(self, obj, value):
14        if not isinstance(value, self.expected_type):
15            raise TypeError(
16                f"{self.name} 必須是 {self.expected_type.__name__}"
17            )
18        obj.__dict__[self.name] = value
19
20class Person:
21    name = Typed(str)
22    age = Typed(int)
23
24    def __init__(self, name, age):
25        self.name = name
26        self.age = age
27
28p = Person("Alice", 30)  # OK
29p = Person("Bob", "thirty")  # TypeError!

類似 Django Model Field

 1class Field:
 2    def __init__(self, default=None):
 3        self.default = default
 4
 5    def __set_name__(self, owner, name):
 6        self.name = name
 7        self.private_name = f"_{name}"
 8
 9    def __get__(self, obj, objtype=None):
10        if obj is None:
11            return self
12        return getattr(obj, self.private_name, self.default)
13
14    def __set__(self, obj, value):
15        setattr(obj, self.private_name, value)
16
17class CharField(Field):
18    def __init__(self, max_length, **kwargs):
19        super().__init__(**kwargs)
20        self.max_length = max_length
21
22    def __set__(self, obj, value):
23        if len(value) > self.max_length:
24            raise ValueError(f"超過最大長度 {self.max_length}")
25        super().__set__(obj, value)
26
27class User:
28    name = CharField(max_length=50)
29    email = CharField(max_length=100)

思考題

為什麼 __set_name__ 是 Python 3.6 才加入的？之前怎麼解決這個問題？
@property 是 Data Descriptor 還是 Non-data Descriptor？為什麼？
如果 Descriptor 存在於實例的 __dict__ 中會怎樣？

實作練習

實作一個 @cached_property 裝飾器
實作一個範圍驗證的 Descriptor（如 age = Range(0, 150)）
實作一個只讀屬性的 Descriptor

延伸閱讀

下一章：Metaclass 設計與應用

2.2 Metaclass 設計與應用

Tue, 20 Jan 2026 00:00:00 +0000

Metaclass 是「類別的類別」，控制類別本身的建立過程。這是 Python 中最深層的元編程機制。

先備知識

2.1 Descriptor Protocol

本章目標

學完本章後，你將能夠：

理解「類別也是物件」的概念
理解類別的建立流程
使用 Metaclass 控制類別行為
選擇適當的元編程工具

【原理層】類別也是物件

type 是所有類別的 Metaclass

在 Python 中，類別本身也是物件：

 1class MyClass:
 2    pass
 3
 4# 類別是 type 的實例
 5print(type(MyClass))  # 
 6print(isinstance(MyClass, type))  # True
 7
 8# 物件是類別的實例
 9obj = MyClass()
10print(type(obj))  # 
11print(isinstance(obj, MyClass))  # True

 1關係圖：
 2
 3type ─────────────┐
 4  │               │
 5  ├── MyClass ────┤
 6  │     │         │ (都是 type 的實例)
 7  │     └── obj   │
 8  │               │
 9  └── int ────────┘
10        │
11        └── 42

type() 的三參數形式

type() 可以動態建立類別：

 1# 這兩種方式等價
 2class MyClass:
 3    x = 10
 4    def method(self):
 5        return self.x
 6
 7# 等價於
 8def method(self):
 9    return self.x
10
11MyClass = type('MyClass', (), {'x': 10, 'method': method})

參數說明：

第一個參數：類別名稱
第二個參數：父類別的 tuple
第三個參數：屬性和方法的 dict

 1# 繼承的例子
 2class Parent:
 3    def greet(self):
 4        return "Hello"
 5
 6Child = type('Child', (Parent,), {'name': 'Child Class'})
 7
 8c = Child()
 9print(c.greet())  # Hello
10print(c.name)     # Child Class

【設計層】類別建立過程

建立流程

當 Python 執行 class 語句時，會依序呼叫這些方法：

1class MyClass(Parent, metaclass=Meta):
2    ...
3
4執行流程：
51. Meta.__prepare__(name, bases) → 返回類別的 namespace（通常是 dict）
62. 執行類別主體，填充 namespace
73. Meta.__new__(mcs, name, bases, namespace) → 建立類別物件
84. Meta.__init__(cls, name, bases, namespace) → 初始化類別物件

 1class LoggingMeta(type):
 2    @classmethod
 3    def __prepare__(mcs, name, bases):
 4        print(f"1. __prepare__: 準備 {name} 的 namespace")
 5        return {}
 6
 7    def __new__(mcs, name, bases, namespace):
 8        print(f"2. __new__: 建立 {name}")
 9        return super().__new__(mcs, name, bases, namespace)
10
11    def __init__(cls, name, bases, namespace):
12        print(f"3. __init__: 初始化 {name}")
13        super().__init__(name, bases, namespace)
14
15class MyClass(metaclass=LoggingMeta):
16    x = 10
17    print("   （執行類別主體）")
18
19# 輸出：
20# 1. __prepare__: 準備 MyClass 的 namespace
21#    （執行類別主體）
22# 2. __new__: 建立 MyClass
23# 3. __init__: 初始化 MyClass

call 控制實例建立

Metaclass 的 __call__ 控制類別被呼叫時的行為：

 1class SingletonMeta(type):
 2    _instances = {}
 3
 4    def __call__(cls, *args, **kwargs):
 5        if cls not in cls._instances:
 6            cls._instances[cls] = super().__call__(*args, **kwargs)
 7        return cls._instances[cls]
 8
 9class Singleton(metaclass=SingletonMeta):
10    def __init__(self, value):
11        self.value = value
12
13s1 = Singleton(1)
14s2 = Singleton(2)
15print(s1 is s2)  # True
16print(s1.value)  # 1（第二次初始化被跳過）

【設計層】init_subclass - 輕量替代方案

Python 3.6 引入了 __init_subclass__，很多情況下可以替代 Metaclass：

 1class Plugin:
 2    _plugins = {}
 3
 4    def __init_subclass__(cls, plugin_name=None, **kwargs):
 5        super().__init_subclass__(**kwargs)
 6        name = plugin_name or cls.__name__
 7        cls._plugins[name] = cls
 8        print(f"註冊插件: {name}")
 9
10class EmailPlugin(Plugin, plugin_name="email"):
11    pass
12
13class SMSPlugin(Plugin, plugin_name="sms"):
14    pass
15
16print(Plugin._plugins)
17# {'email': , 'sms': }

何時用 init_subclass，何時用 Metaclass？

需求	推薦方案
註冊子類別	`__init_subclass__`
驗證類別屬性	`__init_subclass__`
修改類別的 namespace	Metaclass（`__prepare__`）
控制實例建立	Metaclass（`__call__`）
修改類別建立過程	Metaclass
需要影響多層繼承	Metaclass

【實作層】實用範例

自動註冊子類別

 1class Registry:
 2    _registry = {}
 3
 4    def __init_subclass__(cls, **kwargs):
 5        super().__init_subclass__(**kwargs)
 6        if cls.__name__ != 'Base':  # 跳過中間類別
 7            Registry._registry[cls.__name__] = cls
 8
 9    @classmethod
10    def get(cls, name):
11        return cls._registry.get(name)
12
13    @classmethod
14    def create(cls, name, *args, **kwargs):
15        klass = cls.get(name)
16        if klass:
17            return klass(*args, **kwargs)
18        raise ValueError(f"Unknown type: {name}")
19
20class Handler(Registry):
21    pass
22
23class JSONHandler(Handler):
24    def process(self, data):
25        return f"Processing JSON: {data}"
26
27class XMLHandler(Handler):
28    def process(self, data):
29        return f"Processing XML: {data}"
30
31# 使用
32handler = Registry.create("JSONHandler")
33print(handler.process("data"))  # Processing JSON: data

介面驗證

 1class InterfaceMeta(type):
 2    def __new__(mcs, name, bases, namespace):
 3        cls = super().__new__(mcs, name, bases, namespace)
 4
 5        # 跳過基類本身
 6        if bases:
 7            # 檢查是否實現了必要的方法
 8            required = getattr(cls, '_required_methods', [])
 9            for method in required:
10                if method not in namespace:
11                    raise TypeError(
12                        f"{name} 必須實現 {method} 方法"
13                    )
14        return cls
15
16class Serializable(metaclass=InterfaceMeta):
17    _required_methods = ['serialize', 'deserialize']
18
19# 這會引發 TypeError
20# class BadSerializer(Serializable):
21#     pass
22
23class GoodSerializer(Serializable):
24    def serialize(self, obj):
25        return str(obj)
26
27    def deserialize(self, data):
28        return eval(data)

使用 prepare 記錄定義順序

 1from collections import OrderedDict
 2
 3class OrderedMeta(type):
 4    @classmethod
 5    def __prepare__(mcs, name, bases):
 6        return OrderedDict()
 7
 8    def __new__(mcs, name, bases, namespace):
 9        cls = super().__new__(mcs, name, bases, dict(namespace))
10        cls._field_order = [
11            k for k in namespace.keys()
12            if not k.startswith('_')
13        ]
14        return cls
15
16class Form(metaclass=OrderedMeta):
17    name = "text"
18    email = "email"
19    age = "number"
20
21print(Form._field_order)  # ['name', 'email', 'age']

簡單的 ORM 基類

 1class Field:
 2    pass
 3
 4class CharField(Field):
 5    def __init__(self, max_length):
 6        self.max_length = max_length
 7
 8class IntegerField(Field):
 9    pass
10
11class ModelMeta(type):
12    def __new__(mcs, name, bases, namespace):
13        # 收集欄位
14        fields = {}
15        for key, value in namespace.items():
16            if isinstance(value, Field):
17                fields[key] = value
18
19        cls = super().__new__(mcs, name, bases, namespace)
20        cls._fields = fields
21        return cls
22
23class Model(metaclass=ModelMeta):
24    def __init__(self, **kwargs):
25        for name in self._fields:
26            setattr(self, name, kwargs.get(name))
27
28    def __repr__(self):
29        fields = ', '.join(
30            f"{k}={getattr(self, k)!r}"
31            for k in self._fields
32        )
33        return f"{self.__class__.__name__}({fields})"
34
35class User(Model):
36    name = CharField(max_length=100)
37    age = IntegerField()
38
39u = User(name="Alice", age=30)
40print(u)  # User(name='Alice', age=30)
41print(User._fields)  # {'name': CharField, 'age': IntegerField}

【選擇指南】元編程工具比較

 1問題：我需要修改類別的行為
 2
 3├── 只是想在子類別定義時做些事？
 4│   └── 用 __init_subclass__
 5│
 6├── 需要驗證或轉換類別屬性？
 7│   ├── 簡單驗證 → __init_subclass__
 8│   └── 需要修改 namespace → Metaclass
 9│
10├── 需要控制實例建立？
11│   ├── 簡單快取 → __new__
12│   └── 複雜邏輯 → Metaclass.__call__
13│
14├── 需要記錄屬性定義順序？
15│   └── Metaclass.__prepare__
16│
17└── 只是想在實例上添加行為？
18    └── 用類別裝飾器（下一章）

思考題

為什麼 type(type) 是 type 自己？這是如何實現的？
如果一個類別同時有 Metaclass 和 __init_subclass__，執行順序是什麼？
Django 的 Model 是如何使用 Metaclass 的？

實作練習

實作一個 Metaclass，自動為類別添加 __repr__ 方法
實作一個 @abstractmethod 裝飾器和配套的 Metaclass
使用 __init_subclass__ 實作一個事件處理器註冊系統

延伸閱讀

上一章：Descriptor Protocol 完整指南 下一章：類別裝飾器與動態類別

2.3 類別裝飾器與動態類別

Tue, 20 Jan 2026 00:00:00 +0000

類別裝飾器是比 Metaclass 更簡單、更實用的元編程工具。大多數情況下，類別裝飾器就能滿足需求。

先備知識

2.2 Metaclass 設計與應用

本章目標

學完本章後，你將能夠：

編寫類別裝飾器
理解 @dataclass 的實現原理
使用 type() 動態建立類別
選擇合適的元編程工具

【原理層】類別裝飾器

基本結構

類別裝飾器是一個接收類別、返回類別的函式：

 1def my_decorator(cls):
 2 # 修改或增強 cls
 3 return cls
 4
 5@my_decorator
 6class MyClass:
 7 pass
 8
 9# 等價於
10class MyClass:
11 pass
12MyClass = my_decorator(MyClass)

與函式裝飾器的差異

 1# 函式裝飾器通常返回包裝函式
 2def func_decorator(func):
 3 def wrapper(*args, **kwargs):
 4 print("Before")
 5 result = func(*args, **kwargs)
 6 print("After")
 7 return result
 8 return wrapper
 9
10# 類別裝飾器通常直接修改類別
11def class_decorator(cls):
12 cls.new_attribute = "added"
13 return cls

執行時機

 1def decorator(cls):
 2 print(f"裝飾 {cls.__name__}")
 3 return cls
 4
 5@decorator
 6class MyClass:
 7 print("定義類別主體")
 8
 9# 輸出：
10# 定義類別主體
11# 裝飾 MyClass

類別裝飾器在類別定義完成後立即執行。

【設計層】帶參數的裝飾器

裝飾器工廠

 1def repeat_method(times):
 2 """讓指定方法重複執行 times 次"""
 3 def decorator(cls):
 4 original_init = cls.__init__
 5
 6 def new_init(self, *args, **kwargs):
 7 for _ in range(times):
 8 original_init(self, *args, **kwargs)
 9
10 cls.__init__ = new_init
11 return cls
12
13 return decorator
14
15@repeat_method(3)
16class Counter:
17 count = 0
18
19 def __init__(self):
20 Counter.count += 1
21
22c = Counter()
23print(Counter.count) # 3

實用範例：@singleton

 1def singleton(cls):
 2 """單例模式裝飾器"""
 3 instances = {}
 4
 5 def get_instance(*args, **kwargs):
 6 if cls not in instances:
 7 instances[cls] = cls(*args, **kwargs)
 8 return instances[cls]
 9
10 return get_instance
11
12@singleton
13class Database:
14 def __init__(self, host):
15 self.host = host
16 print(f"連接到 {host}")
17
18db1 = Database("localhost") # 連接到 localhost
19db2 = Database("remote") # 不會再次連接
20print(db1 is db2) # True

注意：這個實現返回的是函式而不是類別，所以 isinstance(db1, Database) 會失敗。更好的實現：

 1def singleton(cls):
 2 """保持類別特性的單例裝飾器"""
 3 _instance = None
 4
 5 class SingletonWrapper(cls):
 6 def __new__(wrapper_cls, *args, **kwargs):
 7 nonlocal _instance
 8 if _instance is None:
 9 _instance = super().__new__(wrapper_cls)
10 return _instance
11
12 SingletonWrapper.__name__ = cls.__name__
13 SingletonWrapper.__qualname__ = cls.__qualname__
14 return SingletonWrapper

【實作層】實用類別裝飾器

@auto_repr

 1def auto_repr(cls):
 2 """自動生成 __repr__ 方法"""
 3 def __repr__(self):
 4 attrs = ', '.join(
 5 f"{k}={v!r}"
 6 for k, v in self.__dict__.items()
 7 if not k.startswith('_')
 8 )
 9 return f"{cls.__name__}({attrs})"
10
11 cls.__repr__ = __repr__
12 return cls
13
14@auto_repr
15class Person:
16 def __init__(self, name, age):
17 self.name = name
18 self.age = age
19
20p = Person("Alice", 30)
21print(p) # Person(name='Alice', age=30)

@dataclass 的簡化實現

 1def dataclass(cls):
 2 """簡化版 dataclass"""
 3 # 收集類別屬性中的型別註解
 4 annotations = getattr(cls, '__annotations__', {})
 5
 6 # 生成 __init__
 7 def __init__(self, **kwargs):
 8 for name in annotations:
 9 setattr(self, name, kwargs.get(name))
10
11 # 生成 __repr__
12 def __repr__(self):
13 attrs = ', '.join(
14 f"{name}={getattr(self, name)!r}"
15 for name in annotations
16 )
17 return f"{cls.__name__}({attrs})"
18
19 # 生成 __eq__
20 def __eq__(self, other):
21 if not isinstance(other, cls):
22 return NotImplemented
23 return all(
24 getattr(self, name) == getattr(other, name)
25 for name in annotations
26 )
27
28 cls.__init__ = __init__
29 cls.__repr__ = __repr__
30 cls.__eq__ = __eq__
31
32 return cls
33
34@dataclass
35class Point:
36 x: int
37 y: int
38
39p1 = Point(x=1, y=2)
40p2 = Point(x=1, y=2)
41print(p1) # Point(x=1, y=2)
42print(p1 == p2) # True

@timer（方法計時）

 1import time
 2from functools import wraps
 3
 4def timer(cls):
 5 """為所有公開方法添加計時"""
 6 for name, method in list(cls.__dict__.items()):
 7 if callable(method) and not name.startswith('_'):
 8 @wraps(method)
 9 def timed_method(self, *args, _method=method, _name=name, **kwargs):
10 start = time.perf_counter()
11 result = _method(self, *args, **kwargs)
12 elapsed = time.perf_counter() - start
13 print(f"{_name}: {elapsed:.4f}s")
14 return result
15
16 setattr(cls, name, timed_method)
17
18 return cls
19
20@timer
21class Calculator:
22 def slow_add(self, a, b):
23 time.sleep(0.1)
24 return a + b
25
26calc = Calculator()
27calc.slow_add(1, 2) # slow_add: 0.1001s

【設計層】動態建立類別

使用 type()

 1# 基本用法
 2def greet(self):
 3 return f"Hello, {self.name}"
 4
 5Person = type('Person', (), {
 6 'species': 'Human',
 7 'greet': greet,
 8})
 9
10p = Person()
11p.name = "Alice"
12print(p.greet()) # Hello, Alice

動態繼承

 1def create_model(name, fields):
 2 """動態建立模型類別"""
 3
 4 def __init__(self, **kwargs):
 5 for field in fields:
 6 setattr(self, field, kwargs.get(field))
 7
 8 def __repr__(self):
 9 attrs = ', '.join(f"{f}={getattr(self, f)!r}" for f in fields)
10 return f"{name}({attrs})"
11
12 return type(name, (), {
13 '__init__': __init__,
14 '__repr__': __repr__,
15 '_fields': fields,
16 })
17
18User = create_model('User', ['id', 'name', 'email'])
19Product = create_model('Product', ['id', 'name', 'price'])
20
21u = User(id=1, name="Alice", email="alice@example.com")
22print(u) # User(id=1, name='Alice', email='alice@example.com')

條件繼承

 1def create_handler(use_async=False):
 2 """根據條件選擇基類"""
 3
 4 if use_async:
 5 import asyncio
 6
 7 class AsyncBase:
 8 async def handle(self, data):
 9 await asyncio.sleep(0.1)
10 return f"Async: {data}"
11
12 base = AsyncBase
13 else:
14 class SyncBase:
15 def handle(self, data):
16 return f"Sync: {data}"
17
18 base = SyncBase
19
20 return type('Handler', (base,), {})
21
22SyncHandler = create_handler(use_async=False)
23AsyncHandler = create_handler(use_async=True)

【選擇指南】

Metaclass vs 類別裝飾器 vs init_subclass

特性	類別裝飾器	init_subclass	Metaclass
學習曲線	低	低	高
影響子類別	否	是	是
可堆疊	是	是（需 super）	困難
控制程度	類別建立後	子類別定義時	類別建立中
適用場景	添加/修改方法	註冊/驗證	深度自訂

決策流程

 1需要修改類別的行為？
 2│
 3├── 只在單一類別上？
 4│ └── 類別裝飾器
 5│
 6├── 需要自動影響所有子類別？
 7│ ├── 只是註冊或簡單驗證？
 8│ │ └── __init_subclass__
 9│ │
10│ └── 需要修改類別建立過程？
11│ └── Metaclass
12│
13└── 需要完全動態建立類別？
14 └── type()

【實戰】組合使用

 1from functools import wraps
 2
 3def validate_types(cls):
 4 """型別驗證裝飾器"""
 5 original_init = cls.__init__
 6 annotations = getattr(cls, '__annotations__', {})
 7
 8 @wraps(original_init)
 9 def validated_init(self, *args, **kwargs):
10 # 將位置參數轉換為關鍵字參數
11 import inspect
12 sig = inspect.signature(original_init)
13 params = list(sig.parameters.keys())[1:] # 跳過 self
14
15 for i, arg in enumerate(args):
16 if i < len(params):
17 kwargs[params[i]] = arg
18
19 # 驗證型別
20 for name, expected_type in annotations.items():
21 if name in kwargs:
22 value = kwargs[name]
23 if not isinstance(value, expected_type):
24 raise TypeError(
25 f"{name} 應為 {expected_type.__name__}，"
26 f"但得到 {type(value).__name__}"
27 )
28
29 original_init(self, **kwargs)
30
31 cls.__init__ = validated_init
32 return cls
33
34@validate_types
35class User:
36 name: str
37 age: int
38
39 def __init__(self, name, age):
40 self.name = name
41 self.age = age
42
43User("Alice", 30) # OK
44# User("Bob", "thirty") # TypeError!

思考題

類別裝飾器和 Metaclass 可以同時使用嗎？執行順序是什麼？
@dataclass 實際上使用了哪些技術？
動態建立的類別和靜態定義的類別有什麼差異？

實作練習

實作一個 @frozen 裝飾器，讓類別的實例不可變
實作一個 @trace 裝飾器，追蹤所有方法呼叫
使用 type() 建立一個簡單的 Enum 類別

延伸閱讀

上一章：Metaclass 設計與應用 下一章：反射與 inspect 模組

2.4 反射與 inspect 模組

Tue, 20 Jan 2026 00:00:00 +0000

反射是程式檢視和修改自身結構的能力。Python 提供了強大的反射工具，讓你能夠動態地檢視物件、取得函式簽名、甚至修改執行中的程式。

先備知識

2.3 類別裝飾器與動態類別

本章目標

學完本章後，你將能夠：

使用內建反射函式（getattr、setattr 等）
使用 inspect 模組分析物件
理解 getattr 和 getattribute 的差異
實作動態代理和 Mock 物件

【原理層】反射的基本概念

什麼是反射？

反射是程式在執行時檢視自身結構的能力：

 1class MyClass:
 2    def __init__(self, value):
 3        self.value = value
 4
 5    def method(self):
 6        return self.value * 2
 7
 8obj = MyClass(10)
 9
10# 反射：程式檢視自己
11print(type(obj))                    # 
12print(obj.__class__.__name__)       # MyClass
13print(dir(obj))                     # ['__class__', 'method', 'value', ...]
14print(hasattr(obj, 'value'))        # True
15print(getattr(obj, 'value'))        # 10

內建反射函式

 1obj = MyClass(10)
 2
 3# getattr - 取得屬性
 4value = getattr(obj, 'value')                    # 10
 5default = getattr(obj, 'missing', 'default')     # 'default'
 6
 7# setattr - 設定屬性
 8setattr(obj, 'value', 20)
 9print(obj.value)  # 20
10
11# hasattr - 檢查屬性是否存在
12print(hasattr(obj, 'value'))   # True
13print(hasattr(obj, 'missing')) # False
14
15# delattr - 刪除屬性
16delattr(obj, 'value')
17print(hasattr(obj, 'value'))   # False

vars() 和 dict

 1class Person:
 2    species = "Human"  # 類別屬性
 3
 4    def __init__(self, name):
 5        self.name = name  # 實例屬性
 6
 7p = Person("Alice")
 8
 9# 實例的 __dict__：只包含實例屬性
10print(vars(p))         # {'name': 'Alice'}
11print(p.__dict__)      # {'name': 'Alice'}
12
13# 類別的 __dict__：包含類別屬性和方法
14print(vars(Person))    # {'species': 'Human', '__init__': ..., ...}

【設計層】getattr vs getattribute

getattr

當正常屬性查找失敗時呼叫：

 1class FlexibleObject:
 2    def __init__(self):
 3        self.existing = "I exist"
 4
 5    def __getattr__(self, name):
 6        return f"動態屬性: {name}"
 7
 8obj = FlexibleObject()
 9print(obj.existing)  # I exist（正常查找成功）
10print(obj.missing)   # 動態屬性: missing（__getattr__ 被呼叫）

getattribute

所有屬性存取都會呼叫（包括存在的屬性）：

 1class LoggedObject:
 2    def __init__(self, value):
 3        object.__setattr__(self, 'value', value)
 4
 5    def __getattribute__(self, name):
 6        print(f"存取屬性: {name}")
 7        return object.__getattribute__(self, name)
 8
 9obj = LoggedObject(10)
10print(obj.value)
11# 輸出：
12# 存取屬性: value
13# 10

注意：在 __getattribute__ 中要避免無限遞迴：

1class Dangerous:
2    def __getattribute__(self, name):
3        # 錯誤！這會造成無限遞迴
4        # return self.data[name]
5
6        # 正確：使用 object.__getattribute__
7        data = object.__getattribute__(self, 'data')
8        return data.get(name)

【實作層】inspect 模組

檢視物件類型

 1import inspect
 2
 3def my_function():
 4    pass
 5
 6class MyClass:
 7    def method(self):
 8        pass
 9
10print(inspect.isfunction(my_function))  # True
11print(inspect.ismethod(my_function))    # False
12print(inspect.isclass(MyClass))         # True
13
14obj = MyClass()
15print(inspect.ismethod(obj.method))     # True

取得函式簽名

 1import inspect
 2
 3def greet(name: str, greeting: str = "Hello") -> str:
 4    """打招呼函式"""
 5    return f"{greeting}, {name}!"
 6
 7# 取得簽名
 8sig = inspect.signature(greet)
 9print(sig)  # (name: str, greeting: str = 'Hello') -> str
10
11# 檢視參數
12for param_name, param in sig.parameters.items():
13    print(f"  {param_name}:")
14    print(f"    default: {param.default}")
15    print(f"    annotation: {param.annotation}")
16    print(f"    kind: {param.kind}")
17
18# 輸出：
19#   name:
20#     default: 
21#     annotation: 
22#     kind: POSITIONAL_OR_KEYWORD
23#   greeting:
24#     default: Hello
25#     annotation: 
26#     kind: POSITIONAL_OR_KEYWORD

取得原始碼

 1import inspect
 2
 3def example_function():
 4    """這是範例函式"""
 5    x = 1
 6    return x + 1
 7
 8# 取得原始碼
 9print(inspect.getsource(example_function))
10# def example_function():
11#     """這是範例函式"""
12#     x = 1
13#     return x + 1
14
15# 取得文件字串
16print(inspect.getdoc(example_function))
17# 這是範例函式
18
19# 取得檔案位置
20print(inspect.getfile(example_function))

取得呼叫堆疊

 1import inspect
 2
 3def inner():
 4    stack = inspect.stack()
 5    for frame_info in stack:
 6        print(f"{frame_info.function} at {frame_info.lineno}")
 7
 8def outer():
 9    inner()
10
11def main():
12    outer()
13
14main()
15# 輸出：
16# inner at 5
17# outer at 9
18# main at 12
19#  at 14

【實戰】實用應用

動態呼叫方法

 1class Calculator:
 2    def add(self, a, b):
 3        return a + b
 4
 5    def subtract(self, a, b):
 6        return a - b
 7
 8    def multiply(self, a, b):
 9        return a * b
10
11def execute(calc, operation, a, b):
12    """動態執行運算"""
13    method = getattr(calc, operation, None)
14    if method and callable(method):
15        return method(a, b)
16    raise ValueError(f"不支援的運算: {operation}")
17
18calc = Calculator()
19print(execute(calc, "add", 5, 3))       # 8
20print(execute(calc, "multiply", 5, 3))  # 15

簡單的 Mock 物件

 1class Mock:
 2    """簡單的 Mock 物件"""
 3
 4    def __init__(self):
 5        self._calls = []
 6
 7    def __getattr__(self, name):
 8        def method(*args, **kwargs):
 9            self._calls.append({
10                'method': name,
11                'args': args,
12                'kwargs': kwargs,
13            })
14            return Mock()  # 支援鏈式呼叫
15
16        return method
17
18    @property
19    def call_count(self):
20        return len(self._calls)
21
22    def assert_called_with(self, method, *args, **kwargs):
23        for call in self._calls:
24            if (call['method'] == method and
25                call['args'] == args and
26                call['kwargs'] == kwargs):
27                return True
28        raise AssertionError(f"{method} 沒有以預期的參數被呼叫")
29
30# 使用
31mock = Mock()
32mock.save("data", flush=True)
33mock.load("file.txt")
34
35print(mock.call_count)  # 2
36mock.assert_called_with("save", "data", flush=True)  # OK

動態代理

 1class LoggingProxy:
 2    """記錄所有方法呼叫的代理"""
 3
 4    def __init__(self, target):
 5        object.__setattr__(self, '_target', target)
 6        object.__setattr__(self, '_log', [])
 7
 8    def __getattr__(self, name):
 9        attr = getattr(self._target, name)
10
11        if callable(attr):
12            def logged_method(*args, **kwargs):
13                self._log.append({
14                    'method': name,
15                    'args': args,
16                    'kwargs': kwargs,
17                })
18                return attr(*args, **kwargs)
19            return logged_method
20
21        return attr
22
23    def __setattr__(self, name, value):
24        setattr(self._target, name, value)
25
26    def get_log(self):
27        return self._log
28
29# 使用
30class Database:
31    def query(self, sql):
32        return f"執行: {sql}"
33
34    def insert(self, table, data):
35        return f"插入到 {table}"
36
37db = LoggingProxy(Database())
38db.query("SELECT * FROM users")
39db.insert("users", {"name": "Alice"})
40
41for entry in db.get_log():
42    print(entry)
43# {'method': 'query', 'args': ('SELECT * FROM users',), 'kwargs': {}}
44# {'method': 'insert', 'args': ('users', {'name': 'Alice'}), 'kwargs': {}}

自動生成 API 文件

 1import inspect
 2
 3def generate_api_doc(cls):
 4    """為類別生成簡單的 API 文件"""
 5    lines = [f"# {cls.__name__}", ""]
 6
 7    if cls.__doc__:
 8        lines.extend([cls.__doc__, ""])
 9
10    lines.append("## Methods")
11    lines.append("")
12
13    for name, method in inspect.getmembers(cls, predicate=inspect.isfunction):
14        if name.startswith('_'):
15            continue
16
17        sig = inspect.signature(method)
18        doc = inspect.getdoc(method) or "No description"
19
20        lines.append(f"### `{name}{sig}`")
21        lines.append("")
22        lines.append(doc)
23        lines.append("")
24
25    return '\n'.join(lines)
26
27class UserService:
28    """用戶服務類別"""
29
30    def create_user(self, name: str, email: str) -> dict:
31        """建立新用戶
32
33        Args:
34            name: 用戶名稱
35            email: 電子郵件
36
37        Returns:
38            新建立的用戶資料
39        """
40        pass
41
42    def get_user(self, user_id: int) -> dict:
43        """取得用戶資料"""
44        pass
45
46print(generate_api_doc(UserService))

【框架應用】

pytest 的反射使用

 1# pytest 使用反射來發現測試
 2import inspect
 3
 4def discover_tests(module):
 5    """模擬 pytest 的測試發現"""
 6    tests = []
 7
 8    for name, obj in inspect.getmembers(module):
 9        if name.startswith('test_') and inspect.isfunction(obj):
10            tests.append(obj)
11
12    return tests
13
14# 使用
15def test_addition():
16    assert 1 + 1 == 2
17
18def test_subtraction():
19    assert 2 - 1 == 1
20
21def helper_function():  # 不會被發現
22    pass
23
24import sys
25tests = discover_tests(sys.modules[__name__])
26for test in tests:
27    print(f"發現測試: {test.__name__}")

FastAPI 的參數解析

 1import inspect
 2from typing import get_type_hints
 3
 4def parse_function_params(func):
 5    """模擬 FastAPI 的參數解析"""
 6    sig = inspect.signature(func)
 7    hints = get_type_hints(func)
 8
 9    params = []
10    for name, param in sig.parameters.items():
11        params.append({
12            'name': name,
13            'type': hints.get(name, 'Any'),
14            'default': None if param.default is inspect.Parameter.empty else param.default,
15            'required': param.default is inspect.Parameter.empty,
16        })
17
18    return params
19
20def create_user(name: str, age: int, active: bool = True):
21    pass
22
23params = parse_function_params(create_user)
24for p in params:
25    print(p)
26# {'name': 'name', 'type': , 'default': None, 'required': True}
27# {'name': 'age', 'type': , 'default': None, 'required': True}
28# {'name': 'active', 'type': , 'default': True, 'required': False}

思考題

為什麼 hasattr 可能會觸發副作用？什麼情況下應該避免使用？
__getattr__ 和 __getattribute__ 在效能上有什麼差異？
如何用反射實作一個簡單的依賴注入框架？

實作練習

實作一個 @deprecated 裝飾器，使用 inspect 記錄呼叫位置
建立一個簡單的 RPC 框架，根據方法名稱動態呼叫遠端方法
實作一個物件比較工具，使用反射比較兩個物件的所有屬性

延伸閱讀

上一章：類別裝飾器與動態類別 下一模組：模組三：CPython 內部機制