1import os
 2
 3# 組合路徑
 4config_path = os.path.join(project_root, ".claude", "config.json")
 5
 6# 取得父目錄
 7parent = os.path.dirname(file_path)
 8
 9# 取得檔名
10filename = os.path.basename(file_path)
11
12# 檢查存在
13if os.path.exists(config_path):
14    ...

 1from pathlib import Path
 2
 3# 組合路徑
 4config_path = project_root / ".claude" / "config.json"
 5
 6# 取得父目錄
 7parent = file_path.parent
 8
 9# 取得檔名
10filename = file_path.name
11
12# 檢查存在
13if config_path.exists():
14    ...

 1from pathlib import Path
 2
 3# 從字串建立
 4p = Path("/home/user/project")
 5
 6# 當前目錄
 7cwd = Path.cwd()
 8
 9# 使用者目錄
10home = Path.home()
11
12# 從 __file__ 建立
13current_file = Path(__file__)

1from pathlib import Path
2
3project = Path("/home/user/project")
4config = project / ".claude" / "config.json"
5
6# 等同於
7config = project.joinpath(".claude", "config.json")

1p = Path("/home/user/project/file.txt")
2
3p.name        # "file.txt"
4p.stem        # "file"（不含副檔名）
5p.suffix      # ".txt"
6p.parent      # Path("/home/user/project")
7p.parents[0]  # Path("/home/user/project")
8p.parents[1]  # Path("/home/user")
9p.parts       # ('/', 'home', 'user', 'project', 'file.txt')

 1from pathlib import Path
 2
 3def setup_hook_logging(hook_name: str) -> logging.Logger:
 4    # 建立日誌目錄
 5    project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 6    log_dir = Path(project_root) / ".claude" / "hook-logs" / hook_name
 7
 8    # mkdir 的 parents=True 會建立所有不存在的父目錄
 9    # exist_ok=True 表示如果目錄已存在不會報錯
10    log_dir.mkdir(parents=True, exist_ok=True)
11
12    # 日誌檔案路徑
13    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
14    log_file = log_dir / f"{hook_name}-{timestamp}.log"
15
16    # ...

 1def load_config(config_name: str) -> dict:
 2    config_dir = get_config_dir()
 3
 4    # 優先嘗試不同副檔名
 5    yaml_path = config_dir / f"{config_name}.yaml"
 6    yml_path = config_dir / f"{config_name}.yml"
 7    json_path = config_dir / f"{config_name}.json"
 8
 9    if yaml_path.exists():
10        return _load_yaml_file(yaml_path)
11    elif yml_path.exists():
12        return _load_yaml_file(yml_path)
13    elif json_path.exists():
14        return _load_json_file(json_path)
15
16    raise FileNotFoundError(f"Configuration not found: {config_name}")

1from pathlib import Path
2
3p = Path("config.json")
4
5# 讀取文字
6content = p.read_text(encoding="utf-8")
7
8# 讀取位元組
9data = p.read_bytes()

1from pathlib import Path
2
3p = Path("output.txt")
4
5# 寫入文字
6p.write_text("Hello, World!", encoding="utf-8")
7
8# 寫入位元組
9p.write_bytes(b"binary data")

1p = Path("/some/path")
2
3p.exists()      # 是否存在
4p.is_file()     # 是否為檔案
5p.is_dir()      # 是否為目錄
6p.is_symlink()  # 是否為符號連結

1from pathlib import Path
2
3p = Path("new_dir/sub_dir")
4
5# 建立目錄（包含父目錄）
6p.mkdir(parents=True, exist_ok=True)

 1from pathlib import Path
 2
 3p = Path(".")
 4
 5# 列出所有項目
 6for item in p.iterdir():
 7    print(item)
 8
 9# 使用 glob 模式
