案例研究 on Tarragon

案例：打包共用庫

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib 整體結構，展示如何將內部共用庫打包成可重用的 Python 套件。

先備知識

模組六：打包與發布
Python 模組與套件基礎

問題背景

現有設計

.claude/lib 目錄結構：

 1.claude/lib/
 2├── __init__.py              # Package entry point with version
 3├── config_loader.py         # YAML/JSON configuration loader
 4├── git_utils.py             # Git operations (branch, worktree)
 5├── hook_io.py               # Hook I/O standardization
 6├── hook_logging.py          # Logging system for hooks
 7├── hook_validator.py        # Hook compliance validator
 8├── markdown_link_checker.py # Markdown link validation
 9├── README.md                # API documentation
10└── tests/                   # Unit tests
11    ├── __init__.py
12    ├── test_config_loader.py
13    ├── test_git_utils.py
14    ├── test_hook_io.py
15    └── test_hook_logging.py

這是一個典型的內部工具庫，包含四個核心模組：

模組	功能	相依性
`config_loader`	YAML/JSON 配置載入	PyYAML (optional)
`git_utils`	Git 命令執行與分支管理	無（使用 subprocess）
`hook_io`	Hook 輸入輸出標準化	無（使用標準庫）
`hook_logging`	日誌系統設定	無（使用標準庫）

現有限制

作為內部目錄的問題：

無法跨專案重用：程式碼被鎖定在單一專案中
沒有版本管理：無法追蹤 API 變更
無法透過 pip 安裝：其他專案必須複製程式碼
相依性管理不明確：PyYAML 是可選還是必要？

進階解決方案

設計目標

建立標準的 Python 套件結構
使用 pyproject.toml 管理元資料
支援 pip install
建立 CI/CD 發布流程

實作步驟

步驟 1：重組目錄結構

從內部目錄結構轉換為標準的 src layout：

 1claude-hooks-lib/
 2├── pyproject.toml           # Package metadata and build config
 3├── README.md                # Package documentation
 4├── LICENSE                  # License file (MIT recommended)
 5├── CHANGELOG.md             # Version history
 6├── src/
 7│   └── claude_hooks_lib/    # Package directory (underscore for import)
 8│       ├── __init__.py      # Public API exports
 9│       ├── config_loader.py
10│       ├── git_utils.py
11│       ├── hook_io.py
12│       ├── hook_logging.py
13│       ├── hook_validator.py
14│       └── py.typed         # PEP 561 marker for type hints
15└── tests/
16    ├── __init__.py
17    ├── conftest.py          # Pytest fixtures
18    ├── test_config_loader.py
19    ├── test_git_utils.py
20    ├── test_hook_io.py
21    └── test_hook_logging.py

為什麼選擇 src layout？

 1# Flat layout (不推薦用於套件發布)
 2my-package/
 3├── my_package/          # Package 直接在根目錄
 4│   └── __init__.py
 5└── tests/
 6
 7# Src layout (推薦)
 8my-package/
 9├── src/
10│   └── my_package/      # Package 在 src/ 下
11│       └── __init__.py
12└── tests/

特性	Flat Layout	Src Layout
測試環境	可能意外導入本地版本	強制安裝後測試
套件發布	容易遺漏檔案	明確的套件邊界
複雜度	較低	稍高
推薦場景	簡單專案、應用程式	套件發布、函式庫

