Typing on Tarragon

2.1 Type Hints 基礎

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

Python 3.5 引入了型別提示（Type Hints），讓你可以為變數和函式添加型別註解。型別提示不會影響執行，但能大幅提升程式碼的可讀性和 IDE 的智慧提示功能。

為什麼需要型別提示？

沒有型別提示的程式碼

1def process(data):
2    return data.strip()
3
4result = process(input_value)  # data 是什麼型別？strip() 能用嗎？

有型別提示的程式碼

1def process(data: str) -> str:
2    return data.strip()
3
4result = process(input_value)  # 清楚知道需要字串，返回字串

基本語法

變數型別註解

1# 基本型別
2name: str = "Python"
3count: int = 42
4ratio: float = 3.14
5is_valid: bool = True
6
7# 可以不賦值（用於宣告）
8message: str  # 稍後賦值

函式型別註解

1def greet(name: str) -> str:
2    return f"Hello, {name}!"
3
4def add(a: int, b: int) -> int:
5    return a + b
6
7def print_message(msg: str) -> None:
8    print(msg)  # 沒有返回值用 None

實際範例：Hook 系統

來自 .claude/lib/git_utils.py 的範例：

 1def run_git_command(
 2    args: list[str],
 3    cwd: Optional[str] = None,
 4    timeout: int = 10
 5) -> tuple[bool, str]:
 6    """
 7    執行 git 命令並返回結果
 8
 9    Args:
10        args: git 命令參數列表（不含 'git'）
11        cwd: 執行目錄，預設為當前目錄
12        timeout: 命令超時時間（秒）
13
14    Returns:
15        tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
16    """
17    try:
18        result = subprocess.run(
19            ["git"] + args,
20            cwd=cwd,
21            capture_output=True,
22            text=True,
23            timeout=timeout
24        )
25        if result.returncode == 0:
26            return True, result.stdout.strip()
27        else:
28            return False, result.stderr.strip()
29    except subprocess.TimeoutExpired:
30        return False, f"Command timed out after {timeout}s"

分析這個函式的型別提示：

參數	型別	說明
`args`	`list[str]`	字串列表
`cwd`	`Optional[str]`	可選字串，可以是 None
`timeout`	`int`	整數，有預設值
返回值	`tuple[bool, str]`	布林和字串組成的元組

容器型別

列表（List）

1from typing import List  # Python 3.9 前需要
2
3# Python 3.9+
4def process_names(names: list[str]) -> list[str]:
5    return [name.upper() for name in names]
6
7# Python 3.8 及之前
8def process_names(names: List[str]) -> List[str]:
9    return [name.upper() for name in names]

字典（Dict）

1from typing import Dict
2
3# Python 3.9+
4def get_config() -> dict[str, int]:
5    return {"timeout": 10, "retries": 3}
6
7# Python 3.8 及之前
8def get_config() -> Dict[str, int]:
9    return {"timeout": 10, "retries": 3}

集合（Set）

1# Python 3.9+
2def get_unique_items(items: list[str]) -> set[str]:
3    return set(items)

元組（Tuple）

1# 固定長度和型別
2def get_position() -> tuple[int, int]:
3    return (10, 20)
4
5# 可變長度（同質）
6def get_values() -> tuple[int, ...]:
7    return (1, 2, 3, 4, 5)

實際應用：Hook 輸出建立

來自 .claude/lib/hook_io.py：

 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: 詢問用戶的訊息
