python-packaging

Python 打包

使用现代打包工具、pyproject.toml 创建、组织和分发 Python 包，并将其发布到 PyPI。

适用场景

• 创建用于分发的 Python 库
• 使用入口点构建 CLI 工具
• 将包发布到 PyPI 或私有仓库
• 设置 Python 项目结构（src 布局或扁平布局）
• 配置 pyproject.toml、setup.py 或 setup.cfg
• 构建 wheel 和源码分发包
• 管理 Python 包的版本和发布
• 创建命名空间包或多包项目

核心概念

包结构

• 源码布局：src/package_name/（推荐）
• 扁平布局：package_name/（更简单，但灵活性较低）
• 包元数据：pyproject.toml、setup.py 或 setup.cfg
• 分发格式：wheel（.whl）和源码分发包（.tar.gz）

现代打包标准

• PEP 517/518：构建系统要求
• PEP 621：pyproject.toml 中的元数据
• PEP 660：可编辑安装
• pyproject.toml：统一的配置来源

构建后端

• setuptools：传统且广泛使用
• hatchling：现代且具有明确主张
• flit：轻量，适用于纯 Python 包
• poetry：依赖管理 + 打包

分发

• PyPI：Python Package Index（公共）
• TestPyPI：正式发布前的测试
• 私有仓库：JFrog、AWS CodeArtifact 等

快速入门

最小包结构

my-package/
  pyproject.toml
  README.md
  LICENSE
  src/
    my_package/
      __init__.py
      module.py
  tests/
    test_module.py

最小 pyproject.toml

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "0.1.0"
description = "A short description"
authors = [{name = "Your Name", email = "[email protected]"}]
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
]

源码布局配置

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

包结构模式

源码布局（推荐）

my-package/
  pyproject.toml
  README.md
  LICENSE
  .gitignore
  src/
    my_package/
      __init__.py
      core.py
      utils.py
      py.typed
  tests/
    __init__.py
    test_core.py
    test_utils.py
  docs/
    index.md

优势：避免意外从源码导入，测试导入更简洁，隔离性更好。

扁平布局

my-package/
  pyproject.toml
  README.md
  my_package/
    __init__.py
    module.py
  tests/
    test_module.py

更简单，但无需安装即可导入包。

多包项目

project/
  pyproject.toml
  packages/
    package-a/
      src/
        package_a/
    package-b/
      src/
        package_b/
  tests/

动态版本管理

[build-system]
requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "my_package.__version__"}

在 init.py 中：

__version__ = "1.0.0"

# Or with setuptools-scm
from importlib.metadata import version
__version__ = version("my-package")

构建和发布

在本地构建包

pip install build twine

# Build distribution
python -m build

# Check the distribution
twine check dist/*

发布到 PyPI

# Test on TestPyPI first
twine upload --repository testpypi dist/*

# Install from TestPyPI to verify
pip install --index-url https://test.pypi.org/simple/ my-package

# Publish to PyPI
twine upload dist/*

使用 API 令牌（推荐）：

# Create ~/.pypirc
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-...your-token...

[testpypi]
username = __token__
password = pypi-...your-test-token...

测试安装

可编辑安装

pip install -e .
pip install -e ".[dev]"
pip install -e ".[dev,docs]"

在隔离环境中测试

python -m venv test-env
source test-env/bin/activate

pip install dist/my_package-1.0.0-py3-none-any.whl
python -c "import my_package; print(my_package.__version__)"
my-tool --help

deactivate
rm -rf test-env

版本约束

dependencies = [
    "requests>=2.28.0,<3.0.0",  # Compatible range
    "click~=8.1.0",              # Compatible release (>=8.1.0,<8.2.0)
    "pydantic>=2.0",             # Minimum version
    "numpy==1.24.3",             # Exact version (avoid if possible)
]

最佳实践

1. 使用 src/ 布局，让包结构更清晰
2. 使用 pyproject.toml 进行现代化打包
3. 在 build-system.requires 中固定构建依赖
4. 使用语义化版本合理管理版本
5. 包含所有元数据（分类器、URL 等）
6. 在干净的环境中测试安装
7. 发布到 PyPI 前先使用 TestPyPI
8. 使用 README 和文档字符串编写完整文档
9. 包含 LICENSE 文件
10. 使用 CI/CD自动化发布

发布检查清单

• 代码已通过测试（pytest 通过）
• 文档完整（README、文档字符串）
• 版本号已更新
• CHANGELOG.md 已更新
• 已包含许可证文件
• pyproject.toml 已配置完整
• 包构建无错误
• 已在干净的环境中测试安装
• CLI 工具可正常工作（如适用）
• PyPI 元数据正确（分类器、关键词）
• 已关联 GitHub 仓库
• 已先在 TestPyPI 上测试
• 已为此次发布创建 Git 标签

参考资料

• references/packaging-guide.md - 功能完整的 pyproject.toml 示例，包含所有工具配置、CLI 模式（Click 和 argparse）、使用 GitHub Actions 进行 CI/CD 发布、多架构 wheel、数据文件、命名空间包、C 扩展、基于 git 的版本管理、私有包索引、文件模板（.gitignore、MANIFEST.in、README.md）

资源

• Python 打包指南：https://packaging.python.org/
• PyPI：https://pypi.org/
• TestPyPI：https://test.pypi.org/
• setuptools 文档：https://setuptools.pypa.io/
• build：https://pypa-build.readthedocs.io/
• twine：https://twine.readthedocs.io/