Modules on Tarragon

模組一：Python 基礎概念

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

本模組帶你快速回顧 Python 的核心概念。如果你已經有其他程式語言經驗，這些內容能幫助你理解 Python 的「思考方式」，以及程式如何從單一 script 長成多檔案與 package。

章節列表

章節	主題	關鍵收穫
1.1	Python 哲學與設計理念	理解「Pythonic」的真正含義
1.2	從單一 script 到多檔案專案	理解 `.py` module、package、執行方式與測試結構如何逐步出現
1.3	模組與套件組織	掌握 `__init__.py` 的作用
1.4	導入機制與路徑管理	解決「找不到模組」的困擾

實際範例來源

本模組的範例主要來自：

.claude/lib/__init__.py - 模組初始化範例
Hook 腳本的導入結構

後續補寫提示：1.2 從單一 script 到多檔案專案 應改用中立範例，避免依賴特定 Hook 系統背景。這一章負責補上初學者從單檔到 package 的過渡；1.3 和 1.4 再處理既有專案中的 module、package 與 import 問題。

預備知識

基本程式設計概念（變數、函式、迴圈）
對任一程式語言有基礎了解

學習時間

預計 45-60 分鐘

1.2 從單一 script 到多檔案專案

Wed, 22 Apr 2026 00:00:00 +0000

Python 程式變大的第一個斷點通常是執行方式與 import 邊界，而非物件導向或架構分層。初學者常從一個 script.py 開始，接著拆出 helper module，最後才整理成 package；每一步都會改變程式如何被執行、如何 import，以及測試如何找到程式碼。

撰寫提示：本章先保留大綱，詳細內容之後補。補寫時請使用中立範例，例如 notify.py、config.py、parser.py、service.py，避免綁定特定專案或 Hook 系統細節。

本章目標

學完本章後，你將能夠：

判斷何時保留單一 script
理解一個 .py 檔案就是一個 module
分辨「同層多檔案」與「package」的差異
看懂 python file.py 與 python -m package.module 的差異
判斷何時需要 __init__.py、pyproject.toml 或 src/ layout

章節大綱

1. 單一 script 是合理起點

核心原則：小工具與實驗程式可以先從單一 .py 檔案開始。這個階段的重點是讓流程清楚，不是急著拆資料夾。

後續補寫範例：

1notify.py

應補充重點：

if __name__ == "__main__" 的基本用途。
函式先集中在同一檔案，避免過早拆分。
當檔案開始同時包含 CLI、設定、解析、業務規則時，再考慮拆檔。

2. 拆成同層 module

核心原則：Python 的每個 .py 檔案都是 module。同層拆檔可以降低單檔負擔，但 import 會受到目前執行位置與 sys.path 影響。

後續補寫範例：

1notify/
2├── notify.py
3├── config.py
4├── parser.py
5└── service.py

應補充重點：

import config 與 from config import load_config。
從專案根目錄執行與從其他目錄執行的差異。
同層 module 適合小型工具，但不一定適合長期擴張。

3. 整理成 package

核心原則：package 是一組 module 的命名空間。當多個 module 共同形成一個概念，就可以用資料夾與 __init__.py 整理成 package。

後續補寫範例：

1notify/
2├── notify_app/
3│   ├── __init__.py
4│   ├── config.py
5│   ├── parser.py
6│   └── service.py
7└── main.py

應補充重點：

__init__.py 的角色：初始化、公開 API、package 標記。
package 內部使用 absolute import 或 relative import 的取捨。
不要把所有名稱都重新 export 到 __init__.py。

4. 執行方式會影響 import

核心原則：Python 的 import 行為和執行方式密切相關。python main.py、python -m package.module、測試工具與安裝後執行，可能會看到不同的 module search path。

後續補寫範例：

1python main.py
2python -m notify_app.cli
3python -m pytest

應補充重點：

__name__ 與 __package__ 的差異。
為什麼 package 內相對 import 在直接執行檔案時容易失敗。
CLI 入口和 library module 最好分開。

5. 測試會推動專案結構

核心原則：當程式需要測試時，專案結構必須讓測試穩定 import 目標程式碼。測試是拆分 module 與 package 的重要壓力來源。

後續補寫範例：

1notify/
2├── notify_app/
3│   ├── __init__.py
4│   └── service.py
5└── tests/
6    └── test_service.py

應補充重點：