10for py_file in p.glob("*.py"):
11    print(py_file)
12
13# 遞迴搜尋
14for md_file in p.rglob("*.md"):
15    print(md_file)

 1def validate_all_hooks(self, hooks_dir: Optional[str] = None):
 2    if hooks_dir is None:
 3        hooks_dir = str(self.project_root / ".claude" / "hooks")
 4
 5    hooks_dir = self._resolve_path(hooks_dir)
 6
 7    # 找出所有 .py 檔案
 8    results = []
 9    for hook_file in sorted(hooks_dir.glob("*.py")):
10        if hook_file.name.startswith("_"):
11            continue  # 跳過 __init__.py 等
12        results.append(self.validate_hook(str(hook_file)))
13
14    return results

1from pathlib import Path
2
3p = Path("./relative/path")
4
5# 轉換為絕對路徑
6absolute = p.resolve()
7
8# 相對於某個目錄
9relative = p.relative_to(Path.cwd())

1def _resolve_path(self, path: str) -> Path:
2    """解析路徑為絕對路徑"""
3    p = Path(path)
4    if p.is_absolute():
5        return p
6    return self.project_root / p

1# 在 .claude/hooks/my_hook.py 中
2from pathlib import Path
3
4# 取得 lib 目錄
5lib_path = Path(__file__).parent.parent / "lib"
6# __file__ = .claude/hooks/my_hook.py
7# parent = .claude/hooks/
8# parent.parent = .claude/
9# / "lib" = .claude/lib/

1def ensure_extension(path: Path, ext: str) -> Path:
2    """確保檔案有指定的副檔名"""
3    if path.suffix != ext:
4        return path.with_suffix(ext)
5    return path
6
7# 使用
8p = Path("config")
9p = ensure_extension(p, ".json")  # Path("config.json")

1def safe_read_file(path: Path) -> Optional[str]:
2    """安全讀取檔案，不存在時返回 None"""
3    if not path.exists():
4        return None
5    try:
6        return path.read_text(encoding="utf-8")
7    except Exception:
8        return None

 1import json
 2
 3# 字典轉 JSON 字串
 4data = {"name": "Python", "version": 3.11}
 5json_str = json.dumps(data)
 6# '{"name": "Python", "version": 3.11}'
 7
 8# 格式化輸出
 9json_str = json.dumps(data, indent=2)
10# {
11#   "name": "Python",
12#   "version": 3.11
13# }

1import json
2
3json_str = '{"name": "Python", "version": 3.11}'
4data = json.loads(json_str)
5# {'name': 'Python', 'version': 3.11}

1import json
2
3# 寫入檔案
4with open("config.json", "w", encoding="utf-8") as f:
5    json.dump(data, f, indent=2)
6
7# 讀取檔案
8with open("config.json", "r", encoding="utf-8") as f:
9    data = json.load(f)

 1import json
 2import sys
 3
 4def read_hook_input() -> dict:
 5    """
 6    從 stdin 讀取 Hook 輸入
 7
 8    Returns:
 9        dict: 解析後的 JSON 資料，解析失敗時返回空字典
10    """
11    try:
12        return json.load(sys.stdin)
13    except json.JSONDecodeError:
14        return {}
15    except Exception:
16        return {}

 1def write_hook_output(
 2    output: dict,
 3    ensure_ascii: bool = False,
 4    indent: int = 2
 5) -> None:
 6    """
 7    輸出 Hook 結果到 stdout
 8
 9    Args:
10        output: 要輸出的字典
11        ensure_ascii: 是否確保 ASCII 編碼
12        indent: JSON 縮排空格數
13    """
14    print(json.dumps(output, ensure_ascii=ensure_ascii, indent=indent))

 1import json
 2
 3data = {"message": "你好"}
 4
 5# ensure_ascii=True（預設）
 6json.dumps(data)
 7# '{"message": "\\u4f60\\u597d"}'
 8
 9# ensure_ascii=False（保留原字元）
10json.dumps(data, ensure_ascii=False)
11# '{"message": "你好"}'

 1data = {"name": "Python", "features": ["simple", "readable"]}
 2
 3# 無縮排
 4json.dumps(data)
 5# '{"name": "Python", "features": ["simple", "readable"]}'
 6
 7# 有縮排
 8json.dumps(data, indent=2)
 9# {
