pyproject、打包与发布

“在项目目录能运行”不等于可以交付。打包流程要证明项目元数据完整、构建结果可安装、命令行入口可用，并且在没有源码目录帮助的干净环境中仍能通过验收。

一、学习目标

理解源码包、wheel 与安装环境
使用 pyproject.toml 声明构建和项目元数据
定义控制台脚本
构建并检查分发包
在干净虚拟环境安装验收

二、完整项目元数据

[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[project]
name = "study-tasks"
version = "0.1.0"
description = "A small command-line task manager"
readme = "README.md"
requires-python = ">=3.14"
license = "MIT"
authors = [{ name = "OliverChiu" }]
dependencies = []

[project.optional-dependencies]
dev = [
  "build>=1.2",
  "mypy>=1.15",
  "pytest>=8.3",
  "ruff>=0.11",
]

[project.scripts]
study-tasks = "study_tasks.cli:main"

[tool.hatch.build.targets.wheel]
packages = ["src/study_tasks"]

构建后，安装工具会生成 study-tasks 命令并调用 study_tasks.cli:main。

三、版本与兼容范围

版本号是公开契约的一部分。常见语义化版本含义：

0.1.0：早期开发版本；
修订号：兼容缺陷修复；
次版本：向后兼容功能；
主版本：可能破坏兼容性的变更。

库的 dependencies 通常声明经过验证的兼容范围；应用部署则需要可重复的解析或锁文件。不要把当前虚拟环境中所有间接依赖机械复制成库的直接依赖。

四、构建

先运行质量检查：

pytest
ruff check .
ruff format --check .
mypy -p study_tasks

构建：

python -m pip install --upgrade build
python -m build

产生：

dist/
  study_tasks-0.1.0-py3-none-any.whl
  study_tasks-0.1.0.tar.gz

wheel 是构建好的安装格式。
sdist 是源码分发包，安装时通常还需构建。

两者都应包含许可证、README 和需要的包文件。

五、检查构建内容

python -m zipfile --list dist/study_tasks-0.1.0-py3-none-any.whl

确认：

study_tasks 包全部存在；
没有 .venv、数据库、密钥或测试缓存；
元数据中的版本和 Python 要求正确；
README 能正常渲染。

可使用 twine check dist/* 检查分发元数据和说明文档。

六、干净环境验收

Linux/macOS：

python3.14 -m venv /tmp/study-tasks-verify
/tmp/study-tasks-verify/bin/python -m pip install \
  dist/study_tasks-0.1.0-py3-none-any.whl
/tmp/study-tasks-verify/bin/study-tasks --help

Windows PowerShell：

py -3.14 -m venv "$env:TEMP\study-tasks-verify"
& "$env:TEMP\study-tasks-verify\Scripts\python.exe" -m pip install `
  .\dist\study_tasks-0.1.0-py3-none-any.whl
& "$env:TEMP\study-tasks-verify\Scripts\study-tasks.exe" --help

验收必须离开源码目录执行，避免当前目录意外提供导入路径。

七、发布到 TestPyPI

需要公开发布练习包时，先使用 TestPyPI：

python -m pip install --upgrade twine
python -m twine upload --repository testpypi dist/*

使用 API Token，不把凭据写进命令历史、配置仓库或日志。项目名在仓库中必须唯一，本教程项目无需真的占用公共名称。

安装测试：

python -m pip install --index-url https://test.pypi.org/simple/ \
  --no-deps study-tasks

八、发布自动化

CI 发布流程至少包括：

在支持的 Python 版本运行测试与静态检查。
从干净检出构建 sdist 和 wheel。
安装 wheel 做烟测。
保存构建产物和校验和。
仅由受保护标签或审批触发发布。
使用短期或可信发布凭据。

不要从开发者工作目录直接上传一个未经过 CI 验证的产物。

九、常见错误

只测试可编辑安装，从未安装 wheel。
构建产物包含本地数据库或秘密文件。
源码版本和分发元数据版本不一致。
重复上传同一版本后试图覆盖；包索引通常禁止覆盖。
发布失败后修改内容但不增加版本。

十、练习与自测

构建 wheel 并列出内部文件。
在全新环境安装后创建、列出和完成任务。
给构建文件计算 SHA-256，并记录发布清单。

自测：

wheel 与 sdist 有何区别？
为什么必须在源码目录之外做安装验收？
运行依赖和开发依赖怎样区分？

十一、官方资料

上一篇：测试、调试与代码质量｜下一篇：综合实战与进阶路线