tests/ 和 package 的相對位置。
為什麼測試常揭露 import 路徑設計不穩。
小型專案可以先維持簡單，大型或可發布專案再導入 pyproject.toml。

6. 何時進入可安裝專案與 `src/` layout

核心原則：pyproject.toml 與 src/ layout 是正式專案管理工具，不是所有初學程式的起點。當專案需要被安裝、發布、由多個工具穩定執行時，再導入這些結構。

後續補寫範例：

1notify/
2├── pyproject.toml
3├── src/
4│   └── notify_app/
5│       ├── __init__.py
6│       └── service.py
7└── tests/
8    └── test_service.py

應補充重點：

src/ layout 防止「剛好從目前目錄 import 成功」的假象。
editable install 的用途。
進階打包內容應連到 python-advanced/07-packaging/。

後續補寫時的比較提示

Python 和 Go 在這個主題上的差異應明確說清楚：

主題	Python	Go
最小單位	`.py` module	package
單檔起點	任意 script	`package main` + `func main()`
可見性	`_name` 慣例，runtime 不強制	大小寫由編譯器強制
import 問題	受 `sys.path`、執行方式、安裝方式影響	受 `go.mod`、module path、package 邊界影響
循環依賴	runtime 才可能爆 partially initialized module	編譯期拒絕 import cycle
正式專案	`pyproject.toml`、package、`src/` layout	`go.mod`、package、`cmd/`、`internal/`

本章不處理

不展開 packaging 與發布流程。
不深入 dependency management。
不討論大型框架專案結構。
不把 src/ layout 當成所有專案的預設起點。

和 Python 教材的關係

這一章承接的是 module、package 與測試路徑；如果你要先回看 Python 教材，可以讀：

小結

Python 程式的成長路線通常是 script、同層 module、package、可安裝專案。這條路線的核心是執行方式、import 邊界與測試方式逐步穩定。

6.2 如何擴展共用模組

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

本章介紹如何為 .claude/lib/ 共用程式庫添加新功能。這是維護和擴展 Hook 系統的關鍵技能。

前置知識

建議先閱讀：

共用模組架構

目前的 .claude/lib/ 結構：

1.claude/lib/
2├── __init__.py          # 模組初始化與匯出
3├── git_utils.py         # Git 操作工具
4├── hook_logging.py      # 日誌系統
5├── hook_io.py           # 輸入輸出處理
6├── config_loader.py     # 配置載入器
7├── hook_validator.py    # Hook 驗證器
8└── markdown_link_checker.py  # Markdown 連結檢查

步驟 1：規劃新模組

決定放置位置

情況	建議
新的獨立功能	建立新檔案
擴展現有功能	修改現有檔案
工具函式	加入相關現有模組

設計介面

在寫程式碼之前，先規劃公開介面：

 1# 思考要提供什麼功能給使用者
 2
 3# 函式：簡單操作
 4def validate_yaml(content: str) -> bool:
 5    """驗證 YAML 格式"""
 6    pass
 7
 8# 類別：複雜操作或需要狀態
 9class YamlValidator:
10    """YAML 驗證器"""
11
12    def __init__(self, strict: bool = True):
13        """初始化"""
14        pass
15
16    def validate(self, content: str) -> ValidationResult:
17        """驗證內容"""
18        pass

步驟 2：實作新模組

