术语

本 PEP 使用以下术语

• 构建机器：执行软件包构建过程的机器。
• 主机机器：将安装和运行生成工件的机器。
• 构建依赖项：仅在构建过程中所需的软件包。它必须在构建时可用，并为构建机器的操作系统和架构构建。典型示例包括编译器、代码生成器和构建工具。
• 主机依赖项：在构建期间需要，通常在运行时也需要的软件包。它必须在构建期间可用，并为主机机器的操作系统和架构构建。这些通常是项目链接的库。
• 运行时依赖项：仅在安装后使用软件包时才需要的软件包。它在构建时不需要，但必须在主机机器运行时可用。

请注意，此术语在构建和打包工具之间不一致，因此在比较 pyproject.toml 中的构建/主机依赖项与其他软件包管理器的依赖项时必须小心。

请注意，本 PEP 中未使用“目标机器”或“目标依赖项”。这通常仅与交叉编译编译器或其他此类高级场景相关 [3], [4] – 这超出了本 PEP 的范围。

最后，请注意，虽然“依赖项”是构建时所需软件包最广泛使用的术语，但 pyproject.toml 中用于 PyPI 构建时依赖项的现有键是 build-requires。因此，本 PEP 在 [external] 下使用键 build-requires 和 host-requires 以保持一致性。

构建和主机依赖项

明确分离与构建和主机平台定义相关的元数据，而不是假设构建和主机平台始终相同，这很重要 [5]。

构建依赖项通常在构建过程中运行 - 它们可能是编译器、代码生成器或其他此类工具。如果使用构建依赖项意味着运行时依赖项，则无需显式声明该运行时依赖项。例如，当使用 gfortran 将 Fortran 代码编译成 Python 扩展模块时，该软件包可能会依赖于 libgfortran 运行时库。不显式列出此类运行时依赖项的原因有两方面：（1）它可能取决于编译器/链接器标志或构建环境的详细信息，以确定依赖项是否存在；（2）这些运行时依赖项可以由 auditwheel 等工具自动检测和处理。

主机依赖项通常不在构建过程中运行，而仅用于链接。但这并非规则——可能需要通过模拟器或通过 crossenv 等自定义工具运行主机依赖项。当主机依赖项意味着运行时依赖项时，也不必声明该运行时依赖项，就像构建依赖项一样。

当声明了主机依赖项且正在执行与交叉编译无关的操作的工具，它可能会决定将 host-requires 列表合并到 build-requires 中——这是否有用取决于上下文。

具体软件包规范

“软件包 URL”或 PURL 是一种广泛使用的 URL 字符串，用于标识旨在跨打包生态系统可移植的软件包。其设计是

scheme:type/namespace/name@version?qualifiers#subpath

scheme 组件是一个固定字符串 pkg，其他组件中只有 type 和 name 是必需的。

由于外部依赖项很可能是手动输入的，我们提出了一个 PURL 派生词，为了符合人体工程学和用户友好性，它引入了许多更改（下面将进一步讨论）

• 通过新的 virtual 类型支持虚拟软件包。
• 允许 version 字段中使用版本范围（而不仅仅是字面量）。

在此派生词中，我们将 pkg 方案替换为 dep。因此，我们将它们称为 DepURLs。

例如，PyPI 上 requests 软件包的 DepURL 将是

dep:pypi/requests
# equivalent to pkg:pypi/requests

采用 PURL 兼容字符串在 pyproject.toml 中指定外部依赖项，一次性解决了许多问题，并且 Python 和其他多种语言中已经有该规范的实现。PURL 也已受依赖项相关工具支持，如 SPDX（参见 SPDX 2.3 规范中的外部存储库标识符）、开放源代码漏洞格式 和 Sonatype OSS Index；不必等待数年才能获得此类工具的支持，这是很有价值的。DepURL 可以非常轻松地转换为 PURL，除了 dep:virtual，它在 PURL 中没有等效项。

对于没有可引用的规范包管理器的具体包，可以使用 dep:generic/dep-name，或者直接引用包维护的 VCS 系统（例如，dep:github/user-or-org-name/dep-name）。这两种方式哪种更合适取决于具体情况。本 PEP 建议在包名明确且众所周知（例如，dep:generic/git 或 dep:generic/openblas）时使用 dep:generic，否则使用 VCS 作为类型。为任何给定包选择哪个名称作为规范名称，以及制定和记录此类选择的过程，是 PEP 804 的主题。

虚拟软件包规范

