Metaprogramming on Tarragon

案例：宣告式驗證

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何用 Descriptor Protocol 實現宣告式驗證。

先備知識

2.1 Descriptor Protocol 完整指南

問題背景

現有設計

hook_validator.py 使用命令式驗證方式：

 1class HookValidator:
 2 """Hook 合規性驗證器"""
 3
 4 # 驗證模式定義為類別常數
 5 VALID_NAME_PATTERNS = [
 6 r"^[a-z0-9](/python-advanced/02-metaprogramming/case-studies/declarative-validation/[a-z0-9\-_]*[a-z0-9])?\.py$",
 7 ]
 8
 9 HOOK_IO_PATTERNS = [
10 r"from\s+hook_io\s+import",
11 r"from\s+lib\.hook_io\s+import",
12 ]
13
14 def validate_hook(self, hook_path: str) -> ValidationResult:
15 """驗證單個 Hook 檔案"""
16 issues = []
17 issues.extend(self.check_naming_convention(hook_path))
18 issues.extend(self.check_lib_imports(content, hook_path))
19 issues.extend(self.check_output_format(content))
20 issues.extend(self.check_test_exists(hook_path))
21 return ValidationResult(hook_path=str(hook_path), issues=issues)
22
23 def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
24 """檢查命名規範"""
25 filename = hook_path.name
26 valid_name = any(
27 re.match(pattern, filename)
28 for pattern in self.VALID_NAME_PATTERNS
29 )
30 if not valid_name:
31 return [ValidationIssue(
32 level="warning",
33 message=f"檔案名稱不符合規範: {filename}",
34 suggestion="建議使用 snake-case 或 kebab-case 命名"
35 )]
36 return []

這個設計的優點

直覺易懂：每個 check_* 方法負責一項檢查
彈性高：容易新增或修改檢查邏輯
調試方便：可以單獨執行任一檢查方法

這個設計的限制