步驟 2：建立 pyproject.toml

 1[build-system]
 2requires = ["hatchling"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6name = "claude-hooks-lib"
 7version = "0.28.0"
 8description = "Shared utilities for Claude Code hooks"
 9readme = "README.md"
10license = "MIT"
11requires-python = ">=3.10"
12authors = [
13    { name = "Your Name", email = "your.email@example.com" }
14]
15keywords = ["claude", "hooks", "utilities", "git"]
16classifiers = [
17    "Development Status :: 4 - Beta",
18    "Intended Audience :: Developers",
19    "License :: OSI Approved :: MIT License",
20    "Operating System :: OS Independent",
21    "Programming Language :: Python :: 3",
22    "Programming Language :: Python :: 3.10",
23    "Programming Language :: Python :: 3.11",
24    "Programming Language :: Python :: 3.12",
25    "Programming Language :: Python :: 3.13",
26    "Typing :: Typed",
27]
28
29# Core dependencies (minimal)
30dependencies = []
31
32[project.optional-dependencies]
33# YAML support
34yaml = ["PyYAML>=6.0"]
35
36# Development dependencies
37dev = [
38    "pytest>=8.0",
39    "pytest-cov>=4.0",
40    "mypy>=1.0",
41    "ruff>=0.4",
42]
43
44# All optional features
45all = ["claude-hooks-lib[yaml]"]
46
47[project.urls]
48Homepage = "https://github.com/yourname/claude-hooks-lib"
49Documentation = "https://github.com/yourname/claude-hooks-lib#readme"
50Repository = "https://github.com/yourname/claude-hooks-lib.git"
51Changelog = "https://github.com/yourname/claude-hooks-lib/blob/main/CHANGELOG.md"
52
53[project.scripts]
54# Command-line entry points
55hook-validator = "claude_hooks_lib.hook_validator:main"
56
57[tool.hatch.build.targets.sdist]
58include = [
59    "/src",
60    "/tests",
61]
62
63[tool.hatch.build.targets.wheel]
64packages = ["src/claude_hooks_lib"]

關鍵設定說明

build-system：使用 Hatch 作為建構後端（現代、快速）
requires-python：指定最低 Python 版本
dependencies：核心相依性保持為空（僅使用標準庫）
optional-dependencies：將 PyYAML 設為可選
project.scripts：定義命令列工具入口點

步驟 3：處理相依性

相依性分層策略：

 1[project]
 2# 核心相依性：僅標準庫
 3dependencies = []
 4
 5[project.optional-dependencies]
 6# 功能性相依性（用戶根據需求安裝）
 7yaml = ["PyYAML>=6.0"]
 8
 9# 開發相依性（僅開發者需要）
10dev = [
11    "pytest>=8.0",
12    "pytest-cov>=4.0",
13    "mypy>=1.0",
14    "ruff>=0.4",
15]
16
17# 測試相依性（CI/CD 需要）
18test = [
19    "pytest>=8.0",
20    "pytest-cov>=4.0",
21]
22
23# 文件相依性
24docs = [
25    "mkdocs>=1.5",
26    "mkdocs-material>=9.0",
27]
28
29# 完整安裝
30all = [
31    "claude-hooks-lib[yaml,dev,docs]",
32]

安裝方式範例

 1# 基本安裝（無可選相依性）
 2pip install claude-hooks-lib
 3
 4# 包含 YAML 支援
 5pip install "claude-hooks-lib[yaml]"
 6
 7# 開發者安裝
 8pip install -e ".[dev]"
 9
10# 完整安裝
11pip install "claude-hooks-lib[all]"

步驟 4：版本管理策略

方法 A：單一來源版本（推薦）

在 __init__.py 中定義版本：

 1# src/claude_hooks_lib/__init__.py
 2"""
 3Claude Hooks Library
 4
 5Shared utilities for building Claude Code hooks.
 6"""
 7
 8__version__ = "0.28.0"
 9__all__ = [
10    # Version
11    "__version__",
12    # git_utils
13    "run_git_command",
14    "get_current_branch",
15    "get_project_root",
16    "get_worktree_list",
17    "is_protected_branch",
18    "is_allowed_branch",
19    # hook_logging
20    "setup_hook_logging",
21    # hook_io
22    "read_hook_input",
23    "write_hook_output",
24    "create_pretooluse_output",
25    "create_posttooluse_output",
26    # config_loader
27    "load_config",
28    "load_agents_config",
29    "load_quality_rules",
30    "clear_config_cache",
31]
32
33from .git_utils import (
34    run_git_command,
35    get_current_branch,
36    get_project_root,
37    get_worktree_list,
38    is_protected_branch,
39    is_allowed_branch,
40)
41
42from .hook_logging import setup_hook_logging
43
44from .hook_io import (
45    read_hook_input,
46    write_hook_output,
47    create_pretooluse_output,
48    create_posttooluse_output,
49)
50
51from .config_loader import (
52    load_config,
53    load_agents_config,
54    load_quality_rules,
55    clear_config_cache,
56)

在 pyproject.toml 中使用動態版本：

1[project]
2name = "claude-hooks-lib"
3dynamic = ["version"]
4
5[tool.hatch.version]
6path = "src/claude_hooks_lib/__init__.py"

方法 B：使用 hatch-vcs（Git tag 版本）

 1[build-system]
 2requires = ["hatchling", "hatch-vcs"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6dynamic = ["version"]
 7
 8[tool.hatch.version]
 9source = "vcs"
10
11[tool.hatch.build.hooks.vcs]
12version-file = "src/claude_hooks_lib/_version.py"

1# Create version tag
2git tag v0.28.0
3git push --tags

步驟 5：建立發布流程

.github/workflows/publish.yml：

 1name: Publish to PyPI
 2
 3on:
 4  release:
 5    types: [published]
 6
 7permissions:
 8  contents: read
 9  id-token: write  # Required for trusted publishing
10
11jobs:
12  build:
13    runs-on: ubuntu-latest
14    steps:
15      - uses: actions/checkout@v4
16
17      - name: Set up Python
18        uses: actions/setup-python@v5
19        with:
20          python-version: "3.12"
21
22      - name: Install build tools
23        run: |
24          python -m pip install --upgrade pip
25          pip install build
26
27      - name: Build package
28        run: python -m build
29
30      - name: Upload artifacts
31        uses: actions/upload-artifact@v4
32        with:
33          name: dist
34          path: dist/
35
36  test:
37    runs-on: ubuntu-latest
38    strategy:
39      matrix:
40        python-version: ["3.10", "3.11", "3.12", "3.13"]
41    steps:
42      - uses: actions/checkout@v4
43
44      - name: Set up Python ${{ matrix.python-version }}
45        uses: actions/setup-python@v5
46        with:
47          python-version: ${{ matrix.python-version }}
48
49      - name: Install dependencies
50        run: |
51          python -m pip install --upgrade pip
52          pip install -e ".[dev,yaml]"
53
54      - name: Run tests
55        run: pytest tests/ -v --cov=src/claude_hooks_lib
56
57      - name: Type check
58        run: mypy src/claude_hooks_lib
59
60  publish-testpypi:
61    needs: [build, test]
62    runs-on: ubuntu-latest
63    environment: testpypi
64    steps:
65      - name: Download artifacts
66        uses: actions/download-artifact@v4
67        with:
68          name: dist
69          path: dist/
70
71      - name: Publish to TestPyPI
72        uses: pypa/gh-action-pypi-publish@release/v1
73        with:
74          repository-url: https://test.pypi.org/legacy/
75
76  publish-pypi:
77    needs: [publish-testpypi]
78    runs-on: ubuntu-latest
79    environment: pypi
80    steps:
81      - name: Download artifacts
82        uses: actions/download-artifact@v4
83        with:
84          name: dist
85          path: dist/
86
87      - name: Publish to PyPI
88        uses: pypa/gh-action-pypi-publish@release/v1

CI 測試工作流程（.github/workflows/test.yml）：

 1name: Tests
 2
 3on:
 4  push:
 5    branches: [main]
 6  pull_request:
 7    branches: [main]
 8
 9jobs:
10  test:
11    runs-on: ${{ matrix.os }}
12    strategy:
13      fail-fast: false
14      matrix:
15        os: [ubuntu-latest, macos-latest, windows-latest]
16        python-version: ["3.10", "3.11", "3.12", "3.13"]
17
18    steps:
19      - uses: actions/checkout@v4
20
21      - name: Set up Python ${{ matrix.python-version }}
22        uses: actions/setup-python@v5
23        with:
24          python-version: ${{ matrix.python-version }}
25
26      - name: Install dependencies
27        run: |
28          python -m pip install --upgrade pip
29          pip install -e ".[dev,yaml]"
30
31      - name: Lint with ruff
32        run: ruff check src/ tests/
33
34      - name: Format check with ruff
35        run: ruff format --check src/ tests/
36
37      - name: Type check with mypy
38        run: mypy src/claude_hooks_lib
39
40      - name: Run tests with coverage
41        run: |
42          pytest tests/ -v --cov=src/claude_hooks_lib --cov-report=xml
43
44      - name: Upload coverage
45        uses: codecov/codecov-action@v4
46        with:
47          files: ./coverage.xml

完整程式碼

完整的 pyproject.toml

  1[build-system]
  2requires = ["hatchling"]
  3build-backend = "hatchling.build"
  4
  5[project]
  6name = "claude-hooks-lib"
  7dynamic = ["version"]
  8description = "Shared utilities for Claude Code hooks"
  9readme = "README.md"
 10license = "MIT"
 11requires-python = ">=3.10"
 12authors = [
 13    { name = "Your Name", email = "your.email@example.com" }
 14]
 15keywords = ["claude", "hooks", "utilities", "git", "automation"]
 16classifiers = [
 17    "Development Status :: 4 - Beta",
 18    "Intended Audience :: Developers",
 19    "License :: OSI Approved :: MIT License",
 20    "Operating System :: OS Independent",
 21    "Programming Language :: Python :: 3",
 22    "Programming Language :: Python :: 3.10",
 23    "Programming Language :: Python :: 3.11",
 24    "Programming Language :: Python :: 3.12",
 25    "Programming Language :: Python :: 3.13",
 26    "Typing :: Typed",
 27    "Topic :: Software Development :: Libraries :: Python Modules",
 28]
 29
 30dependencies = []
 31
 32[project.optional-dependencies]
 33yaml = ["PyYAML>=6.0"]
 34dev = [
 35    "pytest>=8.0",
 36    "pytest-cov>=4.0",
 37    "mypy>=1.0",
 38    "ruff>=0.4",
 39    "PyYAML>=6.0",
 40]
 41docs = [
 42    "mkdocs>=1.5",
 43    "mkdocs-material>=9.0",
 44]
 45all = ["claude-hooks-lib[yaml,dev,docs]"]
 46
 47[project.urls]
 48Homepage = "https://github.com/yourname/claude-hooks-lib"
 49Documentation = "https://github.com/yourname/claude-hooks-lib#readme"
 50Repository = "https://github.com/yourname/claude-hooks-lib.git"
 51Changelog = "https://github.com/yourname/claude-hooks-lib/blob/main/CHANGELOG.md"
 52
 53[project.scripts]
 54hook-validator = "claude_hooks_lib.hook_validator:main"
 55
 56# ===== Build Configuration =====
 57
 58[tool.hatch.version]
 59path = "src/claude_hooks_lib/__init__.py"
 60
 61[tool.hatch.build.targets.sdist]
 62include = ["/src", "/tests", "/README.md", "/LICENSE"]
 63
 64[tool.hatch.build.targets.wheel]
 65packages = ["src/claude_hooks_lib"]
 66
 67# ===== Tool Configuration =====
 68
 69[tool.ruff]
 70src = ["src"]
 71line-length = 88
 72target-version = "py310"
 73
 74[tool.ruff.lint]
 75select = [
 76    "E",      # pycodestyle errors
 77    "W",      # pycodestyle warnings
 78    "F",      # pyflakes
 79    "I",      # isort
 80    "B",      # flake8-bugbear
 81    "C4",     # flake8-comprehensions
 82    "UP",     # pyupgrade
 83]
 84ignore = ["E501"]  # Line too long (handled by formatter)
 85
 86[tool.ruff.lint.isort]
 87known-first-party = ["claude_hooks_lib"]
 88
 89[tool.mypy]
 90python_version = "3.10"
 91warn_return_any = true
 92warn_unused_ignores = true
 93disallow_untyped_defs = true
 94strict = true
 95
 96[[tool.mypy.overrides]]
 97module = "yaml"
 98ignore_missing_imports = true
 99
100[tool.pytest.ini_options]
101testpaths = ["tests"]
102python_files = "test_*.py"
103python_functions = "test_*"
104addopts = "-v --tb=short"
105
106[tool.coverage.run]
107source = ["src/claude_hooks_lib"]
108branch = true
109
110[tool.coverage.report]
111exclude_lines = [
112    "pragma: no cover",
113    "if TYPE_CHECKING:",
114    "raise NotImplementedError",
115]

使用範例

安裝套件

 1# From PyPI (after publishing)
 2pip install claude-hooks-lib
 3
 4# With YAML support
 5pip install "claude-hooks-lib[yaml]"
 6
 7# Development installation (from source)
 8git clone https://github.com/yourname/claude-hooks-lib
 9cd claude-hooks-lib
10pip install -e ".[dev]"

Python 使用範例

 1# Basic usage
 2from claude_hooks_lib import (
 3    get_current_branch,
 4    is_protected_branch,
 5    setup_hook_logging,
 6    read_hook_input,
 7    write_hook_output,
 8    create_pretooluse_output,
 9)
10
11# Initialize logging
12logger = setup_hook_logging("my-custom-hook")
13
14# Check branch protection
15branch = get_current_branch()
16if branch and is_protected_branch(branch):
17    logger.warning(f"Operating on protected branch: {branch}")
18
19# Process hook input
20input_data = read_hook_input()
21tool_name = input_data.get("tool_name", "")
22
23# Generate output
24output = create_pretooluse_output(
25    decision="allow",
26    reason="All checks passed"
27)
28write_hook_output(output)

命令列工具使用

 1# Validate a single hook
 2hook-validator .claude/hooks/my-hook.py
 3
 4# Validate all hooks
 5hook-validator --all
 6
 7# Output as JSON
 8hook-validator --all --json
 9
10# Strict mode (warnings as errors)
11hook-validator --all --strict

設計權衡

面向	內部目錄	獨立套件
重用性	僅限單專案	跨專案共用
版本管理	與專案綁定	獨立語意化版本
維護成本	低（無發布流程）	中（需維護 CI/CD）
相依管理	隱式（需手動追蹤）	顯式（pyproject.toml）
安裝方式	複製程式碼或 sys.path	pip install
測試隔離	可能測試到本地版本	強制測試安裝版本
API 穩定性	無保證	版本號約束

專案結構比較

Layout	適用場景	優點	缺點
Flat Layout	簡單應用、腳本	簡單直覺	測試可能導入錯誤版本
Src Layout	函式庫、套件發布	測試隔離、明確邊界	額外一層目錄

建構工具比較

工具	特點	推薦場景
setuptools	成熟穩定、生態最大	需要相容舊專案
Hatch	現代、快速、功能完整	新專案首選
Poetry	依賴鎖定、虛擬環境管理	需要嚴格依賴控制
Flit	極簡、僅純 Python	簡單函式庫

什麼時候該打包成套件？

適合打包

多個專案需要使用相同程式碼
程式碼相對穩定，API 不常變動
需要版本控制和變更追蹤
希望其他人能 pip install 使用
需要明確的相依性管理

不建議打包

僅單一專案使用
程式碼還在快速迭代
與專案緊密耦合（如特定的配置路徑）
維護成本超過重用收益

決策流程圖

1程式碼需要跨專案使用？
2├── 否 → 保持內部目錄
3└── 是 → API 穩定嗎？
4         ├── 否 → 等待穩定後再打包
5         └── 是 → 有維護能力嗎？
6                  ├── 否 → 考慮 monorepo
7                  └── 是 → 打包發布

練習

基礎練習：建立最小的 pyproject.toml

目標：為一個簡單的工具函式庫建立 pyproject.toml

1# src/my_utils/__init__.py
2"""Simple utilities."""
3
4__version__ = "0.1.0"
5
6def greet(name: str) -> str:
7    """Return a greeting message."""
8    return f"Hello, {name}!"

要求：

使用 hatchling 作為建構後端
設定專案名稱、版本、描述
指定 Python 版本要求（>=3.10）

參考答案

案例：使用 Poetry 完整工作流

Wed, 21 Jan 2026 00:00:00 +0000

本案例展示如何使用 Poetry 管理現代 Python 專案的完整生命週期，從專案建立到套件發布。

先備知識

建構系統比較
Python 虛擬環境基礎
套件相依性概念

問題背景

現代專案的挑戰

傳統的 Python 專案管理面臨以下問題：

 1傳統工作流程的痛點：
 2├── 相依性管理
 3│ ├── requirements.txt 無法鎖定間接相依性
 4│ ├── pip freeze 產生的版本可能過於嚴格
 5│ └── 開發與生產環境相依性混在一起
 6├── 虛擬環境
 7│ ├── 需要手動建立和管理
 8│ ├── 不同專案的環境容易混淆
 9│ └── 缺乏與專案的關聯性
10├── 建構與發布
11│ ├── setup.py 設定複雜
12│ ├── 發布流程需要多個工具
13│ └── 版本管理不一致
14└── 團隊協作
15 ├── 環境難以重現
16 ├── 「在我電腦上可以跑」問題
17 └── 新成員上手困難

為什麼選擇 Poetry？

特性	pip + venv	Poetry
相依性鎖定	手動（pip freeze）	自動（poetry.lock）
間接相依性追蹤	無	完整追蹤
虛擬環境管理	手動	自動整合
建構系統	需要額外工具	內建
發布流程	需要 twine	內建
相依性群組	無原生支援	完整支援

解決方案

安裝 Poetry

1# 官方推薦的安裝方式（獨立安裝）
2curl -sSL https://install.python-poetry.org | python3 -
3
4# 或使用 pipx（推薦用於 CLI 工具）
5pipx install poetry
6
7# 確認安裝
8poetry --version

設定 Poetry

1# 在專案目錄中建立虛擬環境（推薦）
2poetry config virtualenvs.in-project true
3
4# 查看所有設定
5poetry config --list

工作流一：建立新專案

使用 poetry new（完整專案結構）

 1# 建立新專案
 2poetry new my-awesome-lib
 3
 4# 產生的目錄結構
 5my-awesome-lib/
 6├── pyproject.toml
 7├── README.md
 8├── my_awesome_lib/
 9│ └── __init__.py
10└── tests/
11 └── __init__.py

 1# 使用 src layout（推薦用於函式庫）
 2poetry new --src my-awesome-lib
 3
 4# 產生的目錄結構
 5my-awesome-lib/
 6├── pyproject.toml
 7├── README.md
 8├── src/
 9│ └── my_awesome_lib/
10│ └── __init__.py
11└── tests/
12 └── __init__.py

使用 poetry init（現有專案）

 1# 在現有目錄初始化
 2cd existing-project
 3poetry init
 4
 5# 互動式問答
 6# - Package name
 7# - Version
 8# - Description
 9# - Author
10# - License
11# - Python version
12# - Dependencies

互動式初始化範例

 1This command will guide you through creating your pyproject.toml config.
 2
 3Package name [existing-project]: my-package
 4Version [0.1.0]: 1.0.0
 5Description []: A useful Python package
 6Author [Your Name <you@example.com>, n to skip]:
 7License []: MIT
 8Compatible Python versions [^3.10]: ^3.10
 9
10Would you like to define your main dependencies interactively? (yes/no) [yes]
11Search for package to add (or leave blank to continue): requests
12...

工作流二：管理相依性

新增相依性

 1# 新增生產相依性
 2poetry add requests
 3poetry add "httpx>=0.24"
 4
 5# 新增開發相依性
 6poetry add pytest --group dev
 7poetry add ruff mypy --group dev
 8
 9# 新增文件相依性
10poetry add mkdocs mkdocs-material --group docs
11
12# 新增可選相依性（extras）
13poetry add pyyaml --optional

pyproject.toml 的變化

 1[tool.poetry.dependencies]
 2python = "^3.10"
 3requests = "^2.31.0"
 4httpx = ">=0.24"
 5
 6[tool.poetry.group.dev.dependencies]
 7pytest = "^8.0.0"
 8ruff = "^0.4.0"
 9mypy = "^1.10.0"
10
11[tool.poetry.group.docs.dependencies]
12mkdocs = "^1.5.0"
13mkdocs-material = "^9.5.0"
14
15[tool.poetry.extras]
16yaml = ["pyyaml"]

移除相依性

1# 移除生產相依性
2poetry remove requests
3
4# 移除開發相依性
5poetry remove pytest --group dev

更新相依性

 1# 更新所有相依性
 2poetry update
 3
 4# 更新特定套件
 5poetry update requests
 6
 7# 檢視可更新的套件
 8poetry show --outdated
 9
10# 檢視相依性樹
11poetry show --tree

相依性樹範例輸出

1requests 2.31.0 Python HTTP for Humans.
2├── certifi >=2017.4.17
3├── charset-normalizer >=2,<4
4├── idna >=2.5,<4
5└── urllib3 >=1.21.1,<3

工作流三：虛擬環境管理

自動環境管理

 1# 安裝所有相依性（自動建立虛擬環境）
 2poetry install
 3
 4# 僅安裝生產相依性
 5poetry install --only main
 6
 7# 安裝包含特定群組
 8poetry install --with dev,docs
 9
10# 排除特定群組
11poetry install --without docs
12
13# 安裝 extras
14poetry install --extras yaml
15poetry install --all-extras

環境操作

 1# 進入虛擬環境 shell
 2poetry shell
 3
 4# 在虛擬環境中執行命令（不進入 shell）
 5poetry run python script.py
 6poetry run pytest
 7poetry run python -c "import my_package; print(my_package.__version__)"
 8
 9# 顯示環境資訊
10poetry env info
11
12# 顯示環境路徑
13poetry env info --path
14
15# 列出所有環境
16poetry env list
17
18# 切換 Python 版本
19poetry env use python3.11
20poetry env use 3.12
21
22# 刪除環境
23poetry env remove python3.11
24poetry env remove --all

環境資訊範例輸出

 1Virtualenv
 2Python: 3.11.6
 3Implementation: CPython
 4Path: /path/to/project/.venv
 5Executable: /path/to/project/.venv/bin/python
 6Valid: True
 7
 8Base
 9Platform: darwin
10OS: posix
11Python: 3.11.6
12Path: /opt/homebrew/Cellar/python@3.11/3.11.6/Frameworks/Python.framework/Versions/3.11
13Executable: /opt/homebrew/Cellar/python@3.11/3.11.6/Frameworks/Python.framework/Versions/3.11/bin/python3.11

工作流四：建構與發布

建構套件

 1# 建構 sdist 和 wheel
 2poetry build
 3
 4# 僅建構 wheel
 5poetry build --format wheel
 6
 7# 建構結果
 8dist/
 9├── my_package-1.0.0-py3-none-any.whl
10└── my_package-1.0.0.tar.gz

發布到 PyPI

 1# 設定 PyPI token
 2poetry config pypi-token.pypi pypi-XXXXXXXXXXXX
 3
 4# 發布到 PyPI
 5poetry publish
 6
 7# 建構並發布（一步完成）
 8poetry publish --build
 9
10# 發布到 TestPyPI
11poetry config repositories.testpypi https://test.pypi.org/legacy/
12poetry config pypi-token.testpypi pypi-XXXXXXXXXXXX
13poetry publish --repository testpypi

版本管理

 1# 查看當前版本
 2poetry version
 3
 4# 升級版本
 5poetry version patch # 1.0.0 -> 1.0.1
 6poetry version minor # 1.0.0 -> 1.1.0
 7poetry version major # 1.0.0 -> 2.0.0
 8
 9# 設定特定版本
10poetry version 2.0.0
11
12# 預發布版本
13poetry version prepatch # 1.0.0 -> 1.0.1a0
14poetry version preminor # 1.0.0 -> 1.1.0a0
15poetry version premajor # 1.0.0 -> 2.0.0a0

完整 pyproject.toml 範例

 1[build-system]
 2requires = ["poetry-core>=2.0"]
 3build-backend = "poetry.core.masonry.api"
 4
 5[project]
 6name = "my-awesome-lib"
 7version = "1.0.0"
 8description = "A feature-rich Python library"
 9readme = "README.md"
10license = "MIT"
11requires-python = ">=3.10"
12authors = [
13 { name = "Your Name", email = "you@example.com" }
14]
15keywords = ["python", "library", "utilities"]
16classifiers = [
17 "Development Status :: 4 - Beta",
18 "Intended Audience :: Developers",
19 "License :: OSI Approved :: MIT License",
20 "Operating System :: OS Independent",
21 "Programming Language :: Python :: 3",
22 "Programming Language :: Python :: 3.10",
23 "Programming Language :: Python :: 3.11",
24 "Programming Language :: Python :: 3.12",
25 "Programming Language :: Python :: 3.13",
26 "Typing :: Typed",
27]
28
29[project.urls]
30Homepage = "https://github.com/yourname/my-awesome-lib"
31Documentation = "https://my-awesome-lib.readthedocs.io"
32Repository = "https://github.com/yourname/my-awesome-lib.git"
33Changelog = "https://github.com/yourname/my-awesome-lib/blob/main/CHANGELOG.md"
34
35[project.scripts]
36my-cli = "my_awesome_lib.cli:main"
37
38[project.optional-dependencies]
39yaml = ["pyyaml>=6.0"]
40all = ["my-awesome-lib[yaml]"]
41
42# ===== Poetry 特定設定 =====
43
44[tool.poetry]
45packages = [{ include = "my_awesome_lib", from = "src" }]
46
47[tool.poetry.dependencies]
48python = "^3.10"
49requests = "^2.31"
50click = "^8.1"
51
52[tool.poetry.group.dev.dependencies]
53pytest = "^8.0"
54pytest-cov = "^4.1"
55pytest-asyncio = "^0.23"
56mypy = "^1.10"
57ruff = "^0.4"
58
59[tool.poetry.group.docs]
60optional = true
61
62[tool.poetry.group.docs.dependencies]
63mkdocs = "^1.5"
64mkdocs-material = "^9.5"
65
66# ===== 工具設定 =====
67
68[tool.ruff]
69src = ["src"]
70line-length = 88
71target-version = "py310"
72
73[tool.ruff.lint]
74select = ["E", "W", "F", "I", "B", "C4", "UP"]
75
76[tool.mypy]
77python_version = "3.10"
78strict = true
79
80[tool.pytest.ini_options]
81testpaths = ["tests"]
82addopts = "-v --tb=short"

與其他工具的比較

Poetry vs pip

操作	pip	Poetry
安裝相依性	`pip install -r requirements.txt`	`poetry install`
新增相依性	手動編輯 requirements.txt	`poetry add package`
鎖定版本	`pip freeze > requirements.txt`	自動更新 poetry.lock
建立環境	`python -m venv .venv`	自動建立
執行命令	`source .venv/bin/activate && python`	`poetry run python`
建構套件	`python -m build`	`poetry build`
發布套件	`twine upload dist/*`	`poetry publish`

Poetry vs setuptools

面向	setuptools	Poetry
設定格式	pyproject.toml + 可能需要 setup.py	僅 pyproject.toml
相依性管理	需要額外工具	內建完整支援
環境管理	無	內建
學習曲線	較陡（歷史包袱）	較平緩
C 擴展支援	完整	不支援
生態系統	最廣泛	持續成長

Poetry vs Hatch

面向	Hatch	Poetry
設計理念	PEP 標準優先	使用者體驗優先
相依性鎖定	無內建	核心功能
環境管理	多環境（類似 tox）	單一虛擬環境
腳本系統	完整	基本
建構後端	hatchling	poetry-core
適用場景	開源函式庫	應用程式、內部工具

實用技巧

技巧一：善用 Lock 檔案

 1# poetry.lock 的重要性
 2# - 記錄所有相依性的精確版本（包含間接相依性）
 3# - 確保團隊成員、CI/CD 使用相同版本
 4# - 應該提交到版本控制
 5
 6# 根據 lock 檔案安裝（不更新）
 7poetry install --no-update
 8
 9# 驗證 lock 檔案與 pyproject.toml 一致
10poetry check --lock
11
12# 匯出為 requirements.txt（部署用）
13poetry export -f requirements.txt -o requirements.txt
14poetry export -f requirements.txt --with dev -o requirements-dev.txt
15poetry export --without-hashes -o requirements.txt

技巧二：善用相依性群組

 1# 開發相依性
 2[tool.poetry.group.dev.dependencies]
 3pytest = "^8.0"
 4ruff = "^0.4"
 5
 6# 可選群組（預設不安裝）
 7[tool.poetry.group.docs]
 8optional = true
 9
10[tool.poetry.group.docs.dependencies]
11mkdocs = "^1.5"
12
13# CI 專用群組
14[tool.poetry.group.ci]
15optional = true
16
17[tool.poetry.group.ci.dependencies]
18pytest-cov = "^4.1"
19codecov = "^2.1"

1# 安裝特定群組
2poetry install --with docs
3poetry install --with ci
4
5# CI 環境中的安裝
6poetry install --only main,ci

技巧三：善用 Extras

1[project.optional-dependencies]
2# 功能性 extras
3yaml = ["pyyaml>=6.0"]
4async = ["httpx>=0.24", "aiofiles>=23.0"]
5
6# 完整安裝
7all = ["my-package[yaml,async]"]

1# 使用者安裝方式
2pip install my-package # 基本功能
3pip install "my-package[yaml]" # 包含 YAML 支援
4pip install "my-package[all]" # 所有功能

技巧四：本地相依性和 Git 相依性

1[tool.poetry.dependencies]
2# 本地路徑相依性
3my-local-lib = { path = "../my-local-lib", develop = true }
4
5# Git 相依性
6my-git-lib = { git = "https://github.com/user/repo.git" }
7my-git-lib = { git = "https://github.com/user/repo.git", branch = "develop" }
8my-git-lib = { git = "https://github.com/user/repo.git", tag = "v1.0.0" }
9my-git-lib = { git = "https://github.com/user/repo.git", rev = "abc123" }

技巧五：平台特定相依性

1[tool.poetry.dependencies]
2# 僅 Windows
3pywin32 = { version = "^306", markers = "sys_platform == 'win32'" }
4
5# 僅 Linux
6uvloop = { version = "^0.19", markers = "sys_platform == 'linux'" }
7
8# Python 版本限制
9typing-extensions = { version = "^4.0", python = "<3.11" }

技巧六：Poetry 腳本

1[tool.poetry.scripts]
2my-cli = "my_package.cli:main"
3my-tool = "my_package.tools:run"

 1# src/my_package/cli.py
 2import click
 3
 4@click.command()
 5@click.option("--name", default="World", help="Name to greet")
 6def main(name: str) -> None:
 7 """Greet someone."""
 8 click.echo(f"Hello, {name}!")
 9
10if __name__ == "__main__":
11 main()

1# 安裝後即可使用
2my-cli --name Python
3# 輸出：Hello, Python!

常見問題與解決

問題一：相依性解析衝突

 1# 錯誤訊息
 2SolverProblemError: ...
 3
 4# 解決方法
 5# 1. 檢視衝突詳情
 6poetry show --tree
 7
 8# 2. 放寬版本限制
 9poetry add "package>=1.0,<3.0"
10
11# 3. 強制更新 lock 檔案
12poetry lock --no-update

問題二：虛擬環境問題

1# 重建虛擬環境
2poetry env remove --all
3poetry install
4
5# 指定 Python 版本
6poetry env use /usr/bin/python3.11

問題三：CI/CD 快取

 1# GitHub Actions 範例
 2- name: Install Poetry
 3 uses: snok/install-poetry@v1
 4 with:
 5 virtualenvs-create: true
 6 virtualenvs-in-project: true
 7
 8- name: Load cached venv
 9 uses: actions/cache@v4
10 with:
11 path: .venv
12 key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
13
14- name: Install dependencies
15 if: steps.cache.outputs.cache-hit != 'true'
16 run: poetry install --no-interaction

設計權衡

面向	優點	缺點
相依性鎖定	環境可重現、團隊一致	lock 檔案衝突、更新需謹慎
一體化工具	學習成本低、工作流統一	與其他工具整合需調整
虛擬環境整合	自動管理、不易混淆	自訂環境位置需設定
建構與發布	流程簡化	不支援 C 擴展

練習

基礎練習：建立 Poetry 專案

目標：使用 Poetry 建立一個簡單的專案

案例：使用 Hatch 完整工作流

Wed, 21 Jan 2026 00:00:00 +0000

本案例展示如何使用 Hatch 這個 PyPA 推薦的現代 Python 專案管理工具，完成從專案建立到發布的完整流程。

先備知識

6.2 建構系統比較
Python 虛擬環境基礎
基本的命令列操作

問題背景

Hatch 是什麼？

Hatch 是由 PyPA（Python Packaging Authority）成員開發維護的現代 Python 專案管理工具，整合了：

1Hatch 功能整合：
2├── 專案腳手架（hatch new）
3├── 環境管理（類似 tox + virtualenv）
4├── 版本管理（自動更新版本號）
5├── 建構系統（hatchling）
6└── 發布工具（hatch publish）

為什麼選擇 Hatch？

優勢	說明
標準優先	完全遵循 PEP 517/518/621 標準
一站式工具	不需要額外安裝 tox、virtualenv、bump2version
快速建構	hatchling 建構速度優於 setuptools
環境矩陣	內建多 Python 版本測試支援
腳本系統	定義可重用的專案腳本

完整工作流

第一步：安裝 Hatch

1# 使用 pip 安裝
2pip install hatch
3
4# 或使用 pipx（推薦，隔離安裝）
5pipx install hatch
6
7# 驗證安裝
8hatch --version

第二步：建立新專案

1# 建立新專案
2hatch new my-awesome-lib
3
4# 互動式建立（可自訂選項）
5hatch new my-awesome-lib --init
6
7# 建立應用程式專案（非函式庫）
8hatch new --cli my-cli-app

預設專案結構

 1my-awesome-lib/
 2├── src/
 3│ └── my_awesome_lib/
 4│ ├── __init__.py
 5│ └── __about__.py # 版本資訊
 6├── tests/
 7│ └── __init__.py
 8├── pyproject.toml
 9├── README.md
10└── LICENSE.txt

生成的 pyproject.toml

 1[build-system]
 2requires = ["hatchling"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6name = "my-awesome-lib"
 7dynamic = ["version"]
 8description = ''
 9readme = "README.md"
10requires-python = ">=3.8"
11license = "MIT"
12keywords = []
13authors = [
14 { name = "Your Name", email = "you@example.com" },
15]
16classifiers = [
17 "Development Status :: 4 - Beta",
18 "Programming Language :: Python",
19 "Programming Language :: Python :: 3.8",
20 "Programming Language :: Python :: 3.9",
21 "Programming Language :: Python :: 3.10",
22 "Programming Language :: Python :: 3.11",
23 "Programming Language :: Python :: 3.12",
24]
25dependencies = []
26
27[project.urls]
28Documentation = "https://github.com/yourname/my-awesome-lib#readme"
29Issues = "https://github.com/yourname/my-awesome-lib/issues"
30Source = "https://github.com/yourname/my-awesome-lib"
31
32[tool.hatch.version]
33path = "src/my_awesome_lib/__about__.py"

第三步：環境管理（hatch env）

定義環境

 1# pyproject.toml
 2
 3# 預設環境
 4[tool.hatch.envs.default]
 5dependencies = [
 6 "pytest",
 7 "pytest-cov",
 8]
 9
10[tool.hatch.envs.default.scripts]
11test = "pytest {args:tests}"
12test-cov = "pytest --cov=my_awesome_lib --cov-report=term-missing {args:tests}"
13
14# Lint 環境
15[tool.hatch.envs.lint]
16dependencies = [
17 "ruff>=0.4",
18 "mypy>=1.0",
19]
20
21[tool.hatch.envs.lint.scripts]
22check = [
23 "ruff check src tests",
24 "ruff format --check src tests",
25]
26fix = [
27 "ruff check --fix src tests",
28 "ruff format src tests",
29]
30typing = "mypy src"
31all = ["check", "typing"]
32
33# 文件環境
34[tool.hatch.envs.docs]
35dependencies = [
36 "mkdocs>=1.5",
37 "mkdocs-material>=9.0",
38]
39
40[tool.hatch.envs.docs.scripts]
41build = "mkdocs build"
42serve = "mkdocs serve"

使用環境

 1# 顯示所有環境
 2hatch env show
 3
 4# 執行預設環境的腳本
 5hatch run test
 6hatch run test-cov
 7
 8# 執行特定環境的腳本
 9hatch run lint:check
10hatch run lint:fix
11hatch run lint:typing
12
13# 進入環境 shell
14hatch shell
15
16# 進入特定環境
17hatch shell lint
18
19# 移除環境
20hatch env remove
21hatch env remove lint
22
23# 清除所有環境
24hatch env prune

第四步：版本管理（hatch version）

設定版本來源

方法 A：從檔案讀取版本

1[tool.hatch.version]
2path = "src/my_awesome_lib/__about__.py"

1# src/my_awesome_lib/__about__.py
2__version__ = "0.1.0"

方法 B：從 Git 標籤讀取版本（推薦用於開源專案）

1[build-system]
2requires = ["hatchling", "hatch-vcs"]
3build-backend = "hatchling.build"
4
5[tool.hatch.version]
6source = "vcs"
7
8[tool.hatch.build.hooks.vcs]
9version-file = "src/my_awesome_lib/_version.py"

版本操作

 1# 顯示當前版本
 2hatch version
 3
 4# 設定特定版本
 5hatch version 1.0.0
 6
 7# 語意化版本升級
 8hatch version patch # 0.1.0 → 0.1.1
 9hatch version minor # 0.1.1 → 0.2.0
10hatch version major # 0.2.0 → 1.0.0
11
12# 預發布版本
13hatch version alpha # 1.0.0 → 1.0.1a0
14hatch version beta # 1.0.1a0 → 1.0.1b0
15hatch version rc # 1.0.1b0 → 1.0.1rc0
16hatch version release # 1.0.1rc0 → 1.0.1
17
18# 開發版本
19hatch version dev # 1.0.0 → 1.0.1.dev0

第五步：建構與發布

建構套件

 1# 建構 wheel 和 sdist
 2hatch build
 3
 4# 只建構 wheel
 5hatch build --target wheel
 6
 7# 只建構 sdist
 8hatch build --target sdist
 9
10# 清除建構產物後重建
11hatch build --clean

建構產物

1dist/
2├── my_awesome_lib-0.1.0-py3-none-any.whl
3└── my_awesome_lib-0.1.0.tar.gz

發布套件

1# 發布到 PyPI（需要設定認證）
2hatch publish
3
4# 發布到 TestPyPI
5hatch publish --repo test
6
7# 指定發布的檔案
8hatch publish dist/my_awesome_lib-0.1.0-py3-none-any.whl

設定 PyPI 認證

1# 設定 PyPI token
2hatch config set pypi.auth.username __token__
3hatch config set pypi.auth.password pypi-xxxxx
4
5# 或使用環境變數
6export HATCH_INDEX_USER=__token__
7export HATCH_INDEX_AUTH=pypi-xxxxx

pyproject.toml 的 Hatch 特定設定

[tool.hatch.build] 建構設定

 1[tool.hatch.build]
 2# 包含的檔案（支援 glob）
 3include = [
 4 "src/my_awesome_lib",
 5 "README.md",
 6]
 7
 8# 排除的檔案
 9exclude = [
10 "*.pyc",
11 "__pycache__",
12 ".git",
13]
14
15# 是否可重現建構
16reproducible = true
17
18# 開發模式設定
19dev-mode-dirs = ["src"]
20
21[tool.hatch.build.targets.sdist]
22# 原始碼發布設定
23include = [
24 "/src",
25 "/tests",
26 "/README.md",
27 "/LICENSE.txt",
28]
29
30[tool.hatch.build.targets.wheel]
31# Wheel 發布設定
32packages = ["src/my_awesome_lib"]
33
34# 只包含特定平台
35# only-include = ["my_awesome_lib"]

[tool.hatch.envs] 環境設定

 1[tool.hatch.envs.default]
 2# 相依性
 3dependencies = ["pytest"]
 4
 5# 額外安裝的 features
 6features = ["yaml"]
 7
 8# 環境變數
 9[tool.hatch.envs.default.env-vars]
10PYTHONPATH = "src"
11LOG_LEVEL = "DEBUG"
12
13# 腳本定義
14[tool.hatch.envs.default.scripts]
15test = "pytest {args}"
16
17# 平台特定設定
18[tool.hatch.envs.default.overrides]
19platform.windows.scripts = [
20 'test = "pytest --no-header {args}"',
21]

[tool.hatch.version] 版本設定

 1# 從檔案讀取
 2[tool.hatch.version]
 3path = "src/my_awesome_lib/__about__.py"
 4pattern = "^__version__ = ['\"](/python-advanced/07-packaging/case-studies/hatch-workflow/?P<version>[^'\"]+)['\"]"
 5
 6# 從 VCS 讀取
 7[tool.hatch.version]
 8source = "vcs"
 9raw-options = { local_scheme = "no-local-version" }
10
11[tool.hatch.build.hooks.vcs]
12version-file = "src/my_awesome_lib/_version.py"

[tool.hatch.metadata] 元資料設定

 1[tool.hatch.metadata]
 2# 允許直接依賴（通常應該避免）
 3allow-direct-references = false
 4
 5# 動態讀取 README
 6[tool.hatch.metadata.hooks.fancy-pypi-readme]
 7content-type = "text/markdown"
 8
 9[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
10path = "README.md"

與 Poetry 的比較

設計理念差異

 1Hatch：
 2├── 遵循 PEP 標準優先
 3├── 環境管理內建
 4├── 不提供依賴鎖定
 5├── 建構系統（hatchling）可獨立使用
 6└── 設定完全在 [tool.hatch]
 7
 8Poetry：
 9├── 自有生態系統
10├── 強調依賴鎖定（poetry.lock）
11├── 虛擬環境管理
12├── poetry.core 可獨立使用
13└── 混合 [project] 和 [tool.poetry]

功能對照

功能	Hatch	Poetry
依賴鎖定	不支援	poetry.lock
環境管理	內建矩陣支援	單一環境
PEP 621	完全支援	Poetry 2.0 支援
腳本系統	強大（環境分離）	基本
版本管理	內建 bump	需外掛或手動
插件系統	支援	支援

pyproject.toml 比較

Hatch 風格

 1[build-system]
 2requires = ["hatchling"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6name = "my-package"
 7version = "1.0.0"
 8dependencies = ["requests>=2.28"]
 9
10[project.optional-dependencies]
11dev = ["pytest>=8.0"]
12
13[tool.hatch.envs.default]
14features = ["dev"]

Poetry 風格（2.0）

 1[build-system]
 2requires = ["poetry-core>=2.0"]
 3build-backend = "poetry.core.masonry.api"
 4
 5[project]
 6name = "my-package"
 7version = "1.0.0"
 8dependencies = ["requests>=2.28"]
 9
10[tool.poetry.group.dev.dependencies]
11pytest = "^8.0"

選擇建議

 1選擇 Hatch：
 2├── 開發 Python 函式庫
 3├── 需要多環境測試
 4├── 偏好標準優先
 5└── 不需要依賴鎖定
 6
 7選擇 Poetry：
 8├── 開發應用程式
 9├── 需要嚴格的依賴鎖定
10├── 團隊習慣 Poetry 工作流
11└── 需要與現有 Poetry 專案整合

實用技巧

多環境測試矩陣

 1# 定義多 Python 版本測試
 2[tool.hatch.envs.test]
 3dependencies = ["pytest", "pytest-cov"]
 4
 5[[tool.hatch.envs.test.matrix]]
 6python = ["3.9", "3.10", "3.11", "3.12", "3.13"]
 7
 8[tool.hatch.envs.test.scripts]
 9run = "pytest {args:tests}"
10cov = "pytest --cov=my_awesome_lib {args:tests}"

1# 在所有矩陣環境執行測試
2hatch run test:run
3
4# 在特定版本執行
5hatch run +py=3.12 test:run
6
7# 顯示矩陣環境
8hatch env show --ascii

複合腳本

 1[tool.hatch.envs.default.scripts]
 2# 單一命令
 3test = "pytest {args:tests}"
 4
 5# 多命令（依序執行）
 6ci = [
 7 "ruff check src tests",
 8 "pytest --cov",
 9 "mypy src",
10]
11
12# 呼叫其他腳本
13all = ["lint:check", "test:cov"]
14
15# 帶預設參數
16lint = "ruff check {args:.}"

環境繼承

 1# 基礎環境
 2[tool.hatch.envs.base]
 3dependencies = ["pytest"]
 4
 5# 繼承基礎環境
 6[tool.hatch.envs.coverage]
 7template = "base"
 8dependencies = ["pytest-cov"]
 9
10[tool.hatch.envs.coverage.scripts]
11run = "pytest --cov {args:tests}"

條件依賴

 1[tool.hatch.envs.default]
 2dependencies = [
 3 "pytest",
 4]
 5
 6# 根據平台新增依賴
 7[tool.hatch.envs.default.overrides]
 8platform.linux.dependencies = ["pytest-xdist"]
 9platform.darwin.dependencies = ["pytest-xdist"]
10
11# 根據 Python 版本
12python.3.8.dependencies = ["typing-extensions"]

自訂建構 Hook

1[tool.hatch.build.hooks.custom]
2# 建構前執行
3path = "hatch_build.py"

1# hatch_build.py
2from hatchling.builders.hooks.plugin.interface import BuildHookInterface
3
4class CustomBuildHook(BuildHookInterface):
5 def initialize(self, version, build_data):
6 # 建構前的自訂邏輯
7 print(f"Building version {version}")

完整範例：CLI 應用程式

 1# pyproject.toml
 2[build-system]
 3requires = ["hatchling"]
 4build-backend = "hatchling.build"
 5
 6[project]
 7name = "my-cli"
 8dynamic = ["version"]
 9description = "A useful CLI tool"
10readme = "README.md"
11requires-python = ">=3.10"
12license = "MIT"
13dependencies = [
14 "click>=8.0",
15 "rich>=13.0",
16]
17
18[project.scripts]
19my-cli = "my_cli.main:app"
20
21[project.optional-dependencies]
22yaml = ["PyYAML>=6.0"]
23
24[tool.hatch.version]
25path = "src/my_cli/__about__.py"
26
27[tool.hatch.build.targets.wheel]
28packages = ["src/my_cli"]
29
30# ===== 環境設定 =====
31
32[tool.hatch.envs.default]
33dependencies = [
34 "pytest>=8.0",
35 "pytest-cov>=4.0",
36]
37
38[tool.hatch.envs.default.scripts]
39test = "pytest {args:tests}"
40cov = "pytest --cov=my_cli --cov-report=term-missing {args:tests}"
41
42[tool.hatch.envs.lint]
43dependencies = [
44 "ruff>=0.4",
45 "mypy>=1.0",
46]
47
48[tool.hatch.envs.lint.scripts]
49check = ["ruff check src tests", "ruff format --check src tests"]
50fix = ["ruff check --fix src tests", "ruff format src tests"]
51typing = "mypy src"
52all = ["check", "typing"]
53
54[[tool.hatch.envs.test.matrix]]
55python = ["3.10", "3.11", "3.12", "3.13"]
56
57# ===== 工具設定 =====
58
59[tool.ruff]
60src = ["src"]
61line-length = 88
62
63[tool.ruff.lint]
64select = ["E", "W", "F", "I", "B", "UP"]
65
66[tool.mypy]
67python_version = "3.10"
68strict = true
69
70[tool.pytest.ini_options]
71testpaths = ["tests"]
72addopts = "-v"

發布檢查清單

 1發布前檢查：
 2├── [ ] hatch run lint:all 通過
 3├── [ ] hatch run test:run 在所有 Python 版本通過
 4├── [ ] hatch version 更新版本號
 5├── [ ] 更新 CHANGELOG.md
 6├── [ ] hatch build 建構成功
 7├── [ ] 在虛擬環境測試安裝：pip install dist/*.whl
 8├── [ ] hatch publish --repo test 發布到 TestPyPI
 9├── [ ] 從 TestPyPI 測試安裝
10└── [ ] hatch publish 發布到 PyPI

延伸閱讀

返回：案例研究