PURL 尚未提供对虚拟或虚拟依赖规范的支持。添加虚拟类型 的提案正在为修订版 1.1 讨论中。

与此同时，我们建议为我们的 dep: 派生词添加一个新的*类型*，即 virtual 类型，它可以接受两个*命名空间*（可通过 PEP 804 中给出的过程进行扩展）

• interface：用于 BLAS 或 MPI 等组件。
• compiler：用于 C 或 Rust 等编译语言。

此*名称*应是接口或语言最常见的名称，小写。一些示例包括

dep:virtual/compiler/c
dep:virtual/compiler/cxx
dep:virtual/compiler/rust
dep:virtual/interface/blas
dep:virtual/interface/lapack

由于此类依赖项数量有限，似乎它将被理解并很好地映射到具有虚拟软件包的 Linux 发行版以及 conda 和 Spack 等。

版本控制

PURL 通过 URL 的 @ 组件支持固定版本。例如，numpy===2.0 可以表达为 pkg:pypi/numpy@2.0。

PURL 支持超越固定版本的版本表达式和范围，通过 vers URI（参见规范）

vers:type/version-constraint|version-constraint|...

用户应该将 pkg: URL 与 vers: URL 耦合。例如，要表达 numpy>=2.0，PURL 等效项将是 pkg:pypi/numpy 加上 vers:pypi/>=2.0。这可以通过以下方式完成

• 一个两项列表：["pkg:pypi/numpy", "vers:pypi/>=2.0"]。
• 一个百分比编码的 URL 限定符：pkg:pypi/numpy?vers=vers:pypi%2F%3E%3D2.0。

由于这些选项都不太符合人体工程学，我们选择让 DepURLs 也接受版本范围指定符，其语义是 PEP 440 语义的子集。允许的运算符是那些在包管理器中广泛可用的运算符（例如，==、> 和 >= 很常见，而 ~= 则不常见）。

一些例子

• dep:pypi/numpy@2.0: numpy 精确锁定在 2.0 版本。
• dep:pypi/numpy@>=2.0: numpy 版本大于或等于 2.0。
• dep:virtual/interface/lapack@>=3.7.1: 任何实现 LAPACK 接口且版本大于或等于 3.7.1 的包。

特定虚拟软件包的版本方案（如果上游项目或标准未明确定义）将在中央注册表中定义（参见 PEP 804）。

环境标记

可以在 DepURLs 后面使用常规环境标记（最初定义于 PEP 508）。PURL 限定符，使用 ? 后跟包类型特定的依赖项规范器组件，不应用于环境标记足以满足的目的。这样做的原因是务实的：环境标记已用于 pyproject.toml 中的其他元数据，因此与 pyproject.toml 一起使用的任何工具可能已经有一个强大的实现来解析它。我们不期望需要 PURL 限定符提供的额外可能性（例如，指定 Conan 或 conda 频道，或 RubyGems 平台）。

我们将 DepURL 和环境标记的组合命名为“外部依赖项规范器”，类似于现有的依赖项规范器。

依赖项的规范名称和 -dev(el) 分割软件包

发行版将一个软件包拆分成两个或更多软件包的情况相当常见，但远非普遍。特别是，运行时组件通常可以与开发组件（头文件、pkg-config 和 CMake 文件等）分开安装。后者通常具有名称，并在项目/库名称后附加 -dev 或 -devel。此外，为了保持安装大小可控，较大的软件包有时会被拆分成多个独立的软件包。通常情况下，此类软件包拆分未由软件包维护者定义或识别，因此任何拆分的含义都是模糊的。因此，此类拆分不应反映在 [external] 表中。无法以在所有发行版中都适用的合理方式指定此内容，因此 [external] 中应仅使用规范名称。

使用 DepURL 的预期含义是“具有指定名称的完整软件包”。即，包括软件包中的所有可安装工件。软件包拆分是否相关将取决于元数据使用的上下文。例如，如果 libffi 是主机依赖项，并且工具想要为构建 wheel 准备环境，那么如果发行版已将 libffi 的头文件拆分到 libffi-devel 软件包中，那么该工具必须同时安装 libffi 和 libffi-devel。

关于如何定义规范软件包名称以及工具在实际使用 [external] 进行安装时如何处理软件包拆分，请参考 PEP 804。

Python 开发头文件