10#   "name": "Python",
11#   "features": [
12#     "simple",
13#     "readable"
14#   ]
15# }

1data = {"z": 1, "a": 2, "m": 3}
2
3json.dumps(data, sort_keys=True)
4# '{"a": 2, "m": 3, "z": 1}'

 1from datetime import datetime
 2import json
 3
 4def json_serializer(obj):
 5    if isinstance(obj, datetime):
 6        return obj.isoformat()
 7    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
 8
 9data = {"timestamp": datetime.now()}
10json.dumps(data, default=json_serializer)
11# '{"timestamp": "2024-01-20T15:30:00"}'

1import json
2
3def safe_parse_json(json_str: str) -> dict:
4    """安全解析 JSON，失敗時返回空字典"""
5    try:
6        return json.loads(json_str)
7    except json.JSONDecodeError as e:
8        print(f"JSON 解析錯誤: {e}")
9        return {}

 1import json
 2from dataclasses import dataclass, asdict
 3
 4@dataclass
 5class Config:
 6    name: str
 7    timeout: int
 8
 9config = Config("test", 30)
10
11# 錯誤：dataclass 無法直接序列化
12# json.dumps(config)  # TypeError
13
14# 正確：轉換為字典
15json.dumps(asdict(config))
16# '{"name": "test", "timeout": 30}'

1def _load_json_file(file_path: Path) -> dict:
2    """載入 JSON 檔案"""
3    import json
4    with open(file_path, "r", encoding="utf-8") as f:
5        return json.load(f)

 1# 嘗試導入 PyYAML，如果失敗則使用 JSON 作為備案
 2try:
 3    import yaml
 4    HAS_YAML = True
 5except ImportError:
 6    HAS_YAML = False
 7    import json
 8
 9def load_config(config_name: str) -> dict:
10    if yaml_path.exists() and HAS_YAML:
11        return _load_yaml_file(yaml_path)
12    elif json_path.exists():
13        return _load_json_file(json_path)

1# 好
2with open("data.json", "w", encoding="utf-8") as f:
3    json.dump(data, f)
4
5# 不好（可能在不同系統有不同行為）
6with open("data.json", "w") as f:
7    json.dump(data, f)

1def read_config(path: str) -> dict:
2    try:
3        with open(path, "r", encoding="utf-8") as f:
4            return json.load(f)
5    except FileNotFoundError:
6        return {}
7    except json.JSONDecodeError:
8        return {}

1# 輸出中文友好的 JSON
2json.dumps(data, ensure_ascii=False, indent=2)

 1import subprocess
 2
 3# 基本執行
 4result = subprocess.run(["ls", "-la"])
 5
 6# 捕獲輸出
 7result = subprocess.run(
 8    ["ls", "-la"],
 9    capture_output=True,
10    text=True
11)
12print(result.stdout)  # 標準輸出
13print(result.stderr)  # 錯誤輸出
14print(result.returncode)  # 返回碼

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

 1# 取得當前分支
 2success, output = run_git_command(["branch", "--show-current"])
 3if success:
 4    print(f"Current branch: {output}")
 5
 6# 取得專案根目錄
 7success, output = run_git_command(["rev-parse", "--show-toplevel"])
 8
 9# 取得 worktree 列表
10success, output = run_git_command(["worktree", "list", "--porcelain"])

 1# 捕獲輸出
 2result = subprocess.run(
 3    ["git", "status"],
 4    capture_output=True,  # 等同於 stdout=PIPE, stderr=PIPE
 5    text=True
 6)
 7
 8# 等價寫法
 9result = subprocess.run(
10    ["git", "status"],
11    stdout=subprocess.PIPE,
12    stderr=subprocess.PIPE,
13    text=True
14)

