如何在Python中编写符合PEP 517标准的包构建后端？-Python教程-PHP中文网

pep 517构建后端是通过pyproject.toml指定的可导入python模块，提供build_wheel等四个标准函数，取代直接执行setup.py；后者是命令式脚本易产生副作用，前者为声明式、隔离化接口。

如何在python中编写符合pep 517标准的包构建后端？

什么是PEP 517构建后端，它和setup.py有什么区别？

PEP 517定义了一套与构建工具解耦的接口规范，要求包必须通过一个明确的、可导入的Python模块（即“构建后端”）来提供构建逻辑，而不是依赖全局可执行的setup.py脚本。这意味着：setup.py不再被直接执行，而是由构建前端（如pip、build）调用后端模块里的函数。

关键区别在于控制权转移：

setup.py是命令式脚本，容易产生副作用（比如修改sys.path、意外执行install逻辑）
PEP 517后端是声明式、纯函数式接口，只暴露四个标准函数：build_wheel、build_sdist、get_requires_for_build_wheel、get_requires_for_build_sdist

如果你还在用python setup.py bdist_wheel，那就不符合PEP 517；pip >=21.3默认强制启用PEP 517，老式setup.py会被忽略或报错。

如何写一个最小可行的PEP 517构建后端？

最简实现只需一个pyproject.toml + 一个Python模块（比如build.py），不依赖任何第三方构建库：

# pyproject.toml
[build-system]
requires = ["wheel"]
build-backend = "build:build_backend"

# build.py
from wheel.wheel import Wheel
from pathlib import Path
import tarfile
import zipfile
<p>def get_requires_for_build_wheel(config_settings=None):
return ["wheel"]</p><p>def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):</p><h1>构建一个空wheel（仅示意结构）</h1><pre class="brush:python;toolbar:false;">wheel_path = Path(wheel_directory) / "mypkg-0.1-py3-none-any.whl"
with zipfile.ZipFile(wheel_path, "w") as w:
    w.writestr("mypkg/__init__.py", "")
    w.writestr("mypkg-0.1.dist-info/METADATA", "Name: mypkg\nVersion: 0.1\n")
return wheel_path.name

def get_requires_for_build_sdist(config_settings=None): return []

def build_sdist(sdist_directory, config_settings=None): sdist_path = Path(sdist_directory) / "mypkg-0.1.tar.gz" with tarfile.open(sdist_path, "w:gz") as t: t.add("pyproject.toml", "mypkg-0.1/pyproject.toml") return sdist_path.name

注意点：

python-parallelization

将顺序 Python 代码转换为并行/并发实现，用于在需要并行化 Python 代码、提升性能时使用。

下载

build-backend值格式为"module:object"，module必须可导入（即路径在Python path里）
所有函数必须接受config_settings参数（即使不用），否则pip会报TypeError
返回值必须是字符串（文件名），不能是Path对象或绝对路径
build_wheel必须返回wheel文件名，且该文件必须已写入wheel_directory

为什么用setuptools.build_meta而不是自己手写后端？

除非你有特殊需求（比如定制元数据生成、规避setuptools依赖、嵌入式场景精简），否则不要从零手写后端。原因很实际：

setuptools.build_meta已稳定支持PEP 517，并兼容pyproject.toml配置
它自动处理动态版本、入口点、data_files、C扩展等复杂逻辑
pip和build工具对它的路径解析、缓存、隔离环境支持最完善

正确做法是：

# pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

然后把原来setup.py里的逻辑迁移到pyproject.toml的[project]和[project.optional-dependencies]等段落中。
如果仍需部分逻辑（如动态读取VERSION），可用dynamic字段配合setup.py——但此时setup.py只作为数据源，不参与构建执行。