Python 打包（深度工作流）

打包将源代码转化为可安装的制品。应优先保障可复现构建、依赖准确无误，以及安全的自动化发布。

何时提供该工作流

触发条件：

• 新建库或 CLI 工具；需在 Poetry、Hatch、setuptools、uv 等方案中做选型
• 在某些 Python 版本或平台上安装失败
• 需从 CI 向 PyPI 或私有索引发布制品

初始建议：

采用六个阶段：（1）项目结构，（2）元数据与入口点，（3）依赖管理，（4）构建后端与 wheel 包，（5）版本控制与 Git 标签，（6）发布与 CI 集成。请确认支持的 Python 版本及目标索引地址。

阶段 1：项目结构

目标：推荐采用 src/ 结构，避免因从仓库根目录意外导入导致的问题；确保只有一个明确的顶层导入包名。

退出条件：在干净的 venv 中执行 pip install . 后，能正确导入该包。

阶段 2：元数据与入口点

目标：使用符合 PEP 621 规范的 pyproject.toml 定义元数据；通过 [project.scripts] 或 [project.gui-scripts] 声明 CLI 入口点。

实践建议

• 关联 README 文件；使用 SPDX 标识符声明许可证
• 合理使用分类器（classifiers），提升在 PyPI 上的可发现性

阶段 3：依赖管理

目标：区分运行时依赖与可选扩展（如 dev、docs、speedups）；库与应用对依赖版本约束策略不同。

库

• 除非必要，避免设置过严的上界版本限制（以免为使用者引入依赖地狱）

应用

• 使用 lockfile（如 pip-tools、uv、poetry lock）保障部署可复现

阶段 4：构建后端与 wheel 包

目标：选择合适的构建后端（如 hatchling、setuptools、flit）；按需生成 wheel 与 sdist 制品。

原生扩展（Native extensions）

• 使用 cibuildwheel 或类似工具，覆盖 manylinux/macOS/Windows 多平台构建矩阵

阶段 5：版本控制与 Git 标签

目标：版本号来源唯一（静态定义于 pyproject 或动态源自 VCS）；Git 标签需与正式发布严格对应。

阶段 6：发布与 CI 集成

目标：PyPI 推荐使用 可信发布（Trusted Publishing）（基于 OIDC），而非长期有效的 API token（存储于 secrets 中）。

实践建议

• 初次学习该流程时，先在 TestPyPI 上验证发布逻辑
• 严格限制 token 权限范围，并在 PyPI 账户启用双因素认证（2FA）

最终审查清单

• 已验证 src 结构及 clean venv 下的导入行为
• pyproject 元数据完整；命令行脚本可正常执行
• 已明确记录依赖策略（含 extras 定义与版本约束规则）
• 制品已在目标平台完成构建验证
• 版本控制机制与 Git 标签一致；CI 发布流程具备安全性

高效指导小贴士

• 类型化库（typed libraries）应添加 py.typed 文件（遵循 PEP 561）
• 对开销较大的可选依赖，应在函数内部惰性导入（lazy-import），以保持 CLI 启动速度
• 命名空间包（namespace packages）易配置错误——建议始终使用一个清晰的顶层包名

应对常见偏差场景

• 单体仓库（Monorepos）：统一协调各子模块版本，或为每个子目录定义独立包并配备清晰的工具链支持
• Docker-only 应用：仍应进行标准打包（便于测试）；Dockerfile 中通过安装 wheel 包完成部署