1# text=False（預設）
2result = subprocess.run(["echo", "hello"], capture_output=True)
3print(result.stdout)  # b'hello\n'（bytes）
4
5# text=True
6result = subprocess.run(["echo", "hello"], capture_output=True, text=True)
7print(result.stdout)  # 'hello\n'（str）

1result = subprocess.run(
2    ["git", "status"],
3    cwd="/path/to/repo",
4    capture_output=True,
5    text=True
6)

1try:
2    result = subprocess.run(
3        ["long_running_command"],
4        timeout=10,
5        capture_output=True
6    )
7except subprocess.TimeoutExpired:
8    print("Command timed out!")

 1try:
 2    # 如果返回碼非零，拋出 CalledProcessError
 3    result = subprocess.run(
 4        ["git", "status"],
 5        check=True,
 6        capture_output=True,
 7        text=True
 8    )
 9except subprocess.CalledProcessError as e:
10    print(f"Command failed with return code {e.returncode}")
11    print(f"Error output: {e.stderr}")

 1import subprocess
 2
 3def safe_run_command(args: list[str]) -> tuple[bool, str]:
 4    try:
 5        result = subprocess.run(
 6            args,
 7            capture_output=True,
 8            text=True,
 9            timeout=30
10        )
11        if result.returncode == 0:
12            return True, result.stdout.strip()
13        return False, result.stderr.strip()
14
15    except subprocess.TimeoutExpired:
16        return False, "Command timed out"
17
18    except FileNotFoundError:
19        return False, f"Command not found: {args[0]}"
20
21    except PermissionError:
22        return False, f"Permission denied: {args[0]}"
23
24    except Exception as e:
25        return False, str(e)

1# 危險：使用者輸入可能導致命令注入
2user_input = "file.txt; rm -rf /"
3subprocess.run(f"cat {user_input}", shell=True)  # 危險！
4
5# 安全：使用列表傳遞參數
6subprocess.run(["cat", user_input])  # 安全

1def run_git_command(args: list[str]) -> tuple[bool, str]:
2    # 驗證第一個參數是否為有效的 git 子命令
3    valid_commands = ["status", "branch", "log", "diff", "rev-parse"]
4    if args and args[0] not in valid_commands:
5        return False, f"Invalid git command: {args[0]}"
6    # ...

 1# 模擬 "ls -la | grep .py"
 2ls_process = subprocess.run(
 3    ["ls", "-la"],
 4    capture_output=True,
 5    text=True
 6)
 7
 8grep_process = subprocess.run(
 9    ["grep", ".py"],
10    input=ls_process.stdout,
11    capture_output=True,
12    text=True
13)

 1import os
 2
 3# 自訂環境變數
 4env = os.environ.copy()
 5env["MY_VAR"] = "value"
 6
 7result = subprocess.run(
 8    ["my_script.sh"],
 9    env=env,
10    capture_output=True
11)

 1def get_current_branch() -> Optional[str]:
 2    """獲取當前分支名稱"""
 3    success, output = run_git_command(["branch", "--show-current"])
 4    return output if success and output else None
 5
 6def get_project_root() -> str:
 7    """獲取專案根目錄"""
 8    success, output = run_git_command(["rev-parse", "--show-toplevel"])
 9    return output if success else os.getcwd()
10
11def get_worktree_list() -> list[dict]:
12    """獲取所有 worktree 列表"""
13    success, output = run_git_command(["worktree", "list", "--porcelain"])
14    if not success:
15        return []
16
17    worktrees = []
18    current_worktree = {}
19
20    for line in output.split("\n"):
21        if line.startswith("worktree "):
22            if current_worktree:
23                worktrees.append(current_worktree)
24            current_worktree = {"path": line[9:]}  # 移除 "worktree " 前綴
25        elif line.startswith("branch "):
26            branch_ref = line[7:]  # 移除 "branch " 前綴
27            if branch_ref.startswith("refs/heads/"):
28                branch_ref = branch_ref[11:]
29            current_worktree["branch"] = branch_ref
30
31    if current_worktree:
32        worktrees.append(current_worktree)
33
34    return worktrees