Python 头文件和其他构建支持文件也可能被拆分。这与上面一节的情况相同（因为 Python 在发行版中只是一个常规软件包）。然而，python-dev|devel 依赖项很特殊，因为在 pyproject.toml 中，Python 本身是隐式而非显式依赖项。因此，这里需要做出选择——是隐式添加 python-dev，还是让每个软件包作者在 [external] 下显式添加它。为了保持 Python 依赖项和外部依赖项之间的一致性，我们选择隐式添加它。当 [external] 表包含一个或多个编译器软件包时，必须假定 Python 开发头文件是必需的。

捆绑共享库对 wheel 元数据的影响

一个 wheel 可以捆绑其外部依赖项。这在将 wheel 分发到 PyPI 或其他 Python 包索引时尤其常见——auditwheel、delvewheel 和 delocate 等工具会自动完成此过程。因此，sdist 中的 Requires-External-Dep 条目可能会从使用 cibuildwheel 等工具从该 sdist 构建的 wheel 中消失。也可能 Requires-External-Dep 条目保留在 wheel 中，保持不变或具有更严格的限制。auditwheel 默认不捆绑某些允许列表中的依赖项，例如 OpenGL。此外，auditwheel 和 delvewheel 允许用户通过 --exclude 或 --no-dll 命令行标志手动排除依赖项。这用于避免捆绑大型共享库，例如来自 CUDA 的库。

因此，从 pyproject.toml 中的外部依赖项生成的 Requires-External-Dep 条目可能因构建/分发过程而异，在 sdist 及其对应的 wheel(s) 之间存在差异。

请注意，这并不意味着该字段必须标记为 Dynamic，因为此区分仅适用于由构建后端从 sdist 构建的 wheel。特别是，从其他 wheel 构建的 wheel 不需要满足此约束。

可选依赖项与依赖项组

external.dependency-groups 的理由与 PEP 735 中引入 [dependency-groups] 的理由相同。因此，其预期的使用和包含/排除到核心元数据中的语义与 [dependency-groups] 相同。

external.optional-dependencies 将出现在核心元数据中。external.dependency-groups 则不会。

弃用

External-Requires 核心元数据字段将被标记为*已弃用*，不鼓励使用。

新增

核心元数据新增两个字段

• Requires-External-Dep。外部需求，表示为外部依赖项规范器字符串。
• Provides-External-Extra。一个仅包含外部依赖项（如 Requires-External-Dep 中所发现的）的*额外*组。

版本提升

鉴于拟议的更改纯粹是增量式的，核心元数据版本将提升至 2.6。

这只会影响 PyPI 和支持外部运行时依赖项的工具，否则不需要任何更改。

表名

工具**必须**将本 PEP 定义的字段指定在名为 [external] 的表中。任何工具均不得向此表添加非本 PEP 或后续 PEP 定义的字段。缺少 [external] 表意味着该软件包不包含任何外部依赖项，或者其包含的外部依赖项被假定已存在于系统中。

build-requires/optional-build-requires

• 格式：外部依赖项规范器数组（build-requires）以及一个包含外部依赖项规范器数组值的表（optional-build-requires）
• 核心元数据：不适用

构建项目所需的（可选）外部构建要求。

对于 build-requires，它是一个键，其值是字符串数组。每个字符串表示项目的一个构建要求，并且**必须**格式化为有效的外部依赖项规范器。

对于 optional-build-requires，它是一个表，其中每个键指定一组额外的构建要求，其值是一个字符串数组。数组的字符串**必须**是有效的外部依赖项规范器。

host-requires/optional-host-requires

• 格式：外部依赖项规范器数组（host-requires）以及一个包含外部依赖项规范器数组值的表（optional-host-requires） - 核心元数据：不适用

构建项目所需的（可选）外部主机要求。

对于 host-requires，它是一个键，其值是字符串数组。每个字符串表示项目的主机要求，并且**必须**格式化为有效的外部依赖项规范器。

对于 optional-host-requires，它是一个表，其中每个键指定一组额外的主机要求，其值是一个字符串数组。数组的字符串**必须**是有效的外部依赖项规范器。

dependencies/optional-dependencies

• 格式：外部依赖项规范器数组（dependencies）以及一个包含外部依赖项规范器数组值的表（optional-dependencies）
• 核心元数据：Requires-External-Dep，Provides-External-Extra

项目（可选）的运行时依赖项。

对于 dependencies，它是一个键，其值是字符串数组。每个字符串表示项目的依赖项，并且**必须**格式化为有效的外部依赖项规范器。每个字符串都必须作为 Requires-External-Dep 字段添加到核心元数据中。

