python-packaging

Python Packaging

使用 pyproject.toml、uv 和最佳实践进行现代 Python 打包与分发。

快速入门

# Create new project with uv
uv init my-package
cd my-package

# Add dependencies
uv add requests click

# Build package
uv build

# Publish to PyPI
uv publish

验证： 使用 --help 标志运行命令，以确认其可用。

适用场景

• 创建可分发的 Python 库
• 构建 CLI 工具
• 发布到 PyPI
• 设置开发环境
• 管理项目依赖项

不适用场景

• 测试包——请改用 python-testing
• 优化包性能——请使用 python-performance
• 测试包——请改用 python-testing
• 优化包性能——请使用 python-performance

核心决策

1. 目录布局选择

# Source layout (recommended)
src/my_package/
    __init__.py
    module.py

# Flat layout (simple)
my_package/
    __init__.py
    module.py

验证： 使用 --help 标志运行命令，以确认其可用。

源代码目录布局的优势：

• 明确区分源代码与测试
• 避免意外导入未安装的代码
• 更适合结构复杂的包

2. 项目结构

最小项目：

**Verification:** Run `pytest -v` to verify tests pass.
my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_package/
│       └── __init__.py
└── tests/
    └── test_init.py

验证： 运行 pytest -v，确认测试通过。

完整项目：

**Verification:** Run the command with `--help` flag to verify availability.
my-project/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── cli.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── conftest.py
│   └── test_core.py
└── docs/
    └── index.md

验证： 运行 pytest -v，确认测试通过。

详细主题

如需了解详细信息，请参阅各模块：

• uv 工作流 - 完整的 uv 命令和故障排查
• pyproject.toml 模式 - 不同包类型的配置示例
• 入口点 - 控制台脚本、GUI 脚本和插件
• CI/CD 集成 - GitHub Actions 和自动化发布

最佳实践

1. 除简单包外，均使用源代码目录布局
2. 为直接依赖项指定最低版本
3. 使用可选依赖组管理 dev/docs/test 依赖
4. 添加 py.typed 以支持类型提示
5. 编写包含用法示例的详细 README
6. 使用语义化版本（MAJOR.MINOR.PATCH）
7. 发布前在多个 Python 版本上进行测试

退出标准

• 使用现代 pyproject.toml 配置
• 清晰指定依赖项
• 正确管理版本
• 包含测试且测试通过
• 构建流程可复现
• 发布流程已自动化