範例：建立 YAML 工具模組

  1# .claude/lib/yaml_utils.py
  2"""
  3YAML 工具模組
  4
  5提供 YAML 檔案的讀取、驗證和處理功能。
  6"""
  7
  8from pathlib import Path
  9from typing import Optional, Any
 10from dataclasses import dataclass
 11
 12# 嘗試導入 yaml
 13try:
 14    import yaml
 15    HAS_YAML = True
 16except ImportError:
 17    HAS_YAML = False
 18
 19
 20@dataclass
 21class YamlResult:
 22    """YAML 處理結果"""
 23    success: bool
 24    data: Optional[dict] = None
 25    error: Optional[str] = None
 26
 27
 28def load_yaml(path: str, encoding: str = "utf-8") -> YamlResult:
 29    """
 30    載入 YAML 檔案
 31
 32    Args:
 33        path: 檔案路徑
 34        encoding: 檔案編碼
 35
 36    Returns:
 37        YamlResult: 載入結果
 38
 39    Example:
 40        result = load_yaml("config.yaml")
 41        if result.success:
 42            print(result.data)
 43        else:
 44            print(f"錯誤: {result.error}")
 45    """
 46    if not HAS_YAML:
 47        return YamlResult(
 48            success=False,
 49            error="PyYAML 未安裝。請執行: pip install pyyaml"
 50        )
 51
 52    file_path = Path(path)
 53
 54    if not file_path.exists():
 55        return YamlResult(
 56            success=False,
 57            error=f"檔案不存在: {path}"
 58        )
 59
 60    try:
 61        content = file_path.read_text(encoding=encoding)
 62        data = yaml.safe_load(content)
 63        return YamlResult(success=True, data=data or {})
 64    except yaml.YAMLError as e:
 65        return YamlResult(success=False, error=f"YAML 解析錯誤: {e}")
 66
 67
 68def validate_yaml(content: str) -> bool:
 69    """
 70    驗證 YAML 格式
 71
 72    Args:
 73        content: YAML 內容字串
 74
 75    Returns:
 76        bool: 格式正確返回 True
 77    """
 78    if not HAS_YAML:
 79        return False
 80
 81    try:
 82        yaml.safe_load(content)
 83        return True
 84    except yaml.YAMLError:
 85        return False
 86
 87
 88def merge_yaml_configs(*configs: dict) -> dict:
 89    """
 90    合併多個 YAML 配置
 91
 92    後面的配置會覆蓋前面的。
 93
 94    Args:
 95        *configs: 要合併的配置字典
 96
 97    Returns:
 98        dict: 合併後的配置
 99
100    Example:
101        base = {"a": 1, "b": 2}
102        override = {"b": 3, "c": 4}
103        result = merge_yaml_configs(base, override)
104        # result = {"a": 1, "b": 3, "c": 4}
105    """
106    result = {}
107    for config in configs:
108        if config:
109            _deep_merge(result, config)
110    return result
111
112
113def _deep_merge(base: dict, override: dict) -> None:
114    """深度合併字典（就地修改 base）"""
115    for key, value in override.items():
116        if (
117            key in base
118            and isinstance(base[key], dict)
119            and isinstance(value, dict)
120        ):
121            _deep_merge(base[key], value)
122        else:
123            base[key] = value

步驟 3：更新 `init.py`

在 __init__.py 中註冊新模組：

 1# .claude/lib/__init__.py
 2"""
 3Claude Hooks 共用程式庫
 4"""
 5
 6# 現有匯入
 7from .git_utils import (
 8    run_git_command,
 9    get_current_branch,
10    # ...
11)
12
13from .hook_logging import setup_hook_logging
14from .hook_io import read_hook_input, write_hook_output
15
16# 新增：YAML 工具
17from .yaml_utils import (
18    load_yaml,
19    validate_yaml,
20    merge_yaml_configs,
21    YamlResult,
22)
23
24__all__ = [
25    # 現有匯出
26    "run_git_command",
27    "get_current_branch",
28    "setup_hook_logging",
29    "read_hook_input",
30    "write_hook_output",
31    # 新增
32    "load_yaml",
33    "validate_yaml",
34    "merge_yaml_configs",
35    "YamlResult",
36]
37
38__version__ = "0.29.0"  # 更新版本