1# 好
2subprocess.run(["git", "commit", "-m", "Fix bug"])
3
4# 不好
5subprocess.run("git commit -m 'Fix bug'", shell=True)

1# 為長時間運行的命令設定超時
2subprocess.run(["long_task"], timeout=300)  # 5 分鐘

 1def robust_run(args):
 2    try:
 3        result = subprocess.run(args, ...)
 4        return True, result.stdout
 5    except subprocess.TimeoutExpired:
 6        return False, "Timeout"
 7    except FileNotFoundError:
 8        return False, "Command not found"
 9    except Exception as e:
10        return False, str(e)

1import re
2
3text = "Hello, Python 3.11!"
4
5# 搜尋數字
6match = re.search(r'\d+\.\d+', text)
7if match:
8    print(match.group())  # "3.11"

1import re
2
3text = "Python is great"
4
5# 只從字串開頭匹配
6match = re.match(r'Python', text)  # 成功
7match = re.match(r'great', text)   # None（不是從開頭開始）

1import re
2
3text = "Call 123-456-7890 or 098-765-4321"
4
5# 找出所有電話號碼
6phones = re.findall(r'\d{3}-\d{3}-\d{4}', text)
7# ['123-456-7890', '098-765-4321']

1import re
2
3text = "Hello   World"
4
5# 將多個空格替換為單個
6result = re.sub(r'\s+', ' ', text)
7# "Hello World"

1import re
2
3text = "[Link Text](https://example.com)"
4
5# 使用群組擷取
6match = re.search(r'\[([^\]]+)\]\(([^)]+)\)', text)
7if match:
8    link_text = match.group(1)  # "Link Text"
9    link_url = match.group(2)   # "https://example.com"

 1import re
 2
 3class MarkdownLinkChecker:
 4    # Markdown 連結正則表達式
 5    # 匹配 [text](/python/03-stdlib/regex/target) 格式，排除圖片 ![alt](/python/03-stdlib/regex/src)
 6    INLINE_LINK_PATTERN = re.compile(
 7        r'(?<!!)\[([^\]]+)\]\(([^)]+)\)'
 8    )
 9
10    # 引用式連結定義 [ref]: target
11    REFERENCE_DEF_PATTERN = re.compile(
12        r'^\s*\[([^\]]+)\]:\s*(.+)$',
13        re.MULTILINE
14    )
15
16    # 引用式連結使用 [text][ref]
17    REFERENCE_USE_PATTERN = re.compile(
18        r'\[([^\]]+)\]\[([^\]]+)\]'
19    )

 1def parse_markdown_links(self, content: str) -> list[dict]:
 2    """解析 Markdown 內容中的所有連結"""
 3    links = []
 4    lines = content.split('\n')
 5
 6    for line_num, line in enumerate(lines, start=1):
 7        # 行內連結 [text](/python/03-stdlib/regex/target)
 8        for match in self.INLINE_LINK_PATTERN.finditer(line):
 9            links.append({
10                "text": match.group(1),
11                "target": match.group(2),
12                "line": line_num
13            })
14
15    return links

1import re
2
3# 編譯模式
4pattern = re.compile(r'\d+')
5
6# 重複使用
7pattern.search(text1)
8pattern.findall(text2)
9pattern.sub('X', text3)

 1class HookValidator:
 2    # 共用模組導入模式
 3    HOOK_IO_PATTERNS = [
 4        r"from\s+hook_io\s+import",
 5        r"from\s+lib\.hook_io\s+import",
 6    ]
 7
 8    # 命名規範模式
 9    VALID_NAME_PATTERNS = [
10        r"^[a-z0-9](/python/03-stdlib/regex/[a-z0-9\-_]*[a-z0-9])?\.py$",
11    ]
12
13    def _has_import(self, content: str, patterns: list[str]) -> bool:
14        """檢查是否有符合任一模式的導入"""
15        return any(
16            re.search(pattern, content)
17            for pattern in patterns
18        )
19
20    def check_naming_convention(self, hook_path: Path) -> list:
21        """檢查命名規範"""
22        filename = hook_path.name
23
24        valid_name = any(
25            re.match(pattern, filename)
26            for pattern in self.VALID_NAME_PATTERNS
27        )
28        # ...