对于 optional-dependencies，它是一个表，其中每个键指定一个*额外*项，其值是字符串数组。数组的字符串**必须**是有效的外部依赖项规范器。对于每个 optional-dependencies 组

• 组的名称**必须**作为 Provides-External-Extra 字段添加到核心元数据中。
• 该组中的外部依赖项规范器**必须**作为 Requires-External-Dep 字段添加到核心元数据中，并带有相应的 ; extra == 'name' 环境标记。

dependency-groups

• 格式：一个表，其中每个键是组的名称，值是外部依赖项规范器数组、表或两者的混合。
• 核心元数据：不适用

PEP 735 风格的依赖项组，但使用外部依赖项规范器而不是 PEP 508 字符串。所有其他细节（例如组包含、名称规范化）遵循官方的依赖项组规范。

cryptography 39.0

pyproject.toml 内容

[external]
build-requires = [
  "dep:virtual/compiler/c",
  "dep:virtual/compiler/rust",
  "dep:generic/pkg-config",
]
host-requires = [
  "dep:generic/openssl",
  "dep:generic/libffi",
]

PKG-INFO / METADATA 内容：不适用。

SciPy 1.10

pyproject.toml 内容

[external]
build-requires = [
  "dep:virtual/compiler/c",
  "dep:virtual/compiler/cpp",
  "dep:virtual/compiler/fortran",
  "dep:generic/ninja",
  "dep:generic/pkg-config",
]
host-requires = [
  "dep:virtual/interface/blas",
  "dep:virtual/interface/lapack@>=3.7.1",
]

PKG-INFO / METADATA 内容：不适用。

Pillow 10.1.0

pyproject.toml 内容

[external]
build-requires = [
  "dep:virtual/compiler/c",
]
host-requires = [
  "dep:generic/libjpeg",
  "dep:generic/zlib",
]

[external.optional-host-requires]
extra = [
  "dep:generic/lcms2",
  "dep:generic/freetype",
  "dep:generic/libimagequant",
  "dep:generic/libraqm",
  "dep:generic/libtiff",
  "dep:generic/libxcb",
  "dep:generic/libwebp",
  "dep:generic/openjpeg@>=2.0",
  "dep:generic/tk",
]

PKG-INFO / METADATA 内容：不适用。

NAVis 1.4.0

pyproject.toml 内容

[project.optional-dependencies]
r = ["rpy2"]

[external]
build-requires = [
  "dep:generic/XCB; platform_system=='Linux'",
]

[external.optional-dependencies]
nat = [
  "dep:cran/nat",
  "dep:cran/nat.nblast",
]

PKG-INFO / METADATA 内容

Provides-External-Extra: nat
Requires-External-Dep: dep:cran/nat; extra == 'nat'
Requires-External-Dep: dep:cran/nat.nblast; extra == 'nat'

Spyder 6.0

pyproject.toml 内容

[external]
dependencies = [
  "dep:cargo/ripgrep",
  "dep:cargo/tree-sitter-cli",
  "dep:golang/github.com/junegunn/fzf",
]

PKG-INFO / METADATA 内容

Requires-External-Dep: dep:cargo/ripgrep
Requires-External-Dep: dep:cargo/tree-sitter-cli
Requires-External-Dep: dep:golang/github.com/junegunn/fzf

jupyterlab-git 0.41.0

pyproject.toml 内容

[external]
dependencies = [
  "dep:generic/git",
]

[external.optional-build-requires]
dev = [
  "dep:generic/nodejs",
]

PKG-INFO / METADATA 内容

Requires-External-Dep: dep:generic/git

PyEnchant 3.2.2

pyproject.toml 内容

[external]
dependencies = [
  # libenchant is needed on all platforms but vendored into wheels
  # distributed on PyPI for Windows. Hence choose to encode that in
  # the metadata. Note: there is no completely unambiguous way to do
  # this; another choice is to leave out the environment marker in the
  # source distribution and either live with the unnecessary ``METADATA``
  # entry in the distributed Windows wheels, or to apply a patch to this
  # metadata when building those wheels.
  "dep:github/AbiWord/enchant; platform_system!='Windows'",
]

PKG-INFO / METADATA 内容

Requires-External-Dep: dep:github/AbiWord/enchant; platform_system!="Windows"

带依赖项组

pyproject.toml 内容

[external.dependency-groups]
dev = [
  "dep:generic/catch2",
  "dep:generic/valgrind",
]

PKG-INFO / METADATA 内容：不适用。