1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7My Custom Hook - 簡短描述
 8
 9Hook Event: SessionStart
10
11這裡寫詳細說明。
12"""
13
14import sys
15from pathlib import Path
16
17# 添加 lib 目錄到路徑
18sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
19
20from hook_logging import setup_hook_logging
21
22def main():
23    """Hook 主函式"""
24    logger = setup_hook_logging("my_custom_hook")
25    logger.info("Hook 開始執行")
26
27    # 你的邏輯在這裡
28
29    logger.info("Hook 執行完成")
30    return 0
31
32if __name__ == "__main__":
33    sys.exit(main())

 1import sys
 2from pathlib import Path
 3
 4# 添加 lib 目錄到路徑
 5sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 6
 7# 現在可以導入共用模組
 8from git_utils import get_current_branch
 9from hook_logging import setup_hook_logging
10from hook_io import read_hook_input, write_hook_output

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7Branch Status Reminder - 分支狀態提醒
 8
 9Hook Event: SessionStart
10"""
11
12import sys
13from pathlib import Path
14
15sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
16
17from git_utils import (
18    get_current_branch,
19    get_project_root,
20    is_protected_branch,
21)
22
23
24def main():
25    print("=" * 60)
26    print("Branch Status Reminder")
27    print("=" * 60)
28
29    current_branch = get_current_branch()
30    if not current_branch:
31        print("警告: 無法獲取分支資訊")
32        return 0
33
34    is_protected = is_protected_branch(current_branch)
35    branch_status = "保護分支" if is_protected else "開發分支"
36
37    print(f"當前分支: {current_branch} ({branch_status})")
38    print(f"工作目錄: {get_project_root()}")
39
40    if is_protected:
41        print()
42        print("警告: 當前在保護分支上")
43        print("建議: 建立 feature 分支後再進行開發")
44
45    print("=" * 60)
46    return 0
47
48
49if __name__ == "__main__":
50    sys.exit(main())

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7Tool Usage Logger - 記錄工具使用情況
 8
 9Hook Event: PostToolUse
10"""
11
12import sys
13from pathlib import Path
14
15sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
16
17from hook_io import read_hook_input, write_hook_output
18from hook_logging import setup_hook_logging
19
20
21def main():
22    logger = setup_hook_logging("tool_usage_logger")
23
24    try:
25        # 讀取 Hook 輸入
26        hook_input = read_hook_input()
27
28        if hook_input is None:
29            write_hook_output(continue_execution=True)
30            return 0
31
32        # 取得工具資訊
33        tool_name = hook_input.get("tool_name", "unknown")
34        tool_input = hook_input.get("tool_input", {})
35
36        # 記錄使用情況
37        logger.info(f"工具使用: {tool_name}")
38        logger.debug(f"輸入參數: {tool_input}")
39
40        # 輸出結果（不阻擋執行）
41        write_hook_output(continue_execution=True)
42
43    except Exception as e:
44        logger.error(f"Hook 執行錯誤: {e}")
45        write_hook_output(continue_execution=True)
46
47    return 0
48
49
50if __name__ == "__main__":
51    sys.exit(main())

 1from git_utils import (
 2    run_git_command,
 3    get_current_branch,
 4    get_project_root,
 5    is_protected_branch,
 6    is_allowed_branch,
 7)
 8
 9# 取得當前分支
10branch = get_current_branch()
11
12# 檢查是否為保護分支
13if is_protected_branch(branch):
14    print("警告：你在保護分支上")
15
16# 執行 git 命令
17success, output = run_git_command(["status", "--short"])
18if success:
19    print(output)

 1from hook_logging import setup_hook_logging
 2
 3# 設定日誌
 4logger = setup_hook_logging("my_hook")
 5
 6# 使用日誌
 7logger.debug("詳細資訊")
 8logger.info("一般資訊")
 9logger.warning("警告訊息")
10logger.error("錯誤訊息")

 1from hook_io import (
 2    read_hook_input,
 3    write_hook_output,
 4    create_pretooluse_output,
 5    create_posttooluse_output,
 6)
 7
 8# 讀取輸入
 9hook_input = read_hook_input()
10
11# 允許繼續執行
12write_hook_output(continue_execution=True)
13
14# 阻擋執行並附帶訊息
15write_hook_output(
16    continue_execution=False,
17    decision="block",
18    reason="不允許此操作"
19)
20
21# PreToolUse 專用輸出
22output = create_pretooluse_output(
23    decision="allow",  # 或 "block", "modify"
24    reason="操作允許"
25)
26print(json.dumps(output))

 1{
 2  "hooks": {
 3    "SessionStart": [
 4      {
 5        "type": "command",
 6        "command": "python .claude/hooks/branch-status-reminder.py",
 7        "event": "SessionStart"
 8      }
 9    ],
10    "PreToolUse": [
11      {
12        "type": "command",
13        "command": "python .claude/hooks/tool-guard.py",
14        "event": "PreToolUse"
15      }
16    ]
17  }
18}

 1# tests/test_my_hook.py
 2"""
 3My Hook 測試
 4"""
 5
 6import unittest
 7from unittest.mock import patch, MagicMock
 8import sys
 9from pathlib import Path
10
11# 添加 hooks 目錄到路徑
12sys.path.insert(0, str(Path(__file__).parent.parent / ".claude" / "hooks"))
13
14
15class TestMyHook(unittest.TestCase):
16    """測試 My Hook"""
17
18    @patch("my_hook.get_current_branch")
19    def test_protected_branch_warning(self, mock_branch):
20        """測試保護分支警告"""
21        mock_branch.return_value = "main"
22
23        # 導入並測試
24        from my_hook import check_branch_status
25
26        result = check_branch_status()
27        self.assertTrue(result["is_protected"])
28
29    @patch("my_hook.read_hook_input")
30    def test_empty_input_handling(self, mock_input):
31        """測試空輸入處理"""
32        mock_input.return_value = None
33
34        from my_hook import main
35
36        # 應該正常退出，不拋出異常
37        result = main()
38        self.assertEqual(result, 0)
39
40
41if __name__ == "__main__":
42    unittest.main()

 1#!/usr/bin/env -S uv run --quiet --script
 2# /// script
 3# requires-python = ">=3.10"
 4# dependencies = []
 5# ///
 6"""
 7File Type Permission Hook - 檔案類型權限檢查
 8
 9阻止對特定類型檔案的危險操作。
