1.背景

Python程序员日常开发中，需要用Pip安装开源的第三方的包，调用该包的API, 而不需要自己重新实现，比如numpy/pandas。最近转绝色，需要作为一个Package的作者，将自己的代码打包成whl格式，上传到pypi, 供其他人使用。

本文对Python打包做一个总结，介绍python包的构建与分发的基本原理与步骤，从配置文件、构建前端、构建后端角度对Python打包的细节做一个介绍。

python分发的文件有两类:

• source distribution(sdist): tar.gz, 仅含源代码和元数据
• binary distribution(bdist): .whl(本质是zip)，含.so

简单来说, 作为一个维护者，分发一个python包需要两步：

• 调用构建前端，构建轮子，如python3 -m build --sdist source-tree-directory
• 背后步骤如下(先不用纠结细节，后文会详细描述)
• 创建独立的环境
• 准备构建的依赖 (backend.get_requires_for_build_wheel)
• 产生包的元数据 (backend.prepare_metadata_for_build_wheel)
• 构建: 编译、打包, 生成sdist(tar.gz)/bdist(wheel) (backend.build_wheel/build_sdist)
• 将build artifacts 上传到pypi

twine upload dist/package-name-version.tar.gz dist/package-name-version-py3-none-any.whl

作为一个使用者，安装一个python包只需要(下载build artifacts; 安装到python环境)

python3 -m pip install package-name

2.构建配置

配置文件，描述package的元数据以及如何创建build artifacts, 通常是pyproject.toml。

• pyproject.toml (建议)
• setup.py (历史兼容)

3.构建前端(build frontend)

构建前端的责任: 准备环境，调用backend完成整个构建流程

• 为“构建后端”准备好独立的环境，比如setup_tools, wheel等工具。准备环境，可以是一个临时目录或虚拟环境(通过venv构建一个轻量级的环境，通过链接复用当前的python)安装pyproject.toml中的build-system.requires中的构建依赖的包安装"后端的get_requires_for_build_sdist/wheel"的依赖包
• 调用后端，生成元数据、构建

[build-system]
requires = ["setuptools >= 68.2.2", "wheel"]
build-backend = 'setuptools.build_meta'

常见的有下面两种前端：

• pip: pip wheel 构建bdist
• build: python -m build 更灵活，支持sdist/bdist (每次编译时间都很长，build cache不生效)

build 是一个python构建前端，"python -m build" 本身就是一个命令行程序, 解析pyproject.toml, 准备构建环境，调用构建后端，最终构建出sdist/bidist。

# pip install build
pip wheel .
python -m build .

source -> sdist(source distribution, tar.gz) -> bidst(binary distribution, wheel)

4.构建后端(build backend)

核心责任是:

• 生成元数据
• 构建(含编译、打包等步骤)，生成最终的构建产出。

常见的比如setuptools.build_meta、hatchling、Flit、PDM等。

PEP 517 给出了一种构建后端的规范，约定了一系列的接口，只要按规范实现这些接口，都是后端的一个实现。接口如下：

• get_requires_for_build_sdist
• build_sdist
• get_requires_for_build_wheel
• prepare_metadata_for_build_wheel
• build_wheel

构建前端(比如python -m build)在构建的过程中，会调用相应的函数，执行安装依赖、构建等相关步骤。

def get_requires_for_build_sdist(config_settings=None):
    ...

def build_sdist(sdist_directory, config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings=None):
    ...

def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
    ...

def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
    ...

4.1.术语

source tree: 是一个源码目录(tree), 通常是一个基于VCS(版本控制系统，比如git)的一个checkout

source distribuion(sdist): 源码分发，含Package源代码和元数据，基于source tree打包而成，通常是一个名为xxx-3.14.tar.gz的压缩包

binary distribution(bdist, whl): 二进制分发, 含动态链接库及二进制执行程序。

1. build
2. build fontendbuild、pipbuild backendsetup.build_meta、hatchling、Flit、PDM
3. source tree: VCS的一个checkout
4. source distribution: 待打包package相关源码的一个快照
5. build frontend: 从source tree(或sdist)中，构建whl, 背后是调用backend.
6. pyo3 (Rust bindings for the Python interpreter)

4.2.参考资料

• https://peps.python.org/pep-0517/
• https://github.com/daneah/publishing-python-packages
• https://toml.io/cn/v1.0.0
• https://peps.python.org/pep-0517/
• https://packaging.python.org/en/latest/
• https://pip.pypa.io/en/stable/
• https://github.com/PyO3/setuptools-rust
• https://github.com/python-poetry/poetry