Packaging 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）

參考答案

6.1 pyproject.toml 完整指南

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

本章介紹 pyproject.toml 的結構與設定方式。

本章目標

學完本章後，你將能夠：

理解 pyproject.toml 的三個主要表
設定專案元數據（PEP 621）
設定建構系統（PEP 518）

【原理層】pyproject.toml 的演進

歷史背景

1Python 打包的演進：
2├── 2000s: setup.py（純 Python 腳本）
3├── 2010s: setup.cfg（宣告式設定）
4├── 2016: PEP 518（pyproject.toml 誕生）
5├── 2020: PEP 621（標準化元數據）
6└── 2025: pyproject.toml 成為主流標準

為什麼需要 pyproject.toml？

 1setup.py 的問題：
 2├── 需要執行程式碼才能讀取元數據
 3├── 安全風險（任意程式碼執行）
 4├── 無法標準化建構依賴
 5└── 不同工具使用不同設定檔
 6
 7pyproject.toml 的優點：
 8├── 靜態設定，不需執行
 9├── 標準化格式（TOML）
10├── 統一的設定位置
11└── 支援多種建構後端

PEP	內容	狀態
PEP 518	build-system 表	已採納
PEP 621	project 元數據	已採納
PEP 639	license 欄位改進	已採納
PEP 660	可編輯安裝	已採納
PEP 735	依賴群組	草案中

【設計層】三個主要表

檔案結構總覽

 1# pyproject.toml 的三個主要表
 2
 3[build-system]
 4# 定義如何建構套件
 5requires = ["setuptools>=61.0"]
 6build-backend = "setuptools.build_meta"
 7
 8[project]
 9# 定義套件的元數據
10name = "my-package"
11version = "1.0.0"
12# ...
13
14[tool.xxx]
15# 各種工具的設定
16# [tool.setuptools], [tool.pytest], [tool.ruff], etc.

[build-system]：建構設定

 1[build-system]
 2# 建構時需要的套件（PEP 518）
 3requires = [
 4 "setuptools>=61.0",
 5 "wheel",
 6 # 如果有 C 擴展
 7 # "cython>=3.0",
 8]
 9
10# 建構後端（PEP 517）
11build-backend = "setuptools.build_meta"
12
13# 選用：後端路徑（較少使用）
14# backend-path = ["."]

常見的建構後端：

1建構後端 requires
2─────────────────────────────────────────────────────
3setuptools.build_meta ["setuptools>=61.0"]
4flit_core.buildapi ["flit_core>=3.4"]
5hatchling.build ["hatchling"]
6poetry.core.masonry.api ["poetry-core>=1.0.0"]
7maturin ["maturin>=1.5"]
8scikit_build_core.build ["scikit-build-core>=0.5"]
9mesonpy ["meson-python"]

[project]：專案元數據

 1[project]
 2# === 必填欄位 ===
 3name = "my-awesome-package"
 4version = "1.0.0"
 5
 6# === 基本資訊 ===
 7description = "A short description of the package"
 8readme = "README.md" # 或 {file = "README.md", content-type = "text/markdown"}
 9license = {text = "MIT"} # 或 {file = "LICENSE"}
10requires-python = ">=3.8"
11
12# === 作者資訊 ===
13authors = [
14 {name = "Your Name", email = "you@example.com"},
15]
16maintainers = [
17 {name = "Maintainer", email = "maintainer@example.com"},
18]
19
20# === 分類與關鍵字 ===
21keywords = ["example", "package", "demo"]
22classifiers = [
23 "Development Status :: 4 - Beta",
24 "Intended Audience :: Developers",
25 "License :: OSI Approved :: MIT License",
26 "Programming Language :: Python :: 3",
27 "Programming Language :: Python :: 3.8",
28 "Programming Language :: Python :: 3.9",
29 "Programming Language :: Python :: 3.10",
30 "Programming Language :: Python :: 3.11",
31 "Programming Language :: Python :: 3.12",
32]
33
34# === URL ===
35[project.urls]
36Homepage = "https://github.com/user/project"
37Documentation = "https://project.readthedocs.io"
38Repository = "https://github.com/user/project"
39Changelog = "https://github.com/user/project/blob/main/CHANGELOG.md"
40
41# === 依賴 ===
42dependencies = [
43 "requests>=2.28",
44 "click>=8.0",
45]
46
47[project.optional-dependencies]
48dev = [
49 "pytest>=7.0",
50 "pytest-cov",
51 "ruff",
52 "mypy",
53]
54docs = [
55 "sphinx>=6.0",
56 "sphinx-rtd-theme",
57]
58
59# === 入口點 ===
60[project.scripts]
61my-cli = "my_package.cli:main"
62
63[project.gui-scripts]
64my-gui = "my_package.gui:main"
65
66[project.entry-points."my_package.plugins"]
67plugin1 = "my_package.plugins.plugin1:Plugin"

[tool.xxx]：工具設定

 1# === setuptools 設定 ===
 2[tool.setuptools]
 3packages = ["my_package"]
 4# 或使用自動發現
 5package-dir = {"" = "src"}
 6
 7[tool.setuptools.packages.find]
 8where = ["src"]
 9
10[tool.setuptools.package-data]
11my_package = ["*.json", "data/*"]
12
13# === pytest 設定 ===
14[tool.pytest.ini_options]
15testpaths = ["tests"]
16python_files = ["test_*.py"]
17addopts = "-v --cov=my_package"
18
19# === ruff 設定 ===
20[tool.ruff]
21line-length = 88
22target-version = "py38"
23
24[tool.ruff.lint]
25select = ["E", "F", "W", "I", "UP"]
26ignore = ["E501"]
27
28# === mypy 設定 ===
29[tool.mypy]
30python_version = "3.8"
31strict = true
32warn_return_any = true
33
34# === coverage 設定 ===
35[tool.coverage.run]
36source = ["my_package"]
37branch = true
38
39[tool.coverage.report]
40exclude_lines = [
41 "pragma: no cover",
42 "if TYPE_CHECKING:",
43]

【實作層】完整範例

最小可行設定

1# 最小的 pyproject.toml
2[build-system]
3requires = ["setuptools>=61.0"]
4build-backend = "setuptools.build_meta"
5
6[project]
7name = "my-package"
8version = "0.1.0"

標準函式庫風格

 1[build-system]
 2requires = ["setuptools>=61.0"]
 3build-backend = "setuptools.build_meta"
 4
 5[project]
 6name = "my-package"
 7version = "1.0.0"
 8description = "A well-documented Python package"
 9readme = "README.md"
10license = {text = "MIT"}
11requires-python = ">=3.8"
12authors = [{name = "Your Name", email = "you@example.com"}]
13classifiers = [
14 "Development Status :: 4 - Beta",
15 "Intended Audience :: Developers",
16 "License :: OSI Approved :: MIT License",
17 "Operating System :: OS Independent",
18 "Programming Language :: Python :: 3",
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 "Typing :: Typed",
25]
26dependencies = []
27
28[project.optional-dependencies]
29dev = ["pytest>=7.0", "ruff", "mypy"]
30
31[project.urls]
32Homepage = "https://github.com/user/my-package"
33Repository = "https://github.com/user/my-package"
34
35[tool.setuptools.packages.find]
36where = ["src"]

含 CLI 的應用程式

 1[build-system]
 2requires = ["setuptools>=61.0"]
 3build-backend = "setuptools.build_meta"
 4
 5[project]
 6name = "my-cli-tool"
 7version = "2.0.0"
 8description = "A powerful CLI tool"
 9readme = "README.md"
10license = {text = "Apache-2.0"}
11requires-python = ">=3.9"
12authors = [{name = "CLI Team"}]
13dependencies = [
14 "click>=8.0",
15 "rich>=13.0",
16]
17
18[project.optional-dependencies]
19dev = ["pytest", "pytest-cov"]
20
21[project.scripts]
22my-tool = "my_cli_tool.main:cli"
23
24[project.urls]
25Homepage = "https://my-cli-tool.dev"
26
27[tool.setuptools.packages.find]
28where = ["src"]
29
30[tool.setuptools.package-data]
31my_cli_tool = ["templates/*.txt", "config/*.yaml"]

【進階】動態欄位

動態版本

1[project]
2name = "my-package"
3dynamic = ["version"] # 版本由其他來源決定
4
5[tool.setuptools.dynamic]
6version = {attr = "my_package.__version__"}
7# 或從檔案讀取
8# version = {file = "VERSION"}

1# src/my_package/__init__.py
2__version__ = "1.2.3"

動態依賴

1[project]
2name = "my-package"
3dynamic = ["dependencies", "optional-dependencies"]
4
5[tool.setuptools.dynamic]
6dependencies = {file = ["requirements.txt"]}
7optional-dependencies.dev = {file = ["requirements-dev.txt"]}

使用 setuptools-scm（Git 標籤版本）

 1[build-system]
 2requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
 3build-backend = "setuptools.build_meta"
 4
 5[project]
 6name = "my-package"
 7dynamic = ["version"]
 8
 9[tool.setuptools_scm]
10# 版本從 git tag 自動產生
11# v1.0.0 -> 1.0.0
12# v1.0.0-2-gabcdef -> 1.0.0.dev2+gabcdef

【實作層】專案結構對應

Flat Layout

1my-package/
2├── pyproject.toml
3├── README.md
4├── my_package/
5│ ├── __init__.py
6│ └── module.py
7└── tests/
8 └── test_module.py

1[tool.setuptools]
2packages = ["my_package"]

Src Layout（推薦）

1my-package/
2├── pyproject.toml
3├── README.md
4├── src/
5│ └── my_package/
6│ ├── __init__.py
7│ └── module.py
8└── tests/
9 └── test_module.py

1[tool.setuptools.packages.find]
2where = ["src"]

為什麼推薦 src layout？

1Src Layout 的優點：
2├── 避免匯入本地未安裝的套件
3├── 強制測試已安裝的版本
4├── 清楚區分原始碼和專案根目錄
5└── 避免名稱衝突

【進階】PEP 639 授權條款

新的 license 語法

 1# PEP 639（Python 3.14+，但建構工具已支援）
 2
 3# SPDX 表示法
 4[project]
 5license = "MIT"
 6# 或
 7license = "Apache-2.0 OR MIT"
 8# 或
 9license = "GPL-3.0-only"
10
11# 授權檔案
12license-files = ["LICENSE", "LICENSES/*"]

常見的 SPDX 識別碼

 1識別碼 完整名稱
 2─────────────────────────────────────────
 3MIT MIT License
 4Apache-2.0 Apache License 2.0
 5GPL-3.0-only GNU GPL v3.0 only
 6GPL-3.0-or-later GNU GPL v3.0 or later
 7BSD-3-Clause BSD 3-Clause License
 8BSD-2-Clause BSD 2-Clause License
 9MPL-2.0 Mozilla Public License 2.0
10LGPL-3.0-only GNU LGPL v3.0 only
11ISC ISC License
12Unlicense The Unlicense

【驗證】檢查設定

使用 validate-pyproject

1pip install validate-pyproject
2
3# 驗證 pyproject.toml
4validate-pyproject pyproject.toml

使用 build 測試建構

1pip install build
2
3# 建構套件（會驗證設定）
4python -m build
5
6# 建構結果
7ls dist/
8# my_package-1.0.0.tar.gz
9# my_package-1.0.0-py3-none-any.whl

