Imports 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.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 中所有存在的目錄
建立一個簡單的模組，然後在另一個檔案中使用兩種不同的方式導入它

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

Imports on Tarragon

模組一：Python 基礎概念

章節列表

實際範例來源

預備知識

學習時間

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 *

長導入的換行

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

思考題

實作練習

`init.py` 的作用

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

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

相對導入（使用 `.`）

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

避免 `import *`