當需要設定類別時（例如 Hook 配置），命令式驗證會有問題：

 1class HookConfig:
 2 """Hook 配置類別"""
 3 def __init__(self, name: str, event: str, command: str):
 4 # 驗證邏輯散落在 __init__ 中
 5 if not re.match(r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$", name):
 6 raise ValueError(f"無效的 Hook 名稱: {name}")
 7 if event not in ("PreToolUse", "PostToolUse", "Stop"):
 8 raise ValueError(f"無效的事件類型: {event}")
 9 if not command:
10 raise ValueError("命令不能為空")
11
12 self.name = name
13 self.event = event
14 self.command = command

問題：

驗證邏輯在 __init__ 中，不容易重用
修改屬性時不會重新驗證
無法在類別定義中看到驗證規則

進階解決方案：宣告式驗證

設計目標

驗證規則在類別定義中可見
賦值時自動驗證
驗證邏輯可重用

實作步驟

步驟 1：建立基礎 Descriptor

 1import re
 2from typing import Any, Callable, Optional
 3
 4class ValidatedField:
 5 """
 6 驗證欄位 Descriptor
 7
 8 將驗證邏輯封裝在屬性定義中，
 9 賦值時自動執行驗證。
10 """
11
12 def __init__(
13 self,
14 validator: Callable[[Any], bool],
15 error_msg: str = "驗證失敗"
16 ):
17 """
18 Args:
19 validator: 驗證函式，接受值，返回 bool
20 error_msg: 驗證失敗時的錯誤訊息
21 """
22 self.validator = validator
23 self.error_msg = error_msg
24 # __set_name__ 會設定這些
25 self.name: str = ""
26 self.private_name: str = ""
27
28 def __set_name__(self, owner: type, name: str) -> None:
29 """
30 Python 3.6+ 自動呼叫，取得屬性名稱
31
32 Args:
33 owner: 擁有此 Descriptor 的類別
34 name: 屬性名稱
35 """
36 self.name = name
37 self.private_name = f"_{name}"
38
39 def __get__(self, obj: Any, objtype: type = None) -> Any:
40 """
41 讀取屬性時呼叫
42
43 Args:
44 obj: 實例（如果透過實例存取）
45 objtype: 類別
46
47 Returns:
48 屬性值，或透過類別存取時返回 Descriptor 本身
49 """
50 if obj is None:
51 return self # 透過類別存取，返回 Descriptor
52 return getattr(obj, self.private_name, None)
53
54 def __set__(self, obj: Any, value: Any) -> None:
55 """
56 設定屬性時呼叫，執行驗證
57
58 Args:
59 obj: 實例
60 value: 要設定的值
61
62 Raises:
63 ValueError: 驗證失敗時
64 """
65 if not self.validator(value):
66 raise ValueError(f"{self.name}: {self.error_msg}")
67 setattr(obj, self.private_name, value)

步驟 2：建立特化的驗證 Descriptor

 1class PatternField(ValidatedField):
 2 """
 3 正則表達式驗證欄位
 4
 5 簡化常見的模式匹配驗證。
 6 """
 7
 8 def __init__(self, pattern: str, error_msg: str = "格式不符"):
 9 """
10 Args:
11 pattern: 正則表達式模式
12 error_msg: 驗證失敗時的錯誤訊息
13 """
14 self.pattern = re.compile(pattern)
15 super().__init__(
16 validator=lambda v: bool(self.pattern.match(str(v))),
17 error_msg=error_msg
18 )
19
20class ChoiceField(ValidatedField):
21 """
22 選項驗證欄位
23
24 限制值必須在指定選項中。
25 """
26
27 def __init__(self, choices: tuple, error_msg: str = "無效的選項"):
28 """
29 Args:
30 choices: 允許的選項
31 error_msg: 驗證失敗時的錯誤訊息
32 """
33 self.choices = choices
34 super().__init__(
35 validator=lambda v: v in self.choices,
36 error_msg=f"{error_msg}，必須是: {', '.join(str(c) for c in choices)}"
37 )
38
39class NonEmptyField(ValidatedField):
40 """
41 非空驗證欄位
42
43 確保值不為空。
44 """
45
46 def __init__(self, error_msg: str = "不能為空"):
47 super().__init__(
48 validator=lambda v: bool(v),
49 error_msg=error_msg
50 )
51
52class RangeField(ValidatedField):
53 """
54 範圍驗證欄位
55
56 確保數值在指定範圍內。
57 """
58
59 def __init__(
60 self,
61 min_val: Optional[float] = None,
62 max_val: Optional[float] = None,
63 error_msg: str = "超出範圍"
64 ):
65 """
66 Args:
67 min_val: 最小值（None 表示無下限）
68 max_val: 最大值（None 表示無上限）
69 error_msg: 驗證失敗時的錯誤訊息
70 """
71 self.min_val = min_val
72 self.max_val = max_val
73
74 def validator(v):
75 if min_val is not None and v < min_val:
76 return False
77 if max_val is not None and v > max_val:
78 return False
79 return True
80
81 range_desc = []
82 if min_val is not None:
83 range_desc.append(f">= {min_val}")
84 if max_val is not None:
85 range_desc.append(f"<= {max_val}")
86
87 super().__init__(
88 validator=validator,
89 error_msg=f"{error_msg}，必須 {' 且 '.join(range_desc)}"
90 )

步驟 3：使用宣告式驗證

 1class HookConfig:
 2 """
 3 Hook 配置類別 - 宣告式驗證版本
 4
 5 驗證規則直接在類別定義中可見。
 6 """
 7
 8 # 宣告式驗證：欄位定義即驗證規則
 9 name = PatternField(
10 r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$",
11 "Hook 名稱必須是小寫字母、數字、連字號或底線，且不能以連字號開頭或結尾"
12 )
13
14 event = ChoiceField(
15 ("PreToolUse", "PostToolUse", "Stop", "SessionStart", "SessionEnd"),
16 "無效的事件類型"
17 )
18
19 command = NonEmptyField("命令不能為空")
20
21 timeout = RangeField(
22 min_val=0,
23 max_val=300,
24 error_msg="超時時間無效"
25 )
26
27 def __init__(
28 self,
29 name: str,
30 event: str,
31 command: str,
32 timeout: int = 30
33 ):
34 """
35 初始化 Hook 配置
36
37 Args:
38 name: Hook 名稱
39 event: 事件類型
40 command: 執行的命令
41 timeout: 超時時間（秒）
42
43 驗證會在賦值時自動執行。
44 """
45 self.name = name # 自動驗證名稱格式
46 self.event = event # 自動驗證事件類型
47 self.command = command # 自動驗證非空
48 self.timeout = timeout # 自動驗證範圍
49
50 def __repr__(self) -> str:
51 return (
52 f"HookConfig(name={self.name!r}, event={self.event!r}, "
53 f"command={self.command!r}, timeout={self.timeout})"
54 )

完整程式碼

 1#!/usr/bin/env python3
 2"""
 3宣告式驗證 - 完整範例
 4
 5展示如何用 Descriptor Protocol 實現宣告式驗證。
 6"""
 7
 8import re
 9from typing import Any, Callable, Optional
 10
 11# ===== Descriptor 定義 =====
 12
 13class ValidatedField:
 14 """驗證欄位 Descriptor 基類"""
 15
 16 def __init__(
 17 self,
 18 validator: Callable[[Any], bool],
 19 error_msg: str = "驗證失敗"
 20 ):
 21 self.validator = validator
 22 self.error_msg = error_msg
 23 self.name: str = ""
 24 self.private_name: str = ""
 25
 26 def __set_name__(self, owner: type, name: str) -> None:
 27 self.name = name
 28 self.private_name = f"_{name}"
 29
 30 def __get__(self, obj: Any, objtype: type = None) -> Any:
 31 if obj is None:
 32 return self
 33 return getattr(obj, self.private_name, None)
 34
 35 def __set__(self, obj: Any, value: Any) -> None:
 36 if not self.validator(value):
 37 raise ValueError(f"{self.name}: {self.error_msg}")
 38 setattr(obj, self.private_name, value)
 39
 40class PatternField(ValidatedField):
 41 """正則表達式驗證欄位"""
 42
 43 def __init__(self, pattern: str, error_msg: str = "格式不符"):
 44 self.pattern = re.compile(pattern)
 45 super().__init__(
 46 validator=lambda v: bool(self.pattern.match(str(v))),
 47 error_msg=error_msg
 48 )
 49
 50class ChoiceField(ValidatedField):
 51 """選項驗證欄位"""
 52
 53 def __init__(self, choices: tuple, error_msg: str = "無效的選項"):
 54 self.choices = choices
 55 super().__init__(
 56 validator=lambda v: v in self.choices,
 57 error_msg=f"{error_msg}，必須是: {', '.join(str(c) for c in choices)}"
 58 )
 59
 60class NonEmptyField(ValidatedField):
 61 """非空驗證欄位"""
 62
 63 def __init__(self, error_msg: str = "不能為空"):
 64 super().__init__(
 65 validator=lambda v: bool(v),
 66 error_msg=error_msg
 67 )
 68
 69class RangeField(ValidatedField):
 70 """範圍驗證欄位"""
 71
 72 def __init__(
 73 self,
 74 min_val: Optional[float] = None,
 75 max_val: Optional[float] = None,
 76 error_msg: str = "超出範圍"
 77 ):
 78 self.min_val = min_val
 79 self.max_val = max_val
 80
 81 def validator(v):
 82 if min_val is not None and v < min_val:
 83 return False
 84 if max_val is not None and v > max_val:
 85 return False
 86 return True
 87
 88 range_desc = []
 89 if min_val is not None:
 90 range_desc.append(f">= {min_val}")
 91 if max_val is not None:
 92 range_desc.append(f"<= {max_val}")
 93
 94 super().__init__(
 95 validator=validator,
 96 error_msg=f"{error_msg}，必須 {' 且 '.join(range_desc)}"
 97 )
 98
 99# ===== 使用範例 =====
100
101class HookConfig:
102 """Hook 配置類別 - 宣告式驗證"""
103
104 name = PatternField(
105 r"^[a-z0-9][a-z0-9\-_]*[a-z0-9]$",
106 "Hook 名稱格式無效"
107 )
108
109 event = ChoiceField(
110 ("PreToolUse", "PostToolUse", "Stop", "SessionStart", "SessionEnd"),
111 "無效的事件類型"
112 )
113
114 command = NonEmptyField("命令不能為空")
115
116 timeout = RangeField(min_val=0, max_val=300, error_msg="超時時間無效")
117
118 def __init__(self, name: str, event: str, command: str, timeout: int = 30):
119 self.name = name
120 self.event = event
121 self.command = command
122 self.timeout = timeout
123
124 def __repr__(self) -> str:
125 return f"HookConfig({self.name!r}, {self.event!r}, {self.command!r})"
126
127# ===== 測試 =====
128
129if __name__ == "__main__":
130 # 正確的配置
131 config = HookConfig(
132 name="check-format",
133 event="PreToolUse",
134 command="python check.py"
135 )
136 print(f"建立成功: {config}")
137
138 # 修改屬性也會驗證
139 config.timeout = 60
140 print(f"修改 timeout: {config.timeout}")
141
142 # 驗證失敗的例子
143 try:
144 bad_config = HookConfig(
145 name="Check-Format", # 錯誤：大寫
146 event="PreToolUse",
147 command="python check.py"
148 )
149 except ValueError as e:
150 print(f"驗證失敗: {e}")
151
152 try:
153 config.event = "InvalidEvent" # 錯誤：無效的事件
154 except ValueError as e:
155 print(f"驗證失敗: {e}")
156
157 try:
158 config.timeout = 500 # 錯誤：超出範圍
159 except ValueError as e:
160 print(f"驗證失敗: {e}")

使用範例

 1# 正確的配置
 2>>> config = HookConfig(
 3... name="check-format",
 4... event="PreToolUse",
 5... command="python check.py"
 6... )
 7>>> config
 8HookConfig('check-format', 'PreToolUse', 'python check.py')
 9
10# 修改屬性也會驗證
11>>> config.timeout = 60
12>>> config.timeout
1360
14
15# 驗證失敗
16>>> config.name = "Invalid Name"
17ValueError: name: Hook 名稱格式無效
18
19>>> config.event = "BadEvent"
20ValueError: event: 無效的事件類型，必須是: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd
21
22>>> config.timeout = -1
23ValueError: timeout: 超時時間無效，必須 >= 0 且 <= 300

設計權衡

面向	命令式驗證	宣告式驗證（Descriptor）
可讀性	驗證邏輯散落在方法中	驗證規則在類別定義中可見
重用性	需要複製驗證邏輯	Descriptor 可在多個類別重用
賦值驗證	需要手動呼叫驗證	自動在賦值時驗證
複雜度	簡單直覺	需要理解 Descriptor Protocol
調試	容易追蹤	需要了解 `__get__`/`__set__`
彈性	高	中等（需要遵循 Descriptor 協議）

什麼時候該用宣告式驗證？

適合使用：

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 設計與應用

案例：自動註冊機制

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_validator.py 的實際程式碼，展示如何用 Metaclass 實現檢查器的自動註冊。

先備知識

問題背景

現有設計

hook_validator.py 的 HookValidator 類別包含多個 check_* 方法，需要在 validate_hook() 中手動呼叫：

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    def validate_hook(self, hook_path: str) -> ValidationResult:
 5        """驗證單個 Hook 檔案"""
 6        # ... 前置處理 ...
 7
 8        # 執行各項檢查 - 手動呼叫每個 check 方法
 9        issues = []
10        issues.extend(self.check_naming_convention(hook_path))
11        issues.extend(self.check_lib_imports(content, hook_path))
12        issues.extend(self.check_output_format(content))
13        issues.extend(self.check_test_exists(hook_path))
14
15        return ValidationResult(hook_path=str(hook_path), issues=issues)
16
17    def check_naming_convention(self, hook_path: Path) -> List[ValidationIssue]:
18        """檢查命名規範"""
19        # ... 實作 ...
20
21    def check_lib_imports(self, content: str, hook_path: Path) -> List[ValidationIssue]:
22        """檢查共用模組導入"""
23        # ... 實作 ...
24
25    def check_output_format(self, content: str) -> List[ValidationIssue]:
26        """檢查 Hook 輸出格式"""
27        # ... 實作 ...
28
29    def check_test_exists(self, hook_path: Path) -> List[ValidationIssue]:
30        """檢查對應的測試檔案是否存在"""
31        # ... 實作 ...

這個設計的優點

明確的執行順序：可以精確控制檢查項的執行順序
容易理解呼叫流程：閱讀 validate_hook() 就知道會執行哪些檢查
簡單直覺：不需要學習額外的抽象概念

這個設計的限制

新增檢查項時：

需要修改兩處程式碼：新增 check_* 方法 + 修改 validate_hook() 呼叫
容易忘記註冊：新增方法後忘記在 validate_hook() 中呼叫
無法動態控制：無法在執行時期啟用/停用特定檢查項
難以擴展：子類別新增檢查項也需要覆寫 validate_hook()

進階解決方案

設計目標

定義檢查方法時自動註冊到執行清單
支援優先順序控制
支援動態啟用/停用特定檢查項
子類別的檢查項自動繼承

實作步驟

步驟 1：用裝飾器標記檢查方法

首先，我們需要一個方式來標記哪些方法是「檢查器」。裝飾器是最自然的選擇：

 1from functools import wraps
 2from typing import Callable, Optional
 3
 4def check(
 5    priority: int = 100,
 6    enabled: bool = True,
 7    description: str = ""
 8) -> Callable:
 9    """
10    Decorator to mark a method as a checker.
11
12    Args:
13        priority: Execution order (lower runs first)
14        enabled: Whether this check is enabled by default
15        description: Human-readable description
16
17    Example:
18        @check(priority=10, description="Validate filename format")
19        def check_naming(self, hook_path):
20            ...
21    """
22    def decorator(func: Callable) -> Callable:
23        # Store metadata on the function object
24        func._is_checker = True
25        func._checker_priority = priority
26        func._checker_enabled = enabled
27        func._checker_description = description or func.__doc__ or func.__name__
28
29        @wraps(func)
30        def wrapper(*args, **kwargs):
31            return func(*args, **kwargs)
32
33        # Copy metadata to wrapper
34        wrapper._is_checker = True
35        wrapper._checker_priority = priority
36        wrapper._checker_enabled = enabled
37        wrapper._checker_description = description or func.__doc__ or func.__name__
38
39        return wrapper
40    return decorator

使用方式：

 1class Validator:
 2    @check(priority=10, description="Check filename format")
 3    def check_naming_convention(self, hook_path):
 4        """檢查命名規範"""
 5        ...
 6
 7    @check(priority=20, description="Check library imports")
 8    def check_lib_imports(self, content, hook_path):
 9        """檢查共用模組導入"""
10        ...

步驟 2：用 Metaclass 收集標記的方法

接下來，用 Metaclass 在類別建立時自動收集所有被 @check 標記的方法：

 1class CheckerMeta(type):
 2    """
 3    Metaclass that automatically collects methods marked with @check.
 4
 5    When a class is created, this metaclass:
 6    1. Scans all methods for the _is_checker attribute
 7    2. Collects them into a _checkers registry
 8    3. Sorts by priority for execution order
 9    """
10
11    def __new__(mcs, name: str, bases: tuple, namespace: dict):
12        # Create the class first
13        cls = super().__new__(mcs, name, bases, namespace)
14
15        # Collect checkers from parent classes
16        inherited_checkers = {}
17        for base in bases:
18            if hasattr(base, '_checkers'):
19                inherited_checkers.update(base._checkers)
20
21        # Collect checkers from current class
22        current_checkers = {}
23        for attr_name, attr_value in namespace.items():
24            if callable(attr_value) and getattr(attr_value, '_is_checker', False):
25                current_checkers[attr_name] = {
26                    'method': attr_name,
27                    'priority': attr_value._checker_priority,
28                    'enabled': attr_value._checker_enabled,
29                    'description': attr_value._checker_description,
30                }
31
32        # Merge: current class can override parent checkers
33        all_checkers = {**inherited_checkers, **current_checkers}
34
35        # Store as class attribute
36        cls._checkers = all_checkers
37
38        return cls

步驟 3：實作優先順序

在 Metaclass 中已經收集了優先順序資訊，現在需要一個方法按順序執行：

 1class CheckerBase(metaclass=CheckerMeta):
 2    """
 3    Base class for validators with auto-registration.
 4
 5    Provides run_all_checks() to execute registered checkers.
 6    """
 7
 8    def get_sorted_checkers(self) -> list:
 9        """
10        Get all enabled checkers sorted by priority.
11
12        Returns:
13            List of (method_name, checker_info) tuples
14        """
15        checkers = [
16            (name, info)
17            for name, info in self._checkers.items()
18            if info['enabled']
19        ]
20        # Sort by priority (lower number = higher priority)
21        return sorted(checkers, key=lambda x: x[1]['priority'])
22
23    def run_all_checks(self, *args, **kwargs) -> list:
24        """
25        Run all enabled checkers in priority order.
26
27        Args:
28            *args, **kwargs: Arguments passed to each checker
29
30        Returns:
31            Combined list of issues from all checkers
32        """
33        all_issues = []
34
35        for method_name, info in self.get_sorted_checkers():
36            method = getattr(self, method_name)
37            try:
38                issues = method(*args, **kwargs)
39                if issues:
40                    all_issues.extend(issues)
41            except Exception as e:
42                # Optionally handle checker errors
43                all_issues.append({
44                    'level': 'error',
45                    'message': f"Checker {method_name} failed: {e}"
46                })
47
48        return all_issues

步驟 4：實作啟用/停用機制

允許在執行時期動態控制檢查項：

 1class CheckerBase(metaclass=CheckerMeta):
 2    """
 3    Base class for validators with auto-registration.
 4    """
 5
 6    def __init__(self):
 7        # Instance-level override for checker states
 8        self._checker_overrides = {}
 9
10    def enable_checker(self, checker_name: str) -> None:
11        """
12        Enable a specific checker for this instance.
13
14        Args:
15            checker_name: Name of the checker method
16        """
17        if checker_name not in self._checkers:
18            raise ValueError(f"Unknown checker: {checker_name}")
19        self._checker_overrides[checker_name] = True
20
21    def disable_checker(self, checker_name: str) -> None:
22        """
23        Disable a specific checker for this instance.
24
25        Args:
26            checker_name: Name of the checker method
27        """
28        if checker_name not in self._checkers:
29            raise ValueError(f"Unknown checker: {checker_name}")
30        self._checker_overrides[checker_name] = False
31
32    def is_checker_enabled(self, checker_name: str) -> bool:
33        """
34        Check if a specific checker is enabled.
35
36        Instance overrides take precedence over class defaults.
37        """
38        if checker_name in self._checker_overrides:
39            return self._checker_overrides[checker_name]
40        return self._checkers.get(checker_name, {}).get('enabled', False)
41
42    def get_sorted_checkers(self) -> list:
43        """Get all enabled checkers sorted by priority."""
44        checkers = [
45            (name, info)
46            for name, info in self._checkers.items()
47            if self.is_checker_enabled(name)
48        ]
49        return sorted(checkers, key=lambda x: x[1]['priority'])
50
51    def list_checkers(self) -> list:
52        """
53        List all available checkers with their status.
54
55        Returns:
56            List of dicts with checker information
57        """
58        result = []
59        for name, info in sorted(
60            self._checkers.items(),
61            key=lambda x: x[1]['priority']
62        ):
63            result.append({
64                'name': name,
65                'priority': info['priority'],
66                'enabled': self.is_checker_enabled(name),
67                'description': info['description'],
68            })
69        return result

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Auto-registration pattern using Metaclass.
  4
  5This module demonstrates how to automatically register checker methods
  6using a combination of decorators and metaclasses.
  7"""
  8
  9from dataclasses import dataclass, field
 10from functools import wraps
 11from pathlib import Path
 12from typing import Callable, List, Optional, Any
 13import re
 14
 15# ===== Data Classes =====
 16
 17@dataclass
 18class ValidationIssue:
 19    """Represents a validation issue."""
 20    level: str  # "error" | "warning" | "info"
 21    message: str
 22    line: Optional[int] = None
 23    suggestion: Optional[str] = None
 24
 25@dataclass
 26class ValidationResult:
 27    """Validation result for a single target."""
 28    target: str
 29    issues: List[ValidationIssue] = field(default_factory=list)
 30
 31    @property
 32    def is_valid(self) -> bool:
 33        """True if no errors found."""
 34        return not any(issue.level == "error" for issue in self.issues)
 35
 36# ===== Decorator =====
 37
 38def check(
 39    priority: int = 100,
 40    enabled: bool = True,
 41    description: str = ""
 42) -> Callable:
 43    """
 44    Decorator to mark a method as a checker.
 45
 46    Args:
 47        priority: Execution order (lower runs first)
 48        enabled: Whether this check is enabled by default
 49        description: Human-readable description
 50    """
 51    def decorator(func: Callable) -> Callable:
 52        @wraps(func)
 53        def wrapper(*args, **kwargs):
 54            return func(*args, **kwargs)
 55
 56        # Store metadata
 57        wrapper._is_checker = True
 58        wrapper._checker_priority = priority
 59        wrapper._checker_enabled = enabled
 60        wrapper._checker_description = description or func.__doc__ or func.__name__
 61
 62        return wrapper
 63    return decorator
 64
 65# ===== Metaclass =====
 66
 67class CheckerMeta(type):
 68    """
 69    Metaclass that automatically collects @check decorated methods.
 70    """
 71
 72    def __new__(mcs, name: str, bases: tuple, namespace: dict):
 73        cls = super().__new__(mcs, name, bases, namespace)
 74
 75        # Inherit checkers from parent classes
 76        inherited_checkers = {}
 77        for base in bases:
 78            if hasattr(base, '_checkers'):
 79                inherited_checkers.update(base._checkers)
 80
 81        # Collect checkers from current class
 82        current_checkers = {}
 83        for attr_name, attr_value in namespace.items():
 84            if callable(attr_value) and getattr(attr_value, '_is_checker', False):
 85                current_checkers[attr_name] = {
 86                    'method': attr_name,
 87                    'priority': attr_value._checker_priority,
 88                    'enabled': attr_value._checker_enabled,
 89                    'description': attr_value._checker_description,
 90                }
 91
 92        # Merge checkers
 93        cls._checkers = {**inherited_checkers, **current_checkers}
 94
 95        return cls
 96
 97# ===== Base Class =====
 98
 99class CheckerBase(metaclass=CheckerMeta):
100    """
101    Base class providing auto-registration functionality.
102    """
103
104    def __init__(self):
105        self._checker_overrides = {}
106
107    def enable_checker(self, name: str) -> None:
108        """Enable a checker for this instance."""
109        if name not in self._checkers:
110            raise ValueError(f"Unknown checker: {name}")
111        self._checker_overrides[name] = True
112
113    def disable_checker(self, name: str) -> None:
114        """Disable a checker for this instance."""
115        if name not in self._checkers:
116            raise ValueError(f"Unknown checker: {name}")
117        self._checker_overrides[name] = False
118
119    def is_checker_enabled(self, name: str) -> bool:
120        """Check if a checker is enabled."""
121        if name in self._checker_overrides:
122            return self._checker_overrides[name]
123        return self._checkers.get(name, {}).get('enabled', False)
124
125    def get_sorted_checkers(self) -> list:
126        """Get enabled checkers sorted by priority."""
127        return sorted(
128            [(n, i) for n, i in self._checkers.items() if self.is_checker_enabled(n)],
129            key=lambda x: x[1]['priority']
130        )
131
132    def list_checkers(self) -> list:
133        """List all checkers with their status."""
134        return [
135            {
136                'name': name,
137                'priority': info['priority'],
138                'enabled': self.is_checker_enabled(name),
139                'description': info['description'],
140            }
141            for name, info in sorted(
142                self._checkers.items(),
143                key=lambda x: x[1]['priority']
144            )
145        ]
146
147# ===== Implementation Example =====
148
149class HookValidator(CheckerBase):
150    """
151    Hook validator with auto-registered checkers.
152
153    Checkers are automatically discovered and executed in priority order.
154    """
155
156    # Pattern constants
157    VALID_NAME_PATTERN = r"^[a-z0-9](/python-advanced/02-metaprogramming/case-studies/auto-registration/[a-z0-9\-_]*[a-z0-9])?\.py$"
158    HOOK_IO_PATTERNS = [
159        r"from\s+hook_io\s+import",
160        r"from\s+lib\.hook_io\s+import",
161    ]
162    BAD_OUTPUT_PATTERNS = [
163        r'print\s*\(\s*json\.dumps\s*\(',
164    ]
165
166    def __init__(self, project_root: Optional[str] = None):
167        super().__init__()
168        self.project_root = Path(project_root) if project_root else Path.cwd()
169
170    def validate(self, hook_path: str) -> ValidationResult:
171        """
172        Validate a hook file by running all enabled checkers.
173
174        Args:
175            hook_path: Path to the hook file
176
177        Returns:
178            ValidationResult with all issues found
179        """
180        path = Path(hook_path)
181        if not path.is_absolute():
182            path = self.project_root / path
183
184        # Read file content
185        try:
186            content = path.read_text(encoding='utf-8')
187        except Exception as e:
188            return ValidationResult(
189                target=str(path),
190                issues=[ValidationIssue(
191                    level="error",
192                    message=f"Cannot read file: {e}"
193                )]
194            )
195
196        # Prepare context for checkers
197        context = {
198            'path': path,
199            'content': content,
200            'filename': path.name,
201        }
202
203        # Run all enabled checkers
204        all_issues = []
205        for method_name, _ in self.get_sorted_checkers():
206            method = getattr(self, method_name)
207            try:
208                issues = method(context)
209                if issues:
210                    all_issues.extend(issues)
211            except Exception as e:
212                all_issues.append(ValidationIssue(
213                    level="error",
214                    message=f"Checker '{method_name}' crashed: {e}"
215                ))
216
217        return ValidationResult(target=str(path), issues=all_issues)
218
219    @check(priority=10, description="Check filename format")
220    def check_naming_convention(self, ctx: dict) -> List[ValidationIssue]:
221        """Validate hook filename follows naming convention."""
222        issues = []
223        filename = ctx['filename']
224
225        if not re.match(self.VALID_NAME_PATTERN, filename):
226            issues.append(ValidationIssue(
227                level="warning",
228                message=f"Filename '{filename}' doesn't follow naming convention",
229                suggestion="Use snake_case or kebab-case, e.g., check_format.py"
230            ))
231
232        return issues
233
234    @check(priority=20, description="Check hook_io import")
235    def check_lib_imports(self, ctx: dict) -> List[ValidationIssue]:
236        """Check if hook_io module is properly imported."""
237        issues = []
238        content = ctx['content']
239
240        has_import = any(
241            re.search(pattern, content)
242            for pattern in self.HOOK_IO_PATTERNS
243        )
244
245        if not has_import:
246            issues.append(ValidationIssue(
247                level="warning",
248                message="hook_io module not imported",
249                suggestion="Add: from hook_io import read_hook_input, write_hook_output"
250            ))
251
252        return issues
253
254    @check(priority=30, description="Check output format")
255    def check_output_format(self, ctx: dict) -> List[ValidationIssue]:
256        """Check if proper output functions are used."""
257        issues = []
258        content = ctx['content']
259
260        for pattern in self.BAD_OUTPUT_PATTERNS:
261            if re.search(pattern, content):
262                issues.append(ValidationIssue(
263                    level="warning",
264                    message="Using print(json.dumps(...)) instead of write_hook_output()",
265                    suggestion="Replace with: write_hook_output(output_dict)"
266                ))
267                break
268
269        return issues
270
271    @check(priority=40, enabled=False, description="Check test file exists")
272    def check_test_exists(self, ctx: dict) -> List[ValidationIssue]:
273        """Check if corresponding test file exists."""
274        issues = []
275        hook_name = ctx['path'].stem
276        test_name = f"test_{hook_name.replace('-', '_')}.py"
277
278        test_path = self.project_root / ".claude" / "lib" / "tests" / test_name
279        if not test_path.exists():
280            issues.append(ValidationIssue(
281                level="info",
282                message=f"No test file found: {test_name}",
283                suggestion=f"Create test at: {test_path}"
284            ))
285
286        return issues
287
288# ===== Extended Example: Subclass =====
289
290class StrictHookValidator(HookValidator):
291    """
292    Extended validator with additional checks.
293
294    Inherits all checks from HookValidator and adds more.
295    """
296
297    @check(priority=15, description="Check shebang line")
298    def check_shebang(self, ctx: dict) -> List[ValidationIssue]:
299        """Check if file starts with proper shebang."""
300        issues = []
301        content = ctx['content']
302
303        if not content.startswith('#!/usr/bin/env python'):
304            issues.append(ValidationIssue(
305                level="info",
306                message="Missing shebang line",
307                suggestion="Add: #!/usr/bin/env python3"
308            ))
309
310        return issues
311
312    @check(priority=25, description="Check docstring exists")
313    def check_docstring(self, ctx: dict) -> List[ValidationIssue]:
314        """Check if module has a docstring."""
315        issues = []
316        content = ctx['content']
317
318        # Simple check: look for triple quotes near the start
319        lines = content.split('\n')[:10]  # First 10 lines
320        has_docstring = any('"""' in line or "'''" in line for line in lines)
321
322        if not has_docstring:
323            issues.append(ValidationIssue(
324                level="info",
325                message="Module docstring not found",
326                suggestion="Add a docstring at the top of the file"
327            ))
328
329        return issues
330
331# ===== Demo =====
332
333if __name__ == "__main__":
334    print("=" * 60)
335    print("Auto-Registration Demo")
336    print("=" * 60)
337
338    # Create validator
339    validator = HookValidator()
340
341    # List all registered checkers
342    print("\n[Registered Checkers]")
343    for checker in validator.list_checkers():
344        status = "ON" if checker['enabled'] else "OFF"
345        print(f"  [{status}] {checker['name']} (priority: {checker['priority']})")
346        print(f"        {checker['description']}")
347
348    # Enable disabled checker
349    print("\n[Enable check_test_exists]")
350    validator.enable_checker('check_test_exists')
351    for checker in validator.list_checkers():
352        if checker['name'] == 'check_test_exists':
353            status = "ON" if checker['enabled'] else "OFF"
354            print(f"  [{status}] {checker['name']}")
355
356    # Demo with extended validator
357    print("\n[Extended Validator - StrictHookValidator]")
358    strict_validator = StrictHookValidator()
359    for checker in strict_validator.list_checkers():
360        status = "ON" if checker['enabled'] else "OFF"
361        print(f"  [{status}] {checker['name']} (priority: {checker['priority']})")
362
363    print("\n" + "=" * 60)

使用範例

 1# Create validator instance
 2validator = HookValidator(project_root="/path/to/project")
 3
 4# List available checkers
 5for checker in validator.list_checkers():
 6    print(f"[{'ON' if checker['enabled'] else 'OFF'}] {checker['name']}")
 7
 8# Output:
 9# [ON] check_naming_convention
10# [ON] check_lib_imports
11# [ON] check_output_format
12# [OFF] check_test_exists
13
14# Enable/disable checkers dynamically
15validator.enable_checker('check_test_exists')
16validator.disable_checker('check_output_format')
17
18# Validate a hook file
19result = validator.validate(".claude/hooks/my-hook.py")
20print(f"Valid: {result.is_valid}")
21for issue in result.issues:
22    print(f"  [{issue.level}] {issue.message}")
23
24# Create extended validator with more checks
25strict = StrictHookValidator()
26print(f"Total checkers: {len(strict.list_checkers())}")  # Inherits parent's checkers

替代方案：`__init_subclass__`

Python 3.6 引入了 __init_subclass__，可以在不使用 Metaclass 的情況下實現部分功能：

 1class CheckerBase:
 2    """
 3    Base class using __init_subclass__ for auto-registration.
 4
 5    Simpler than metaclass, but less powerful.
 6    """
 7    _checkers = {}
 8
 9    def __init_subclass__(cls, **kwargs):
10        super().__init_subclass__(**kwargs)
11
12        # Collect checkers from this subclass
13        for attr_name in dir(cls):
14            attr = getattr(cls, attr_name, None)
15            if callable(attr) and getattr(attr, '_is_checker', False):
16                cls._checkers[attr_name] = {
17                    'method': attr_name,
18                    'priority': attr._checker_priority,
19                    'enabled': attr._checker_enabled,
20                    'description': attr._checker_description,
21                }
22
23class HookValidator(CheckerBase):
24    """Validator using __init_subclass__."""
25
26    @check(priority=10)
27    def check_naming(self, ctx):
28        """Check naming convention."""
29        pass
30
31    @check(priority=20)
32    def check_imports(self, ctx):
33        """Check imports."""
34        pass

`__init_subclass__` vs Metaclass

面向	`__init_subclass__`	Metaclass
複雜度	低	高
適用場景	子類別註冊	完整控制類別建立
效能	較好	略差
修改類別	有限	完整
繼承處理	需手動	自動
推薦情況	優先使用	需要進階功能時

原則：如果 __init_subclass__ 能滿足需求，優先使用它。

設計權衡

面向	手動註冊	Metaclass 自動註冊
程式碼重複	高（每次新增都要改兩處）	低（只需加裝飾器）
理解難度	低	中（需理解 Metaclass）
擴展性	差（子類別需覆寫）	好（自動繼承）
除錯難度	低	中（執行流程隱含）
動態控制	需額外實作	內建支援
執行順序	明確可見	由 priority 決定

什麼時候該用這個技術？

適合使用：

插件系統：需要自動發現和載入插件
框架開發：Django admin、pytest fixtures 等
大量相似元件：多個檢查器/處理器需統一管理
需要動態控制：執行時期啟用/停用功能

不建議使用：

只有少數幾個檢查項：手動維護更簡單
團隊不熟悉 Metaclass：增加維護負擔
簡單的應用程式：過度工程
執行順序非常重要：手動呼叫更明確

練習

基礎練習

實作一個簡單的命令註冊系統：

 1class CommandRegistry:
 2    """
 3    命令註冊系統
 4
 5    需求：
 6    1. 用 @command(name="xxx") 裝飾器註冊命令
 7    2. 提供 execute(name, *args) 執行指定命令
 8    3. 提供 list_commands() 列出所有命令
 9    """
10    pass
11
12# 使用範例
13class MyApp(CommandRegistry):
14    @command(name="greet")
15    def say_hello(self, name):
16        return f"Hello, {name}!"
17
18    @command(name="add")
19    def add_numbers(self, a, b):
20        return a + b
21
22app = MyApp()
23print(app.execute("greet", "World"))  # Hello, World!
24print(app.list_commands())  # ['add', 'greet']

進階練習

新增檢查項的相依性管理：

1@check(priority=10, depends_on=['check_file_exists'])
2def check_content(self, ctx):
3    """只有在檔案存在檢查通過後才執行"""
4    pass

提示：

在 @check 裝飾器加入 depends_on 參數
在 run_all_checks() 中追蹤每個檢查項的結果
檢查相依項是否通過再執行

挑戰題

實作跨模組的檢查項發現（類似 pytest）：

 1# checkers/naming.py
 2@check(priority=10)
 3def check_naming(ctx):
 4    pass
 5
 6# checkers/imports.py
 7@check(priority=20)
 8def check_imports(ctx):
 9    pass
10
11# main.py
12validator = HookValidator()
13validator.discover_checkers('checkers/')  # 自動載入目錄下的所有檢查項

提示：

使用 importlib 動態載入模組
掃描模組中帶有 _is_checker 標記的函式
將函式綁定為實例方法

延伸閱讀

上一章：宣告式驗證 下一章：類似 Django Field

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 完整指南 下一章：類別裝飾器與動態類別

模組二：元編程

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

元編程（Metaprogramming）是指撰寫可以操作程式碼的程式碼。Python 提供了豐富的元編程機制，包括 Descriptor、Metaclass、類別裝飾器等。

你已經在使用元編程

如果你完成了入門系列，你其實已經接觸過元編程了：

 1# 1. @property - Descriptor Protocol 的應用
 2class User:
 3 @property
 4 def full_name(self):
 5 return f"{self.first} {self.last}"
 6
 7# 2. @dataclass - 類別裝飾器 + 元類別技術
 8@dataclass
 9class Config:
10 name: str
11 timeout: int = 30
12
13# 3. ABC - 元類別控制子類別行為
14from abc import ABC, abstractmethod
15class Parser(ABC):
16 @abstractmethod
17 def parse(self, content: str) -> dict:
18 pass

這些都是元編程的入門應用。本模組將深入探討它們背後的原理，以及如何創建自己的元編程工具。

為什麼學習元編程？

理解元編程機制有多重好處：

理解框架：Django Model、SQLAlchemy、Pydantic 都大量使用元編程
建立抽象：可以設計更優雅的 API
深入 Python：理解 Python 物件模型的本質

章節列表

章節	主題	關鍵收穫
2.1	Descriptor Protocol 完整指南	理解 @property 的本質
2.2	Metaclass 設計與應用	控制類別的建立過程
2.3	類別裝飾器與動態類別	@dataclass 的實現原理
2.4	反射與 inspect 模組	程式檢視自身的能力

案例研究

基於 .claude/lib 實際程式碼的進階案例：

案例	素材	學習重點
宣告式驗證	hook_validator.py	Descriptor Protocol
自動註冊機制	hook_validator.py	Metaclass
類似 Django Field	hook_io.py	Descriptor + dataclass

先備知識

入門系列 4.4 單例與快取
熟悉 Python 的類別與物件

何時使用元編程？

元編程強大但複雜，使用前請考慮：

場景	建議
需要驗證屬性	先考慮 @property
需要修改類別	先考慮類別裝飾器
需要控制子類別	先考慮 init_subclass
需要深度定制	才考慮 Metaclass

原則：能用簡單方案解決就不用複雜方案。

學習時間

每章節約 30-45 分鐘，全模組約 2-3 小時

上一模組：模組一：非同步程式設計 下一模組：模組三：CPython 內部機制

案例：類似 Django Field 的設計

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/hook_io.py 的實際程式碼，展示如何結合 Descriptor 和 dataclass 設計類似 Django Model Field 的宣告式 API。

先備知識

問題背景

現有設計

hook_io.py 使用函式工廠模式建構 Hook 輸出：

 1def create_pretooluse_output(
 2    decision: str,
 3    reason: str,
 4    user_prompt: Optional[str] = None,
 5    system_message: Optional[str] = None,
 6    suppress_output: bool = False
 7) -> dict:
 8    """
 9    建立 PreToolUse Hook 輸出格式
10
11    Args:
12        decision: 決策結果 ("allow" | "deny" | "ask")
13        reason: 決策原因說明
14        user_prompt: 詢問用戶的訊息（僅當 decision 為 "ask" 時使用）
15        system_message: 系統訊息（可選）
16        suppress_output: 是否抑制輸出（預設 False）
17
18    Returns:
19        dict: 標準 PreToolUse Hook 輸出格式
20    """
21    output: dict[str, Any] = {
22        "hookSpecificOutput": {
23            "hookEventName": "PreToolUse",
24            "permissionDecision": decision,
25            "permissionDecisionReason": reason
26        }
27    }
28
29    if user_prompt:
30        output["hookSpecificOutput"]["userPrompt"] = user_prompt
31
32    if system_message:
33        output["systemMessage"] = system_message
34
35    if suppress_output:
36        output["suppressOutput"] = True
37
38    return output

這個設計的優點

清晰的建構流程：函式簽名清楚說明所需參數
支援可選參數：使用 Optional 和預設值處理可選欄位
型別提示完整：有完整的參數型別標註

這個設計的限制

當需要序列化/反序列化時：

需要手動處理每個欄位：to_dict 和 from_dict 需要逐一處理
欄位定義與驗證分離：型別檢查和業務驗證在不同地方
難以生成文件或 schema：無法自動產生 JSON Schema 或 API 文件

進階解決方案

設計目標

欄位定義包含型別、驗證、序列化
自動生成 __init__、to_dict、from_dict
支援巢狀結構

實作步驟

步驟 1：設計 Field 基類

 1from typing import Any, Optional, Type, Generic, TypeVar, Callable, get_type_hints
 2
 3T = TypeVar("T")
 4
 5class Field(Generic[T]):
 6    """
 7    Field Descriptor base class
 8
 9    Combines Django's field declaration style with Python's
10    descriptor protocol for type-safe, declarative model design.
11    """
12
13    def __init__(
14        self,
15        *,
16        default: Optional[T] = None,
17        required: bool = True,
18        serialized_name: Optional[str] = None,
19        validator: Optional[Callable[[T], bool]] = None,
20        error_msg: str = "Validation failed"
21    ):
22        """
23        Args:
24            default: Default value when not provided
25            required: Whether field is required (default True)
26            serialized_name: Name used in serialization (default: attribute name)
27            validator: Optional validation function
28            error_msg: Error message for validation failure
29        """
30        self.default = default
31        self.required = required
32        self.serialized_name = serialized_name
33        self.validator = validator
34        self.error_msg = error_msg
35
36        # Set by __set_name__
37        self.name: str = ""
38        self.private_name: str = ""
39
40    def __set_name__(self, owner: type, name: str) -> None:
41        """
42        Called automatically when the descriptor is assigned to a class attribute.
43
44        This is where we get the attribute name from the class definition,
45        eliminating the need to pass it explicitly.
46        """
47        self.name = name
48        self.private_name = f"_field_{name}"
49        # Use attribute name as serialized name if not specified
50        if self.serialized_name is None:
51            self.serialized_name = name
52
53    def __get__(self, obj: Any, objtype: type = None) -> Any:
54        """Return field value or descriptor itself if accessed on class."""
55        if obj is None:
56            return self  # Class access returns descriptor
57        return getattr(obj, self.private_name, self.default)
58
59    def __set__(self, obj: Any, value: Any) -> None:
60        """Validate and set field value."""
61        # Handle None for optional fields
62        if value is None:
63            if self.required and self.default is None:
64                raise ValueError(f"{self.name}: This field is required")
65            setattr(obj, self.private_name, self.default)
66            return
67
68        # Run custom validator if provided
69        if self.validator and not self.validator(value):
70            raise ValueError(f"{self.name}: {self.error_msg}")
71
72        setattr(obj, self.private_name, value)
73
74    def serialize(self, value: T) -> Any:
75        """Convert Python value to serializable format."""
76        return value
77
78    def deserialize(self, value: Any) -> T:
79        """Convert serialized value to Python type."""
80        return value

關鍵設計要點：

__set_name__ 自動取得屬性名稱，不需要像 Django 早期版本手動傳入
serialized_name 支援序列化時使用不同的欄位名稱（如 camelCase）
serialize/deserialize 方法供子類覆寫，實現型別轉換

步驟 2：實作型別特定的 Field

  1import re
  2from datetime import datetime
  3from typing import List, Type, TypeVar
  4
  5class StringField(Field[str]):
  6    """String field with optional pattern validation."""
  7
  8    def __init__(
  9        self,
 10        *,
 11        pattern: Optional[str] = None,
 12        min_length: int = 0,
 13        max_length: Optional[int] = None,
 14        **kwargs
 15    ):
 16        super().__init__(**kwargs)
 17        self.pattern = re.compile(pattern) if pattern else None
 18        self.min_length = min_length
 19        self.max_length = max_length
 20
 21    def __set__(self, obj: Any, value: Any) -> None:
 22        if value is not None:
 23            if not isinstance(value, str):
 24                raise TypeError(f"{self.name}: Expected str, got {type(value).__name__}")
 25
 26            if self.min_length and len(value) < self.min_length:
 27                raise ValueError(f"{self.name}: Minimum length is {self.min_length}")
 28
 29            if self.max_length and len(value) > self.max_length:
 30                raise ValueError(f"{self.name}: Maximum length is {self.max_length}")
 31
 32            if self.pattern and not self.pattern.match(value):
 33                raise ValueError(f"{self.name}: Does not match pattern")
 34
 35        super().__set__(obj, value)
 36
 37class IntField(Field[int]):
 38    """Integer field with range validation."""
 39
 40    def __init__(
 41        self,
 42        *,
 43        min_value: Optional[int] = None,
 44        max_value: Optional[int] = None,
 45        **kwargs
 46    ):
 47        super().__init__(**kwargs)
 48        self.min_value = min_value
 49        self.max_value = max_value
 50
 51    def __set__(self, obj: Any, value: Any) -> None:
 52        if value is not None:
 53            if not isinstance(value, int) or isinstance(value, bool):
 54                raise TypeError(f"{self.name}: Expected int, got {type(value).__name__}")
 55
 56            if self.min_value is not None and value < self.min_value:
 57                raise ValueError(f"{self.name}: Minimum value is {self.min_value}")
 58
 59            if self.max_value is not None and value > self.max_value:
 60                raise ValueError(f"{self.name}: Maximum value is {self.max_value}")
 61
 62        super().__set__(obj, value)
 63
 64class BoolField(Field[bool]):
 65    """Boolean field."""
 66
 67    def __set__(self, obj: Any, value: Any) -> None:
 68        if value is not None and not isinstance(value, bool):
 69            raise TypeError(f"{self.name}: Expected bool, got {type(value).__name__}")
 70        super().__set__(obj, value)
 71
 72class ChoiceField(Field[str]):
 73    """Field with predefined choices."""
 74
 75    def __init__(self, *, choices: tuple[str, ...], **kwargs):
 76        super().__init__(**kwargs)
 77        self.choices = choices
 78
 79    def __set__(self, obj: Any, value: Any) -> None:
 80        if value is not None and value not in self.choices:
 81            choices_str = ", ".join(repr(c) for c in self.choices)
 82            raise ValueError(f"{self.name}: Must be one of: {choices_str}")
 83        super().__set__(obj, value)
 84
 85class ListField(Field[list]):
 86    """List field with item type validation."""
 87
 88    def __init__(self, *, item_field: Field, **kwargs):
 89        # ListField defaults to empty list, not required
 90        kwargs.setdefault("default", [])
 91        kwargs.setdefault("required", False)
 92        super().__init__(**kwargs)
 93        self.item_field = item_field
 94
 95    def __set__(self, obj: Any, value: Any) -> None:
 96        if value is not None:
 97            if not isinstance(value, list):
 98                raise TypeError(f"{self.name}: Expected list, got {type(value).__name__}")
 99            # Validate each item using item_field's validation logic
100            # (simplified - in production you'd want proper item validation)
101        super().__set__(obj, value if value is not None else [])
102
103    def serialize(self, value: list) -> list:
104        """Serialize list items."""
105        return [self.item_field.serialize(item) for item in value]
106
107    def deserialize(self, value: list) -> list:
108        """Deserialize list items."""
109        return [self.item_field.deserialize(item) for item in value]
110
111class DateTimeField(Field[datetime]):
112    """DateTime field with ISO format serialization."""
113
114    def __init__(self, *, format: str = "%Y-%m-%dT%H:%M:%S", **kwargs):
115        super().__init__(**kwargs)
116        self.format = format
117
118    def __set__(self, obj: Any, value: Any) -> None:
119        if value is not None and not isinstance(value, datetime):
120            raise TypeError(f"{self.name}: Expected datetime, got {type(value).__name__}")
121        super().__set__(obj, value)
122
123    def serialize(self, value: datetime) -> str:
124        """Convert datetime to ISO string."""
125        return value.strftime(self.format) if value else None
126
127    def deserialize(self, value: str) -> datetime:
128        """Parse ISO string to datetime."""
129        return datetime.strptime(value, self.format) if value else None

步驟 3：用 Metaclass 處理欄位收集

  1class ModelMeta(type):
  2    """
  3    Metaclass for Model classes.
  4
  5    Responsibilities:
  6    1. Collect all Field descriptors from class definition
  7    2. Store field metadata for serialization/deserialization
  8    3. Generate __init__ signature from fields
  9    """
 10
 11    def __new__(mcs, name: str, bases: tuple, namespace: dict):
 12        # Collect fields from this class and parent classes
 13        fields: dict[str, Field] = {}
 14
 15        # Inherit fields from parent Model classes
 16        for base in bases:
 17            if hasattr(base, "_fields"):
 18                fields.update(base._fields)
 19
 20        # Collect fields from current class
 21        for attr_name, attr_value in namespace.items():
 22            if isinstance(attr_value, Field):
 23                fields[attr_name] = attr_value
 24
 25        # Store fields metadata
 26        namespace["_fields"] = fields
 27
 28        return super().__new__(mcs, name, bases, namespace)
 29
 30class Model(metaclass=ModelMeta):
 31    """
 32    Base class for declarative models.
 33
 34    Provides:
 35    - Automatic __init__ from field definitions
 36    - to_dict() for serialization
 37    - from_dict() for deserialization
 38    """
 39
 40    _fields: dict[str, Field]  # Set by metaclass
 41
 42    def __init__(self, **kwargs):
 43        """
 44        Initialize model from keyword arguments.
 45
 46        All defined fields can be passed as keyword arguments.
 47        Required fields must be provided unless they have defaults.
 48        """
 49        # Set each field value, triggering descriptor validation
 50        for field_name, field in self._fields.items():
 51            value = kwargs.get(field_name, field.default)
 52            setattr(self, field_name, value)
 53
 54        # Check for unknown fields
 55        unknown = set(kwargs.keys()) - set(self._fields.keys())
 56        if unknown:
 57            raise TypeError(f"Unknown fields: {', '.join(unknown)}")
 58
 59    def to_dict(self) -> dict:
 60        """
 61        Serialize model to dictionary.
 62
 63        Uses each field's serialized_name and serialize() method.
 64        """
 65        result = {}
 66        for field_name, field in self._fields.items():
 67            value = getattr(self, field_name)
 68            if value is not None or field.required:
 69                serialized_name = field.serialized_name or field_name
 70                result[serialized_name] = field.serialize(value)
 71        return result
 72
 73    @classmethod
 74    def from_dict(cls, data: dict) -> "Model":
 75        """
 76        Deserialize dictionary to model instance.
 77
 78        Handles field name mapping and type conversion.
 79        """
 80        kwargs = {}
 81
 82        for field_name, field in cls._fields.items():
 83            serialized_name = field.serialized_name or field_name
 84
 85            if serialized_name in data:
 86                kwargs[field_name] = field.deserialize(data[serialized_name])
 87            elif field_name in data:
 88                # Fallback to field name if serialized name not found
 89                kwargs[field_name] = field.deserialize(data[field_name])
 90
 91        return cls(**kwargs)
 92
 93    def __repr__(self) -> str:
 94        """Generate readable representation."""
 95        field_strs = []
 96        for field_name in self._fields:
 97            value = getattr(self, field_name)
 98            field_strs.append(f"{field_name}={value!r}")
 99        return f"{self.__class__.__name__}({', '.join(field_strs)})"
100
101    def __eq__(self, other) -> bool:
102        """Compare models by their field values."""
103        if not isinstance(other, self.__class__):
104            return False
105        for field_name in self._fields:
106            if getattr(self, field_name) != getattr(other, field_name):
107                return False
108        return True

步驟 4：加入巢狀 Model 支援

 1class EmbeddedField(Field):
 2    """
 3    Embedded model field for nested structures.
 4
 5    Allows nesting Model instances within other Models.
 6    """
 7
 8    def __init__(self, *, model_class: Type[Model], **kwargs):
 9        super().__init__(**kwargs)
10        self.model_class = model_class
11
12    def __set__(self, obj: Any, value: Any) -> None:
13        if value is not None:
14            # Accept dict and convert to model
15            if isinstance(value, dict):
16                value = self.model_class.from_dict(value)
17            elif not isinstance(value, self.model_class):
18                raise TypeError(
19                    f"{self.name}: Expected {self.model_class.__name__} or dict, "
20                    f"got {type(value).__name__}"
21                )
22        super().__set__(obj, value)
23
24    def serialize(self, value: Model) -> dict:
25        """Serialize embedded model to dict."""
26        return value.to_dict() if value else None
27
28    def deserialize(self, value: dict) -> Model:
29        """Deserialize dict to embedded model."""
30        return self.model_class.from_dict(value) if value else None

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Django-style Field Descriptor - Complete Implementation
  4
  5Demonstrates how to combine Descriptor protocol with Metaclass
  6to create a declarative API similar to Django Model Fields.
  7"""
  8
  9from __future__ import annotations
 10import re
 11from datetime import datetime
 12from typing import Any, Optional, Type, Generic, TypeVar, Callable
 13
 14T = TypeVar("T")
 15
 16# ===== Field Descriptors =====
 17
 18class Field(Generic[T]):
 19    """Base Field Descriptor with validation and serialization."""
 20
 21    def __init__(
 22        self,
 23        *,
 24        default: Optional[T] = None,
 25        required: bool = True,
 26        serialized_name: Optional[str] = None,
 27        validator: Optional[Callable[[T], bool]] = None,
 28        error_msg: str = "Validation failed"
 29    ):
 30        self.default = default
 31        self.required = required
 32        self.serialized_name = serialized_name
 33        self.validator = validator
 34        self.error_msg = error_msg
 35        self.name: str = ""
 36        self.private_name: str = ""
 37
 38    def __set_name__(self, owner: type, name: str) -> None:
 39        self.name = name
 40        self.private_name = f"_field_{name}"
 41        if self.serialized_name is None:
 42            self.serialized_name = name
 43
 44    def __get__(self, obj: Any, objtype: type = None) -> Any:
 45        if obj is None:
 46            return self
 47        return getattr(obj, self.private_name, self.default)
 48
 49    def __set__(self, obj: Any, value: Any) -> None:
 50        if value is None:
 51            if self.required and self.default is None:
 52                raise ValueError(f"{self.name}: This field is required")
 53            setattr(obj, self.private_name, self.default)
 54            return
 55
 56        if self.validator and not self.validator(value):
 57            raise ValueError(f"{self.name}: {self.error_msg}")
 58
 59        setattr(obj, self.private_name, value)
 60
 61    def serialize(self, value: T) -> Any:
 62        return value
 63
 64    def deserialize(self, value: Any) -> T:
 65        return value
 66
 67class StringField(Field[str]):
 68    """String field with pattern and length validation."""
 69
 70    def __init__(
 71        self,
 72        *,
 73        pattern: Optional[str] = None,
 74        min_length: int = 0,
 75        max_length: Optional[int] = None,
 76        **kwargs
 77    ):
 78        super().__init__(**kwargs)
 79        self.pattern = re.compile(pattern) if pattern else None
 80        self.min_length = min_length
 81        self.max_length = max_length
 82
 83    def __set__(self, obj: Any, value: Any) -> None:
 84        if value is not None:
 85            if not isinstance(value, str):
 86                raise TypeError(f"{self.name}: Expected str, got {type(value).__name__}")
 87            if self.min_length and len(value) < self.min_length:
 88                raise ValueError(f"{self.name}: Minimum length is {self.min_length}")
 89            if self.max_length and len(value) > self.max_length:
 90                raise ValueError(f"{self.name}: Maximum length is {self.max_length}")
 91            if self.pattern and not self.pattern.match(value):
 92                raise ValueError(f"{self.name}: Does not match required pattern")
 93        super().__set__(obj, value)
 94
 95class IntField(Field[int]):
 96    """Integer field with range validation."""
 97
 98    def __init__(
 99        self,
100        *,
101        min_value: Optional[int] = None,
102        max_value: Optional[int] = None,
103        **kwargs
104    ):
105        super().__init__(**kwargs)
106        self.min_value = min_value
107        self.max_value = max_value
108
109    def __set__(self, obj: Any, value: Any) -> None:
110        if value is not None:
111            if not isinstance(value, int) or isinstance(value, bool):
112                raise TypeError(f"{self.name}: Expected int, got {type(value).__name__}")
113            if self.min_value is not None and value < self.min_value:
114                raise ValueError(f"{self.name}: Minimum value is {self.min_value}")
115            if self.max_value is not None and value > self.max_value:
116                raise ValueError(f"{self.name}: Maximum value is {self.max_value}")
117        super().__set__(obj, value)
118
119class BoolField(Field[bool]):
120    """Boolean field."""
121
122    def __set__(self, obj: Any, value: Any) -> None:
123        if value is not None and not isinstance(value, bool):
124            raise TypeError(f"{self.name}: Expected bool, got {type(value).__name__}")
125        super().__set__(obj, value)
126
127class ChoiceField(Field[str]):
128    """Field with predefined choices."""
129
130    def __init__(self, *, choices: tuple[str, ...], **kwargs):
131        super().__init__(**kwargs)
132        self.choices = choices
133
134    def __set__(self, obj: Any, value: Any) -> None:
135        if value is not None and value not in self.choices:
136            choices_str = ", ".join(repr(c) for c in self.choices)
137            raise ValueError(f"{self.name}: Must be one of: {choices_str}")
138        super().__set__(obj, value)
139
140class ListField(Field[list]):
141    """List field with item type."""
142
143    def __init__(self, *, item_field: Field, **kwargs):
144        kwargs.setdefault("default", [])
145        kwargs.setdefault("required", False)
146        super().__init__(**kwargs)
147        self.item_field = item_field
148
149    def __set__(self, obj: Any, value: Any) -> None:
150        if value is not None and not isinstance(value, list):
151            raise TypeError(f"{self.name}: Expected list, got {type(value).__name__}")
152        super().__set__(obj, value if value is not None else [])
153
154    def serialize(self, value: list) -> list:
155        return [self.item_field.serialize(item) for item in (value or [])]
156
157    def deserialize(self, value: list) -> list:
158        return [self.item_field.deserialize(item) for item in (value or [])]
159
160class DateTimeField(Field[datetime]):
161    """DateTime field with ISO format."""
162
163    def __init__(self, *, format: str = "%Y-%m-%dT%H:%M:%S", **kwargs):
164        super().__init__(**kwargs)
165        self.format = format
166
167    def __set__(self, obj: Any, value: Any) -> None:
168        if value is not None and not isinstance(value, datetime):
169            raise TypeError(f"{self.name}: Expected datetime, got {type(value).__name__}")
170        super().__set__(obj, value)
171
172    def serialize(self, value: datetime) -> Optional[str]:
173        return value.strftime(self.format) if value else None
174
175    def deserialize(self, value: str) -> Optional[datetime]:
176        return datetime.strptime(value, self.format) if value else None
177
178# ===== Metaclass and Model =====
179
180class ModelMeta(type):
181    """Metaclass that collects Field descriptors."""
182
183    def __new__(mcs, name: str, bases: tuple, namespace: dict):
184        fields: dict[str, Field] = {}
185
186        # Inherit from parent classes
187        for base in bases:
188            if hasattr(base, "_fields"):
189                fields.update(base._fields)
190
191        # Collect from current class
192        for attr_name, attr_value in namespace.items():
193            if isinstance(attr_value, Field):
194                fields[attr_name] = attr_value
195
196        namespace["_fields"] = fields
197        return super().__new__(mcs, name, bases, namespace)
198
199class Model(metaclass=ModelMeta):
200    """Base Model with automatic serialization."""
201
202    _fields: dict[str, Field]
203
204    def __init__(self, **kwargs):
205        for field_name, field in self._fields.items():
206            value = kwargs.get(field_name, field.default)
207            setattr(self, field_name, value)
208
209        unknown = set(kwargs.keys()) - set(self._fields.keys())
210        if unknown:
211            raise TypeError(f"Unknown fields: {', '.join(unknown)}")
212
213    def to_dict(self) -> dict:
214        result = {}
215        for field_name, field in self._fields.items():
216            value = getattr(self, field_name)
217            if value is not None or field.required:
218                key = field.serialized_name or field_name
219                result[key] = field.serialize(value)
220        return result
221
222    @classmethod
223    def from_dict(cls, data: dict) -> "Model":
224        kwargs = {}
225        for field_name, field in cls._fields.items():
226            key = field.serialized_name or field_name
227            if key in data:
228                kwargs[field_name] = field.deserialize(data[key])
229            elif field_name in data:
230                kwargs[field_name] = field.deserialize(data[field_name])
231        return cls(**kwargs)
232
233    def __repr__(self) -> str:
234        parts = [f"{k}={getattr(self, k)!r}" for k in self._fields]
235        return f"{self.__class__.__name__}({', '.join(parts)})"
236
237    def __eq__(self, other) -> bool:
238        if not isinstance(other, self.__class__):
239            return False
240        return all(
241            getattr(self, k) == getattr(other, k)
242            for k in self._fields
243        )
244
245class EmbeddedField(Field):
246    """Embedded model field for nested structures."""
247
248    def __init__(self, *, model_class: Type[Model], **kwargs):
249        super().__init__(**kwargs)
250        self.model_class = model_class
251
252    def __set__(self, obj: Any, value: Any) -> None:
253        if value is not None:
254            if isinstance(value, dict):
255                value = self.model_class.from_dict(value)
256            elif not isinstance(value, self.model_class):
257                raise TypeError(
258                    f"{self.name}: Expected {self.model_class.__name__} or dict"
259                )
260        super().__set__(obj, value)
261
262    def serialize(self, value: Model) -> Optional[dict]:
263        return value.to_dict() if value else None
264
265    def deserialize(self, value: dict) -> Optional[Model]:
266        return self.model_class.from_dict(value) if value else None

使用範例

 1# ===== Define Models =====
 2
 3class HookSpecificOutput(Model):
 4    """Nested model for hook-specific output."""
 5
 6    hook_event_name = ChoiceField(
 7        choices=("PreToolUse", "PostToolUse", "Stop"),
 8        serialized_name="hookEventName"
 9    )
10    permission_decision = ChoiceField(
11        choices=("allow", "deny", "ask"),
12        serialized_name="permissionDecision"
13    )
14    permission_reason = StringField(
15        min_length=1,
16        serialized_name="permissionDecisionReason"
17    )
18    user_prompt = StringField(
19        required=False,
20        serialized_name="userPrompt"
21    )
22
23class HookOutput(Model):
24    """
25    Hook Output model - similar to create_pretooluse_output
26
27    Declarative definition replaces the factory function.
28    """
29
30    hook_specific_output = EmbeddedField(
31        model_class=HookSpecificOutput,
32        serialized_name="hookSpecificOutput"
33    )
34    system_message = StringField(
35        required=False,
36        serialized_name="systemMessage"
37    )
38    suppress_output = BoolField(
39        default=False,
40        required=False,
41        serialized_name="suppressOutput"
42    )
43
44# ===== Usage Examples =====
45
46if __name__ == "__main__":
47    # Create model instance
48    output = HookOutput(
49        hook_specific_output=HookSpecificOutput(
50            hook_event_name="PreToolUse",
51            permission_decision="allow",
52            permission_reason="Operation permitted"
53        ),
54        system_message="Check completed"
55    )
56    print(f"Created: {output}")
57
58    # Serialize to dict (ready for JSON)
59    data = output.to_dict()
60    print(f"Serialized: {data}")
61    # Output:
62    # {
63    #     "hookSpecificOutput": {
64    #         "hookEventName": "PreToolUse",
65    #         "permissionDecision": "allow",
66    #         "permissionDecisionReason": "Operation permitted"
67    #     },
68    #     "systemMessage": "Check completed",
69    #     "suppressOutput": False
70    # }
71
72    # Deserialize from dict
73    restored = HookOutput.from_dict(data)
74    print(f"Restored: {restored}")
75    print(f"Equal: {output == restored}")
76
77    # Validation examples
78    try:
79        bad = HookSpecificOutput(
80            hook_event_name="InvalidEvent",  # Error: not in choices
81            permission_decision="allow",
82            permission_reason="Test"
83        )
84    except ValueError as e:
85        print(f"Validation error: {e}")
86
87    # Nested dict conversion
88    output2 = HookOutput(
89        hook_specific_output={  # Auto-converts dict to model
90            "hook_event_name": "PostToolUse",
91            "permission_decision": "deny",
92            "permission_reason": "Access denied"
93        }
94    )
95    print(f"From nested dict: {output2}")

執行結果：

1Created: HookOutput(hook_specific_output=HookSpecificOutput(...), system_message='Check completed', suppress_output=False)
2Serialized: {'hookSpecificOutput': {'hookEventName': 'PreToolUse', 'permissionDecision': 'allow', 'permissionDecisionReason': 'Operation permitted'}, 'systemMessage': 'Check completed', 'suppressOutput': False}
3Restored: HookOutput(hook_specific_output=HookSpecificOutput(...), system_message='Check completed', suppress_output=False)
4Equal: True
5Validation error: hook_event_name: Must be one of: 'PreToolUse', 'PostToolUse', 'Stop'
6From nested dict: HookOutput(hook_specific_output=HookSpecificOutput(...), system_message=None, suppress_output=False)

設計權衡

面向	函式工廠模式	Field Descriptor
學習曲線	低，只需了解函式	中，需理解 Descriptor + Metaclass
程式碼量	每個輸出類型一個函式	一次性建立後可重用
欄位定義	分散在函式簽名和函式體	集中在類別定義中
型別提示	需手動維護	與欄位定義整合
序列化	每個函式獨立實作	自動生成
驗證時機	呼叫時驗證	賦值時驗證
巢狀結構	需手動處理	EmbeddedField 自動處理
Schema 生成	無法自動化	可從 _fields 元資料生成
調試	直覺，錯誤位置明確	需理解 Descriptor 協議

關鍵差異說明

函式工廠模式（如 hook_io.py）：

適合簡單、一次性的資料建構
不需要額外的學習成本
但重複程式碼多，難以維護

Field Descriptor 模式：

初期投入較高，但長期收益大
欄位定義即文檔
易於擴展和測試

什麼時候該用這個技術？

適合使用：

ORM/ODM 設計（如 Django Model、MongoDB ODM）
配置檔案解析（型別安全的 YAML/JSON 解析）
API 請求/回應模型（REST API、GraphQL）
需要 Schema 自動生成的場景
多個類似結構的資料類別

不建議使用：

簡單的資料容器（直接用 dataclass）
不需要序列化的內部類別
Pydantic 已經滿足需求
團隊不熟悉元編程
單一用途的資料結構

與 Pydantic 的比較

功能	自製 Field Descriptor	Pydantic
型別驗證	手動實作	自動
JSON Schema	需額外實作	內建
效能	依實作而定	高度優化
學習價值	高，理解原理	低，直接使用
客製化彈性	完全控制	受框架限制

建議：在生產環境優先考慮 Pydantic；學習元編程時使用自製實作。

練習

基礎練習

1. 實作 `BoolField` 和 `DateTimeField`

完成以下 Field 類別，支援型別驗證和序列化：

1class BoolField(Field[bool]):
2    """Boolean field with strict type checking."""
3    pass  # TODO: implement
4
5class DateTimeField(Field[datetime]):
6    """DateTime field with custom format."""
7    pass  # TODO: implement

2. 新增欄位的預設值和 required 屬性

修改 Field 基類，讓以下程式碼能正確運作：

1class Config(Model):
2    name = StringField(required=True)
3    timeout = IntField(default=30, required=False)
4    debug = BoolField(default=False, required=False)
5
6# 應該能建立實例
7config = Config(name="test")
8assert config.timeout == 30
9assert config.debug == False

進階練習

3. 實作巢狀 Model（`EmbeddedField`）

讓以下程式碼能正確運作：

 1class Address(Model):
 2    city = StringField()
 3    street = StringField()
 4
 5class Person(Model):
 6    name = StringField()
 7    address = EmbeddedField(model_class=Address)
 8
 9# 從巢狀 dict 建立
10person = Person.from_dict({
11    "name": "Alice",
12    "address": {"city": "Taipei", "street": "Main St"}
13})
14
15# 序列化回 dict
16data = person.to_dict()

4. 實作 ListField 的完整驗證

讓以下程式碼能驗證列表中的每個項目：

 1class Tag(Model):
 2    name = StringField(pattern=r"^[a-z]+$")
 3    priority = IntField(min_value=1, max_value=10)
 4
 5class Article(Model):
 6    title = StringField()
 7    tags = ListField(item_field=EmbeddedField(model_class=Tag))
 8
 9# 每個 tag 都應該被驗證
10article = Article(
11    title="Python Tips",
12    tags=[
13        {"name": "python", "priority": 5},
14        {"name": "INVALID", "priority": 5}  # Should raise error
15    ]
16)

挑戰題

5. 實作 Schema 自動生成

為 Model 類別新增 to_json_schema() 類別方法，自動生成 JSON Schema：

 1class User(Model):
 2    name = StringField(min_length=1, max_length=100)
 3    age = IntField(min_value=0, max_value=150)
 4    email = StringField(pattern=r"^[\w.-]+@[\w.-]+\.\w+$")
 5
 6schema = User.to_json_schema()
 7# 應該輸出：
 8# {
 9#     "type": "object",
10#     "properties": {
11#         "name": {"type": "string", "minLength": 1, "maxLength": 100},
12#         "age": {"type": "integer", "minimum": 0, "maximum": 150},
13#         "email": {"type": "string", "pattern": "^[\\w.-]+@[\\w.-]+\\.\\w+$"}
14#     },
15#     "required": ["name", "age", "email"]
16# }

延伸閱讀

上一章：自動註冊機制 返回：模組二：元編程

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 內部機制

3.5.4 插件系統設計

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

插件系統讓應用程式可以在不修改核心程式碼的情況下擴展功能。本章介紹三種常見的插件架構模式，以及如何使用 Python 的動態載入機制實現它們。

先備知識

本進階系列模組二：元編程
特別是 Metaclass 與 __init_subclass__

插件架構模式

模式一：基於繼承

最簡單的插件模式，插件必須繼承基類：

 1from abc import ABC, abstractmethod
 2from typing import ClassVar
 3
 4class Plugin(ABC):
 5    """插件基類"""
 6    name: ClassVar[str]  # 每個插件必須定義名稱
 7
 8    @abstractmethod
 9    def execute(self, context: dict) -> dict:
10        """執行插件邏輯"""
11        ...
12
13class LoggingPlugin(Plugin):
14    name = "logging"
15
16    def execute(self, context: dict) -> dict:
17        print(f"Processing: {context}")
18        return context
19
20class ValidationPlugin(Plugin):
21    name = "validation"
22
23    def execute(self, context: dict) -> dict:
24        if not context.get("valid"):
25            raise ValueError("Invalid context")
26        return context

優點：簡單明確，IDE 支援好缺點：強制耦合，無法使用第三方類別

模式二：基於註冊

使用裝飾器或顯式註冊，更靈活：

 1from typing import Callable, TypeAlias
 2
 3PluginFunc: TypeAlias = Callable[[dict], dict]
 4
 5class PluginRegistry:
 6    """插件註冊表"""
 7
 8    def __init__(self) -> None:
 9        self._plugins: dict[str, PluginFunc] = {}
10
11    def register(self, name: str) -> Callable[[PluginFunc], PluginFunc]:
12        """裝飾器：註冊插件"""
13        def decorator(func: PluginFunc) -> PluginFunc:
14            if name in self._plugins:
15                raise ValueError(f"Plugin '{name}' already registered")
16            self._plugins[name] = func
17            return func
18        return decorator
19
20    def get(self, name: str) -> PluginFunc | None:
21        return self._plugins.get(name)
22
23    def list_plugins(self) -> list[str]:
24        return list(self._plugins.keys())
25
26# 全域註冊表
27registry = PluginRegistry()
28
29@registry.register("uppercase")
30def uppercase_plugin(context: dict) -> dict:
31    context["text"] = context.get("text", "").upper()
32    return context
33
34@registry.register("lowercase")
35def lowercase_plugin(context: dict) -> dict:
36    context["text"] = context.get("text", "").lower()
37    return context
38
39# 使用
40plugin = registry.get("uppercase")
41if plugin:
42    result = plugin({"text": "Hello"})

優點：靈活，支援函式和類別缺點：需要顯式註冊

模式三：基於發現（使用 `__init_subclass__`）

利用 Python 的元編程機制自動發現插件：

 1from typing import ClassVar
 2
 3class AutoRegisterPlugin:
 4    """自動註冊的插件基類"""
 5    _registry: ClassVar[dict[str, type["AutoRegisterPlugin"]]] = {}
 6    name: ClassVar[str]
 7
 8    def __init_subclass__(cls, **kwargs) -> None:
 9        super().__init_subclass__(**kwargs)
10        # 跳過沒有定義 name 的中間類別
11        if hasattr(cls, "name") and cls.name:
12            if cls.name in AutoRegisterPlugin._registry:
13                raise ValueError(f"Plugin '{cls.name}' already registered")
14            AutoRegisterPlugin._registry[cls.name] = cls
15
16    @classmethod
17    def get_plugin(cls, name: str) -> type["AutoRegisterPlugin"] | None:
18        return cls._registry.get(name)
19
20    @classmethod
21    def list_plugins(cls) -> list[str]:
22        return list(cls._registry.keys())
23
24    def execute(self, context: dict) -> dict:
25        raise NotImplementedError
26
27# 定義插件只需要繼承，自動註冊
28class FormatPlugin(AutoRegisterPlugin):
29    name = "format"
30
31    def execute(self, context: dict) -> dict:
32        context["formatted"] = True
33        return context
34
35class CompressPlugin(AutoRegisterPlugin):
36    name = "compress"
37
38    def execute(self, context: dict) -> dict:
39        context["compressed"] = True
40        return context
41
42# 自動發現
43print(AutoRegisterPlugin.list_plugins())  # ['format', 'compress']

優點：無需顯式註冊，只要繼承就會被發現缺點：必須繼承基類，Python 專屬

使用 Metaclass 的進階版本

 1from typing import ClassVar
 2
 3class PluginMeta(type):
 4    """插件元類別"""
 5    _registry: dict[str, type] = {}
 6
 7    def __new__(mcs, name: str, bases: tuple, namespace: dict) -> type:
 8        cls = super().__new__(mcs, name, bases, namespace)
 9
10        # 跳過基類
11        if bases and hasattr(cls, "plugin_name"):
12            plugin_name = cls.plugin_name
13            if plugin_name in mcs._registry:
14                raise ValueError(f"Plugin '{plugin_name}' already registered")
15            mcs._registry[plugin_name] = cls
16
17        return cls
18
19    @classmethod
20    def get_plugin(mcs, name: str) -> type | None:
21        return mcs._registry.get(name)
22
23class PluginBase(metaclass=PluginMeta):
24    """插件基類"""
25    plugin_name: ClassVar[str]
26
27    def run(self) -> None:
28        raise NotImplementedError
29
30class MyPlugin(PluginBase):
31    plugin_name = "my_plugin"
32
33    def run(self) -> None:
34        print("MyPlugin running")
35
36# 使用
37plugin_cls = PluginMeta.get_plugin("my_plugin")
38if plugin_cls:
39    plugin_cls().run()

動態載入模組

importlib 基礎

 1import importlib
 2from types import ModuleType
 3
 4def load_module(module_path: str) -> ModuleType:
 5    """動態載入模組"""
 6    return importlib.import_module(module_path)
 7
 8def load_class(module_path: str, class_name: str) -> type:
 9    """從模組載入類別"""
10    module = importlib.import_module(module_path)
11    return getattr(module, class_name)
12
13# 使用
14# 假設有 myapp/plugins/custom.py 定義了 CustomPlugin
15plugin_cls = load_class("myapp.plugins.custom", "CustomPlugin")
16plugin = plugin_cls()

從檔案路徑載入

 1import importlib.util
 2from pathlib import Path
 3from types import ModuleType
 4
 5def load_module_from_path(path: Path) -> ModuleType:
 6    """從檔案路徑載入模組"""
 7    spec = importlib.util.spec_from_file_location(
 8        path.stem,  # 模組名稱
 9        path        # 檔案路徑
10    )
11    if spec is None or spec.loader is None:
12        raise ImportError(f"Cannot load module from {path}")
13
14    module = importlib.util.module_from_spec(spec)
15    spec.loader.exec_module(module)
16    return module
17
18# 使用
19plugin_module = load_module_from_path(Path("./plugins/custom_plugin.py"))

importlib.metadata 的 entry_points（現代做法）

這是 Python 套件生態系統推薦的插件發現機制：

 1# 在 pyproject.toml 中定義 entry points
 2"""
 3[project.entry-points."myapp.plugins"]
 4format = "myapp_format_plugin:FormatPlugin"
 5compress = "myapp_compress_plugin:CompressPlugin"
 6"""
 7
 8from importlib.metadata import entry_points
 9
10def discover_plugins(group: str) -> dict[str, type]:
11    """發現已安裝套件中的插件"""
12    plugins = {}
13
14    # Python 3.10+
15    eps = entry_points(group=group)
16
17    for ep in eps:
18        try:
19            plugin_cls = ep.load()
20            plugins[ep.name] = plugin_cls
21        except Exception as e:
22            print(f"Failed to load plugin {ep.name}: {e}")
23
24    return plugins
25
26# 發現所有 myapp.plugins 群組的插件
27plugins = discover_plugins("myapp.plugins")
28for name, cls in plugins.items():
29    print(f"Found plugin: {name} -> {cls}")

優點：

標準化的發現機制
支援第三方套件提供插件
pip 安裝即可使用

實際範例一：Hook 系統的插件化改造

基於入門系列的 Hook 系統概念，設計一個插件化的 Hook 框架：

  1from abc import ABC, abstractmethod
  2from dataclasses import dataclass
  3from enum import Enum
  4from pathlib import Path
  5from typing import ClassVar
  6import importlib.util
  7
  8class HookEvent(Enum):
  9    PRE_TOOL_USE = "PreToolUse"
 10    POST_TOOL_USE = "PostToolUse"
 11    SESSION_START = "SessionStart"
 12    SESSION_END = "SessionEnd"
 13
 14@dataclass
 15class HookContext:
 16    """Hook 執行的上下文"""
 17    event: HookEvent
 18    tool_name: str | None = None
 19    input_data: dict | None = None
 20
 21@dataclass
 22class HookResult:
 23    """Hook 執行結果"""
 24    success: bool
 25    message: str
 26    modified_context: HookContext | None = None
 27
 28class HookPlugin(ABC):
 29    """Hook 插件基類"""
 30    _registry: ClassVar[dict[str, list[type["HookPlugin"]]]] = {}
 31
 32    # 子類別必須定義的屬性
 33    name: ClassVar[str]
 34    events: ClassVar[list[HookEvent]]
 35    priority: ClassVar[int] = 100  # 預設優先級
 36
 37    def __init_subclass__(cls, **kwargs) -> None:
 38        super().__init_subclass__(**kwargs)
 39        if hasattr(cls, "name") and hasattr(cls, "events"):
 40            for event in cls.events:
 41                event_name = event.value
 42                if event_name not in HookPlugin._registry:
 43                    HookPlugin._registry[event_name] = []
 44                HookPlugin._registry[event_name].append(cls)
 45                # 按優先級排序
 46                HookPlugin._registry[event_name].sort(
 47                    key=lambda c: c.priority
 48                )
 49
 50    @abstractmethod
 51    def execute(self, context: HookContext) -> HookResult:
 52        """執行 Hook 邏輯"""
 53        ...
 54
 55    @classmethod
 56    def get_hooks_for_event(cls, event: HookEvent) -> list[type["HookPlugin"]]:
 57        """取得特定事件的所有 Hook"""
 58        return cls._registry.get(event.value, [])
 59
 60# 定義具體的 Hook 插件
 61class SecurityCheckHook(HookPlugin):
 62    """安全檢查 Hook"""
 63    name = "security_check"
 64    events = [HookEvent.PRE_TOOL_USE]
 65    priority = 10  # 高優先級，先執行
 66
 67    DANGEROUS_PATTERNS = ["rm -rf", "DROP TABLE", "sudo"]
 68
 69    def execute(self, context: HookContext) -> HookResult:
 70        if context.input_data:
 71            command = context.input_data.get("command", "")
 72            for pattern in self.DANGEROUS_PATTERNS:
 73                if pattern in command:
 74                    return HookResult(
 75                        success=False,
 76                        message=f"Blocked dangerous pattern: {pattern}"
 77                    )
 78        return HookResult(success=True, message="Security check passed")
 79
 80class LoggingHook(HookPlugin):
 81    """日誌記錄 Hook"""
 82    name = "logging"
 83    events = [HookEvent.PRE_TOOL_USE, HookEvent.POST_TOOL_USE]
 84    priority = 1000  # 低優先級，最後執行
 85
 86    def execute(self, context: HookContext) -> HookResult:
 87        print(f"[{context.event.value}] Tool: {context.tool_name}")
 88        return HookResult(success=True, message="Logged")
 89
 90# Hook 執行器
 91class HookRunner:
 92    """執行 Hook 的管理器"""
 93
 94    def run_hooks(self, event: HookEvent, context: HookContext) -> list[HookResult]:
 95        """執行特定事件的所有 Hook"""
 96        results = []
 97        hook_classes = HookPlugin.get_hooks_for_event(event)
 98
 99        for hook_cls in hook_classes:
100            hook = hook_cls()
101            try:
102                result = hook.execute(context)
103                results.append(result)
104                # 如果 Hook 失敗且事件是 PRE，中斷執行
105                if not result.success and event == HookEvent.PRE_TOOL_USE:
106                    break
107            except Exception as e:
108                results.append(HookResult(
109                    success=False,
110                    message=f"Hook {hook_cls.name} failed: {e}"
111                ))
112
113        return results
114
115# 使用
116runner = HookRunner()
117context = HookContext(
118    event=HookEvent.PRE_TOOL_USE,
119    tool_name="Bash",
120    input_data={"command": "ls -la"}
121)
122results = runner.run_hooks(HookEvent.PRE_TOOL_USE, context)

實際範例二：通用插件框架設計

一個更通用的插件框架，支援動態載入和生命週期管理：

  1from abc import ABC, abstractmethod
  2from dataclasses import dataclass, field
  3from enum import Enum, auto
  4from pathlib import Path
  5from typing import Any
  6import importlib.util
  7
  8class PluginState(Enum):
  9    UNLOADED = auto()
 10    LOADED = auto()
 11    ACTIVE = auto()
 12    ERROR = auto()
 13
 14@dataclass
 15class PluginInfo:
 16    """插件元資訊"""
 17    name: str
 18    version: str
 19    description: str
 20    author: str = ""
 21    dependencies: list[str] = field(default_factory=list)
 22
 23class BasePlugin(ABC):
 24    """插件基類"""
 25
 26    @property
 27    @abstractmethod
 28    def info(self) -> PluginInfo:
 29        """返回插件資訊"""
 30        ...
 31
 32    def on_load(self) -> None:
 33        """插件載入時呼叫"""
 34        pass
 35
 36    def on_unload(self) -> None:
 37        """插件卸載時呼叫"""
 38        pass
 39
 40    def on_activate(self) -> None:
 41        """插件啟用時呼叫"""
 42        pass
 43
 44    def on_deactivate(self) -> None:
 45        """插件停用時呼叫"""
 46        pass
 47
 48@dataclass
 49class LoadedPlugin:
 50    """已載入的插件包裝"""
 51    plugin: BasePlugin
 52    state: PluginState = PluginState.UNLOADED
 53    error: str | None = None
 54
 55class PluginManager:
 56    """插件管理器"""
 57
 58    def __init__(self, plugin_dir: Path | None = None) -> None:
 59        self._plugins: dict[str, LoadedPlugin] = {}
 60        self._plugin_dir = plugin_dir
 61
 62    def load_plugin(self, path: Path) -> str:
 63        """從檔案載入插件"""
 64        try:
 65            # 動態載入模組
 66            spec = importlib.util.spec_from_file_location(
 67                path.stem, path
 68            )
 69            if spec is None or spec.loader is None:
 70                raise ImportError(f"Cannot load {path}")
 71
 72            module = importlib.util.module_from_spec(spec)
 73            spec.loader.exec_module(module)
 74
 75            # 尋找 BasePlugin 的子類別
 76            plugin_cls = None
 77            for attr_name in dir(module):
 78                attr = getattr(module, attr_name)
 79                if (isinstance(attr, type) and
 80                    issubclass(attr, BasePlugin) and
 81                    attr is not BasePlugin):
 82                    plugin_cls = attr
 83                    break
 84
 85            if plugin_cls is None:
 86                raise ImportError(f"No plugin class found in {path}")
 87
 88            # 實例化插件
 89            plugin = plugin_cls()
 90            plugin_name = plugin.info.name
 91
 92            # 檢查依賴
 93            for dep in plugin.info.dependencies:
 94                if dep not in self._plugins:
 95                    raise ImportError(f"Missing dependency: {dep}")
 96
 97            # 呼叫生命週期方法
 98            plugin.on_load()
 99
100            self._plugins[plugin_name] = LoadedPlugin(
101                plugin=plugin,
102                state=PluginState.LOADED
103            )
104
105            return plugin_name
106
107        except Exception as e:
108            raise ImportError(f"Failed to load plugin from {path}: {e}")
109
110    def unload_plugin(self, name: str) -> None:
111        """卸載插件"""
112        if name not in self._plugins:
113            raise KeyError(f"Plugin '{name}' not found")
114
115        loaded = self._plugins[name]
116
117        # 先停用
118        if loaded.state == PluginState.ACTIVE:
119            self.deactivate_plugin(name)
120
121        # 呼叫生命週期方法
122        loaded.plugin.on_unload()
123
124        del self._plugins[name]
125
126    def activate_plugin(self, name: str) -> None:
127        """啟用插件"""
128        if name not in self._plugins:
129            raise KeyError(f"Plugin '{name}' not found")
130
131        loaded = self._plugins[name]
132        if loaded.state != PluginState.LOADED:
133            raise RuntimeError(f"Plugin '{name}' is not in LOADED state")
134
135        try:
136            loaded.plugin.on_activate()
137            loaded.state = PluginState.ACTIVE
138        except Exception as e:
139            loaded.state = PluginState.ERROR
140            loaded.error = str(e)
141            raise
142
143    def deactivate_plugin(self, name: str) -> None:
144        """停用插件"""
145        if name not in self._plugins:
146            raise KeyError(f"Plugin '{name}' not found")
147
148        loaded = self._plugins[name]
149        if loaded.state != PluginState.ACTIVE:
150            return
151
152        loaded.plugin.on_deactivate()
153        loaded.state = PluginState.LOADED
154
155    def discover_plugins(self) -> list[Path]:
156        """發現插件目錄中的所有插件"""
157        if self._plugin_dir is None:
158            return []
159
160        return list(self._plugin_dir.glob("*.py"))
161
162    def load_all_plugins(self) -> dict[str, str | None]:
163        """載入所有發現的插件"""
164        results: dict[str, str | None] = {}
165        for path in self.discover_plugins():
166            try:
167                name = self.load_plugin(path)
168                results[name] = None
169            except Exception as e:
170                results[path.stem] = str(e)
171        return results
172
173    def get_plugin(self, name: str) -> BasePlugin | None:
174        """取得插件實例"""
175        loaded = self._plugins.get(name)
176        return loaded.plugin if loaded else None
177
178    def list_plugins(self) -> list[PluginInfo]:
179        """列出所有已載入的插件"""
180        return [lp.plugin.info for lp in self._plugins.values()]
181
182# 範例插件（放在獨立檔案中）
183class GreeterPlugin(BasePlugin):
184    """簡單的問候插件"""
185
186    @property
187    def info(self) -> PluginInfo:
188        return PluginInfo(
189            name="greeter",
190            version="1.0.0",
191            description="A simple greeting plugin"
192        )
193
194    def on_activate(self) -> None:
195        print("Greeter plugin activated!")
196
197    def greet(self, name: str) -> str:
198        return f"Hello, {name}!"
199
200# 使用
201manager = PluginManager(Path("./plugins"))
202manager.load_all_plugins()
203manager.activate_plugin("greeter")
204
205greeter = manager.get_plugin("greeter")
206if isinstance(greeter, GreeterPlugin):
207    print(greeter.greet("World"))

設計考量

安全性

 1# 限制插件可以存取的模組
 2import sys
 3from types import ModuleType
 4
 5class SandboxedImporter:
 6    """限制插件可以 import 的模組"""
 7    ALLOWED_MODULES = {"json", "re", "datetime", "typing"}
 8
 9    def find_module(self, name: str, path=None):
10        if name.split(".")[0] not in self.ALLOWED_MODULES:
11            return self  # 攔截
12        return None
13
14    def load_module(self, name: str) -> ModuleType:
15        raise ImportError(f"Module '{name}' is not allowed in plugins")
16
17# 使用時插入到 sys.meta_path
18# sys.meta_path.insert(0, SandboxedImporter())

版本相容性

 1from packaging import version
 2
 3def check_compatibility(
 4    plugin_info: PluginInfo,
 5    app_version: str
 6) -> bool:
 7    """檢查插件與應用程式版本相容性"""
 8    # 插件可以定義 min_app_version 屬性
 9    min_version = getattr(plugin_info, "min_app_version", "0.0.0")
10    return version.parse(app_version) >= version.parse(min_version)

小結

模式	適用場景
基於繼承	簡單場景，需要型別安全
基於註冊	需要靈活性，支援函式插件
基於發現	自動發現，減少樣板程式碼
entry_points	套件生態系統，第三方插件

思考題

三種插件模式各有什麼優缺點？
如何實現插件之間的依賴管理？
如何確保插件的安全性？

上一章：3.5.3 進階上下文管理 下一章：3.5.5 設計模式整合案例

案例研究：元編程實戰

Wed, 21 Jan 2026 00:00:00 +0000

本系列案例基於 .claude/lib 的實際程式碼，展示如何用元編程技術解決實際問題。

案例列表

案例	素材	進階技術	難度
宣告式驗證	hook_validator.py	Descriptor Protocol	中階
自動註冊機制	hook_validator.py	Metaclass	高階
類似 Django Field	hook_io.py	Descriptor + dataclass	高階

學習路徑

1宣告式驗證（入門）
2 ↓
3自動註冊機制（進階）
4 ↓
5類似 Django Field（整合）

先備知識

建議先完成以下章節：

返回：模組二：元編程

Metaprogramming on Tarragon

案例：宣告式驗證

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

進階解決方案：宣告式驗證

設計目標

實作步驟

步驟 1：建立基礎 Descriptor

步驟 2：建立特化的驗證 Descriptor

步驟 3：使用宣告式驗證

完整程式碼

使用範例

設計權衡

什麼時候該用宣告式驗證？

2.1 Descriptor Protocol 完整指南

先備知識

本章目標

【原理層】@property 的真相

property 是一個 Descriptor

Descriptor Protocol

簡單範例

【設計層】Data vs Non-data Descriptor

兩種 Descriptor

屬性查找順序

為什麼 method 是 Non-data Descriptor？

【實作層】實用的 Descriptor

延遲計算屬性

型別驗證器

類似 Django Model Field

思考題

實作練習

延伸閱讀

案例：自動註冊機制

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

進階解決方案

設計目標

實作步驟

步驟 1：用裝飾器標記檢查方法

步驟 2：用 Metaclass 收集標記的方法

步驟 3：實作優先順序

步驟 4：實作啟用/停用機制

完整程式碼

使用範例

替代方案：__init_subclass__

__init_subclass__ vs Metaclass

設計權衡

什麼時候該用這個技術？

練習

基礎練習

進階練習

挑戰題

延伸閱讀

2.2 Metaclass 設計與應用

先備知識

本章目標

【原理層】類別也是物件

type 是所有類別的 Metaclass

type() 的三參數形式

【設計層】類別建立過程

建立流程

call 控制實例建立

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

何時用 init_subclass，何時用 Metaclass？

【實作層】實用範例

自動註冊子類別

介面驗證

使用 prepare 記錄定義順序

簡單的 ORM 基類

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

思考題

實作練習

延伸閱讀

模組二：元編程

替代方案：`__init_subclass__`

`__init_subclass__` vs Metaclass

1. 實作 `BoolField` 和 `DateTimeField`

3. 實作巢狀 Model（`EmbeddedField`）