步驟 4：撰寫測試

  1# tests/lib/test_yaml_utils.py
  2"""
  3YAML 工具模組測試
  4"""
  5
  6import unittest
  7from unittest.mock import patch, mock_open
  8import sys
  9from pathlib import Path
 10
 11# 添加 lib 目錄到路徑
 12sys.path.insert(0, str(Path(__file__).parent.parent.parent / ".claude" / "lib"))
 13
 14from yaml_utils import load_yaml, validate_yaml, merge_yaml_configs, YamlResult
 15
 16
 17class TestLoadYaml(unittest.TestCase):
 18    """測試 load_yaml 函式"""
 19
 20    def test_load_valid_yaml(self):
 21        """測試載入有效的 YAML 檔案"""
 22        yaml_content = "key: value\nlist:\n  - item1\n  - item2"
 23
 24        with patch("pathlib.Path.exists", return_value=True):
 25            with patch("pathlib.Path.read_text", return_value=yaml_content):
 26                result = load_yaml("test.yaml")
 27
 28        self.assertTrue(result.success)
 29        self.assertEqual(result.data["key"], "value")
 30        self.assertEqual(len(result.data["list"]), 2)
 31
 32    def test_load_nonexistent_file(self):
 33        """測試載入不存在的檔案"""
 34        with patch("pathlib.Path.exists", return_value=False):
 35            result = load_yaml("nonexistent.yaml")
 36
 37        self.assertFalse(result.success)
 38        self.assertIn("不存在", result.error)
 39
 40    def test_load_invalid_yaml(self):
 41        """測試載入無效的 YAML"""
 42        invalid_content = "key: [invalid yaml"
 43
 44        with patch("pathlib.Path.exists", return_value=True):
 45            with patch("pathlib.Path.read_text", return_value=invalid_content):
 46                result = load_yaml("invalid.yaml")
 47
 48        self.assertFalse(result.success)
 49        self.assertIn("解析錯誤", result.error)
 50
 51
 52class TestValidateYaml(unittest.TestCase):
 53    """測試 validate_yaml 函式"""
 54
 55    def test_valid_yaml(self):
 56        """測試有效的 YAML"""
 57        self.assertTrue(validate_yaml("key: value"))
 58        self.assertTrue(validate_yaml("list:\n  - a\n  - b"))
 59
 60    def test_invalid_yaml(self):
 61        """測試無效的 YAML"""
 62        self.assertFalse(validate_yaml("key: [unclosed"))
 63        self.assertFalse(validate_yaml("  bad indent\nkey: value"))
 64
 65
 66class TestMergeYamlConfigs(unittest.TestCase):
 67    """測試 merge_yaml_configs 函式"""
 68
 69    def test_simple_merge(self):
 70        """測試簡單合併"""
 71        base = {"a": 1, "b": 2}
 72        override = {"b": 3, "c": 4}
 73
 74        result = merge_yaml_configs(base, override)
 75
 76        self.assertEqual(result["a"], 1)
 77        self.assertEqual(result["b"], 3)  # 被覆蓋
 78        self.assertEqual(result["c"], 4)
 79
 80    def test_deep_merge(self):
 81        """測試深度合併"""
 82        base = {
 83            "database": {
 84                "host": "localhost",
 85                "port": 5432
 86            }
 87        }
 88        override = {
 89            "database": {
 90                "port": 3306,
 91                "name": "mydb"
 92            }
 93        }
 94
 95        result = merge_yaml_configs(base, override)
 96
 97        self.assertEqual(result["database"]["host"], "localhost")
 98        self.assertEqual(result["database"]["port"], 3306)
 99        self.assertEqual(result["database"]["name"], "mydb")
100
101    def test_multiple_configs(self):
102        """測試多個配置合併"""
103        config1 = {"a": 1}
104        config2 = {"b": 2}
105        config3 = {"c": 3}
106
107        result = merge_yaml_configs(config1, config2, config3)
108
109        self.assertEqual(result, {"a": 1, "b": 2, "c": 3})
110
111
112if __name__ == "__main__":
113    unittest.main()

步驟 5：更新文件

在模組文檔中說明

在模組開頭加入詳細的 docstring：

 1"""
 2YAML 工具模組
 3
 4提供 YAML 檔案的讀取、驗證和處理功能。
 5
 6主要功能:
 7- load_yaml: 載入 YAML 檔案
 8- validate_yaml: 驗證 YAML 格式
 9- merge_yaml_configs: 合併配置
10
11依賴:
12- PyYAML (可選，但建議安裝)
13
14使用方式:
15    from lib.yaml_utils import load_yaml, validate_yaml
16
17    # 載入配置
18    result = load_yaml("config.yaml")
19    if result.success:
20        config = result.data
21
22    # 驗證格式
23    is_valid = validate_yaml(content)
24
25版本: 0.29.0
26"""

擴展現有模組

範例：為 git_utils 添加新功能

 1# 在 .claude/lib/git_utils.py 中添加
 2
 3def get_uncommitted_changes() -> list[str]:
 4    """
 5    取得未提交的變更檔案列表
 6
 7    Returns:
 8        list[str]: 變更檔案的路徑列表
 9
10    Example:
11        changes = get_uncommitted_changes()
12        if changes:
13            print(f"有 {len(changes)} 個未提交的變更")
14    """
15    success, output = run_git_command(["status", "--porcelain"])
16
17    if not success:
18        return []
19
20    files = []
21    for line in output.strip().split("\n"):
22        if line.strip():
23            # 格式: "XY filename" 或 "XY filename -> newname"
24            parts = line[3:].split(" -> ")
25            files.append(parts[-1])
26
27    return files
28
29
30def has_staged_changes() -> bool:
31    """
32    檢查是否有已暫存的變更
33
34    Returns:
35        bool: 有暫存變更返回 True
36    """
37    success, output = run_git_command(["diff", "--cached", "--name-only"])
38    return success and bool(output.strip())

