模組七：打包與發布 on Tarragon

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 設定自動版本管理

延伸閱讀

下一章：建構系統比較

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

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
維護成本：評估長期維護的複雜度
團隊技能：選擇團隊能夠維護的方案

模組七：打包與發布 on Tarragon

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 測試建構

常見錯誤

思考題

實作練習

延伸閱讀

6.2 建構系統比較

本章目標

【總覽】建構系統生態

建構後端 vs 建構前端

主流工具比較

【工具一】setuptools

特點與定位

基本設定

進階設定

C 擴展支援

常用命令

【工具二】Flit

特點與定位

基本設定

常用命令

限制

【工具三】Hatch

特點與定位

基本設定

環境管理

版本管理

常用命令

【工具四】Poetry

特點與定位

基本設定（Poetry 2.0+）

傳統設定（Poetry 1.x）

依賴鎖定

常用命令

【工具五】PDM

特點與定位

基本設定

常用命令

【選擇指南】決策流程

決策樹

場景建議

遷移考量

【比較】功能對照表

核心功能

效能比較

思考題

實作練習

延伸閱讀

6.3 發布到 PyPI

本章目標

【原理層】套件分發格式

sdist vs wheel