10
11Hook Event: PreToolUse
12"""
13
14import sys
15from pathlib import Path
16
17sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
18
19from hook_io import read_hook_input, create_pretooluse_output
20from hook_logging import setup_hook_logging
21import json
22
23
24# 配置：受保護的檔案模式
25PROTECTED_PATTERNS = [
26    "*.env",
27    "*.pem",
28    "*.key",
29    "*credentials*",
30]
31
32# 需要檢查的工具
33MONITORED_TOOLS = ["Write", "Edit", "Bash"]
34
35
36def main():
37    logger = setup_hook_logging("file_type_permission")
38
39    try:
40        hook_input = read_hook_input()
41
42        if hook_input is None:
43            print(json.dumps(create_pretooluse_output("allow")))
44            return 0
45
46        tool_name = hook_input.get("tool_name", "")
47        tool_input = hook_input.get("tool_input", {})
48
49        # 只檢查特定工具
50        if tool_name not in MONITORED_TOOLS:
51            print(json.dumps(create_pretooluse_output("allow")))
52            return 0
53
54        # 取得檔案路徑
55        file_path = tool_input.get("file_path") or tool_input.get("command", "")
56
57        # 檢查是否為受保護的檔案
58        if is_protected_file(file_path):
59            logger.warning(f"阻擋對受保護檔案的操作: {file_path}")
60            output = create_pretooluse_output(
61                decision="block",
62                reason=f"此檔案受保護，不允許直接操作: {file_path}"
63            )
64        else:
65            output = create_pretooluse_output("allow")
66
67        print(json.dumps(output))
68
69    except Exception as e:
70        logger.error(f"Hook 錯誤: {e}")
71        print(json.dumps(create_pretooluse_output("allow")))
72
73    return 0
74
75
76def is_protected_file(file_path: str) -> bool:
77    """檢查檔案是否受保護"""
78    if not file_path:
79        return False
80
81    path = Path(file_path)
82
83    for pattern in PROTECTED_PATTERNS:
84        if path.match(pattern):
85            return True
86
87    return False
88
89
90if __name__ == "__main__":
91    sys.exit(main())

 1def main():
 2    try:
 3        # 你的邏輯
 4        pass
 5    except Exception as e:
 6        logger.error(f"Error: {e}")
 7        # 允許繼續執行，不阻擋系統
 8        write_hook_output(continue_execution=True)
 9
10    return 0  # 總是返回 0

1logger = setup_hook_logging("my_hook", level=logging.DEBUG)
2logger.debug(f"輸入資料: {hook_input}")

1tail -f .claude/hook-logs/my_hook.log

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# 思考要提供什麼功能給使用者
 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

  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

 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"  # 更新版本

  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()

 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"""

 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())

 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# 好：專注於 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(): ...

 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

 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    # ...

 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    """

 1# parsers/base.py
 2from abc import ABC, abstractmethod
 3from typing import Optional
 4
 5class BaseParser(ABC):
 6    """解析器抽象基類"""
 7
 8    def __init__(self, encoding: str = "utf-8"):
 9        self.encoding = encoding
10
11    @abstractmethod
12    def parse(self, content: str) -> dict:
13        """
14        解析內容
15
16        Args:
17            content: 要解析的字串
18
19        Returns:
20            dict: 解析後的字典
21
22        Raises:
23            ParseError: 解析失敗時拋出
24        """
25        pass
26
27    @abstractmethod
28    def validate(self, content: str) -> bool:
29        """
30        驗證內容格式是否正確
31
32        Args:
33            content: 要驗證的字串
34
35        Returns:
36            bool: 格式正確返回 True
37        """
38        pass
39
40    @property
41    @abstractmethod
42    def file_extensions(self) -> list[str]:
43        """支援的檔案副檔名列表"""
44        pass
45
46    # 共用方法（不是抽象的）
47    def parse_file(self, path: str) -> dict:
48        """解析檔案"""
49        from pathlib import Path
50        content = Path(path).read_text(encoding=self.encoding)
51        return self.parse(content)

 1# parsers/toml_parser.py
 2"""
 3TOML 解析器
 4
 5支援 TOML 格式的配置檔案解析。
 6"""
 7
 8from typing import Optional
 9from .base import BaseParser
10
11# 嘗試導入 toml 模組
12try:
13    import tomllib  # Python 3.11+ 內建
14except ImportError:
15    try:
16        import toml as tomllib  # 第三方套件
17    except ImportError:
18        tomllib = None
19
20class TomlParser(BaseParser):
21    """
22    TOML 格式解析器
23
24    支援 .toml 檔案的解析。
25
26    Example:
27        parser = TomlParser()
28        config = parser.parse_file("config.toml")
29    """
30
31    def __init__(self, encoding: str = "utf-8"):
32        """
33        初始化 TOML 解析器
34
35        Args:
36            encoding: 檔案編碼
37
38        Raises:
39            ImportError: 如果 toml 模組不可用
40        """
41        if tomllib is None:
42            raise ImportError(
43                "TOML parser requires 'tomllib' (Python 3.11+) "
44                "or 'toml' package. Install with: pip install toml"
45            )
46        super().__init__(encoding)
47
48    def parse(self, content: str) -> dict:
49        """
50        解析 TOML 內容
51
52        Args:
53            content: TOML 格式的字串
54
55        Returns:
56            dict: 解析後的字典
57
58        Raises:
59            ValueError: 如果 TOML 格式錯誤
60        """
61        try:
62            # Python 3.11+ 的 tomllib 需要 bytes
63            if hasattr(tomllib, 'loads'):
64                return tomllib.loads(content)
65            else:
66                # tomllib (3.11+) 只接受 bytes
67                return tomllib.load(content.encode(self.encoding))
68        except Exception as e:
69            raise ValueError(f"Failed to parse TOML: {e}") from e
70
71    def validate(self, content: str) -> bool:
72        """
73        驗證 TOML 格式
74
75        Args:
76            content: 要驗證的字串
77
78        Returns:
79            bool: 格式正確返回 True
80        """
81        try:
82            self.parse(content)
83            return True
84        except ValueError:
85            return False
86
87    @property
88    def file_extensions(self) -> list[str]:
89        """支援的副檔名"""
90        return [".toml"]

 1# parsers/__init__.py
 2"""
 3解析器模組
 4
 5提供多種格式的檔案解析功能。
 6"""
 7
 8from .base import BaseParser
 9from .factory import ParserFactory
10from .json_parser import JsonParser
11from .yaml_parser import YamlParser
12
13# 註冊內建解析器
14ParserFactory.register("json", [".json"])(JsonParser)
15ParserFactory.register("yaml", [".yaml", ".yml"])(YamlParser)
16
17# 嘗試註冊 TOML 解析器（可選依賴）
18try:
19    from .toml_parser import TomlParser
20    ParserFactory.register("toml", [".toml"])(TomlParser)
21except ImportError:
22    pass  # TOML 支援不可用
23
24__all__ = [
25    "BaseParser",
26    "ParserFactory",
27    "JsonParser",
28    "YamlParser",
29]

1# parsers/toml_parser.py
2from .factory import ParserFactory
3from .base import BaseParser
4
5@ParserFactory.register("toml", [".toml"])
6class TomlParser(BaseParser):
7    """TOML 解析器"""
8    # ... 實作 ...

 1# tests/test_toml_parser.py
 2"""
 3TOML 解析器測試
 4"""
 5
 6import unittest
 7from unittest.mock import patch
 8
 9# 跳過測試如果 toml 不可用
10try:
11    from parsers.toml_parser import TomlParser
12    HAS_TOML = True
13except ImportError:
14    HAS_TOML = False
15
16@unittest.skipUnless(HAS_TOML, "TOML support not available")
17class TestTomlParser(unittest.TestCase):
18    """測試 TomlParser 類別"""
19
20    def setUp(self):
21        """測試前準備"""
22        self.parser = TomlParser()
23
24    def test_parse_simple_toml(self):
25        """測試解析簡單的 TOML"""
26        content = """
27        [server]
28        host = "localhost"
29        port = 8080
30        """
31        result = self.parser.parse(content)
32
33        self.assertEqual(result["server"]["host"], "localhost")
34        self.assertEqual(result["server"]["port"], 8080)
35
36    def test_parse_nested_toml(self):
37        """測試解析巢狀的 TOML"""
38        content = """
39        [database]
40        host = "localhost"
41
42        [database.connection]
43        timeout = 30
44        retries = 3
45        """
46        result = self.parser.parse(content)
47
48        self.assertEqual(result["database"]["host"], "localhost")
49        self.assertEqual(result["database"]["connection"]["timeout"], 30)
50
51    def test_validate_valid_toml(self):
52        """測試驗證有效的 TOML"""
53        content = '[section]\nkey = "value"'
54        self.assertTrue(self.parser.validate(content))
55
56    def test_validate_invalid_toml(self):
57        """測試驗證無效的 TOML"""
58        content = "this is not valid TOML ["
59        self.assertFalse(self.parser.validate(content))
60
61    def test_parse_invalid_raises_error(self):
62        """測試解析無效 TOML 時拋出錯誤"""
63        content = "invalid [ toml"
64        with self.assertRaises(ValueError):
65            self.parser.parse(content)
66
67    def test_file_extensions(self):
68        """測試檔案副檔名"""
69        self.assertIn(".toml", self.parser.file_extensions)
70
71@unittest.skipUnless(HAS_TOML, "TOML support not available")
72class TestTomlParserFactory(unittest.TestCase):
73    """測試 TOML 解析器與工廠的整合"""
74
75    def test_factory_creates_toml_parser(self):
76        """測試工廠可以建立 TOML 解析器"""
77        from parsers import ParserFactory
78
79        parser = ParserFactory.create("toml")
80        self.assertIsInstance(parser, TomlParser)
81
82    def test_factory_creates_from_file(self):
83        """測試工廠根據副檔名建立解析器"""
84        from parsers import ParserFactory
85
86        parser = ParserFactory.create_from_file("config.toml")
87        self.assertIsInstance(parser, TomlParser)
88
89if __name__ == "__main__":
90    unittest.main()

 1## 支援的配置格式
 2
 3- JSON (.json) - 內建支援
 4- YAML (.yaml, .yml) - 需要 PyYAML
 5- TOML (.toml) - 需要 Python 3.11+ 或 toml 套件
 6
 7### 安裝 TOML 支援
 8
 9```bash
10# Python 3.11+ 內建支援
11# 或安裝第三方套件
12pip install toml
13```

1from parsers import ParserFactory
2
3# 自動選擇解析器
4parser = ParserFactory.create_from_file("config.toml")
5config = parser.parse_file("config.toml")

 1
 2## 完整檢查清單
 3
 4新增解析器時的檢查項目：
 5
 6- [ ] 繼承 `BaseParser`
 7- [ ] 實作所有 `@abstractmethod`
 8  - [ ] `parse(content: str) -> dict`
 9  - [ ] `validate(content: str) -> bool`
10  - [ ] `file_extensions` 屬性
11- [ ] 處理可選依賴
12- [ ] 註冊到 `ParserFactory`
13- [ ] 撰寫單元測試
14  - [ ] 正常解析
15  - [ ] 錯誤處理
16  - [ ] 驗證功能
17  - [ ] 工廠整合
18- [ ] 更新文件
19- [ ] 更新 `__all__` 匯出
20
21## 常見問題
22
23### Q: 如果依賴套件不可用怎麼辦？
24
25在 `__init__` 中檢查並提供清楚的錯誤訊息：
26
27```python
28def __init__(self):
29    if required_module is None:
30        raise ImportError(
31            "TomlParser requires 'toml' package. "
32            "Install with: pip install toml"
33        )

1try:
2    import tomllib  # Python 3.11+
3    def parse_toml(content: str) -> dict:
4        return tomllib.loads(content)
5except ImportError:
6    import toml
7    def parse_toml(content: str) -> dict:
8        return toml.loads(content)

1try:
2    return toml.loads(content)
3except toml.TomlDecodeError as e:
4    raise ValueError(f"Invalid TOML: {e}") from e