然後在 __init__.py 中更新匯出：

 1from .git_utils import (
 2    run_git_command,
 3    get_current_branch,
 4    get_project_root,
 5    get_worktree_list,
 6    is_protected_branch,
 7    is_allowed_branch,
 8    # 新增
 9    get_uncommitted_changes,
10    has_staged_changes,
11)
12
13__all__ = [
14    # ... 現有匯出 ...
15    "get_uncommitted_changes",
16    "has_staged_changes",
17]

設計原則

1. 單一職責

每個模組專注一個領域：

 1# 好：專注於 Git 操作
 2# git_utils.py
 3def get_current_branch(): ...
 4def run_git_command(): ...
 5def is_protected_branch(): ...
 6
 7# 不好：混合不同功能
 8# utils.py
 9def get_current_branch(): ...
10def validate_yaml(): ...
11def send_notification(): ...

2. 統一的返回值模式

使用一致的返回值設計：

 1# 簡單操作：返回 (bool, str)
 2def run_command(cmd: str) -> tuple[bool, str]:
 3    """返回 (成功與否, 輸出或錯誤訊息)"""
 4    pass
 5
 6# 複雜操作：返回 dataclass
 7@dataclass
 8class OperationResult:
 9    success: bool
10    data: Optional[Any] = None
11    error: Optional[str] = None
12
13def complex_operation() -> OperationResult:
14    pass

3. 優雅的依賴處理

 1# 處理可選依賴
 2try:
 3    import yaml
 4    HAS_YAML = True
 5except ImportError:
 6    HAS_YAML = False
 7
 8def validate_yaml(content: str) -> bool:
 9    if not HAS_YAML:
10        raise ImportError("需要安裝 PyYAML: pip install pyyaml")
11    # ...

4. 完整的文檔字串

 1def load_config(name: str) -> dict:
 2    """
 3    載入配置檔案
 4
 5    Args:
 6        name: 配置名稱（不含副檔名）
 7
 8    Returns:
 9        dict: 配置內容
10
11    Raises:
12        FileNotFoundError: 配置檔案不存在
13
14    Example:
15        config = load_config("agents")
16        print(config["known_agents"])
17    """

完整檢查清單

擴展共用模組時的檢查項目：

設計清晰的公開介面
使用 Type Hints
撰寫完整的 docstring
處理可選依賴
統一返回值模式
更新 __init__.py
更新 __all__ 匯出
更新版本號
撰寫單元測試
測試與現有 Hook 的整合

思考題

什麼時候應該建立新模組，什麼時候應該擴展現有模組？
如何設計 API 使其易於測試？
__all__ 的作用是什麼？為什麼要維護它？

上一章：如何新增一個 Hook 下一章：如何新增語言解析器 回到首頁：Python 維護工程師實戰指南

1.3 模組與套件組織

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

Python 的模組系統是組織程式碼的基礎。理解模組如何運作，是維護和擴展 Hook 系統的關鍵。

承接提示：如果你還不熟悉程式如何從單一 .py 檔案拆成多個 module，請先閱讀從單一 script 到多檔案專案。本章聚焦在已經出現 package 後，如何理解 module、__init__.py 與公開 API。

基本概念

模組（Module）

一個 .py 檔案就是一個模組。例如 git_utils.py 就是 git_utils 模組。

1# git_utils.py 是一個模組
2# 可以被其他檔案導入
3
4from git_utils import get_current_branch

套件（Package）

包含 __init__.py 的目錄就是一個套件。套件可以包含多個模組。

1.claude/lib/
2├── __init__.py      # 使 lib 成為套件
3├── git_utils.py     # 模組
4├── hook_io.py       # 模組
5├── hook_logging.py  # 模組
6└── config_loader.py # 模組

`init.py` 的作用

__init__.py 是套件的初始化檔案，它在套件被導入時執行。

實際範例：Hook 系統的 `init.py`