常見錯誤

 1錯誤：Unknown key in [project]
 2原因：使用了非標準欄位
 3解決：檢查 PEP 621 允許的欄位
 4
 5錯誤：Invalid version
 6原因：版本格式不符合 PEP 440
 7解決：使用正確格式，如 "1.0.0", "1.0.0a1", "1.0.0.dev1"
 8
 9錯誤：Missing required key
10原因：缺少必填欄位
11解決：至少要有 name 和 version（或 dynamic）

思考題

為什麼 Python 社群花了這麼長時間才標準化打包設定？
[build-system] 中的 requires 和 [project] 中的 dependencies 有什麼區別？
動態欄位在什麼情況下有用？有什麼潛在問題？

實作練習

將一個使用 setup.py 的舊專案遷移到 pyproject.toml
建立一個包含 CLI 入口點的套件，並在本地測試安裝
使用 setuptools-scm 設定自動版本管理

延伸閱讀

下一章：建構系統比較

案例：使用 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 建立一個簡單的專案

6.2 建構系統比較

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

本章比較主流的 Python 套件建構系統。

本章目標

學完本章後，你將能夠：

理解不同建構系統的設計理念
根據專案需求選擇適合的工具
在不同工具之間遷移

【總覽】建構系統生態

建構後端 vs 建構前端

 1建構前端（Frontend）：使用者互動的工具
 2├── pip
 3├── build
 4└── 各工具的 CLI（poetry, hatch, etc.）
 5
 6建構後端（Backend）：實際執行建構的程式
 7├── setuptools.build_meta
 8├── flit_core.buildapi
 9├── hatchling.build
10├── poetry.core.masonry.api
11└── maturin, scikit-build-core, mesonpy

主流工具比較

工具	定位	特點	適用場景
setuptools	建構後端	歷史最久，功能最全	一般專案、C 擴展
Flit	建構後端	極簡設計	純 Python 小型專案
Hatch	全套工具	現代設計，環境管理	新專案
Poetry	全套工具	依賴鎖定，虛擬環境	應用程式開發
PDM	全套工具	PEP 582，快速	實驗性專案

【工具一】setuptools

特點與定位

1setuptools：
2├── Python 打包的「標準」
3├── 歷史最悠久（2004 年開始）
4├── 支援所有功能（C 擴展、資料檔案等）
5├── 學習曲線較陡
6└── PEP 621 支援（61.0.0+ 版本）

基本設定

 1# pyproject.toml
 2[build-system]
 3requires = ["setuptools>=61.0"]
 4build-backend = "setuptools.build_meta"
 5
 6[project]
 7name = "my-package"
 8version = "1.0.0"
 9dependencies = ["requests"]
10
11[tool.setuptools.packages.find]
12where = ["src"]

進階設定

 1[tool.setuptools]
 2# 明確指定套件
 3packages = ["my_package", "my_package.submodule"]
 4
 5# 包含資料檔案
 6package-data = {"my_package" = ["*.json", "data/*"]}
 7
 8# 排除檔案
 9exclude-package-data = {"my_package" = ["test_*"]}
10
11# Zip 安全（是否可以作為 zip 檔案匯入）
12zip-safe = false
13
14[tool.setuptools.dynamic]
15version = {attr = "my_package.__version__"}
16readme = {file = ["README.md"]}

C 擴展支援

1# pyproject.toml
2[build-system]
3requires = ["setuptools>=61.0", "cython>=3.0"]
4build-backend = "setuptools.build_meta"

 1# setup.py（仍需要用於複雜的 C 擴展）
 2from setuptools import setup, Extension
 3from Cython.Build import cythonize
 4
 5extensions = [
 6 Extension(
 7 "my_package.fast_module",
 8 ["src/my_package/fast_module.pyx"],
 9 )
10]
11
12setup(
13 ext_modules=cythonize(extensions),
14)

常用命令

1# 建構
2python -m build
3
4# 可編輯安裝
5pip install -e .
6
7# 開發模式（含額外依賴）
8pip install -e ".[dev]"

【工具二】Flit

特點與定位

1Flit：
2├── 極簡設計
3├── 只支援純 Python 套件
4├── 不支援 C 擴展
5├── 快速建構
6└── 適合簡單函式庫

基本設定

 1# pyproject.toml
 2[build-system]
 3requires = ["flit_core>=3.4"]
 4build-backend = "flit_core.buildapi"
 5
 6[project]
 7name = "my-package"
 8version = "1.0.0"
 9description = "A simple package"
10authors = [{name = "Your Name", email = "you@example.com"}]
11dependencies = ["requests"]
12
13# Flit 自動從 __init__.py 讀取 docstring 和 version
14# 所以常常不需要設定 description 和 version

1# src/my_package/__init__.py
2"""A simple package for doing things."""
3__version__ = "1.0.0"

常用命令

 1# 安裝 flit
 2pip install flit
 3
 4# 建構
 5flit build
 6
 7# 發布
 8flit publish
 9
10# 可編輯安裝
11flit install --symlink # Unix
12flit install --pth-file # Windows

限制

1Flit 不支援：
2├── C/C++/Rust 擴展
3├── 複雜的建構腳本
4├── 資料檔案的細粒度控制
5├── 動態版本（需要在 __init__.py 中定義）
6└── 依賴鎖定

【工具三】Hatch

特點與定位

1Hatch：
2├── 現代化設計
3├── 環境管理（類似 tox）
4├── 版本管理
5├── 腳本系統
6├── PEP 標準優先
7└── 由 PyPA 成員維護

基本設定

 1# pyproject.toml
 2[build-system]
 3requires = ["hatchling"]
 4build-backend = "hatchling.build"
 5
 6[project]
 7name = "my-package"
 8version = "1.0.0"
 9dependencies = ["requests"]
10
11[tool.hatch.build.targets.wheel]
12packages = ["src/my_package"]
13
14[tool.hatch.build.targets.sdist]
15include = ["/src", "/tests"]

環境管理

 1# 定義環境
 2[tool.hatch.envs.default]
 3dependencies = ["pytest", "pytest-cov"]
 4
 5[tool.hatch.envs.default.scripts]
 6test = "pytest {args:tests}"
 7cov = "pytest --cov=my_package {args:tests}"
 8
 9[tool.hatch.envs.lint]
10dependencies = ["ruff", "mypy"]
11
12[tool.hatch.envs.lint.scripts]
13check = ["ruff check .", "mypy src"]
14fix = "ruff check --fix ."
15
16[tool.hatch.envs.docs]
17dependencies = ["sphinx", "sphinx-rtd-theme"]
18
19[tool.hatch.envs.docs.scripts]
20build = "sphinx-build -b html docs docs/_build"

版本管理

1[tool.hatch.version]
2path = "src/my_package/__init__.py"
3
4# 或使用 hatch-vcs 從 git 標籤讀取
5# [tool.hatch.version]
6# source = "vcs"
7#
8# [tool.hatch.build.hooks.vcs]
9# version-file = "src/my_package/_version.py"

常用命令

 1# 安裝 hatch
 2pip install hatch
 3
 4# 建立新專案
 5hatch new my-package
 6
 7# 執行腳本
 8hatch run test
 9hatch run lint:check
10
11# 進入環境 shell
12hatch shell
13
14# 版本管理
15hatch version # 顯示當前版本
16hatch version minor # 升級 minor 版本
17hatch version 2.0.0 # 設定特定版本
18
19# 建構
20hatch build
21
22# 發布
23hatch publish

【工具四】Poetry

特點與定位

1Poetry：
2├── 依賴解析與鎖定
3├── 虛擬環境管理
4├── 發布流程整合
5├── 自己的設定格式（[tool.poetry]）
6├── Poetry 2.0 支援 [project] 表
7└── 適合應用程式開發

基本設定（Poetry 2.0+）

 1# pyproject.toml（Poetry 2.0 風格）
 2[build-system]
 3requires = ["poetry-core>=2.0"]
 4build-backend = "poetry.core.masonry.api"
 5
 6[project]
 7name = "my-package"
 8version = "1.0.0"
 9description = "My awesome package"
10authors = [{name = "Your Name", email = "you@example.com"}]
11dependencies = ["requests>=2.28"]
12requires-python = ">=3.8"
13
14[project.optional-dependencies]
15dev = ["pytest>=7.0", "ruff"]
16
17# Poetry 特定設定仍在 [tool.poetry]
18[tool.poetry]
19packages = [{include = "my_package", from = "src"}]
20
21[tool.poetry.group.dev.dependencies]
22pytest = "^7.0"
23ruff = "^0.1"

傳統設定（Poetry 1.x）

 1# pyproject.toml（舊風格，仍支援）
 2[tool.poetry]
 3name = "my-package"
 4version = "1.0.0"
 5description = "My awesome package"
 6authors = ["Your Name <you@example.com>"]
 7
 8[tool.poetry.dependencies]
 9python = "^3.8"
10requests = "^2.28"
11
12[tool.poetry.group.dev.dependencies]
13pytest = "^7.0"
14ruff = "^0.1"
15
16[build-system]
17requires = ["poetry-core>=1.0.0"]
18build-backend = "poetry.core.masonry.api"

依賴鎖定

 1# poetry.lock 檔案
 2# - 記錄所有依賴的精確版本
 3# - 確保團隊成員使用相同版本
 4# - 應該提交到版本控制
 5
 6# 安裝（使用 lock 檔案）
 7poetry install
 8
 9# 更新依賴
10poetry update
11
12# 新增依賴
13poetry add requests
14poetry add pytest --group dev
15
16# 移除依賴
17poetry remove requests

常用命令

 1# 安裝 poetry
 2pip install poetry
 3# 或官方推薦的安裝方式
 4curl -sSL https://install.python-poetry.org | python3 -
 5
 6# 建立新專案
 7poetry new my-package
 8poetry init # 在現有目錄初始化
 9
10# 虛擬環境
11poetry env use python3.11
12poetry shell # 進入虛擬環境
13
14# 執行命令
15poetry run python script.py
16poetry run pytest
17
18# 建構與發布
19poetry build
20poetry publish
21
22# 設定 PyPI token
23poetry config pypi-token.pypi <your-token>

【工具五】PDM

特點與定位

1PDM：
2├── 支援 PEP 582（__pypackages__）
3├── 快速的依賴解析
4├── 支援 PEP 621
5├── 插件系統
6└── 實驗性功能多

基本設定

 1# pyproject.toml
 2[build-system]
 3requires = ["pdm-backend"]
 4build-backend = "pdm.backend"
 5
 6[project]
 7name = "my-package"
 8version = "1.0.0"
 9dependencies = ["requests"]
10
11[tool.pdm]
12distribution = true
13
14[tool.pdm.dev-dependencies]
15dev = ["pytest", "ruff"]

常用命令

 1# 安裝 pdm
 2pip install pdm
 3
 4# 初始化專案
 5pdm init
 6
 7# 依賴管理
 8pdm add requests
 9pdm add -d pytest # 開發依賴
10pdm remove requests
11pdm update
12
13# 執行
14pdm run python script.py
15pdm run pytest
16
17# 建構
18pdm build
19pdm publish

【選擇指南】決策流程

決策樹

 1需要選擇建構系統？
 2│
 3├── 需要 C/Rust 擴展？
 4│ ├── 是 → setuptools + Cython/pybind11
 5│ │ 或 maturin（Rust）
 6│ └── 否 ↓
 7│
 8├── 需要依賴鎖定？
 9│ ├── 是 → Poetry 或 PDM