1import re
2
3re.search(r'hello', 'Hello World', re.IGNORECASE)  # 匹配

1import re
2
3text = """line 1
4line 2
5line 3"""
6
7# 每行開頭的 "line"
8matches = re.findall(r'^line', text, re.MULTILINE)
9# ['line', 'line', 'line']

1import re
2
3text = "start\nmiddle\nend"
4
5# 無 DOTALL：. 不匹配換行
6re.search(r'start.*end', text)  # None
7
8# 有 DOTALL：. 匹配換行
9re.search(r'start.*end', text, re.DOTALL)  # 匹配

 1class MarkdownLinkChecker:
 2    EXTERNAL_PATTERNS = [
 3        r'^https?://',
 4        r'^mailto:',
 5        r'^tel:',
 6        r'^ftp://',
 7    ]
 8
 9    def _is_external_link(self, target: str) -> bool:
10        """檢查是否為外部連結"""
11        return any(
12            re.match(pattern, target)
13            for pattern in self.EXTERNAL_PATTERNS
14        )

1# 好：使用 r'' 避免跳脫問題
2pattern = r'\d+\.\d+'
3
4# 不好：需要雙重跳脫
5pattern = '\\d+\\.\\d+'

1# 好：編譯後重複使用
2pattern = re.compile(r'\d+')
3for text in texts:
4    pattern.findall(text)
5
6# 不好：每次都重新編譯
7for text in texts:
8    re.findall(r'\d+', text)

1# 有命名群組：更易讀
2pattern = re.compile(r'(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})')
3match = pattern.search("2024-01-20")
4if match:
5    print(match.group('year'))   # "2024"
6    print(match.group('month'))  # "01"

 1# 使用 print 的問題
 2print("Processing started")        # 無法控制輸出等級
 3print(f"Error: {error}")          # 無法區分一般訊息和錯誤
 4print("Debug: x =", x)            # 生產環境也會輸出
 5
 6# 使用 logging 的好處
 7import logging
 8logger = logging.getLogger(__name__)
 9
10logger.info("Processing started")   # 可以控制等級
11logger.error(f"Error: {error}")    # 明確標示為錯誤
12logger.debug(f"x = {x}")           # 只在 DEBUG 模式輸出

 1import logging
 2import os
 3from datetime import datetime
 4from pathlib import Path
 5from typing import Optional
 6
 7
 8def setup_hook_logging(
 9    hook_name: str,
10    log_subdir: Optional[str] = None,
11    log_level: Optional[int] = None,
12    include_stderr: bool = False
13) -> logging.Logger:
14    """
15    設定 Hook 日誌系統
16
17    Args:
18        hook_name: Hook 名稱，用於識別日誌來源
19        log_subdir: 日誌子目錄，預設為 hook_name
20        log_level: 日誌等級，預設根據環境變數決定
21        include_stderr: 是否同時輸出到 stderr
22
23    Returns:
24        logging.Logger: 配置好的 Logger 實例
25    """
26    # 決定日誌等級
27    if log_level is None:
28        debug_mode = os.getenv("HOOK_DEBUG", "").lower() == "true"
29        log_level = logging.DEBUG if debug_mode else logging.INFO
30
31    # 建立 Logger
32    logger = logging.getLogger(hook_name)
33    logger.setLevel(log_level)
34
35    # 避免重複添加 handler
36    if logger.handlers:
37        return logger
38
39    # 建立日誌目錄
40    project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
41    subdir = log_subdir or hook_name
42    log_dir = Path(project_root) / ".claude" / "hook-logs" / subdir
43    log_dir.mkdir(parents=True, exist_ok=True)
44
45    # 日誌檔案路徑
46    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
47    log_file = log_dir / f"{hook_name}-{timestamp}.log"
48
49    # 設定 formatter
50    formatter = logging.Formatter(
51        "[%(asctime)s] %(levelname)s - %(message)s",
52        datefmt="%Y-%m-%d %H:%M:%S"
53    )
54
55    # 檔案 handler
56    file_handler = logging.FileHandler(log_file, encoding="utf-8")
57    file_handler.setFormatter(formatter)
58    logger.addHandler(file_handler)
59
60    # 可選的 stderr handler
61    if include_stderr:
62        import sys
63        stderr_handler = logging.StreamHandler(sys.stderr)
64        stderr_handler.setFormatter(formatter)
65        logger.addHandler(stderr_handler)
66
67    return logger

 1#!/usr/bin/env python3
 2from hook_logging import setup_hook_logging
 3
 4# 初始化 logger
 5logger = setup_hook_logging("branch-verify")
 6
 7def main():
 8    logger.info("Hook started")
 9
