# PEP 517 ![image](https://github.com/Canvis-Me/freebsd-journal-cn/assets/55122738/13314734-7750-4829-9257-e02c12be39ea) * 原文链接： * 作者：CHARLIE LI * 译者：Canvis-Me & ChatGPT 某一天，在 IRC，bofh@ 在尝试更新一个 Python port 时遇到了一个问题：源代码不再包含 setup.py 文件。而没有这样的文件，Ports 框架中的 Python 框架就无法工作，没有前进的路。出于好奇，我开始对这个问题进行了一些浅显的调查，很快就发现了一个全新的打包和分发标准，我们迟早需要支持它。越来越多的软件包在这方面采取了领先或效仿的态度，而最终的 Python 3.12 版本将进一步加剧这个问题。我强调“标准”是因为 setup.py 和以前的第三方/附加 Python 软件分发从未被标准化或完全架构化过…… 于是，PEP 517 应运而生，这是一个实际的 Python 包构建和分发的设计和架构，使用了在 PEP 427 中首次标准化的 wheel 包格式。在浏览了所有相关的 Python Enhancement Proposals (PEPs，Python 编码风格指南) 后，我惊呼道，这好得多，让我们看看如何在 Ports 框架中实现这一点。 ## Python 打包的简要历史 大部分内容摘自“[为什么不应直接调用 setup.py](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html)” “简要”有多种理解方式，所以这可能看起来一点都不简要。这段历史遗憾地又长又曲折，略去了许多微妙之处，所以这是尽可能“简要”的版本。 在 Python 2.0 之前，不像 C 项目的 configure-build-install 工作流，并没有组织良好的分发 Python 代码的方式，。Python 2.0 引入了 distutils，这是标准库/分发中的一个新模块，提供了类似于更常见的 make(1) 目标的功能，处理 configure-build-install。这使得将其整合到像我们的 Ports 框架这样的发行系统中以创建操作系统级别的软件包相对简单。 不幸的是，只有 distutils 并不能很好地指定和强制执行依赖关系。与配置和编译代码的项目不同，那里缺少或不正确的依赖关系会在任何阶段导致错误，但对于解释性的 Python 代码（CPython 有一个字节码编译器，其输出实际上被执行，但这是一个完全不同的主题，有其自己的详细信息和陷阱），除了运行代码本身之外，没有实际的强制执行机制。像我们的 Ports 框架这样的发行系统处理等式的依赖关系部分，但大多数人在这个上下文之外不会阅读 README 或以其他方式找出在本地环境中安装 Python 代码所需的依赖关系。 然后是 setuptools，它被设计为 distutils 的一个增强的替代品，提供了依赖管理等功能。对于大多数在构建链的顶部使用 setuptools 的软件包来说，效果很好。然而，某些软件包在 setuptools 能够发挥作用之前导入依赖项。不同的目标不一定需要相同的依赖关系集。有些软件包甚至指定了确切的 setuptools 版本。最糟糕的是，一切都在同一个（主机）环境中运行，而 setuptools 本身无法正确创建执行所需的正确环境。 对于像我们 Ports 框架这样的发行系统，这些缺陷并不是太大的问题。我们有方法自动管理依赖关系并隔离环境，以提供 setuptools 发挥作用所需的正确环境，特别是使用 poudriere。在开发者场景中情况就不那么简单了，特别是在 Python 虚拟环境出现之前。 此外，由 distutils/setuptools 定义的包格式很不灵活，难以维护，并且在构建和安装 Python 软件包方面阻碍了创新。wheel 标准是作为一个独立于任何构建和安装方案的专用包格式开发的。这很像我们自己的 pkg(8) 或其他操作系统级软件包管理器包格式。不过，distutils/setuptools 本身依赖于另一个名为 wheel 的外部 Python 软件包提供这个功能，而不是在第一次集成时就把它整合进去。有人能闻到循环依赖的味道吗？ 在接下来的几年里，不同的项目涌现出来，试验非 distutils/setuptools 构建系统，特别是当 setuptools 变得像必要的那样臃肿时，但这些项目都是以老式 Unix 哲学的简单性为目标。但由于 distutils/setuptools 仍然是构建和安装的事实上的界面，这些新项目不能在生产中用于执行它们的意图。由于包格式定义为独立于任何构建和安装方案，因此出现了 PEP 517，这是一个生成构建系统实现的 wheel 的最小接口，允许在这个领域进行选择。 ## USE\_PYTHON=distutils 设想一个具有以下源代码布局的 Python 软件包示例： ``` sample/ ├── setup.py ├── … └── src/ └── sample/ ├── __init__.py └── … ``` 该 port 的外观可能如下所示： ``` PORTNAME= sample DISTVERSION= 1.2.3 CATEGORIES= devel python MASTER_SITES= PYPI PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} MAINTAINER= freebsd@example.org COMMENT= Python sample module RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} USES= python USE_PYTHON= autoplist distutils .include ``` 在具备适当配置的正常 setup.py 的情况下，ports 框架会分别对每个 port 目标执行 setup.py 的 configure、build 和 install 目标。Python 包并未指定任何构建依赖项，除了隐式的 distutils/setuptools 提供的全部结构。运行时依赖项被指定，而 distutils/setuptools 仅在安装时检查。生成安装元数据，其中包括一个我们使用的已安装工件列表，经过轻微修改，我们用于制作打包清单。 这遵循了传统上用于 C/C++ 项目的 Makefile 的过程。工件被安装到一个阶段目录层次结构中，然后打包起来。 ## USE\_PYTHON=pep517 设想一个具有以下源代码布局的更新后的 Python 包示例： ``` sample/ ├── pyproject.toml ├── … └── src/ └── sample/ ├── __init__.py └── … ``` 该 port 的外观可能如下所示： ``` PORTNAME= sample DISTVERSION= 1.2.4 CATEGORIES= devel python MASTER_SITES= PYPI PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} MAINTAINER= freebsd@example.org COMMENT= Python sample module BUILD_DEPENDS= ${PYTHON_PKGNAMEPREFIX}flit-core>0:devel/py-flit-core@${PY_FLAVOR} RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} >USES= python USE_PYTHON= autoplist pep517 .include ``` 乍一看，这个 port 几乎看起来是相同的。在设计 port 工作流程时，我们仔细考虑以确保在 Python 软件包更新并采用 PEP 517 时进行尽可能无缝的转换。 通过这种方法，setuptools 不再是关注的焦点。相反，隐式构建依赖项是两个独立的 Python 软件包 ports，即构建前端和集成前端。构建前端解析 pyproject.toml 中的构建特定元数据，以确定构建后端是否存在于环境中，并执行它以构建 wheel。在这个例子中，构建后端是 flit-core，并且它被指定为常规构建依赖项。如果构建成功，将生成一个具有严格格式的文件名的 wheel 文件。集成前端引用严格格式的 wheel 文件，检查运行时依赖项，并安装到分段目录，包括元数据。我们的打包清单来自这个与以前相似的元数据。 与其他方法相比，一个显著的省略是一个独立的配置阶段，它被集成到构建阶段中。这允许 Python 软件包选择其项目中最适合的构建后端，无论是 PyPI 中可用的还是其源代码中的自定义后端。 ## 注意事项和未来考虑 在 PEP 517 支持进入 Ports 框架之后的这段时间里，一些人对我们的实现提出了一些感知上的不灵活性。很可能，这种不灵活性是有意的，基于对 Python 标准以及安全性/完整性等方面的遵循。 一个焦点涉及到在阶段过程中调用的 wheel 文件名。我们可以将整个通配符 wheel 文件名传递给 PEP 517 集成前端，然后就此打住，但这样做浪费了改善 Python 端和 port 之间元数据一致性的黄金机会。一些 port 的名称或版本与它们的 Python 软件包元数据对应不上。更让人愤慨的是，PyPI 曾经出现过拼写错误导致恶意软件的包。能够根据不一致的元数据提前使 port 构建失败提供了另一种机制，即使在提交任何补丁之前，也能使我们的树免受即使是最隐秘的攻击的威胁。 由于 wheel Python 软件包本身切换到了 PEP 517，我们的 setuptools ports 现在可以依赖于它，而不是相反。这将 USE\_PYTHON=distutils 情况下构建 wheel 打开，而不是原始方法，这不仅将围绕 PEP 517 集成前端统一阶段工作流程，而且在过程中享受相同的元数据一致性检查。 总的来说，这是一个曾经并将继续是一场磨难。更现代的语言包括它们自己的包管理器，主要面向开发人员及其隔离的环境，但预计大多数人，包括操作系统级打包者，都会使用它们。至少在 Python 中，一直有某种方式可以至少绕过这种概念，首先是使用 distutils/setuptools，现在是 PEP 517 使事情变得更加清晰。我们仍然需要注意将语言的可接受软件包版本方案映射到我们的标准和总体元数据一致性等问题，但这些问题可以逐渐解决。 *** CHARLIE LI 是一个专注于 GTK 桌面、Python、一些 Rust 以及业余无线电（呼号：K3CL）的 ports 提交者。有时会涉足其他领域进行根本原因分析。在现实生活中，他是一名技术顾问，并且有时在他当地的公共交通机构调度公共汽车。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://freebsd-journal-cn.bsdcn.org/20230910-port-yu-ruan-jian-bao/pep-517.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.