來自 .claude/lib/__init__.py：

 1"""
 2Claude Hooks 共用程式庫
 3
 4提供 Hook 腳本共用的工具函式，消除程式碼重複。
 5
 6模組結構:
 7- git_utils: Git 操作工具（分支、worktree、專案根目錄）
 8- hook_logging: Hook 日誌系統
 9- hook_io: Hook 輸入輸出處理
10"""
11
12# 從子模組導入並重新匯出
13from .git_utils import (
14    run_git_command,
15    get_current_branch,
16    get_project_root,
17    get_worktree_list,
18    is_protected_branch,
19    is_allowed_branch,
20)
21
22from .hook_logging import setup_hook_logging
23
24from .hook_io import (
25    read_hook_input,
26    write_hook_output,
27    create_pretooluse_output,
28    create_posttooluse_output,
29)
30
31from .config_loader import (
32    load_config,
33    load_agents_config,
34    load_quality_rules,
35    clear_config_cache,
36)
37
38# 定義公開 API
39__all__ = [
40    # git_utils
41    "run_git_command",
42    "get_current_branch",
43    # ... 省略其他
44]
45
46__version__ = "0.28.0"

`init.py` 的三個主要功能

1. 宣告套件身份

空的 __init__.py 也能讓目錄成為套件：

1# lib/__init__.py（最簡形式）
2# 即使是空檔案，也使 lib 成為套件

2. 定義公開 API

透過 __all__ 列表控制 from package import * 的行為：

1__all__ = [
2    "run_git_command",
3    "get_current_branch",
4    "setup_hook_logging",
5]
6
7# 當使用者執行 from lib import * 時
8# 只會導入 __all__ 中列出的名稱

3. 簡化導入路徑

使用者可以直接從套件導入，而不需要知道子模組：

1# 有 __init__.py 的重新匯出：簡潔
2from lib import get_current_branch, setup_hook_logging
3
4# 沒有 __init__.py 的重新匯出：冗長
5from lib.git_utils import get_current_branch
6from lib.hook_logging import setup_hook_logging

相對導入與絕對導入

相對導入（使用 `.`）

在套件內部使用相對導入：

1# 在 lib/config_loader.py 中
2from .git_utils import get_project_root  # 同級模組
3from . import hook_io                     # 導入整個模組

絕對導入

從套件外部或在腳本中使用絕對導入：

1# 在 .claude/hooks/some_hook.py 中
2import sys
3sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
4
5from git_utils import get_current_branch  # 絕對導入
6from hook_io import read_hook_input

套件版本管理

在 __init__.py 中定義版本號是常見做法：

1__version__ = "0.28.0"

這樣使用者可以查詢版本：

1import lib
2print(lib.__version__)  # "0.28.0"

模組載入順序

Python 搜尋模組的順序：

內建模組
sys.path[0]（腳本所在目錄）
PYTHONPATH 環境變數
標準庫
site-packages（第三方套件）

實際範例：Hook 腳本的路徑設定

 1#!/usr/bin/env python3
 2"""Branch Verify Hook"""
 3
 4import sys
 5from pathlib import Path
 6
 7# 將 lib 目錄加入搜尋路徑
 8sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 9
10# 現在可以導入 lib 中的模組
11from git_utils import get_current_branch
12from hook_io import read_hook_input, write_hook_output

最佳實踐

1. 避免循環導入

 1# 不好：a.py 和 b.py 互相導入
 2# a.py
 3from b import func_b
 4# b.py
 5from a import func_a  # 循環導入！
 6
 7# 好：重構為第三個模組
 8# common.py
 9def shared_function(): ...
10# a.py
11from common import shared_function
12# b.py
13from common import shared_function

2. 延遲導入

對於可選依賴或避免循環導入：

1def load_yaml_config():
2    # 只在需要時才導入
3    try:
4        import yaml
5        return yaml.safe_load(...)
6    except ImportError:
7        # 備案方案
8        import json
9        return json.load(...)

3. 清晰的模組邊界

每個模組應該有單一、明確的職責：

1lib/
2├── git_utils.py      # Git 操作（單一職責）
3├── hook_io.py        # 輸入輸出處理（單一職責）
4├── hook_logging.py   # 日誌系統（單一職責）
5└── config_loader.py  # 配置載入（單一職責）

思考題

為什麼 __init__.py 使用 from .git_utils import ... 而不是 from git_utils import ...？
Hook 腳本中的 sys.path.insert(0, ...) 為什麼使用 0 作為索引？
__all__ 列表的作用是什麼？如果不定義會怎樣？

實作練習

閱讀 .claude/lib/__init__.py，回答以下問題：

這個套件匯出了多少個公開函式？
套件的版本號是多少？
如果要新增一個 utils.py 模組並匯出 format_message 函式，需要修改哪些地方？