10    branch = get_current_branch()
11    logger.debug(f"Current branch: {branch}")
12
13    if is_protected_branch(branch):
14        logger.warning(f"Operating on protected branch: {branch}")
15
16    try:
17        # 執行操作
18        result = do_something()
19        logger.info(f"Operation completed: {result}")
20    except Exception as e:
21        logger.error(f"Operation failed: {e}")
22        raise
23
24if __name__ == "__main__":
25    main()

1import logging
2
3# 取得 logger（使用模組名稱作為標識）
4logger = logging.getLogger(__name__)
5
6# 或使用自訂名稱
7logger = logging.getLogger("my_app")

 1import logging
 2
 3logger = logging.getLogger("my_app")
 4
 5# 輸出到檔案
 6file_handler = logging.FileHandler("app.log", encoding="utf-8")
 7logger.addHandler(file_handler)
 8
 9# 輸出到控制台
10console_handler = logging.StreamHandler()
11logger.addHandler(console_handler)

1import logging
2
3formatter = logging.Formatter(
4    "[%(asctime)s] %(levelname)s - %(name)s - %(message)s",
5    datefmt="%Y-%m-%d %H:%M:%S"
6)
7
8handler = logging.FileHandler("app.log")
9handler.setFormatter(formatter)

 1def setup_logger(name: str) -> logging.Logger:
 2    logger = logging.getLogger(name)
 3    logger.setLevel(logging.INFO)
 4
 5    # 重要：檢查是否已有 handler
 6    if logger.handlers:
 7        return logger
 8
 9    handler = logging.FileHandler("app.log")
10    logger.addHandler(handler)
11    return logger

 1import os
 2import logging
 3
 4def get_log_level() -> int:
 5    """從環境變數取得日誌等級"""
 6    level_name = os.getenv("LOG_LEVEL", "INFO").upper()
 7    return getattr(logging, level_name, logging.INFO)
 8
 9logger = logging.getLogger(__name__)
10logger.setLevel(get_log_level())

1from logging.handlers import RotatingFileHandler
2
3handler = RotatingFileHandler(
4    "app.log",
5    maxBytes=10*1024*1024,  # 10MB
6    backupCount=5           # 保留 5 個備份
7)

1.claude/hook-logs/
2├── branch-verify/
3│   ├── branch-verify-20240120-153000.log
4│   └── branch-verify-20240120-160000.log
5├── ticket-quality-gate/
6│   └── ticket-quality-gate-20240120-155000.log
7└── ...

1import logging
2
3# 好：使用模組名稱，便於追蹤
4logger = logging.getLogger(__name__)
5
6# 不好：使用固定字串，難以區分來源
7logger = logging.getLogger("my_logger")

1logger.debug("Variable x = %s", x)           # 詳細除錯
2logger.info("Processing file %s", filename)  # 一般操作
3logger.warning("Config not found, using default")  # 警告
4logger.error("Failed to connect: %s", error)  # 錯誤

