模組一：Python 基礎概念 on Tarragon

1.1 Python 哲學與設計理念

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

在學習任何程式語言之前，了解其設計理念能幫助你寫出更符合語言風格的程式碼。Python 有一套廣為人知的設計原則，被稱為「Python 之禪」。

Python 之禪

在 Python 直譯器中輸入 import this，你會看到 Python 的設計原則：

 1>>> import this
 2The Zen of Python, by Tim Peters
 3
 4Beautiful is better than ugly.
 5Explicit is better than implicit.
 6Simple is better than complex.
 7Complex is better than complicated.
 8Flat is better than nested.
 9Sparse is better than dense.
10Readability counts.
11...

實踐中的 Python 哲學

顯式優於隱式（Explicit is better than implicit）

在 Hook 系統中，我們明確導入需要的函式，而不是使用 import *：

1# 好的做法：明確導入
2from lib.hook_io import read_hook_input, write_hook_output
3from lib.git_utils import get_current_branch
4
5# 不好的做法：隱式導入所有
6from lib.hook_io import * # 不知道導入了什麼

可讀性很重要（Readability counts）

函式和變數命名要清楚表達用途：

 1# 好的命名：一看就懂
 2def get_current_branch() -> Optional[str]:
 3 """獲取當前分支名稱"""
 4 success, output = run_git_command(["branch", "--show-current"])
 5 return output if success and output else None
 6
 7# 不好的命名：需要猜測
 8def gcb():
 9 s, o = rgc(["branch", "--show-current"])
10 return o if s and o else None

簡單優於複雜（Simple is better than complex）

Hook 系統使用簡單的 (bool, str) 返回值模式：

 1def run_git_command(args: list[str]) -> tuple[bool, str]:
 2 """
 3 執行 git 命令並返回結果
 4
 5 Returns:
 6 tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
 7 """
 8 try:
 9 result = subprocess.run(
10 ["git"] + args,
11 capture_output=True,
12 text=True,
13 )
14 if result.returncode == 0:
15 return True, result.stdout.strip()
16 else:
17 return False, result.stderr.strip()
18 except Exception as e:
19 return False, str(e)

這個設計比拋出異常更直觀，呼叫者可以用簡單的 if 來處理：

1success, output = run_git_command(["status"])
2if success:
3 print(output)
4else:
5 print(f"Error: {output}")

扁平優於巢狀（Flat is better than nested）

避免過深的巢狀結構：

 1# 不好：過深的巢狀
 2def check_file(path):
 3 if path:
 4 if path.exists():
 5 if path.suffix == '.py':
 6 if path.stat().st_size > 0:
 7 return True
 8 return False
 9
10# 好：使用 early return
11def check_file(path):
12 if not path:
13 return False
14 if not path.exists():
15 return False
16 if path.suffix != '.py':
17 return False
18 if path.stat().st_size <= 0:
19 return False
20 return True

「Pythonic」的含義

當我們說程式碼是「Pythonic」時，意思是它遵循 Python 的慣例和風格。以下是一些例子：

使用 List Comprehension

1# Pythonic
2squares = [x**2 for x in range(10)]
3
4# 非 Pythonic
5squares = []
6for x in range(10):
7 squares.append(x**2)

使用上下文管理器

1# Pythonic
2with open(file_path, "r", encoding="utf-8") as f:
3 content = f.read()
4
5# 非 Pythonic
6f = open(file_path, "r", encoding="utf-8")
7content = f.read()
8f.close() # 容易忘記關閉

使用 enumerate 而非 range(len())

1# Pythonic
2for i, item in enumerate(items):
3 print(f"{i}: {item}")
4
5# 非 Pythonic
6for i in range(len(items)):
7 print(f"{i}: {items[i]}")

實際範例：Hook 系統的設計體現

來自 .claude/lib/hook_io.py 的設計展示了這些原則：

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 邊界與測試方式逐步穩定。

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

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

模組一：Python 基礎概念 on Tarragon

1.1 Python 哲學與設計理念

Python 之禪

實踐中的 Python 哲學

顯式優於隱式（Explicit is better than implicit）

可讀性很重要（Readability counts）

簡單優於複雜（Simple is better than complex）

扁平優於巢狀（Flat is better than nested）

「Pythonic」的含義

使用 List Comprehension

使用上下文管理器

使用 enumerate 而非 range(len())

實際範例：Hook 系統的設計體現

1.2 從單一 script 到多檔案專案

本章目標

章節大綱

1. 單一 script 是合理起點

2. 拆成同層 module

3. 整理成 package

4. 執行方式會影響 import

5. 測試會推動專案結構

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

後續補寫時的比較提示

本章不處理

和 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 腳本開頭

思考題

實作練習

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

`init.py` 的作用

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

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

相對導入（使用 `.`）

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

避免 `import *`