上一章：Python 哲學與設計理念 下一章：導入機制與路徑管理

1.4 導入機制與路徑管理

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

「ModuleNotFoundError」是 Python 開發者最常遇到的錯誤之一。理解導入機制可以幫助你快速解決這類問題。

承接提示：import 問題通常是 script、module、package 與執行位置共同造成的結果，而非單一語法問題。如果還不確定這幾個概念的差異，請先閱讀從單一 script 到多檔案專案。

模組搜尋路徑

Python 使用 sys.path 列表來搜尋模組。你可以查看當前的搜尋路徑：

1import sys
2for path in sys.path:
3    print(path)

典型輸出：

1/current/script/directory     # 腳本所在目錄
2/usr/local/lib/python3.11     # 標準庫
3/usr/local/lib/python3.11/site-packages  # 第三方套件

Hook 腳本的導入問題

問題情境

Hook 腳本位於 .claude/hooks/，共用模組位於 .claude/lib/：

1.claude/
2├── hooks/
3│   └── branch-verify-hook.py    # 需要導入 lib 的模組
4└── lib/
5    ├── __init__.py
6    └── git_utils.py

如果直接在 Hook 腳本中寫 from git_utils import ...，會得到 ModuleNotFoundError。

解決方案

在導入前將 lib 目錄加入搜尋路徑：

 1#!/usr/bin/env python3
 2"""Branch Verify Hook"""
 3
 4import sys
 5from pathlib import Path
 6
 7# 計算 lib 目錄的路徑
 8# __file__ = .claude/hooks/branch-verify-hook.py
 9# parent = .claude/hooks/
10# parent.parent = .claude/
11# parent.parent / "lib" = .claude/lib/
12lib_path = Path(__file__).parent.parent / "lib"
13
14# 插入到搜尋路徑的最前面
15sys.path.insert(0, str(lib_path))
16
17# 現在可以導入了
18from git_utils import get_current_branch
19from hook_io import read_hook_input

為什麼用 `insert(0, ...)` 而不是 `append(...)`？

1# 優先搜尋我們的模組（推薦）
2sys.path.insert(0, str(lib_path))
3
4# 最後才搜尋我們的模組（可能被標準庫覆蓋）
5sys.path.append(str(lib_path))

如果你的模組名稱與標準庫衝突（例如 email.py），使用 append 會導致導入標準庫而非你的模組。

使用 Path 物件

Path 的基本操作

 1from pathlib import Path
 2
 3# 取得目前檔案的路徑
 4current_file = Path(__file__)
 5
 6# 取得父目錄
 7parent_dir = current_file.parent
 8
 9# 組合路徑
10lib_path = parent_dir / "lib"  # 使用 / 運算子
11
12# 轉換為字串
13lib_path_str = str(lib_path)

路徑解析的陷阱

1# __file__ 可能是相對路徑
2print(__file__)  # 可能是 "./hooks/my_hook.py"
3
4# 轉換為絕對路徑
5absolute_path = Path(__file__).resolve()
6print(absolute_path)  # "/home/user/project/.claude/hooks/my_hook.py"

環境變數方式

另一種方法是使用 PYTHONPATH 環境變數：

1# 在 shell 中設定
2export PYTHONPATH="${PYTHONPATH}:/path/to/.claude/lib"
3
4# 然後執行腳本
5python .claude/hooks/my_hook.py

專案根目錄的取得

Hook 系統中經常需要取得專案根目錄：

1def get_project_root() -> str:
2    """
3    獲取專案根目錄（git 倉庫根目錄）
4
5    Returns:
6        str: 專案根目錄路徑
7    """
8    success, output = run_git_command(["rev-parse", "--show-toplevel"])
9    return output if success else os.getcwd()

使用範例：

1root = get_project_root()
2config_path = os.path.join(root, ".claude", "config.json")

常見錯誤與解決

錯誤 1: ModuleNotFoundError

1ModuleNotFoundError: No module named 'git_utils'

解決方案：確認 sys.path.insert() 在導入語句之前。

錯誤 2: 相對導入錯誤

1ImportError: attempted relative import with no known parent package

原因：在腳本中使用相對導入。

解決方案：在腳本中使用絕對導入，相對導入只用於套件內部。

1# 錯誤：在腳本中使用相對導入
2from .lib import git_utils
3
4# 正確：使用絕對導入
5from lib import git_utils

錯誤 3: 循環導入

1ImportError: cannot import name 'xxx' from partially initialized module

