Metaclass 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 協議）

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

適合使用：

案例：自動註冊機制

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

Metaclass on Tarragon

案例：宣告式驗證

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

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

設計目標

實作步驟

步驟 1：建立基礎 Descriptor

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

步驟 3：使用宣告式驗證

完整程式碼

使用範例

設計權衡

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

案例：自動註冊機制

先備知識

問題背景

現有設計

這個設計的優點

這個設計的限制

進階解決方案

設計目標

實作步驟

步驟 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