10│ └── 否 ↓
11│
12├── 需要環境管理？
13│ ├── 是 → Hatch 或 Poetry
14│ └── 否 ↓
15│
16├── 極簡專案？
17│ ├── 是 → Flit
18│ └── 否 → setuptools 或 Hatch

場景建議

1場景 推薦工具
2─────────────────────────────────────────────────────
3純 Python 函式庫 Flit 或 Hatch
4Web 應用程式 Poetry
5資料科學專案 Poetry 或 PDM
6有 C 擴展的函式庫 setuptools
7Rust 擴展 Maturin
8開源專案（多貢獻者） Hatch 或 setuptools
9內部工具 Poetry

遷移考量

 1從 setup.py 遷移：
 2├── 純 Python → 任何工具都可以
 3├── 有 C 擴展 → setuptools（保留部分 setup.py）
 4└── 複雜建構 → 保持 setuptools
 5
 6從 Poetry 1.x 遷移到 2.0：
 7├── 更新 poetry-core 版本
 8├── 可選：將 [tool.poetry.dependencies] 移到 [project]
 9└── 測試建構和安裝
10
11工具之間遷移：
12├── 所有現代工具都支援 PEP 621
13├── 主要差異在 [tool.xxx] 設定
14└── 依賴鎖定檔案不相容

【比較】功能對照表

核心功能

功能	setuptools	Flit	Hatch	Poetry
PEP 621	支援	支援	支援	支援 (2.0)
C 擴展	支援	不支援	不支援	不支援
環境管理	不支援	不支援	支援	支援
依賴鎖定	不支援	不支援	不支援	支援
腳本系統	不支援	不支援	支援	支援
版本管理	有限	不支援	支援	支援
插件系統	支援	不支援	支援	支援

效能比較

1建構速度（純 Python 專案）：
2Flit > Hatch > Poetry > setuptools
3
4依賴解析速度：
5PDM > Poetry > pip
6
7安裝速度：
8pip + lock file > Poetry > PDM

思考題

為什麼 Python 社群有這麼多打包工具？這是好事還是壞事？
依賴鎖定對函式庫和應用程式的重要性有什麼不同？
如果要開始一個新的開源專案，你會選擇哪個工具？為什麼？

實作練習

用 setuptools、Flit、Hatch 三種工具建立相同的簡單套件，比較設定檔的差異
使用 Poetry 建立一個有依賴鎖定的專案，模擬團隊協作場景
將一個現有的 setup.py 專案遷移到 pyproject.toml

延伸閱讀

上一章：pyproject.toml 完整指南 下一章：發布到 PyPI

案例：使用 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

延伸閱讀

返回：案例研究

5.3 Maturin 開發流程

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

本章介紹 Maturin，Rust Python 套件的建構工具。

本章目標

學完本章後，你將能夠：

設定 Maturin 專案
使用 maturin develop 快速迭代
建構跨平台 wheel 並發布到 PyPI

【原理層】Maturin 是什麼？

建構工具的角色

 1傳統 Python 擴展建構：
 2├── setuptools + setup.py
 3├── 複雜的編譯器設定
 4├── 手動處理連結問題
 5└── 跨平台建構困難
 6
 7Maturin 提供：
 8├── 一鍵建構 Rust Python 套件
 9├── 自動處理 PyO3 設定
10├── 跨平台 wheel 生成
11├── 與 pyproject.toml 整合
12└── 開發模式快速迭代

支援的專案類型

1Maturin 支援：
2├── pyo3：純 Rust 擴展（最常用）
3├── cffi：生成 cffi 綁定
4├── uniffi：跨語言綁定
5└── bin：Rust 二進位程式打包

【設計層】專案設定

安裝 Maturin

 1# 使用 pip
 2pip install maturin
 3
 4# 使用 pipx（推薦，隔離環境）
 5pipx install maturin
 6
 7# 使用 cargo
 8cargo install maturin
 9
10# 驗證安裝
11maturin --version

建立新專案

 1# 互動式建立
 2maturin new my_rust_module
 3cd my_rust_module
 4
 5# 或者指定綁定類型
 6maturin new my_rust_module --bindings pyo3
 7
 8# 專案結構
 9my_rust_module/
10├── Cargo.toml
11├── pyproject.toml
12├── src/
13│ └── lib.rs
14└── python/
15 └── my_rust_module/
16 └── __init__.py # 選用

pyproject.toml 設定

 1[build-system]
 2requires = ["maturin>=1.5,<2.0"]
 3build-backend = "maturin"
 4
 5[project]
 6name = "my-rust-module"
 7version = "0.1.0"
 8description = "A Python module written in Rust"
 9requires-python = ">=3.8"
10classifiers = [
11 "Programming Language :: Rust",
12 "Programming Language :: Python :: Implementation :: CPython",
13 "Programming Language :: Python :: Implementation :: PyPy",
14]
15
16[project.optional-dependencies]
17dev = ["pytest", "hypothesis"]
18
19[tool.maturin]
20# 模組名稱（如果與 crate 名稱不同）
21module-name = "my_rust_module"
22
23# Python 原始碼目錄（如果有純 Python 程式碼）
24python-source = "python"
25
26# 功能標誌
27features = ["pyo3/extension-module"]
28
29# 啟用 abi3
30# features = ["pyo3/extension-module", "pyo3/abi3-py38"]
31
32# 排除不需要的檔案
33exclude = ["tests/*", "benches/*"]
34
35# 建構設定
36# strip = true # 移除除錯符號（減小檔案大小）

Cargo.toml 設定

 1[package]
 2name = "my_rust_module"
 3version = "0.1.0"
 4edition = "2021"
 5
 6[lib]
 7name = "my_rust_module"
 8crate-type = ["cdylib"]
 9
10[dependencies]
11pyo3 = { version = "0.23", features = ["extension-module"] }
12
13[profile.release]
14lto = true # Link-Time Optimization
15codegen-units = 1 # 更好的優化
16strip = true # 移除除錯符號
17
18[profile.dev]
19opt-level = 0 # 快速編譯

【實作層】開發流程

maturin develop

 1# 開發模式：編譯並安裝到當前虛擬環境
 2maturin develop
 3
 4# 使用 release 模式（較慢但更快的執行時效能）
 5maturin develop --release
 6
 7# 指定功能
 8maturin develop --features "some-feature"
 9
10# 在其他虛擬環境中安裝
11maturin develop --target-dir target -E /path/to/venv
12
13# 使用後立即測試
14maturin develop && python -c "import my_rust_module; print(my_rust_module.add(1, 2))"

完整開發循環

 1# 1. 建立虛擬環境
 2python -m venv .venv
 3source .venv/bin/activate # Linux/macOS
 4# .venv\Scripts\activate # Windows
 5
 6# 2. 安裝開發依賴
 7pip install maturin pytest
 8
 9# 3. 開發循環
10while editing:
11 # 編輯 Rust 程式碼
12 vim src/lib.rs
13
14 # 建構並安裝
15 maturin develop
16
17 # 執行測試
18 pytest tests/
19
20# 4. 準備發布
21maturin build --release

混合 Python/Rust 專案

 1專案結構：
 2my_package/
 3├── Cargo.toml
 4├── pyproject.toml
 5├── src/
 6│ └── lib.rs # Rust 程式碼
 7└── python/
 8 └── my_package/
 9 ├── __init__.py # 匯入 Rust 模組
10 ├── utils.py # 純 Python 程式碼
11 └── py.typed # 型別標記

1# python/my_package/__init__.py
2from .my_package import * # 從 Rust 模組匯入
3from .utils import helper_function # 純 Python
4
5__version__ = "0.1.0"

1# pyproject.toml
2[tool.maturin]
3python-source = "python"
4module-name = "my_package.my_package"

【實作層】建構與發布

maturin build

 1# 建構 wheel
 2maturin build
 3
 4# Release 模式
 5maturin build --release
 6
 7# 指定 Python 版本
 8maturin build --interpreter python3.11
 9
10# 多個 Python 版本
11maturin build --interpreter python3.10 python3.11 python3.12
12
13# 使用 abi3（穩定 ABI）
14maturin build --release --features pyo3/abi3-py38
15
16# 建構結果位置
17ls target/wheels/
18# my_rust_module-0.1.0-cp311-cp311-linux_x86_64.whl

跨平台建構

 1# 使用 Docker 建構 manylinux wheel
 2maturin build --release --manylinux 2014
 3
 4# 常用的 manylinux 版本
 5# manylinux1: CentOS 5 (非常老舊)
 6# manylinux2010: CentOS 6
 7# manylinux2014: CentOS 7 (推薦)
 8# manylinux_2_28: Debian 9 / Ubuntu 18.04
 9
10# 使用 zig 進行交叉編譯
11pip install ziglang
12maturin build --release --target x86_64-unknown-linux-gnu --zig
13
14# 常見目標平台
15# x86_64-unknown-linux-gnu
16# aarch64-unknown-linux-gnu
17# x86_64-apple-darwin
18# aarch64-apple-darwin
19# x86_64-pc-windows-msvc

發布到 PyPI

 1# 發布到 TestPyPI（測試）
 2maturin publish --repository testpypi
 3
 4# 發布到 PyPI
 5maturin publish
 6
 7# 使用 API token
 8maturin publish --username __token__ --password <your-pypi-token>
 9
10# 或者設定環境變數
11export MATURIN_PYPI_TOKEN=<your-pypi-token>
12maturin publish

【實作層】CI/CD 整合

GitHub Actions

 1# .github/workflows/build.yml
 2name: Build and Publish
 3
 4on:
 5 push:
 6 tags:
 7 - 'v*'
 8 pull_request:
 9 branches:
 10 - main
 11
 12jobs:
 13 # Linux
 14 linux:
 15 runs-on: ubuntu-latest
 16 strategy:
 17 matrix:
 18 target: [x86_64, aarch64]
 19 steps:
 20 - uses: actions/checkout@v4
 21
 22 - uses: actions/setup-python@v5
 23 with:
 24 python-version: '3.11'
 25
 26 - name: Build wheels
 27 uses: PyO3/maturin-action@v1
 28 with:
 29 target: ${{ matrix.target }}
 30 args: --release --out dist
 31 manylinux: auto
 32
 33 - name: Upload wheels
 34 uses: actions/upload-artifact@v4
 35 with:
 36 name: wheels-linux-${{ matrix.target }}
 37 path: dist
 38
 39 # macOS
 40 macos:
 41 runs-on: macos-latest
 42 strategy:
 43 matrix:
 44 target: [x86_64, aarch64]
 45 steps:
 46 - uses: actions/checkout@v4
 47
 48 - uses: actions/setup-python@v5
 49 with:
 50 python-version: '3.11'
 51
 52 - name: Build wheels
 53 uses: PyO3/maturin-action@v1
 54 with:
 55 target: ${{ matrix.target }}-apple-darwin
 56 args: --release --out dist
 57
 58 - name: Upload wheels
 59 uses: actions/upload-artifact@v4
 60 with:
 61 name: wheels-macos-${{ matrix.target }}
 62 path: dist
 63
 64 # Windows
 65 windows:
 66 runs-on: windows-latest
 67 steps:
 68 - uses: actions/checkout@v4
 69
 70 - uses: actions/setup-python@v5
 71 with:
 72 python-version: '3.11'
 73
 74 - name: Build wheels
 75 uses: PyO3/maturin-action@v1
 76 with:
 77 args: --release --out dist
 78
 79 - name: Upload wheels
 80 uses: actions/upload-artifact@v4
 81 with:
 82 name: wheels-windows
 83 path: dist
 84
 85 # 發布
 86 publish:
 87 needs: [linux, macos, windows]
 88 runs-on: ubuntu-latest
 89 if: startsWith(github.ref, 'refs/tags/')
 90 steps:
 91 - uses: actions/download-artifact@v4
 92 with:
 93 pattern: wheels-*
 94 merge-multiple: true
 95 path: dist
 96
 97 - name: Publish to PyPI
 98 uses: PyO3/maturin-action@v1
 99 env:
100 MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
101 with:
102 command: upload
103 args: --non-interactive --skip-existing dist/*

測試工作流程

 1# .github/workflows/test.yml
 2name: Test
 3
 4on:
 5 push:
 6 branches: [main]
 7 pull_request:
 8
 9jobs:
10 test:
11 runs-on: ${{ matrix.os }}
12 strategy:
13 matrix:
14 os: [ubuntu-latest, macos-latest, windows-latest]
15 python-version: ['3.9', '3.10', '3.11', '3.12']
16 steps:
17 - uses: actions/checkout@v4
18
19 - uses: actions/setup-python@v5
20 with:
21 python-version: ${{ matrix.python-version }}
22
23 - name: Install Rust
24 uses: dtolnay/rust-toolchain@stable
25
26 - name: Install maturin
27 run: pip install maturin pytest
28
29 - name: Build and install
30 run: maturin develop
31
32 - name: Run tests
33 run: pytest tests/

【進階】效能優化

編譯優化

1# Cargo.toml
2[profile.release]
3lto = "fat" # 最佳化連結（較慢編譯）
4codegen-units = 1 # 單一編譯單元（更好優化）
5panic = "abort" # 不展開 panic（較小二進位）
6strip = true # 移除符號
7
8# 針對特定 CPU 優化
9# RUSTFLAGS="-C target-cpu=native" maturin build --release

減小二進位大小

 1# Cargo.toml
 2[profile.release]
 3opt-level = "z" # 優化大小而非速度
 4lto = true
 5strip = true
 6panic = "abort"
 7
 8[dependencies]
 9# 使用 features 減少不需要的程式碼
10pyo3 = { version = "0.23", default-features = false, features = ["extension-module"] }

除錯技巧

1# 保留除錯符號
2maturin develop --profile dev
3
4# 啟用 Rust backtrace
5RUST_BACKTRACE=1 python -c "import my_module; my_module.buggy_function()"
6
7# 使用 lldb/gdb
8lldb python
9(lldb) run -c "import my_module; my_module.buggy_function()"

【常見問題】疑難排解

編譯錯誤

 1問題：找不到 Python
 2
 3解決：
 41. 確認 Python 在 PATH 中
 52. 使用 --interpreter 指定路徑
 6 maturin develop --interpreter /usr/bin/python3.11
 7
 8問題：連結錯誤（Linux）
 9
10解決：
111. 安裝 python3-dev
12 sudo apt install python3-dev
132. 安裝 build-essential
14 sudo apt install build-essential
15
16問題：找不到 PyO3
17
18解決：
191. 確認 Cargo.toml 中有正確的 pyo3 依賴
202. 執行 cargo update

執行時錯誤

 1問題：ImportError: undefined symbol
 2
 3原因：模組和 Python 版本不匹配
 4
 5解決：
 61. 重新建構
 7 maturin develop
 82. 確認使用正確的 Python
 9 which python
10
11問題：記憶體錯誤 / Segfault
12
13原因：通常是 unsafe 程式碼或 GIL 問題
14
15解決：
161. 檢查 unsafe 區塊
172. 確認正確使用 py.allow_threads()
183. 使用 RUST_BACKTRACE=1 獲取堆疊追蹤

完整範例專案

專案結構

 1fibonacci_rs/
 2├── Cargo.toml
 3├── pyproject.toml
 4├── src/
 5│ └── lib.rs
 6├── python/
 7│ └── fibonacci_rs/
 8│ ├── __init__.py
 9│ └── py.typed
10├── tests/
11│ └── test_fib.py
12└── README.md

完整程式碼

 1# Cargo.toml
 2[package]
 3name = "fibonacci_rs"
 4version = "0.1.0"
 5edition = "2021"
 6
 7[lib]
 8name = "fibonacci_rs"
 9crate-type = ["cdylib"]
10
11[dependencies]
12pyo3 = { version = "0.23", features = ["extension-module"] }
13
14[profile.release]
15lto = true
16codegen-units = 1

 1# pyproject.toml
 2[build-system]
 3requires = ["maturin>=1.5,<2.0"]
 4build-backend = "maturin"
 5
 6[project]
 7name = "fibonacci-rs"
 8version = "0.1.0"
 9description = "Fast Fibonacci implementation in Rust"
10requires-python = ">=3.8"
11
12[tool.maturin]
13python-source = "python"
14module-name = "fibonacci_rs._core"

 1// src/lib.rs
 2use pyo3::prelude::*;
 3
 4/// 計算 Fibonacci 數列第 n 項
 5#[pyfunction]
 6fn fib(n: u64) -> u64 {
 7 if n <= 1 {
 8 return n;
 9 }
10 let mut a = 0u64;
11 let mut b = 1u64;
12 for _ in 2..=n {
13 let tmp = a + b;
14 a = b;
15 b = tmp;
16 }
17 b
18}
19
20/// 計算 Fibonacci 數列前 n 項
21#[pyfunction]
22fn fib_sequence(py: Python<'_>, n: usize) -> Vec<u64> {
23 py.allow_threads(|| {
24 let mut seq = Vec::with_capacity(n);
25 let (mut a, mut b) = (0u64, 1u64);
26 for _ in 0..n {
27 seq.push(a);
28 let tmp = a + b;
29 a = b;
30 b = tmp;
31 }
32 seq
33 })
34}
35
36#[pymodule]
37fn _core(m: &Bound<'_, PyModule>) -> PyResult<()> {
38 m.add_function(wrap_pyfunction!(fib, m)?)?;
39 m.add_function(wrap_pyfunction!(fib_sequence, m)?)?;
40 Ok(())
41}

1# python/fibonacci_rs/__init__.py
2from ._core import fib, fib_sequence
3
4__all__ = ["fib", "fib_sequence"]
5__version__ = "0.1.0"

 1# tests/test_fib.py
 2import fibonacci_rs
 3
 4def test_fib_zero():
 5 assert fibonacci_rs.fib(0) == 0
 6
 7def test_fib_one():
 8 assert fibonacci_rs.fib(1) == 1
 9
10def test_fib_ten():
11 assert fibonacci_rs.fib(10) == 55
12
13def test_fib_sequence():
14 seq = fibonacci_rs.fib_sequence(10)
15 assert seq == [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

思考題

為什麼 Maturin 使用 cdylib crate type？與 rlib 有什麼差異？
abi3 功能如何減少需要建構的 wheel 數量？有什麼限制？
在 CI 中建構跨平台 wheel 時，最大的挑戰是什麼？

實作練習

建立一個新的 Maturin 專案，實現一個簡單的字串處理函式
設定 GitHub Actions 自動建構並發布到 TestPyPI
比較 maturin develop 和 maturin develop --release 的編譯時間和執行效能

延伸閱讀

上一章：PyO3 基礎 下一章：實戰案例分析

6.3 發布到 PyPI

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

本章介紹如何將套件發布到 PyPI。

本章目標

學完本章後，你將能夠：

建構 sdist 和 wheel
使用 twine 上傳到 PyPI
設定 CI/CD 自動發布

【原理層】套件分發格式

sdist vs wheel

 1sdist（Source Distribution）：
 2├── 格式：.tar.gz
 3├── 內容：原始碼 + pyproject.toml
 4├── 安裝時需要建構
 5├── 可能需要編譯器（C 擴展）
 6└── 作為備用方案
 7
 8wheel（Built Distribution）：
 9├── 格式：.whl（實際上是 zip）
10├── 內容：已編譯的套件
11├── 安裝時直接解壓
12├── 不需要編譯器
13└── 安裝速度快

wheel 命名規則

 1{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl
 2
 3範例：
 4my_package-1.0.0-py3-none-any.whl
 5├── my_package: 套件名稱
 6├── 1.0.0: 版本
 7├── py3: Python 3
 8├── none: 無特定 ABI
 9└── any: 任何平台
10
11numpy-1.26.0-cp311-cp311-manylinux_2_17_x86_64.whl
12├── numpy: 套件名稱
13├── 1.26.0: 版本
14├── cp311: CPython 3.11
15├── cp311: CPython 3.11 ABI
16└── manylinux_2_17_x86_64: Linux x86_64

常見的 platform tag

 1純 Python：
 2├── py3-none-any（Python 3，任何平台）
 3├── py2.py3-none-any（Python 2 和 3）
 4
 5有 C 擴展：
 6├── cp311-cp311-manylinux_2_17_x86_64
 7├── cp311-cp311-macosx_11_0_arm64
 8├── cp311-cp311-win_amd64
 9
10使用 abi3（穩定 ABI）：
11└── cp38-abi3-manylinux_2_17_x86_64

【實作層】建構套件

使用 build 工具

 1# 安裝 build
 2pip install build
 3
 4# 建構 sdist 和 wheel
 5python -m build
 6
 7# 只建構 wheel
 8python -m build --wheel
 9
10# 只建構 sdist
11python -m build --sdist
12
13# 建構結果
14ls dist/
15# my_package-1.0.0.tar.gz     (sdist)
16# my_package-1.0.0-py3-none-any.whl  (wheel)

檢查建構結果

 1# 安裝 twine
 2pip install twine
 3
 4# 檢查套件
 5twine check dist/*
 6
 7# 檢查 wheel 內容
 8unzip -l dist/my_package-1.0.0-py3-none-any.whl
 9
10# 或使用 wheel 工具
11pip install wheel
12wheel unpack dist/my_package-1.0.0-py3-none-any.whl

測試安裝

 1# 在新的虛擬環境中測試
 2python -m venv test_env
 3source test_env/bin/activate
 4
 5# 從本地檔案安裝
 6pip install dist/my_package-1.0.0-py3-none-any.whl
 7
 8# 測試匯入
 9python -c "import my_package; print(my_package.__version__)"
10
11# 清理
12deactivate
13rm -rf test_env

【實作層】發布到 PyPI

註冊帳號

11. 前往 https://pypi.org/account/register/
22. 建立帳號並驗證 email
33. 啟用雙因素認證（強烈建議）
44. 建立 API Token
5   - Account Settings → API tokens → Add API token
6   - Scope: Entire account（首次）或特定專案
7   - 複製 token（只會顯示一次）

設定認證

 1# 方法 1：使用 .pypirc 檔案
 2cat > ~/.pypirc << 'EOF'
 3[pypi]
 4username = __token__
 5password = pypi-xxxxxxxxxxxx
 6
 7[testpypi]
 8username = __token__
 9password = pypi-xxxxxxxxxxxx
10EOF
11
12# 設定檔案權限
13chmod 600 ~/.pypirc
14
15# 方法 2：使用環境變數
16export TWINE_USERNAME=__token__
17export TWINE_PASSWORD=pypi-xxxxxxxxxxxx
18
19# 方法 3：使用 keyring
20pip install keyring
21keyring set https://upload.pypi.org/legacy/ __token__

發布到 TestPyPI（測試）

 1# TestPyPI 是 PyPI 的測試環境
 2# 用於在正式發布前測試
 3
 4# 註冊 TestPyPI 帳號
 5# https://test.pypi.org/account/register/
 6
 7# 上傳到 TestPyPI
 8twine upload --repository testpypi dist/*
 9
10# 從 TestPyPI 安裝測試
11pip install --index-url https://test.pypi.org/simple/ my-package

發布到 PyPI

 1# 確認一切就緒
 2twine check dist/*
 3
 4# 上傳
 5twine upload dist/*
 6
 7# 或指定檔案
 8twine upload dist/my_package-1.0.0*
 9
10# 驗證
11pip install my-package

使用其他工具發布

 1# Poetry
 2poetry publish
 3
 4# Hatch
 5hatch publish
 6
 7# Flit
 8flit publish
 9
10# Maturin（Rust 擴展）
11maturin publish

【實作層】版本管理

語義化版本

 1MAJOR.MINOR.PATCH
 2
 3範例：1.2.3
 4├── MAJOR (1): 不相容的 API 變更
 5├── MINOR (2): 新增功能，向後相容
 6└── PATCH (3): 修復 bug，向後相容
 7
 8預發布版本：
 9├── 1.0.0a1  (alpha)
10├── 1.0.0b1  (beta)
11├── 1.0.0rc1 (release candidate)
12
13開發版本：
14├── 1.0.0.dev1
15├── 1.0.0.post1 (post-release)

PEP 440 版本格式

 1合法的版本號：
 2├── 1.0
 3├── 1.0.0
 4├── 1.0.0a1
 5├── 1.0.0b2
 6├── 1.0.0rc1
 7├── 1.0.0.dev1
 8├── 1.0.0.post1
 9└── 1.0.0+local
10
11不合法（會被正規化）：
12├── 1.0.0-alpha1 → 1.0.0a1
13├── v1.0.0 → 1.0.0
14└── 1.0.0.RELEASE → 1.0.0

自動版本管理

 1# 使用 setuptools-scm
 2# 從 git tag 自動產生版本
 3
 4# 安裝
 5pip install setuptools-scm
 6
 7# pyproject.toml 設定
 8# [tool.setuptools_scm]
 9
10# 建立 tag
11git tag v1.0.0
12git push --tags
13
14# 建構（版本自動從 tag 取得）
15python -m build
16
17# 使用 hatch
18hatch version minor  # 1.0.0 → 1.1.0
19hatch version patch  # 1.1.0 → 1.1.1
20
21# 使用 poetry
22poetry version minor
23poetry version patch

【實作層】CI/CD 自動發布

GitHub Actions

 1# .github/workflows/publish.yml
 2name: Publish to PyPI
 3
 4on:
 5  release:
 6    types: [published]
 7
 8jobs:
 9  build:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v4
13
14      - name: Set up Python
15        uses: actions/setup-python@v5
16        with:
17          python-version: '3.11'
18
19      - name: Install build tools
20        run: pip install build twine
21
22      - name: Build package
23        run: python -m build
24
25      - name: Check package
26        run: twine check dist/*
27
28      - name: Upload artifacts
29        uses: actions/upload-artifact@v4
30        with:
31          name: dist
32          path: dist/
33
34  publish-testpypi:
35    needs: build
36    runs-on: ubuntu-latest
37    environment: testpypi
38    permissions:
39      id-token: write  # 用於 Trusted Publishing
40    steps:
41      - uses: actions/download-artifact@v4
42        with:
43          name: dist
44          path: dist/
45
46      - name: Publish to TestPyPI
47        uses: pypa/gh-action-pypi-publish@release/v1
48        with:
49          repository-url: https://test.pypi.org/legacy/
50
51  publish-pypi:
52    needs: [build, publish-testpypi]
53    runs-on: ubuntu-latest
54    environment: pypi
55    permissions:
56      id-token: write
57    steps:
58      - uses: actions/download-artifact@v4
59        with:
60          name: dist
61          path: dist/
62
63      - name: Publish to PyPI
64        uses: pypa/gh-action-pypi-publish@release/v1

Trusted Publishing（推薦）

 1Trusted Publishing：
 2├── 不需要儲存 API token
 3├── 使用 OIDC（OpenID Connect）
 4├── 更安全的發布方式
 5└── GitHub Actions 原生支援
 6
 7設定步驟：
 81. 在 PyPI 專案設定中新增 Publisher
 92. 選擇 GitHub Actions
103. 填入 repository 和 workflow 資訊
114. 在 workflow 中使用 id-token: write

在 PyPI 設定 Trusted Publisher：

1PyPI → Your Project → Settings → Publishing
2
3新增 publisher：
4├── Owner: your-github-username
5├── Repository: your-repo-name
6├── Workflow name: publish.yml
7└── Environment name: pypi (選填)

完整的 CI/CD 流程

 1# .github/workflows/ci.yml
 2name: CI/CD
 3
 4on:
 5  push:
 6    branches: [main]
 7  pull_request:
 8  release:
 9    types: [published]
10
11jobs:
12  test:
13    runs-on: ${{ matrix.os }}
14    strategy:
15      matrix:
16        os: [ubuntu-latest, macos-latest, windows-latest]
17        python-version: ['3.9', '3.10', '3.11', '3.12']
18    steps:
19      - uses: actions/checkout@v4
20
21      - name: Set up Python
22        uses: actions/setup-python@v5
23        with:
24          python-version: ${{ matrix.python-version }}
25
26      - name: Install dependencies
27        run: |
28          pip install -e ".[dev]"
29
30      - name: Run tests
31        run: pytest --cov
32
33  build:
34    needs: test
35    runs-on: ubuntu-latest
36    steps:
37      - uses: actions/checkout@v4
38        with:
39          fetch-depth: 0  # 完整 history（用於 setuptools-scm）
40
41      - name: Build
42        run: |
43          pip install build
44          python -m build
45
46      - name: Upload
47        uses: actions/upload-artifact@v4
48        with:
49          name: dist
50          path: dist/
51
52  publish:
53    if: github.event_name == 'release'
54    needs: build
55    runs-on: ubuntu-latest
56    environment: pypi
57    permissions:
58      id-token: write
59    steps:
60      - uses: actions/download-artifact@v4
61        with:
62          name: dist
63          path: dist/
64
65      - uses: pypa/gh-action-pypi-publish@release/v1

【進階】多平台 wheel 建構

使用 cibuildwheel

 1# .github/workflows/wheels.yml
 2name: Build wheels
 3
 4on:
 5  release:
 6    types: [published]
 7
 8jobs:
 9  build_wheels:
10    name: Build wheels on ${{ matrix.os }}
11    runs-on: ${{ matrix.os }}
12    strategy:
13      matrix:
14        os: [ubuntu-latest, windows-latest, macos-13, macos-14]
15
16    steps:
17      - uses: actions/checkout@v4
18
19      - name: Build wheels
20        uses: pypa/cibuildwheel@v2.17
21        env:
22          # 建構 Python 3.9-3.12
23          CIBW_BUILD: cp39-* cp310-* cp311-* cp312-*
24          # 跳過 32-bit 和 musl
25          CIBW_SKIP: "*-win32 *-manylinux_i686 *-musllinux*"
26          # 測試命令
27          CIBW_TEST_COMMAND: pytest {project}/tests
28
29      - uses: actions/upload-artifact@v4
30        with:
31          name: wheels-${{ matrix.os }}
32          path: ./wheelhouse/*.whl
33
34  build_sdist:
35    name: Build source distribution
36    runs-on: ubuntu-latest
37    steps:
38      - uses: actions/checkout@v4
39
40      - name: Build sdist
41        run: |
42          pip install build
43          python -m build --sdist
44
45      - uses: actions/upload-artifact@v4
46        with:
47          name: sdist
48          path: dist/*.tar.gz
49
50  publish:
51    needs: [build_wheels, build_sdist]
52    runs-on: ubuntu-latest
53    environment: pypi
54    permissions:
55      id-token: write
56    steps:
57      - uses: actions/download-artifact@v4
58        with:
59          pattern: wheels-*
60          merge-multiple: true
61          path: dist/
62
63      - uses: actions/download-artifact@v4
64        with:
65          name: sdist
66          path: dist/
67
68      - uses: pypa/gh-action-pypi-publish@release/v1

cibuildwheel 設定

 1# pyproject.toml
 2[tool.cibuildwheel]
 3# 建構的 Python 版本
 4build = "cp39-* cp310-* cp311-* cp312-*"
 5
 6# 跳過的組合
 7skip = [
 8    "*-win32",
 9    "*-manylinux_i686",
10    "*-musllinux*",
11]
12
13# 測試設定
14test-command = "pytest {project}/tests"
15test-requires = "pytest"
16
17# 環境變數
18[tool.cibuildwheel.environment]
19MY_VAR = "value"
20
21# 平台特定設定
22[tool.cibuildwheel.linux]
23archs = ["x86_64", "aarch64"]
24manylinux-x86_64-image = "manylinux2014"
25
26[tool.cibuildwheel.macos]
27archs = ["x86_64", "arm64"]
28
29[tool.cibuildwheel.windows]
30archs = ["AMD64"]

【常見問題】疑難排解

上傳失敗

 1問題：HTTPError 403 Forbidden
 2原因：認證失敗
 3解決：
 41. 確認 token 正確
 52. 確認使用 __token__ 作為使用者名稱
 63. 確認 token 的 scope 包含該專案
 7
 8問題：File already exists
 9原因：該版本已經上傳過
10解決：
111. 升級版本號
122. PyPI 不允許覆蓋已發布的版本
13
14問題：Invalid distribution file
15原因：套件格式錯誤
16解決：
171. 執行 twine check dist/*
182. 確認 pyproject.toml 設定正確

安裝問題

 1問題：No matching distribution found
 2原因：沒有相容的 wheel
 3解決：
 41. 確認有發布 sdist
 52. 確認有對應平台的 wheel
 63. 檢查 requires-python 設定
 7
 8問題：Could not build wheels
 9原因：建構失敗（通常是 C 擴展）
10解決：
111. 安裝編譯器（gcc, MSVC）
122. 安裝 python-dev 套件
133. 提供預編譯的 wheel

思考題

為什麼 PyPI 不允許刪除或覆蓋已發布的版本？
Trusted Publishing 相比 API token 有什麼優勢？
在什麼情況下應該同時發布 sdist 和 wheel？

實作練習

建立一個簡單套件並發布到 TestPyPI
設定 GitHub Actions 自動發布流程
使用 cibuildwheel 建構多平台 wheel

延伸閱讀

上一章：建構系統比較 下一章：最佳實踐

6.4 套件維護最佳實踐

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

本章介紹維護 Python 套件的長期策略。

本章目標

學完本章後，你將能夠：

建立良好的專案結構
管理依賴與版本
制定棄用與升級策略

【設計層】專案結構

Src Layout vs Flat Layout

 1Flat Layout：
 2my-package/
 3├── pyproject.toml
 4├── README.md
 5├── my_package/
 6│ ├── __init__.py
 7│ └── module.py
 8└── tests/
 9 └── test_module.py
10
11Src Layout（推薦）：
12my-package/
13├── pyproject.toml
14├── README.md
15├── src/
16│ └── my_package/
17│ ├── __init__.py
18│ └── module.py
19└── tests/
20 └── test_module.py

為什麼推薦 Src Layout？

 1Flat Layout 的問題：
 2├── 可能意外匯入本地未安裝的套件
 3├── 測試可能使用開發版而非安裝版
 4└── 容易混淆專案根目錄和套件目錄
 5
 6Src Layout 的優點：
 7├── 強制測試已安裝的套件
 8├── 清楚區分原始碼和設定檔
 9├── 避免命名衝突
10└── 更接近使用者的安裝環境

完整專案結構範例

 1my-package/
 2├── .github/
 3│ └── workflows/
 4│ ├── ci.yml # 測試與檢查
 5│ └── publish.yml # 發布流程
 6├── docs/
 7│ ├── conf.py
 8│ ├── index.rst
 9│ └── api/
10├── src/
11│ └── my_package/
12│ ├── __init__.py
13│ ├── py.typed # 標記為有型別提示
14│ ├── core.py
15│ └── utils.py
16├── tests/
17│ ├── __init__.py
18│ ├── conftest.py # pytest fixtures
19│ ├── test_core.py
20│ └── test_utils.py
21├── .gitignore
22├── .pre-commit-config.yaml # pre-commit 設定
23├── CHANGELOG.md
24├── LICENSE
25├── README.md
26└── pyproject.toml

【實作層】依賴管理

依賴版本約束策略

 1版本約束類型：
 2
 3精確版本（不推薦用於函式庫）：
 4└── requests==2.31.0
 5
 6最小版本（推薦）：
 7└── requests>=2.28
 8
 9相容版本（~= 運算子）：
10└── requests~=2.28.0 # 等同於 >=2.28.0,<2.29.0
11
12上限版本（謹慎使用）：
13└── requests>=2.28,<3.0

函式庫 vs 應用程式的依賴策略

 1函式庫（被其他專案依賴）：
 2├── 使用寬鬆的版本約束
 3├── 只指定最小版本
 4├── 不鎖定間接依賴
 5└── 讓使用者決定具體版本
 6
 7dependencies = [
 8 "requests>=2.28",
 9 "click>=8.0",
10]
11
12應用程式（直接部署）：
13├── 使用精確的版本鎖定
14├── 鎖定所有間接依賴
15├── 使用 lock 檔案
16└── 確保可重現的環境
17
18# 使用 Poetry/PDM 的 lock 檔案
19# 或 pip-tools 的 requirements.txt

可選依賴（Optional Dependencies）

 1# pyproject.toml
 2[project.optional-dependencies]
 3# 開發依賴
 4dev = [
 5 "pytest>=7.0",
 6 "pytest-cov",
 7 "ruff",
 8 "mypy",
 9]
10
11# 文件依賴
12docs = [
13 "sphinx>=6.0",
14 "sphinx-rtd-theme",
15 "myst-parser",
16]
17
18# 特定功能
19async = ["aiohttp>=3.8"]
20cli = ["click>=8.0", "rich"]
21
22# 全部安裝
23all = [
24 "my-package[async,cli]",
25]

依賴更新策略

 1定期更新流程：
 2
 31. 檢查過期依賴
 4 pip list --outdated
 5 # 或使用工具
 6 pip-audit # 安全性檢查
 7
 82. 更新依賴
 9 # Poetry
10 poetry update
11 poetry update requests # 更新特定套件
12
13 # PDM
14 pdm update
15
163. 執行測試
17 pytest
18
194. 審查變更
20 git diff pyproject.toml poetry.lock
21
225. 提交更新
23 git commit -m "chore: update dependencies"

【實作層】品質保證

測試策略

 1# pyproject.toml
 2[tool.pytest.ini_options]
 3testpaths = ["tests"]
 4python_files = ["test_*.py"]
 5python_functions = ["test_*"]
 6addopts = [
 7 "-v",
 8 "--strict-markers",
 9 "--cov=my_package",
10 "--cov-report=term-missing",
11 "--cov-report=html",
12]
13markers = [
14 "slow: marks tests as slow",
15 "integration: marks integration tests",
16]
17
18[tool.coverage.run]
19source = ["src/my_package"]
20branch = true
21parallel = true
22
23[tool.coverage.report]
24exclude_lines = [
25 "pragma: no cover",
26 "if TYPE_CHECKING:",
27 "raise NotImplementedError",
28 "@overload",
29]
30fail_under = 80

程式碼品質工具

 1# pyproject.toml
 2
 3# Ruff（linter + formatter）
 4[tool.ruff]
 5line-length = 88
 6target-version = "py38"
 7
 8[tool.ruff.lint]
 9select = [
10 "E", # pycodestyle errors
11 "W", # pycodestyle warnings
12 "F", # pyflakes
13 "I", # isort
14 "UP", # pyupgrade
15 "B", # flake8-bugbear
16 "SIM", # flake8-simplify
17 "RUF", # Ruff-specific rules
18]
19ignore = ["E501"] # line too long（由 formatter 處理）
20
21[tool.ruff.lint.isort]
22known-first-party = ["my_package"]
23
24# Mypy（型別檢查）
25[tool.mypy]
26python_version = "3.8"
27strict = true
28warn_return_any = true
29warn_unused_ignores = true
30show_error_codes = true
31
32[[tool.mypy.overrides]]
33module = ["tests.*"]
34disallow_untyped_defs = false

Pre-commit 設定

 1# .pre-commit-config.yaml
 2repos:
 3 - repo: https://github.com/pre-commit/pre-commit-hooks
 4 rev: v4.5.0
 5 hooks:
 6 - id: trailing-whitespace
 7 - id: end-of-file-fixer
 8 - id: check-yaml
 9 - id: check-toml
10 - id: check-added-large-files
11
12 - repo: https://github.com/astral-sh/ruff-pre-commit
13 rev: v0.3.0
14 hooks:
15 - id: ruff
16 args: [--fix]
17 - id: ruff-format
18
19 - repo: https://github.com/pre-commit/mirrors-mypy
20 rev: v1.8.0
21 hooks:
22 - id: mypy
23 additional_dependencies: [types-requests]

1# 安裝 pre-commit
2pip install pre-commit
3pre-commit install
4
5# 手動執行
6pre-commit run --all-files

【實作層】版本與變更管理

語義化版本實踐

 1MAJOR.MINOR.PATCH
 2
 3何時增加 MAJOR：
 4├── 移除已棄用的 API
 5├── 更改現有 API 的行為
 6├── 更改函式簽名（必要參數）
 7└── 不再支援舊版 Python
 8
 9何時增加 MINOR：
10├── 新增功能
11├── 新增可選參數
12├── 棄用現有 API（但不移除）
13└── 效能改進
14
15何時增加 PATCH：
16├── 修復 bug
17├── 安全性修補
18├── 文件修正
19└── 內部重構（不影響 API）

CHANGELOG 格式

 1# Changelog
 2
 3本專案遵循 [Keep a Changelog](https://keepachangelog.com/) 格式。
 4
 5## [Unreleased]
 6
 7### Added
 8- 新功能描述
 9
10### Changed
11- 變更描述
12
13### Deprecated
14- 棄用描述
15
16### Removed
17- 移除描述
18
19### Fixed
20- 修復描述
21
22### Security
23- 安全性修補描述
24
25## [1.2.0] - 2025-01-15
26
27### Added
28- 新增 `process_async` 函式支援非同步處理 (#123)
29- 新增 `Config` 類別用於設定管理
30
31### Changed
32- `process` 函式現在預設啟用快取
33
34### Deprecated
35- `old_function` 將在 2.0.0 移除，請使用 `new_function`
36
37### Fixed
38- 修復在 Windows 上的路徑處理問題 (#456)
39
40## [1.1.0] - 2025-01-01
41...
42
43[Unreleased]: https://github.com/user/project/compare/v1.2.0...HEAD
44[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
45[1.1.0]: https://github.com/user/project/releases/tag/v1.1.0

自動化版本管理

 1# 使用 setuptools-scm
 2[build-system]
 3requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
 4build-backend = "setuptools.build_meta"
 5
 6[project]
 7name = "my-package"
 8dynamic = ["version"]
 9
10[tool.setuptools_scm]
11# 從 git tag 自動產生版本
12# v1.0.0 → 1.0.0
13# v1.0.0-5-g1234abc → 1.0.0.dev5+g1234abc

1# 發布流程
2git tag v1.2.0
3git push --tags
4
5# CI 自動建構並發布

【實作層】棄用策略

棄用流程

 1棄用時間線（範例）：
 2
 3v1.0: 引入 old_function
 4 │
 5v1.5: 引入 new_function
 6 標記 old_function 為棄用
 7 │
 8v1.6: old_function 發出棄用警告
 9v1.7: │
10v1.8: │ 至少保留 2-3 個 minor 版本
11 │
12v2.0: 移除 old_function

實現棄用警告

 1# my_package/deprecated.py
 2import warnings
 3from functools import wraps
 4from typing import Callable, TypeVar
 5
 6F = TypeVar("F", bound=Callable)
 7
 8def deprecated(
 9 reason: str,
10 version: str,
11 replacement: str | None = None,
12) -> Callable[[F], F]:
13 """標記函式為棄用。
14
15 Args:
16 reason: 棄用原因
17 version: 將移除的版本
18 replacement: 替代方案
19
20 Example:
21 @deprecated(
22 reason="使用新的 API",
23 version="2.0.0",
24 replacement="new_function",
25 )
26 def old_function():
27 pass
28 """
29
30 def decorator(func: F) -> F:
31 message = f"{func.__name__} 已棄用，將在 {version} 移除。{reason}"
32 if replacement:
33 message += f" 請使用 {replacement} 替代。"
34
35 @wraps(func)
36 def wrapper(*args, **kwargs):
37 warnings.warn(
38 message,
39 DeprecationWarning,
40 stacklevel=2,
41 )
42 return func(*args, **kwargs)
43
44 # 更新 docstring
45 wrapper.__doc__ = f".. deprecated:: {version}\n {message}\n\n{func.__doc__ or ''}"
46
47 return wrapper # type: ignore
48
49 return decorator
50
51# 使用範例
52@deprecated(
53 reason="效能問題",
54 version="2.0.0",
55 replacement="process_v2",
56)
57def process_v1(data: list) -> list:
58 """處理資料（舊版）。"""
59 return [x * 2 for x in data]
60
61def process_v2(data: list) -> list:
62 """處理資料（新版，更高效）。"""
63 # 新的實現
64 return [x * 2 for x in data]

棄用類別屬性

 1import warnings
 2
 3class Config:
 4 def __init__(self):
 5 self._new_setting = "default"
 6
 7 @property
 8 def old_setting(self) -> str:
 9 """已棄用，請使用 new_setting。"""
10 warnings.warn(
11 "old_setting 已棄用，將在 2.0.0 移除。請使用 new_setting。",
12 DeprecationWarning,
13 stacklevel=2,
14 )
15 return self._new_setting
16
17 @old_setting.setter
18 def old_setting(self, value: str) -> None:
19 warnings.warn(
20 "old_setting 已棄用，將在 2.0.0 移除。請使用 new_setting。",
21 DeprecationWarning,
22 stacklevel=2,
23 )
24 self._new_setting = value
25
26 @property
27 def new_setting(self) -> str:
28 """新的設定屬性。"""
29 return self._new_setting
30
31 @new_setting.setter
32 def new_setting(self, value: str) -> None:
33 self._new_setting = value

【實作層】向後相容性

API 穩定性承諾

 1API 穩定性等級：
 2
 3Public API（穩定）：
 4├── 文件記載的函式和類別
 5├── __all__ 中導出的名稱
 6└── 遵循語義化版本
 7
 8Internal API（不穩定）：
 9├── 以 _ 開頭的名稱
10├── 未在文件中記載
11└── 可能在任何版本變更
12
13Experimental API：
14├── 明確標記為實驗性
15├── 可能在 minor 版本變更
16└── 不保證向後相容

維護向後相容的技巧

 1# 1. 新增可選參數時使用預設值
 2def process(data, *, new_option=None): # 新增 new_option
 3 if new_option is not None:
 4 # 新行為
 5 pass
 6 # 舊行為保持不變
 7
 8# 2. 使用 **kwargs 保持彈性
 9def create_client(host, port, **kwargs):
10 # 未來可以新增參數而不破壞現有程式碼
11 timeout = kwargs.get("timeout", 30)
12 # ...
13
14# 3. 提供相容層
15def old_api(*args, **kwargs):
16 """已棄用，請使用 new_api。"""
17 warnings.warn("...", DeprecationWarning, stacklevel=2)
18 # 轉換參數格式
19 return new_api(*args, **kwargs)
20
21# 4. 版本檢查
22import sys
23
24if sys.version_info >= (3, 10):
25 from typing import TypeAlias
26else:
27 from typing_extensions import TypeAlias

【實作層】文件與社群

文件結構

 1docs/
 2├── index.rst # 首頁
 3├── installation.rst # 安裝指南
 4├── quickstart.rst # 快速開始
 5├── tutorial/ # 教學
 6│ ├── basics.rst
 7│ └── advanced.rst
 8├── api/ # API 參考
 9│ ├── index.rst
10│ └── modules.rst
11├── changelog.rst # 變更日誌
12└── contributing.rst # 貢獻指南

README 模板

 1# My Package
 2
 3[![PyPI version](https://badge.fury.io/py/my-package.svg)](https://pypi.org/project/my-package/)
 4[![Python versions](https://img.shields.io/pypi/pyversions/my-package.svg)](https://pypi.org/project/my-package/)
 5[![License](https://img.shields.io/pypi/l/my-package.svg)](https://github.com/user/my-package/blob/main/LICENSE)
 6[![CI](https://github.com/user/my-package/actions/workflows/ci.yml/badge.svg)](https://github.com/user/my-package/actions)
 7[![codecov](https://codecov.io/gh/user/my-package/branch/main/graph/badge.svg)](https://codecov.io/gh/user/my-package)
 8
 9簡短描述這個套件做什麼。
10
11## 特點
12
13- 功能 1
14- 功能 2
15- 功能 3
16
17## 安裝
18
19\`\`\`bash
20pip install my-package
21\`\`\`
22
23## 快速開始
24
25\`\`\`python
26from my_package import something
27
28result = something.do_thing()
29\`\`\`
30
31## 文件
32
33完整文件請見：https://my-package.readthedocs.io/
34
35## 貢獻
36
37歡迎貢獻！請見 [CONTRIBUTING.md](/python-advanced/07-packaging/best-practices/CONTRIBUTING.md)。
38
39## 授權
40
41MIT License - 詳見 [LICENSE](/python-advanced/07-packaging/best-practices/LICENSE)

Issue 與 PR 模板

 1<!-- .github/ISSUE_TEMPLATE/bug_report.md -->
 2---
 3name: Bug 回報
 4about: 回報問題以協助改進
 5---
 6
 7**描述問題**
 8清楚簡潔地描述問題。
 9
10**重現步驟**
111. ...
122. ...
13
14**預期行為**
15描述你期望的行為。
16
17**環境**
18- OS: [e.g., macOS 14.0]
19- Python: [e.g., 3.11.0]
20- Package version: [e.g., 1.2.0]
21
22**額外資訊**
23任何其他相關資訊。

【進階】維護者工作流程

發布檢查清單

 1發布前檢查：
 2
 3□ 所有測試通過
 4□ 程式碼覆蓋率達標
 5□ 型別檢查通過
 6□ 文件已更新
 7□ CHANGELOG 已更新
 8□ 版本號已更新
 9□ 無安全性漏洞（pip-audit）
10
11發布步驟：
12
131. 更新 CHANGELOG
14 - 將 [Unreleased] 內容移到新版本
15 - 新增發布日期
16
172. 建立發布 commit
18 git add CHANGELOG.md
19 git commit -m "chore: prepare release v1.2.0"
20
213. 建立 tag
22 git tag v1.2.0
23 git push origin main --tags
24
254. CI 自動發布到 PyPI
26
275. 建立 GitHub Release
28 - 使用 CHANGELOG 內容
29 - 附上二進位檔案（如適用）
30
316. 宣布發布
32 - 更新文件網站
33 - 社群媒體/郵件列表

安全性維護

1# 檢查已知漏洞
2pip install pip-audit
3pip-audit
4
5# 檢查依賴更新
6pip list --outdated
7
8# 使用 Dependabot（GitHub）
9# .github/dependabot.yml

 1# .github/dependabot.yml
 2version: 2
 3updates:
 4 - package-ecosystem: "pip"
 5 directory: "/"
 6 schedule:
 7 interval: "weekly"
 8 commit-message:
 9 prefix: "chore(deps)"
10 labels:
11 - "dependencies"
12
13 - package-ecosystem: "github-actions"
14 directory: "/"
15 schedule:
16 interval: "weekly"

總結

最佳實踐清單

 1專案結構：
 2- 使用 src layout
 3- 清楚的目錄組織
 4- 包含 py.typed 標記
 5
 6依賴管理：
 7- 函式庫使用寬鬆版本
 8- 應用程式使用 lock 檔案
 9- 定期更新依賴
10
11品質保證：
12- 完整的測試覆蓋
13- 型別提示和 mypy
14- 使用 pre-commit
15
16版本管理：
17- 遵循語義化版本
18- 維護 CHANGELOG
19- 自動化版本號
20
21向後相容：
22- 清楚的棄用流程
23- 至少 2-3 個版本的過渡期
24- 明確的 API 穩定性承諾
25
26文件與社群：
27- 完整的 README
28- API 文件
29- 貢獻指南

思考題

函式庫和應用程式的依賴管理策略為什麼不同？各有什麼優缺點？
如何平衡「保持向後相容」和「改進 API 設計」的矛盾？
開源專案的維護者應該如何處理安全性漏洞的披露？

實作練習

為一個現有專案加入 pre-commit 設定，包含 ruff 和 mypy
實作一個 @deprecated 裝飾器，並寫測試驗證警告訊息
為一個開源專案撰寫完整的 CONTRIBUTING.md

延伸閱讀

上一章：發布到 PyPI 返回：模組六首頁

6.5 封裝預編譯二進位

Mon, 02 Feb 2026 00:00:00 +0000

本章介紹 Python 套件封裝預編譯二進位的架構模式，讓 Python 能夠調用高效能的原生程式碼。

本章目標

學完本章後，你將能夠：

理解「Python 封裝二進位」的架構模式
評估何時使用這種模式
了解知名套件如何應用這種技術
在純 Python 與封裝二進位之間做出正確選擇

【概念】什麼是封裝預編譯二進位？

架構模式

這種模式將其他語言（如 Go、Rust、C++）編譯的二進位檔案，包裝在 Python 套件中：

1┌─────────────────────────────────────────┐
2│       Python API（薄封裝層）              │  ← 使用者接觸的介面
3├─────────────────────────────────────────┤
4│   subprocess / FFI / ctypes / cffi      │  ← 呼叫機制
5├─────────────────────────────────────────┤
6│   預編譯二進位（Go/Rust/C/C++）          │  ← 實際執行邏輯
7└─────────────────────────────────────────┘

與 C 擴展的差異

面向	C 擴展（模組四/五）	封裝預編譯二進位
編譯時機	安裝時編譯	發布前預編譯
使用者需求	可能需要編譯器	不需要編譯器
整合方式	Python C API / pybind11	subprocess / FFI
典型來源	專為 Python 寫的擴展	獨立的 CLI 工具或函式庫

【案例】

TensorFlow / PyTorch

1TensorFlow 架構：
2├── Python API（tf.* 模組）
3│   └── 使用者撰寫的程式碼
4├── 綁定層（pybind11）
5│   └── Python ↔ C++ 橋接
6└── C++ 核心 + CUDA
7    └── 預編譯的運算核心

選擇原因：

GPU 運算需要原生效能
大量的 C++ 程式碼庫
安裝時編譯太慢（數小時）

cryptography

1cryptography 架構：
2├── Python API（cryptography.*)
3├── cffi 綁定層
4└── OpenSSL / BoringSSL
5    └── 預編譯的加密函式庫

選擇原因：

加密演算法需要經過審計的實現
效能關鍵
支援 PyPy（cffi 是 PyPy 官方推薦）

ruff（Python Linter）

1ruff 架構：
2├── Python 封裝（ruff 套件）
3│   └── 提供 CLI 和簡單 API
4└── Rust 二進位
5    └── 實際的 lint 邏輯

選擇原因：

追求極致速度（比 Flake8 快 10-100 倍）
Rust 的記憶體安全
作為獨立工具也可使用

mermaid-ascii（PyPI 封裝）

1osl-packages/mermaid-ascii 架構：
2├── Python API（mermaid_ascii 模組）
3│   └── mermaid_to_ascii() 函式
4├── subprocess 呼叫
5└── Go 編譯的 mermaid-ascii 二進位
6    └── Mermaid → ASCII 轉換

選擇原因：

重用現有的 Go 實現
不需要 Node.js 依賴
提供 Python 友善的介面

【優點】為什麼使用這種模式？

1. 效能

核心邏輯用高效能語言實現，Python 只做介面：

1# 使用者感受不到底層是 Rust
2import ruff
3
4# 實際上是呼叫 Rust 編譯的二進位
5result = ruff.check("my_code.py")

2. 重用現有實現

不需要用 Python 重寫已經穩定的程式碼：

1情境：有一個優秀的 Go CLI 工具
2選項 A：用 Python 重寫（大量工作）
3選項 B：封裝 Go 二進位（少量工作）← 通常更好

3. 跨語言生態整合

讓 Python 使用者能夠使用其他語言的優秀工具：

1# Python 使用者不需要安裝 Go
2from mermaid_ascii import mermaid_to_ascii
3
4diagram = mermaid_to_ascii("graph LR; A-->B")

4. 維護分離

核心邏輯與 Python 封裝可以獨立更新：

1mermaid-ascii（Go）: v0.6.1 → v0.7.0（核心更新）
2mermaid-ascii（PyPI）: 0.6.1 → 0.7.0（同步更新封裝）

【缺點】這種模式的限制

1. 平台依賴

需要為每個作業系統和 CPU 架構提供預編譯二進位：

 1典型的 wheel 矩陣：
 2├── manylinux_x86_64
 3├── manylinux_aarch64
 4├── macosx_x86_64
 5├── macosx_arm64
 6└── win_amd64
 7
 8缺點：
 9- 維護成本高
10- 新平台支援需要時間
11- CI/CD 複雜度增加

2. 安裝體積

wheel 檔案較大（包含二進位）：

1套件大小比較：
2純 Python 套件   ~50 KB
3封裝二進位套件   ~5-50 MB（依二進位大小）

3. 除錯困難

錯誤可能發生在二進位層，難以追蹤：

1# 錯誤訊息可能是二進位的 stderr
2try:
3    result = some_binary_wrapper()
4except subprocess.CalledProcessError as e:
5    # e.stderr 是二進位的錯誤訊息
6    # 可能不是 Python 友善的格式

4. 無法修改核心邏輯

想改變底層行為必須重編譯核心：

1如果你需要：
2- 修改演算法
3- 加入自訂功能
4- 修復底層 bug
5
6你必須：
71. 修改原始語言的程式碼
82. 重新編譯
93. 重新打包 wheel

5. 供應鏈風險

二進位來源需要信任：

1風險考量：
2├── 二進位是否來自可信來源？
3├── 是否有可驗證的建構流程？
4└── 是否有安全審計？
5
6最佳實踐：
7├── 使用知名維護者的套件
8├── 檢查 GitHub Actions 等 CI 建構紀錄
9└── 考慮自行建構（如果可能）

【比較】純 Python vs 封裝二進位

特性比較表

面向	純 Python	封裝預編譯二進位
效能	較慢	可達原生速度
可移植性	極佳（任何有 Python 的地方）	受限於預編譯平台
除錯	容易（Python 工具鏈）	困難（跨語言）
修改靈活度	高（直接修改程式碼）	低（需重新編譯）
安裝體積	小	大（含二進位）
依賴管理	簡單	複雜
透明度	完全可見	部分黑箱
開發速度	快（Python 生態）	需要多語言技能

決策流程

 1選擇純 Python 如果：
 2├── 效能不是關鍵瓶頸
 3├── 需要頻繁修改邏輯
 4├── 需要最大可移植性
 5├── 功能相對簡單
 6└── 希望保持程式碼透明
 7
 8選擇封裝二進位如果：
 9├── 效能是關鍵需求
10├── 已有成熟的非 Python 實現
11├── 核心邏輯穩定，不常修改
12├── 需要系統級別的操作
13└── 安全性要求使用審計過的實現

【實作】如何封裝二進位

方法一：subprocess 呼叫

最簡單的封裝方式，適合 CLI 工具：

 1# my_wrapper/core.py
 2import subprocess
 3import shutil
 4from pathlib import Path
 5
 6def find_binary():
 7    """找到封裝的二進位檔案"""
 8    # 二進位通常放在套件目錄內
 9    package_dir = Path(__file__).parent
10    binary = package_dir / "bin" / "my_tool"
11
12    if binary.exists():
13        return binary
14
15    # 或者在 PATH 中尋找
16    return shutil.which("my_tool")
17
18def run_tool(input_text: str) -> str:
19    """呼叫封裝的工具"""
20    binary = find_binary()
21    if not binary:
22        raise RuntimeError("找不到 my_tool 二進位")
23
24    result = subprocess.run(
25        [str(binary)],
26        input=input_text,
27        capture_output=True,
28        text=True,
29        check=True
30    )
31    return result.stdout

方法二：ctypes / cffi

適合函式庫（.so / .dll）：

 1# my_wrapper/bindings.py
 2import ctypes
 3from pathlib import Path
 4
 5def load_library():
 6    """載入共享函式庫"""
 7    package_dir = Path(__file__).parent
 8
 9    # 根據平台選擇正確的檔案
10    import platform
11    if platform.system() == "Darwin":
12        lib_name = "libmy_tool.dylib"
13    elif platform.system() == "Windows":
14        lib_name = "my_tool.dll"
15    else:
16        lib_name = "libmy_tool.so"
17
18    lib_path = package_dir / "lib" / lib_name
19    return ctypes.CDLL(str(lib_path))
20
21# 載入並設定函式簽名
22_lib = load_library()
23_lib.process_data.argtypes = [ctypes.c_char_p]
24_lib.process_data.restype = ctypes.c_char_p
25
26def process_data(data: str) -> str:
27    """Python 友善的介面"""
28    result = _lib.process_data(data.encode('utf-8'))
29    return result.decode('utf-8')

方法三：使用專門工具

1推薦工具：
2├── PyOxidizer：打包 Python + Rust
3├── Briefcase：跨平台打包
4├── Nuitka：Python → 原生編譯
5└── 自訂 GitHub Actions：建構多平台 wheel

【打包】建立 wheel

專案結構

 1my_package/
 2├── pyproject.toml
 3├── src/
 4│   └── my_package/
 5│       ├── __init__.py
 6│       ├── core.py          # Python 封裝
 7│       └── bin/             # 預編譯二進位
 8│           ├── my_tool-linux-x64
 9│           ├── my_tool-darwin-arm64
10│           └── my_tool-windows-x64.exe
11└── scripts/
12    └── build_binaries.sh    # 建構腳本

pyproject.toml 設定

 1[build-system]
 2requires = ["hatchling"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6name = "my-package"
 7version = "0.1.0"
 8description = "Python wrapper for my_tool"
 9
10[tool.hatch.build.targets.wheel]
11# 包含二進位檔案
12include = [
13    "src/my_package/bin/*"
14]
15
16# 設定平台特定的 wheel
17[tool.hatch.build.targets.wheel.hooks.custom]
18# 自訂 hook 來處理平台特定二進位

GitHub Actions 範例

 1# .github/workflows/build.yml
 2name: Build wheels
 3
 4on: [push, release]
 5
 6jobs:
 7  build:
 8    strategy:
 9      matrix:
10        os: [ubuntu-latest, macos-latest, windows-latest]
11        arch: [x64, arm64]
12
13    runs-on: ${{ matrix.os }}
14
15    steps:
16      - uses: actions/checkout@v4
17
18      - name: Build binary
19        run: |
20          # 根據目標平台建構二進位
21          ./scripts/build_binary.sh ${{ matrix.arch }}
22
23      - name: Build wheel
24        run: |
25          pip install build
26          python -m build --wheel
27
28      - name: Upload wheel
29        uses: actions/upload-artifact@v4
30        with:
31          name: wheel-${{ matrix.os }}-${{ matrix.arch }}
32          path: dist/*.whl

【案例研究】beautiful-mermaid-py

背景

將 Mermaid 圖表轉換為 ASCII 藝術的工具，存在多種實現：

專案	語言	實現方式	圖表支援
mermaid-ascii	Go	原創實現	2 種
beautiful-mermaid	TypeScript	從 Go 移植並擴展	5 種
beautiful-mermaid-py	Python	從 TypeScript 移植	5 種
osl-packages/mermaid-ascii	Python	封裝 Go 二進位	2 種

兩種 Python 方案比較

1方案 A：封裝 Go 二進位（osl-packages）
2├── 優點：效能較好、維護成本低
3├── 缺點：平台依賴、無法修改邏輯
4└── 適合：追求效能、不需自訂
5
6方案 B：純 Python 移植（beautiful-mermaid-py）
7├── 優點：無依賴、可自訂、跨平台
8├── 缺點：效能略低（但對此任務足夠）
9└── 適合：需要修改、追求簡潔

決策分析

對於 Mermaid ASCII 渲染這個需求：

1效能需求：低（渲染一次圖表不需要毫秒級優化）
2修改需求：可能（未來可能想客製化輸出格式）
3平台多樣性：高（不同開發環境）
4維護成本：純 Python 更低
5
6結論：對於這個場景，純 Python 是更好的選擇

總結

何時封裝二進位

 1適合封裝二進位：
 2├── 效能關鍵的運算（加密、ML、圖像處理）
 3├── 已有成熟的非 Python 實現
 4├── 需要系統級別的操作
 5└── 安全性要求使用審計過的程式碼
 6
 7不適合封裝二進位：
 8├── 簡單的文字處理或資料轉換
 9├── 需要頻繁修改邏輯的功能
10├── 追求最大可移植性的工具
11└── 功能用純 Python 就能達到足夠效能

架構選擇原則

效能驅動：只有當效能是瓶頸時才考慮封裝二進位
重用優先：有成熟實現時考慮封裝，否則考慮純 Python
維護成本：評估長期維護的複雜度
團隊技能：選擇團隊能夠維護的方案

模組七：打包與發布

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

本模組介紹現代 Python 套件的打包標準與發布流程。

為什麼學習打包與發布？

完整生命週期：從開發到發布的完整流程
現代標準：pyproject.toml 與 PEP 標準
工具比較：setuptools、Poetry、Hatch 的選擇

章節列表

章節	主題	關鍵收穫
7.1	pyproject.toml 完整指南	現代設定標準
7.2	建構系統比較	setuptools vs Poetry vs Hatch
7.3	發布到 PyPI	建構與上傳流程
7.4	最佳實踐	套件維護指南
7.5	封裝預編譯二進位	Python 封裝 Go/Rust/C 二進位

先備知識

基本的 Python 開發經驗
了解 pip 和虛擬環境

學習時間

每章節約 30-45 分鐘，全模組約 2-3 小時

上一模組：模組六：用 Rust 擴展 Python

案例研究

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

本節收錄基於 .claude/lib 實際程式碼的案例研究，展示如何將內部共用庫打包成可重用的 Python 套件。

案例列表

案例	素材	學習重點
打包共用庫	整個 lib 目錄	pyproject.toml、版本管理、發布流程

學習路徑

建議先完成本模組的理論章節，再閱讀案例研究：

理解現代 Python 打包標準
學習 pyproject.toml 設定
通過案例實踐打包流程

Packaging on Tarragon

案例：打包共用庫

先備知識

問題背景

現有設計

現有限制

進階解決方案

設計目標

實作步驟

步驟 1：重組目錄結構

為什麼選擇 src layout？

步驟 2：建立 pyproject.toml

關鍵設定說明

步驟 3：處理相依性

安裝方式範例

步驟 4：版本管理策略

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

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

步驟 5：建立發布流程

完整程式碼

完整的 pyproject.toml

使用範例

安裝套件

Python 使用範例

命令列工具使用

設計權衡

專案結構比較

建構工具比較

什麼時候該打包成套件？

適合打包

不建議打包

決策流程圖

練習

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

6.1 pyproject.toml 完整指南

本章目標

【原理層】pyproject.toml 的演進

歷史背景

為什麼需要 pyproject.toml？

相關 PEP

【設計層】三個主要表

檔案結構總覽

[build-system]：建構設定

[project]：專案元數據

[tool.xxx]：工具設定

【實作層】完整範例

最小可行設定

標準函式庫風格

含 CLI 的應用程式

【進階】動態欄位

動態版本

動態依賴

使用 setuptools-scm（Git 標籤版本）

【實作層】專案結構對應

Flat Layout

Src Layout（推薦）

為什麼推薦 src layout？

【進階】PEP 639 授權條款

新的 license 語法

常見的 SPDX 識別碼

【驗證】檢查設定

使用 validate-pyproject

使用 build 測試建構

常見錯誤

思考題

實作練習

延伸閱讀

案例：使用 Poetry 完整工作流

先備知識

問題背景

現代專案的挑戰

為什麼選擇 Poetry？

解決方案

安裝 Poetry

設定 Poetry

工作流一：建立新專案

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

使用 poetry init（現有專案）

互動式初始化範例

工作流二：管理相依性