1# 好：使用 % 格式化（只在需要時才格式化）
2logger.debug("Data: %s", expensive_function())
3
4# 不好：f-string 總是會執行
5logger.debug(f"Data: {expensive_function()}")

1import argparse
2
3parser = argparse.ArgumentParser(description="我的程式")
4parser.add_argument("filename", help="要處理的檔案")
5args = parser.parse_args()
6
7print(f"處理檔案: {args.filename}")

 1$ python script.py myfile.txt
 2處理檔案: myfile.txt
 3
 4$ python script.py --help
 5usage: script.py [-h] filename
 6
 7我的程式
 8
 9positional arguments:
10  filename    要處理的檔案
11
12options:
13  -h, --help  show this help message and exit

1parser.add_argument("filename")
2# 使用: python script.py myfile.txt

1parser.add_argument("-v", "--verbose", action="store_true")
2parser.add_argument("-o", "--output", default="output.txt")
3# 使用: python script.py -v -o result.txt

1# store_true：出現時為 True
2parser.add_argument("--debug", action="store_true")
3
4# store_false：出現時為 False
5parser.add_argument("--no-cache", action="store_false", dest="cache")

 1def main():
 2    """命令行介面"""
 3    parser = argparse.ArgumentParser(
 4        description="Hook 合規性驗證工具",
 5        formatter_class=argparse.RawDescriptionHelpFormatter,
 6        epilog="""
 7使用範例:
 8  # 驗證單一 Hook
 9  python hook_validator.py .claude/hooks/my-hook.py
10
11  # 驗證所有 Hook
12  python hook_validator.py --all
13
14  # 輸出 JSON 格式
15  python hook_validator.py --all --json
16
17  # 自訂 Hook 目錄
18  python hook_validator.py --all --dir .claude/hooks
19        """
20    )
21
22    parser.add_argument(
23        "hook_path",
24        nargs="?",
25        help="Hook 檔案路徑（相對或絕對）"
26    )
27    parser.add_argument(
28        "--all",
29        action="store_true",
30        help="驗證所有 Hook 檔案"
31    )
32    parser.add_argument(
33        "--dir",
34        help="自訂 Hook 目錄路徑（預設 .claude/hooks）"
35    )
36    parser.add_argument(
37        "--json",
38        action="store_true",
39        help="輸出 JSON 格式"
40    )
41    parser.add_argument(
42        "--strict",
43        action="store_true",
44        help="嚴格模式：將 warning 視為 error"
45    )
46
47    args = parser.parse_args()
48
49    # 根據參數執行不同邏輯
50    if args.all:
51        results = validate_all_hooks(hooks_dir=args.dir)
52    elif args.hook_path:
53        results = [validate_hook(args.hook_path)]
54    else:
55        parser.print_help()
56        sys.exit(1)
57
58    # 輸出結果
59    if args.json:
60        print(json.dumps(output, ensure_ascii=False, indent=2))
61    else:
62        print(format_validation_report(results))

 1# 單一值（預設）
 2parser.add_argument("filename")
 3
 4# 可選（0 或 1）
 5parser.add_argument("output", nargs="?", default="out.txt")
 6
 7# 零或多個
 8parser.add_argument("files", nargs="*")
 9
10# 一或多個
11parser.add_argument("files", nargs="+")
12
13# 固定數量
14parser.add_argument("point", nargs=2, type=int)  # 需要兩個整數

1# 整數
2parser.add_argument("--count", type=int, default=10)
3
4# 浮點數
5parser.add_argument("--ratio", type=float)
6
7# 檔案路徑
8from pathlib import Path
9parser.add_argument("--config", type=Path)

1parser.add_argument(
2    "--format",
3    choices=["json", "yaml", "text"],
4    default="text",
5    help="輸出格式"
6)

1parser.add_argument("--timeout", type=int, default=30)
2parser.add_argument("--verbose", action="store_true")  # 預設 False