解決方案：重構程式碼，避免模組間互相依賴。

導入風格指南

導入順序（PEP 8）

 1# 1. 標準庫
 2import os
 3import sys
 4from pathlib import Path
 5
 6# 2. 第三方套件
 7import yaml
 8import requests
 9
10# 3. 本地模組
11from lib.git_utils import get_current_branch
12from lib.hook_io import read_hook_input

避免 `import *`

1# 不推薦
2from lib.git_utils import *
3
4# 推薦
5from lib.git_utils import (
6    get_current_branch,
7    get_project_root,
8    is_protected_branch,
9)

長導入的換行

1from lib.git_utils import (
2    run_git_command,
3    get_current_branch,
4    get_project_root,
5    get_worktree_list,
6    is_protected_branch,
7    is_allowed_branch,
8)

實際範例：完整的 Hook 腳本開頭

 1#!/usr/bin/env python3
 2"""
 3Branch Verify Hook
 4
 5驗證當前分支是否適合進行編輯操作。
 6"""
 7
 8# ===== 標準庫導入 =====
 9import os
10import sys
11from pathlib import Path
12
13# ===== 路徑設定 =====
14# 將 lib 目錄加入搜尋路徑
15sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
16
17# ===== 本地模組導入 =====
18from git_utils import get_current_branch, is_protected_branch
19from hook_io import read_hook_input, write_hook_output, create_pretooluse_output
20from hook_logging import setup_hook_logging
21
22# ===== 初始化 =====
23logger = setup_hook_logging("branch-verify")

思考題

為什麼不把 lib 目錄加入 PYTHONPATH 環境變數，而要在每個腳本中設定 sys.path？
Path(__file__).resolve() 和 Path(__file__) 有什麼區別？
如何驗證一個路徑是否已經在 sys.path 中？

實作練習

寫一個函式，列出 sys.path 中所有存在的目錄
建立一個簡單的模組，然後在另一個檔案中使用兩種不同的方式導入它

上一章：模組與套件組織 下一模組：型別系統

Modules on Tarragon

模組一：Python 基礎概念

章節列表

實際範例來源

預備知識

學習時間

1.2 從單一 script 到多檔案專案

本章目標

章節大綱

1. 單一 script 是合理起點

2. 拆成同層 module

3. 整理成 package

4. 執行方式會影響 import

5. 測試會推動專案結構

6. 何時進入可安裝專案與 src/ layout

後續補寫時的比較提示

本章不處理

和 Python 教材的關係

小結

6.2 如何擴展共用模組

前置知識

共用模組架構

步驟 1：規劃新模組

決定放置位置

設計介面

步驟 2：實作新模組

範例：建立 YAML 工具模組

步驟 3：更新 __init__.py

步驟 4：撰寫測試

步驟 5：更新文件

在模組文檔中說明

擴展現有模組

範例：為 git_utils 添加新功能

設計原則

1. 單一職責

2. 統一的返回值模式

3. 優雅的依賴處理

4. 完整的文檔字串

完整檢查清單

思考題

1.3 模組與套件組織

基本概念

模組（Module）

套件（Package）

__init__.py 的作用

實際範例：Hook 系統的 __init__.py

__init__.py 的三個主要功能

1. 宣告套件身份

2. 定義公開 API

3. 簡化導入路徑

相對導入與絕對導入

相對導入（使用 .）

絕對導入

套件版本管理

模組載入順序

實際範例：Hook 腳本的路徑設定

最佳實踐

1. 避免循環導入

2. 延遲導入

3. 清晰的模組邊界

思考題

實作練習

1.4 導入機制與路徑管理

模組搜尋路徑

Hook 腳本的導入問題

問題情境

解決方案

為什麼用 insert(0, ...) 而不是 append(...)？

使用 Path 物件

Path 的基本操作

路徑解析的陷阱

環境變數方式

專案根目錄的取得

常見錯誤與解決

錯誤 1: ModuleNotFoundError

錯誤 2: 相對導入錯誤

錯誤 3: 循環導入

導入風格指南

導入順序（PEP 8）

避免 import *

6. 何時進入可安裝專案與 `src/` layout

步驟 3：更新 `init.py`

`init.py` 的作用

實際範例：Hook 系統的 `init.py`

`init.py` 的三個主要功能

相對導入（使用 `.`）

為什麼用 `insert(0, ...)` 而不是 `append(...)`？

避免 `import *`