15        system_message: 系統訊息
16        suppress_output: 是否抑制輸出
17    """
18    output: dict[str, Any] = {
19        "hookSpecificOutput": {
20            "hookEventName": "PreToolUse",
21            "permissionDecision": decision,
22            "permissionDecisionReason": reason
23        }
24    }
25
26    if user_prompt:
27        output["hookSpecificOutput"]["userPrompt"] = user_prompt
28
29    if system_message:
30        output["systemMessage"] = system_message
31
32    if suppress_output:
33        output["suppressOutput"] = True
34
35    return output

型別別名

為複雜型別建立別名提升可讀性：

 1from typing import Dict, List, Tuple
 2
 3# 定義型別別名
 4ValidationResult = Tuple[bool, str]
 5ConfigDict = Dict[str, Any]
 6NameList = List[str]
 7
 8# 使用別名
 9def validate_input(data: str) -> ValidationResult:
10    if data:
11        return True, "Valid"
12    return False, "Empty input"
13
14def load_config() -> ConfigDict:
15    return {"key": "value"}

型別檢查工具

型別提示本身不會在執行時檢查，但可以用工具進行靜態檢查：

mypy

1# 安裝
2pip install mypy
3
4# 檢查檔案
5mypy my_script.py
6
7# 檢查目錄
8mypy .claude/lib/

IDE 整合

現代 IDE（VS Code、PyCharm）會自動利用型別提示：

自動完成更準確
型別錯誤即時提示
重構更安全

最佳實踐

1. 為公開 API 添加型別提示

1# 公開函式必須有型別提示
2def get_current_branch() -> Optional[str]:
3    """獲取當前分支名稱"""
4    ...
5
6# 內部輔助函式可以省略
7def _parse_output(text):
8    ...

2. 使用有意義的型別別名

1# 好：清楚表達意圖
2BranchName = str
3ValidationResult = Tuple[bool, str]
4
5def validate_branch(name: BranchName) -> ValidationResult:
6    ...
7
8# 不好：型別別名沒有增加資訊
9MyStr = str  # 這有什麼意義？

3. 逐步添加型別提示

不需要一次為所有程式碼添加型別提示，可以從以下開始：

公開 API
複雜函式
經常被呼叫的函式

思考題

list[str] 和 List[str] 有什麼區別？什麼時候用哪個？
為什麼 run_git_command 返回 tuple[bool, str] 而不是自定義類別？
型別提示會影響程式執行速度嗎？

實作練習

為以下函式添加適當的型別提示：

 1def parse_config(file_path):
 2    with open(file_path) as f:
 3        return json.load(f)
 4
 5def filter_valid_items(items):
 6    return [item for item in items if item.get("valid")]
 7
 8def merge_dicts(dict1, dict2):
 9    result = dict1.copy()
10    result.update(dict2)
11    return result

下一章：Optional、Union、泛型

2.2 Optional、Union、泛型

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

當函式的參數或返回值可能是多種型別時，我們需要使用 Optional、Union 或泛型來表達。這些工具讓型別提示更加精確。

Optional

Optional[T] 表示值可能是 T 型別，也可能是 None。

基本用法

 1from typing import Optional
 2
 3def get_current_branch() -> Optional[str]:
 4    """
 5    獲取當前分支名稱
 6
 7    Returns:
 8        str | None: 分支名稱，如果無法獲取則返回 None
 9    """
10    success, output = run_git_command(["branch", "--show-current"])
11    return output if success and output else None

Optional 等同於 Union[T, None]

 1from typing import Optional, Union
 2
 3# 這兩種寫法等價
 4def find_user(id: int) -> Optional[User]:
 5    ...
 6
 7def find_user(id: int) -> Union[User, None]:
 8    ...
 9
10# Python 3.10+ 可以使用 | 語法
11def find_user(id: int) -> User | None:
12    ...

實際範例：配置載入

來自 .claude/lib/config_loader.py：

 1from typing import Optional
 2
 3# 模組級快取變數
 4_agents_config_cache: Optional[dict] = None
 5_quality_rules_cache: Optional[dict] = None
 6
 7def load_agents_config() -> dict:
 8    """載入代理人配置"""
 9    global _agents_config_cache
10
11    # 快取為 None 表示尚未載入
12    if _agents_config_cache is None:
13        try:
14            _agents_config_cache = load_config("agents")
15        except FileNotFoundError:
16            _agents_config_cache = _get_default_agents_config()
17
18    return _agents_config_cache

Union

Union[A, B, C] 表示值可能是 A、B 或 C 型別。

基本用法

 1from typing import Union
 2
 3def process_input(data: Union[str, bytes]) -> str:
 4    """處理字串或位元組輸入"""
 5    if isinstance(data, bytes):
 6        return data.decode("utf-8")
 7    return data
 8
 9# Python 3.10+ 語法
10def process_input(data: str | bytes) -> str:
11    ...

常見應用

 1from typing import Union, List
 2
 3# 接受單一值或列表
 4def ensure_list(value: Union[str, List[str]]) -> List[str]:
 5    if isinstance(value, str):
 6        return [value]
 7    return value
 8
 9# 返回不同型別
10def parse_value(text: str) -> Union[int, float, str]:
11    try:
12        return int(text)
13    except ValueError:
14        try:
15            return float(text)
16        except ValueError:
17            return text

泛型（Generic）

泛型讓你建立可以與多種型別一起使用的類別和函式。

TypeVar

 1from typing import TypeVar, List
 2
 3T = TypeVar("T")
 4
 5def first_element(items: List[T]) -> T:
 6    """返回列表的第一個元素"""
 7    return items[0]
 8
 9# 使用時會推斷型別
10names = ["Alice", "Bob"]
11first_name = first_element(names)  # 推斷為 str
12
13numbers = [1, 2, 3]
14first_num = first_element(numbers)  # 推斷為 int

有限制的 TypeVar

1from typing import TypeVar
2
3# 只能是 str 或 bytes
4StrOrBytes = TypeVar("StrOrBytes", str, bytes)
5
6def process(data: StrOrBytes) -> StrOrBytes:
7    return data.strip()  # str 和 bytes 都有 strip()

實際範例：Hook 輸出建立

來自 .claude/lib/hook_io.py：

 1from typing import Any, Optional
 2
 3def create_pretooluse_output(
 4    decision: str,
 5    reason: str,
 6    user_prompt: Optional[str] = None,
 7    system_message: Optional[str] = None,
 8    suppress_output: bool = False
 9) -> dict:
10    """建立 PreToolUse Hook 輸出格式"""
11
12    # 使用 dict[str, Any] 表示值可以是任意型別
13    output: dict[str, Any] = {
14        "hookSpecificOutput": {
15            "hookEventName": "PreToolUse",
16            "permissionDecision": decision,
17            "permissionDecisionReason": reason
18        }
19    }
20
21    # Optional 參數的處理
22    if user_prompt:
23        output["hookSpecificOutput"]["userPrompt"] = user_prompt
24
25    if system_message:
26        output["systemMessage"] = system_message
27
28    if suppress_output:
29        output["suppressOutput"] = True
30
31    return output

Any

Any 表示任意型別，相當於關閉型別檢查。

 1from typing import Any
 2
 3def log_value(value: Any) -> None:
 4    """記錄任意型別的值"""
 5    print(f"Value: {value}")
 6
 7# 字典值為任意型別
 8config: dict[str, Any] = {
 9    "name": "test",      # str
10    "count": 10,         # int
11    "enabled": True,     # bool
12    "items": [1, 2, 3]   # list
13}

何時使用 Any？

處理動態資料（如 JSON）
與外部 API 互動
型別過於複雜難以表達

注意：過度使用 Any 會降低型別檢查的效果。

Callable

表示可呼叫物件（函式、方法、lambda）。

 1from typing import Callable
 2
 3def apply_operation(
 4    value: int,
 5    operation: Callable[[int], int]
 6) -> int:
 7    """對值應用操作"""
 8    return operation(value)
 9
10# 使用
11result = apply_operation(5, lambda x: x * 2)  # 10

Python 3.9+ 語法

從 Python 3.9 開始，可以直接使用內建型別：

1# Python 3.9+
2def process(items: list[str]) -> dict[str, int]:
3    ...
4
5# Python 3.8 及之前需要導入
6from typing import List, Dict
7def process(items: List[str]) -> Dict[str, int]:
8    ...

從 Python 3.10 開始，可以使用 | 語法：

1# Python 3.10+
2def find(id: int) -> User | None:
3    ...
4
5# Python 3.9 及之前
6from typing import Optional
7def find(id: int) -> Optional[User]:
8    ...

常見模式

可選參數

1def setup_logging(
2    name: str,
3    level: Optional[int] = None,    # 可以是 int 或 None
4    path: Optional[str] = None      # 可以是 str 或 None
5) -> Logger:
6    if level is None:
7        level = logging.INFO
8    ...

返回值可能為空

1def find_config(name: str) -> Optional[dict]:
2    """找不到配置時返回 None"""
3    path = get_config_path(name)
4    if not path.exists():
5        return None
6    return load_config(path)

字典值型別不確定

1from typing import Any
2
3def parse_json(text: str) -> dict[str, Any]:
4    """JSON 值可能是任意型別"""
5    return json.loads(text)

思考題

Optional[str] 和 str | None 有什麼區別？
什麼時候應該用 Any？什麼時候應該避免？
如何為一個接受任意可迭代物件的函式添加型別提示？

實作練習

為以下函式添加型別提示：

1def get_value(data, key, default=None):
2    return data.get(key, default)

寫一個泛型函式，返回列表中的最大和最小值
為一個回調函式參數添加 Callable 型別提示

模組二：型別系統

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

Python 3.5+ 引入的型別系統讓程式碼更易讀、更易維護。本模組介紹如何善用型別提示來提升程式碼品質。

章節列表

章節	主題	關鍵收穫
2.1	Type Hints 基礎	為函式添加型別註解
2.2	Optional、Union、泛型	處理可能為 None 的值
2.3	Dataclass 資料結構	快速定義資料類別
2.4	Enum 列舉型別	定義有限選項集合
2.5	Callable 與高階函式	描述可呼叫物件契約，支援回調與 DI

實際範例來源

本模組的範例主要來自：

git_utils.py - 型別提示的實際應用
config_loader.py - Optional 和泛型的使用
hook_validator.py - Dataclass 定義
parsers/base.py - Enum 使用範例

為什麼需要型別系統？

1# 沒有型別提示
2def process(data):
3 return data.strip() # data 是什麼？能呼叫 strip 嗎？
4
5# 有型別提示
6def process(data: str) -> str:
7 return data.strip() # 清楚知道是字串

學習時間

預計 45-60 分鐘

2.3 Dataclass 資料結構

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

dataclass 是 Python 3.7+ 引入的裝飾器，用於快速建立主要用於存放資料的類別。它自動產生 __init__、__repr__ 等方法，減少樣板程式碼。

為什麼使用 Dataclass？

傳統類別

 1class ValidationIssue:
 2    def __init__(self, level, message, line=None, suggestion=None):
 3        self.level = level
 4        self.message = message
 5        self.line = line
 6        self.suggestion = suggestion
 7
 8    def __repr__(self):
 9        return f"ValidationIssue(level={self.level!r}, message={self.message!r})"
10
11    def __eq__(self, other):
12        if not isinstance(other, ValidationIssue):
13            return False
14        return (self.level == other.level and
15                self.message == other.message and
16                self.line == other.line and
17                self.suggestion == other.suggestion)

使用 Dataclass

1from dataclasses import dataclass
2from typing import Optional
3
4@dataclass
5class ValidationIssue:
6    level: str
7    message: str
8    line: Optional[int] = None
9    suggestion: Optional[str] = None

自動產生：

__init__
__repr__
__eq__

實際範例：Hook 驗證器

來自 .claude/lib/hook_validator.py：

 1from dataclasses import dataclass, field
 2from typing import Optional, List
 3
 4
 5@dataclass
 6class ValidationIssue:
 7    """驗證問題描述"""
 8    level: str          # "error" | "warning" | "info"
 9    message: str
10    line: Optional[int] = None
11    suggestion: Optional[str] = None
12
13
14@dataclass
15class ValidationResult:
16    """單個 Hook 的驗證結果"""
17    hook_path: str
18    issues: List[ValidationIssue] = field(default_factory=list)
19    is_compliant: bool = True
20
21    def __post_init__(self):
22        """計算 is_compliant 狀態"""
23        self.is_compliant = not any(
24            issue.level == "error" for issue in self.issues
25        )

基本語法

欄位定義

 1from dataclasses import dataclass
 2from typing import List, Optional
 3
 4@dataclass
 5class Person:
 6    # 必要欄位（無預設值）
 7    name: str
 8    age: int
 9
10    # 可選欄位（有預設值）
11    email: Optional[str] = None
12    tags: List[str] = None  # 錯誤！見下方說明

可變預設值的問題

 1from dataclasses import dataclass, field
 2from typing import List
 3
 4# 錯誤：可變物件作為預設值
 5@dataclass
 6class Wrong:
 7    items: List[str] = []  # 所有實例會共用同一個列表！
 8
 9# 正確：使用 field(default_factory=...)
10@dataclass
11class Correct:
12    items: List[str] = field(default_factory=list)

field() 函式

field() 提供更多欄位配置選項：

 1from dataclasses import dataclass, field
 2from typing import List
 3
 4@dataclass
 5class ValidationResult:
 6    hook_path: str
 7    # 使用 default_factory 建立可變預設值
 8    issues: List[ValidationIssue] = field(default_factory=list)
 9    # 不包含在 __repr__ 中
10    _internal: str = field(default="", repr=False)
11    # 不包含在比較中
12    cached: bool = field(default=False, compare=False)

field() 參數

參數	說明	預設值
`default`	預設值	無
`default_factory`	產生預設值的函式	無
`repr`	是否包含在 `__repr__`	True
`compare`	是否包含在比較中	True
`hash`	是否包含在 hash 中	None
`init`	是否包含在 `__init__`	True

post_init

在 __init__ 完成後執行，用於衍生欄位計算：

 1from dataclasses import dataclass, field
 2from typing import List
 3
 4@dataclass
 5class ValidationResult:
 6    hook_path: str
 7    issues: List[ValidationIssue] = field(default_factory=list)
 8    is_compliant: bool = True
 9
10    def __post_init__(self):
11        """根據 issues 計算 is_compliant"""
12        self.is_compliant = not any(
13            issue.level == "error" for issue in self.issues
14        )
15
16# 使用
17result = ValidationResult(
18    hook_path="my_hook.py",
19    issues=[ValidationIssue(level="error", message="Bad")]
20)
21print(result.is_compliant)  # False（自動計算）

不可變 Dataclass

使用 frozen=True 建立不可變物件：

1from dataclasses import dataclass
2
3@dataclass(frozen=True)
4class Point:
5    x: float
6    y: float
7
8p = Point(1.0, 2.0)
9p.x = 3.0  # 錯誤！FrozenInstanceError

不可變 dataclass 可以用作字典鍵或集合元素。

轉換為字典

使用 asdict() 轉換為字典：

 1from dataclasses import dataclass, asdict
 2
 3@dataclass
 4class Config:
 5    name: str
 6    timeout: int
 7
 8config = Config("test", 30)
 9config_dict = asdict(config)
10# {'name': 'test', 'timeout': 30}
11
12# 用於 JSON 序列化
13import json
14json.dumps(asdict(config))

實際應用：Markdown 連結檢查

來自 .claude/lib/markdown_link_checker.py：

 1from dataclasses import dataclass, asdict, field
 2from typing import List
 3
 4@dataclass
 5class BrokenLink:
 6    """失效連結描述"""
 7    file: str
 8    line: int
 9    link_text: str
10    link_target: str
11    suggestion: str = ""
12
13
14@dataclass
15class LinkCheckResult:
16    """單個檔案的連結檢查結果"""
17    file_path: str
18    total_links: int
19    broken_links: List[BrokenLink] = field(default_factory=list)
20    is_valid: bool = True
21
22    def __post_init__(self):
23        """計算 is_valid 狀態"""
24        self.is_valid = len(self.broken_links) == 0
25
26
27# 使用範例
28result = LinkCheckResult(
29    file_path="docs/README.md",
30    total_links=10,
31    broken_links=[
32        BrokenLink(
33            file="docs/README.md",
34            line=15,
35            link_text="Guide",
36            link_target="./guide.md",
37            suggestion="檔案不存在"
38        )
39    ]
40)
41
42# 輸出 JSON
43print(json.dumps(asdict(result), ensure_ascii=False, indent=2))

與 TypedDict 的比較

特性	dataclass	TypedDict
用途	資料物件	字典型別提示
執行時驗證	有（可選）	無
方法	可以定義	不能定義
輸出	物件	字典

 1from typing import TypedDict
 2from dataclasses import dataclass
 3
 4# TypedDict：給字典加型別
 5class ConfigDict(TypedDict):
 6    name: str
 7    timeout: int
 8
 9config: ConfigDict = {"name": "test", "timeout": 30}
10
11# dataclass：建立資料物件
12@dataclass
13class Config:
14    name: str
15    timeout: int
16
17config = Config(name="test", timeout=30)

最佳實踐

1. 必要欄位放前面

1@dataclass
2class Person:
3    # 必要欄位
4    name: str
5    age: int
6    # 可選欄位
7    email: Optional[str] = None

2. 使用 field() 處理可變預設值

1@dataclass
2class Container:
3    items: List[str] = field(default_factory=list)  # 正確
4    # items: List[str] = []  # 錯誤！

3. 善用 post_init

1@dataclass
2class Result:
3    items: List[str] = field(default_factory=list)
4    count: int = 0
5
6    def __post_init__(self):
7        self.count = len(self.items)  # 自動計算

思考題

為什麼 issues: List[str] = [] 是危險的？
__post_init__ 和在 __init__ 中計算有什麼區別？
什麼時候應該使用 frozen=True？

實作練習

建立一個 HookResult dataclass，包含 hook 名稱、執行時間、成功狀態
實作一個 dataclass，使用 __post_init__ 計算衍生欄位
將現有的字典結構重構為 dataclass

上一章：Optional、Union、泛型 下一章：Enum 列舉型別

2.4 Enum 列舉型別

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

Enum（列舉）用於定義一組具名的常數值。當你有一組固定的選項時，使用 Enum 比使用字串或數字更安全、更易讀。

為什麼使用 Enum？

使用字串的問題

1# 使用字串：容易打錯
2def handle_decision(decision: str) -> None:
3 if decision == "alow": # 打錯了！應該是 "allow"
4 allow_action()
5 elif decision == "deny":
6 deny_action()
7
8# 沒有 IDE 自動完成
9# 沒有型別檢查

使用 Enum 的好處

 1from enum import Enum
 2
 3class Decision(Enum):
 4 ALLOW = "allow"
 5 DENY = "deny"
 6 ASK = "ask"
 7
 8def handle_decision(decision: Decision) -> None:
 9 if decision == Decision.ALLOW: # IDE 會自動完成
10 allow_action()
11 elif decision == Decision.DENY:
12 deny_action()
13
14# 打錯會有 AttributeError
15# Decision.ALOW # 錯誤！

基本用法

定義 Enum

 1from enum import Enum
 2
 3class Color(Enum):
 4 RED = 1
 5 GREEN = 2
 6 BLUE = 3
 7
 8# 存取
 9print(Color.RED) # Color.RED
10print(Color.RED.name) # 'RED'
11print(Color.RED.value) # 1

字串值的 Enum

 1from enum import Enum
 2
 3class LogLevel(Enum):
 4 DEBUG = "debug"
 5 INFO = "info"
 6 WARNING = "warning"
 7 ERROR = "error"
 8
 9# 從值建立
10level = LogLevel("info")
11print(level) # LogLevel.INFO

實際範例：Hook 決策

雖然 Hook 系統目前使用字串，但可以用 Enum 改善：

 1from enum import Enum
 2
 3class HookDecision(Enum):
 4 """Hook 決策類型"""
 5 ALLOW = "allow"
 6 DENY = "deny"
 7 ASK = "ask"
 8 BLOCK = "block"
 9
10class HookEventType(Enum):
11 """Hook 事件類型"""
12 PRE_TOOL_USE = "PreToolUse"
13 POST_TOOL_USE = "PostToolUse"
14 STOP = "Stop"
15 SESSION_START = "SessionStart"
16
17# 使用
18def create_output(decision: HookDecision) -> dict:
19 return {
20 "hookSpecificOutput": {
21 "permissionDecision": decision.value
22 }
23 }

進階功能

auto() 自動值

1from enum import Enum, auto
2
3class Priority(Enum):
4 LOW = auto() # 1
5 MEDIUM = auto() # 2
6 HIGH = auto() # 3

IntEnum

當需要 Enum 值可以用作整數時：

 1from enum import IntEnum
 2
 3class HttpStatus(IntEnum):
 4 OK = 200
 5 NOT_FOUND = 404
 6 SERVER_ERROR = 500
 7
 8# 可以直接比較整數
 9if response.status == HttpStatus.OK:
10 ...
11
12# 可以用於數學運算
13print(HttpStatus.OK + 1) # 201

StrEnum (Python 3.11+)

1from enum import StrEnum
2
3class Color(StrEnum):
4 RED = "red"
5 GREEN = "green"
6 BLUE = "blue"
7
8# 可以直接當字串使用
9print(f"Color is {Color.RED}") # "Color is red"

Flag（位元旗標）

 1from enum import Flag, auto
 2
 3class Permission(Flag):
 4 READ = auto()
 5 WRITE = auto()
 6 EXECUTE = auto()
 7
 8# 組合權限
 9user_perms = Permission.READ | Permission.WRITE
10
11# 檢查權限
12if Permission.READ in user_perms:
13 print("Can read")

迭代和比較

迭代所有成員

 1from enum import Enum
 2
 3class Status(Enum):
 4 PENDING = "pending"
 5 RUNNING = "running"
 6 COMPLETED = "completed"
 7
 8# 迭代
 9for status in Status:
10 print(f"{status.name}: {status.value}")
11
12# 取得所有值
13all_values = [s.value for s in Status]
14# ['pending', 'running', 'completed']

比較

 1from enum import Enum
 2
 3class Color(Enum):
 4 RED = 1
 5 GREEN = 2
 6
 7# Enum 成員是單例
 8Color.RED is Color.RED # True
 9Color.RED == Color.RED # True
10
11# 不能與原始值直接比較
12Color.RED == 1 # False
13Color.RED.value == 1 # True

從值建立 Enum

 1from enum import Enum
 2
 3class Status(Enum):
 4 ACTIVE = "active"
 5 INACTIVE = "inactive"
 6
 7# 從值建立
 8status = Status("active") # Status.ACTIVE
 9
10# 從名稱建立
11status = Status["ACTIVE"] # Status.ACTIVE
12
13# 安全地從值建立
14def get_status(value: str) -> Status:
15 try:
16 return Status(value)
17 except ValueError:
18 return Status.INACTIVE

實際應用模式

配置選項

 1from enum import Enum
 2
 3class OutputFormat(Enum):
 4 JSON = "json"
 5 YAML = "yaml"
 6 TEXT = "text"
 7
 8def export_data(data: dict, format: OutputFormat) -> str:
 9 if format == OutputFormat.JSON:
10 return json.dumps(data)
11 elif format == OutputFormat.YAML:
12 return yaml.dump(data)
13 else:
14 return str(data)

狀態機

 1from enum import Enum, auto
 2
 3class TaskState(Enum):
 4 PENDING = auto()
 5 RUNNING = auto()
 6 COMPLETED = auto()
 7 FAILED = auto()
 8
 9class Task:
10 def __init__(self):
11 self.state = TaskState.PENDING
12
13 def start(self):
14 if self.state != TaskState.PENDING:
15 raise ValueError("Cannot start non-pending task")
16 self.state = TaskState.RUNNING
17
18 def complete(self):
19 if self.state != TaskState.RUNNING:
20 raise ValueError("Cannot complete non-running task")
21 self.state = TaskState.COMPLETED

驗證等級

 1from enum import Enum
 2
 3class ValidationLevel(Enum):
 4 ERROR = "error"
 5 WARNING = "warning"
 6 INFO = "info"
 7
 8 def is_blocking(self) -> bool:
 9 """是否會阻止操作"""
10 return self == ValidationLevel.ERROR
11
12# 使用
13issue_level = ValidationLevel.WARNING
14if issue_level.is_blocking():
15 raise ValidationError()

最佳實踐

1. 使用全大寫命名成員

1class Status(Enum):
2 ACTIVE = "active" # 好
3 active = "active" # 不推薦

2. 為 Enum 添加方法

 1class Priority(Enum):
 2 LOW = 1
 3 MEDIUM = 2
 4 HIGH = 3
 5
 6 def is_urgent(self) -> bool:
 7 return self == Priority.HIGH
 8
 9 @classmethod
10 def from_string(cls, value: str) -> "Priority":
11 return cls[value.upper()]

3. 搭配型別提示使用

 1from enum import Enum
 2
 3class Color(Enum):
 4 RED = "red"
 5 BLUE = "blue"
 6
 7def paint(color: Color) -> None: # 型別提示
 8 print(f"Painting with {color.value}")
 9
10paint(Color.RED) # OK
11paint("red") # 型別檢查會警告

思考題

Enum 和 IntEnum 有什麼區別？什麼時候用哪個？
為什麼 Color.RED == 1 會是 False？
如何為 Enum 添加自訂方法？

實作練習

建立一個 HookType Enum，包含所有 Hook 事件類型
實作一個包含 is_valid() 方法的 FileExtension Enum
使用 Flag 實作一個權限系統

上一章：Dataclass 資料結構 下一模組：標準庫實戰

2.5 Callable 型別與高階函式

Fri, 24 Apr 2026 00:00:00 +0000

Callable 的核心概念是「這個值可以被呼叫，而且我要求它的參數與回傳型別符合特定形狀」。當程式碼把函式當值傳進傳出（callback、decorator、依賴注入）時，Callable 讓型別系統幫你在呼叫前就驗證契約，而不是等 runtime 才 AttributeError。

什麼時候會用到 Callable

函式當作一等公民（first-class function）

Python 的函式是值，可以賦給變數、放進資料結構、當成參數傳遞。一旦函式流動起來，就需要描述它的形狀：

1def apply(operation, value):
2    return operation(value)  # operation 是什麼？能不能呼叫？接受什麼參數？

沒有型別註解時，讀者得追 operation 怎麼來的、在哪裡用的，才能知道它的 contract。Callable 把這個 contract 提前到簽名。

加上 Callable 型別後

1from typing import Callable
2
3def apply(operation: Callable[[int], int], value: int) -> int:
4    return operation(value)
5
6apply(lambda x: x * 2, 10)  # 型別檢查通過
7apply("not callable", 10)   # IDE / mypy 立即標紅

讀者看簽名就知道：operation 必須接受一個 int、回傳一個 int。

基本語法

Callable 的泛型形式是 Callable[[ParamType1, ParamType2, ...], ReturnType]。

 1from typing import Callable
 2
 3# 無參數、回傳 None
 4on_shutdown: Callable[[], None]
 5
 6# 接受 str，回傳 bool（驗證器）
 7validator: Callable[[str], bool]
 8
 9# 接受兩個 int，回傳 int（雙元運算）
10binary_op: Callable[[int, int], int]
11
12# 接受任意型別，回傳任意型別
13generic_callback: Callable[..., object]

內建函式、lambda、method、class（可實例化的）、有 __call__ 方法的 class instance，都屬於 Callable。

Python 3.9+ 的新寫法

從 Python 3.9 開始，collections.abc.Callable 支援直接用下標語法，不需要 from typing import：

1from collections.abc import Callable
2
3def register(cb: Callable[[str], None]) -> None:
4    ...

新程式碼優先用 collections.abc.Callable，避免 typing 模組的歷史包袱。

四種典型使用場景

場景一：高階函式（Higher-Order Function）

接受函式作為參數或回傳函式的函式：

 1from collections.abc import Callable
 2
 3def retry(operation: Callable[[], str], times: int = 3) -> str:
 4    last_error: Exception | None = None
 5    for _ in range(times):
 6        try:
 7            return operation()
 8        except Exception as e:
 9            last_error = e
10    raise RuntimeError(f"retry exhausted") from last_error

呼叫端可以傳 lambda、named function、甚至 partial：

1from functools import partial
2
3retry(lambda: fetch_user(user_id=42))
4retry(partial(fetch_user, user_id=42))

場景二：Callback 與事件分派

事件系統、非同步流程、hook 註冊都走這個模式：

 1from collections.abc import Callable
 2
 3EventHandler = Callable[[dict], None]  # type alias 提升可讀性
 4
 5class EventBus:
 6    def __init__(self) -> None:
 7        self._handlers: dict[str, list[EventHandler]] = {}
 8
 9    def subscribe(self, event: str, handler: EventHandler) -> None:
10        self._handlers.setdefault(event, []).append(handler)
11
12    def publish(self, event: str, payload: dict) -> None:
13        for handler in self._handlers.get(event, []):
14            handler(payload)

EventHandler type alias 讓「這個系統期望 handler 是什麼形狀」在多個呼叫點保持一致。

場景三：依賴注入

把相依行為抽成參數，讓測試能替換：

 1from collections.abc import Callable
 2
 3def process_order(
 4    order_id: str,
 5    fetch_order: Callable[[str], dict],
 6    save_invoice: Callable[[dict], None],
 7) -> None:
 8    order = fetch_order(order_id)
 9    invoice = build_invoice(order)
10    save_invoice(invoice)

生產環境注入真實的資料庫與 API client，測試時注入 in-memory fake。型別簽名保證 fake 的形狀與真品一致。

場景四：Decorator 的型別標註

Decorator 本身就是「接受函式、回傳函式」的高階函式：

1from collections.abc import Callable
2from functools import wraps
3
4def log_calls(func: Callable[..., object]) -> Callable[..., object]:
5    @wraps(func)
6    def wrapper(*args: object, **kwargs: object) -> object:
7        print(f"calling {func.__name__}")
8        return func(*args, **kwargs)
9    return wrapper

Callable[..., object] 的 ... 代表「任意參數」，object 作為回傳型別是最寬鬆的上界。這個簽名夠描述「這是個 decorator」，但沒法保留被裝飾函式原本的精確型別 — 那需要 ParamSpec，見下方進階用法。

實際範例：Hook 系統

來自 .claude/lib/hook_runner.py 的 hook 註冊模式：

 1from collections.abc import Callable
 2from dataclasses import dataclass
 3
 4HookFunc = Callable[[dict], dict]
 5
 6@dataclass
 7class HookConfig:
 8    name: str
 9    func: HookFunc
10    priority: int = 0
11
12def register_pre_commit(hooks: list[HookConfig], func: HookFunc, name: str) -> None:
13    hooks.append(HookConfig(name=name, func=func))
14
15def run_hooks(hooks: list[HookConfig], context: dict) -> dict:
16    for hook in sorted(hooks, key=lambda h: h.priority):
17        context = hook.func(context)
18    return context

所有 hook 都承諾 dict → dict 的 pipeline 契約。新的 hook 實作者不用讀 runner 程式碼就知道怎麼接。

進階用法：ParamSpec 保留精確型別

Callable[..., T] 雖然可用，但喪失了「原本的參數型別」。Python 3.10 的 ParamSpec 解決了這個問題，常見於 decorator：

 1from collections.abc import Callable
 2from functools import wraps
 3from typing import ParamSpec, TypeVar
 4
 5P = ParamSpec("P")
 6R = TypeVar("R")
 7
 8def log_calls(func: Callable[P, R]) -> Callable[P, R]:
 9    @wraps(func)
10    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
11        print(f"calling {func.__name__}")
12        return func(*args, **kwargs)
13    return wrapper
14
15@log_calls
16def greet(name: str, greeting: str = "Hi") -> str:
17    return f"{greeting}, {name}"
18
19greet("Ada")           # 保留原本簽名
20greet(123)             # mypy 偵測：name 應該是 str

裝飾後的 greet 仍然具有 (name: str, greeting: str = "Hi") -> str 的精確簽名。沒有 ParamSpec，decorator 會把一切磨成 Callable[..., object]。

Callable vs Protocol

當你需要的不只是「可呼叫」，而是「某個 class 要有特定方法集合」時，Protocol 是更好的選擇：

需求	選擇	範例
只關心「可被呼叫」	`Callable`	`Callable[[int], str]`
需要多個方法（read / write）	`Protocol`	定義一個有 `read()` 與 `write()` 的類型
需要屬性而非方法	`Protocol`	定義一個有 `name: str` 的類型

兩者互補：Callable 是 Protocol 的特例（只有 __call__ 方法）。

常見陷阱

把 Callable 當成「任意函式」使用

1def process(callback: Callable) -> None:  # 失去型別資訊
2    callback(some_value)

沒加參數型別的 Callable 等同於 Callable[..., Any]，型別檢查器會放行任何呼叫。這不是 type hints 的失敗，是契約寫太鬆。若真的要接受任何可呼叫物件，至少寫清楚參數與回傳上界：Callable[..., object]。

忽略 method 和 function 的差異

1class Logger:
2    def log(self, msg: str) -> None:
3        print(msg)
4
5# 直接傳 Logger 的 log method（綁定方法）
6cb: Callable[[str], None] = Logger().log  # 正確用法
7
8# 直接傳 unbound class method（需要 self）
9cb: Callable[[Logger, str], None] = Logger.log  # 另一種簽名

Bound method（實例呼叫的）已經把 self 隱藏起來，型別從簽名看是 (msg: str) -> None。Unbound method 會要你提供 self。混淆兩者在 decorator 場景特別常見。

lambda 的型別推斷有限

1handler: Callable[[int], str] = lambda x: f"got {x}"  # 正確用法
2handler = lambda x: f"got {x}"                          # lambda 參數型別推斷為 Any

lambda 本身不帶型別註解，要靠左側變數註解把型別灌進去。直接賦值給無註解變數時型別會退化。

小結

Callable 是 Python 型別系統描述「函式形狀」的基本工具。當函式開始當值流動（callbacks、decorators、dependency injection），Callable 把「能不能呼叫、接受什麼、回傳什麼」的契約寫進簽名，讓讀者與工具不必追到實作才能理解意圖。進階場景（保留 decorator 的精確型別）使用 ParamSpec；當契約擴展到多個方法或屬性時，升級到 Protocol。

Typing on Tarragon

2.1 Type Hints 基礎

為什麼需要型別提示？

沒有型別提示的程式碼

有型別提示的程式碼

基本語法

變數型別註解

函式型別註解

實際範例：Hook 系統

容器型別

列表（List）

字典（Dict）

集合（Set）

元組（Tuple）

實際應用：Hook 輸出建立

型別別名

型別檢查工具

mypy

IDE 整合

最佳實踐

1. 為公開 API 添加型別提示

2. 使用有意義的型別別名

3. 逐步添加型別提示

思考題

實作練習

2.2 Optional、Union、泛型

Optional

基本用法

Optional 等同於 Union[T, None]

實際範例：配置載入

Union

基本用法

常見應用

泛型（Generic）

TypeVar

有限制的 TypeVar

實際範例：Hook 輸出建立

Any

何時使用 Any？

Callable

Python 3.9+ 語法

常見模式

可選參數

返回值可能為空

字典值型別不確定

思考題

實作練習

延伸閱讀（進階系列）

模組二：型別系統

章節列表

實際範例來源

為什麼需要型別系統？

學習時間

2.3 Dataclass 資料結構

為什麼使用 Dataclass？

傳統類別

使用 Dataclass

實際範例：Hook 驗證器

基本語法

欄位定義

可變預設值的問題

field() 函式

field() 參數

post_init

不可變 Dataclass

轉換為字典

實際應用：Markdown 連結檢查

與 TypedDict 的比較

最佳實踐

1. 必要欄位放前面

2. 使用 field() 處理可變預設值

3. 善用 post_init

思考題

實作練習

2.4 Enum 列舉型別

為什麼使用 Enum？

使用字串的問題

使用 Enum 的好處

基本用法

定義 Enum