推荐但非必需的依赖项

软件包维护者通常使用附加功能来声明可选依赖项，这些依赖项可扩展软件包的功能或性能。在某些情况下，可能很难确定哪些依赖项是必需的，哪些应归类为附加功能。必须在典型用户（可能更喜欢默认提供大多数功能）和需要最小安装且不包含大型可选依赖项的用户之间取得平衡。现有 Python 打包基础设施的一种解决方案是，软件包维护者定义一个名为（例如）recommended 的附加功能，其中包含所有非必需但建议的依赖项。然后指示用户使用 package[recommended] 安装软件包，而那些喜欢更多控制的用户可以使用 package。然而，在实践中，许多用户不知道 [recommended] 语法，这使得他们在典型安装时需要知道这一点。如果有一种方法可以默认安装推荐的依赖项，同时提供一种方式供用户请求更小的安装，那么这将满足此用例，本 PEP 描述了此解决方案。

通过鼓励用户默认包含额外依赖项来演示此模式的软件包示例包括：

• astropy: astropy[recommended]
• sunpy: sunpy[all]
• fastapi: fastapi[standard]

支持多个后端或前端的软件包

使用附加功能的另一个常见用例是定义不同的后端或前端以及每个后端或前端需要安装的依赖项。软件包可能需要安装至少一个后端或前端才能正常运行，但可能对哪个后端或前端是灵活的。此类前端或后端的具体示例包括：

• Qt 前端库，可由 PyQt5、PyQt6、PySide2 或 PySide6 提供
• 后端数据库，例如 MySQL、PostgreSQL、SQLite

根据当前的打包标准，维护者要么必须要求其中一个后端或前端，要么要求用户始终指定附加功能，例如 package[backend]，因此如果用户只安装 package，则存在无法使用的安装风险。如果有一种方法可以指定一个或多个默认后端或前端，并提供一种方法来覆盖这些默认值，这将为用户提供更好的体验，本 PEP 中描述的方法将允许这样做。

请注意，本 PEP 不旨在解决禁止冲突或不兼容的附加功能的问题，例如，如果一个软件包需要恰好一个前端或后端软件包。目前在 Python 打包基础设施中没有机制来禁止安装冲突或不兼容的附加功能，本 PEP 不会改变这一点。

需要至少一个后端或前端才能工作并推荐默认附加功能以安装后端或前端的软件包示例包括：

• kivy: kivy[base]
• napari: napari[all]
• glueviz: glueviz[qt]

在所有这三种情况下，安装不带任何附加功能的软件包会导致安装失败，这对于其中一些软件包来说是一个常见的支持问题。

Default-Extra 元数据字段

一个新的多用途元数据字段 Default-Extra 将添加到核心软件包元数据中。对于此字段，每个条目必须是一个字符串，指定一个附加功能，该附加功能将在未明确指定任何附加功能的情况下安装软件包时自动包含。

只有已在 Provides-Extra 条目中指定的条目才能在 Default-Extra 条目中使用。

示例

Default-Extra: recommended
Default-Extra: backend1
Default-Extra: backend2
Default-Extra: backend3

由于这在核心软件包元数据中引入了一个新字段，因此这将需要将Metadata-Version提升到下一个次要版本（撰写本文时为 2.5）。

[project] 元数据表中的新键

一个新的键将被添加到 PEP 621 中最初定义并在PyPA 规范中定义的 [project] 元数据表中。此键将命名为 default-optional-dependency-keys，描述如下：

• TOML 类型：字符串数组
• 相应的核心元数据字段：Default-Extra

default-optional-dependency-keys 中的每个字符串都必须是在可选依赖项中定义的附加功能的名称，并且此数组中的每个附加功能都将转换为核心软件包元数据中匹配的 Default-Extra 条目。将生成上一节中显示的示例 Default-Extra 条目的有效用法示例是：

[project]
default-optional-dependency-keys = [
    "recommended",
]

和

[project]
default-optional-dependency-keys = [
    "backend1",
    "backend2",
    "backend3"
]

覆盖默认附加功能

如果在依赖项规范中明确给出了附加功能，则忽略默认附加功能。否则，将安装默认附加功能。

例如，如果一个软件包定义了 extra1 默认附加功能以及一个非默认的 extra2 附加功能，那么如果用户使用以下命令安装软件包：

$ pip install package

将包含默认的 extra1 依赖项。如果用户改为使用以下命令安装软件包：

$ pip install package[extra2]

则将安装 extra2 附加功能，但将忽略默认的 extra1 附加功能。

如果在安装命令或依赖项树中多次指定了同一个软件包，则如果任何软件包实例未指定附加功能，则必须安装默认附加功能。例如，如果安装软件包 spam，其中 package 在依赖项树中多次出现：

spam
├── tomato
│   ├── package[extra2]
└── egg
    └── package

则应安装默认附加功能，因为 package 至少出现一次且未指定附加功能。

空附加功能集，例如 package[]，应解释为表示应**不**安装任何默认附加功能（除非 package 出现在依赖项树的其他位置，在这种情况下，将**安装**默认附加功能，如上所述）。这将提供一种获取软件包最小安装的通用方法。

我们还注意到，某些工具（例如 pip）目前会忽略无法识别的附加功能，并向用户发出警告以指示附加功能未被识别，例如：

$ pip install package[non-existent-extra]
WARNING: package 3.0.0 does not provide the extra 'non-existent-extra'
...

对于表现如此（而不是引发错误）的工具，如果在依赖项规范中识别出附加功能无效，则应忽略它；如果所有指定的附加功能都无效，则应将其视为等同于 package[]（而不是 package），并且**不**安装任何默认附加功能。

最后，我们注意到（正如依赖工具来取消选择任何默认附加功能中讨论的那样），软件包安装器可以实现自己的选项来控制上述行为，例如实现一个选项，禁用某些或所有软件包的默认附加功能，无论这些软件包在依赖项树中的位置如何。如果实现了此类工具特定的选项，工具开发人员应使其可选，并且用户应将上述 PEP 771 行为作为默认行为。

示例

本节我们将研究动机一节中描述的用例，以及如何通过使用上面概述的规范来解决这些用例。

[project]
default-optional-dependency-keys = [
    "recommended"
]

[project.optional-dependencies]
recommended = [
    "package1",
    "package2"
]

[project]
default-optional-dependency-keys = [
    "recommended"
]

[project.optional-dependencies]
recommended = [
    "scipy",
    "..."
]

$ pip install astropy

$ pip install astropy[]

[project]
default-optional-dependency-keys = [
    "backend1"
]

[project.optional-dependencies]
backend1 = [
    "package1",
    "package2"
]
backend2 = [
    "package3"
]

[project]
default-optional-dependency-keys = [
    "pyqt5"
]

[project.optional-dependencies]
pyqt5 = [
    "PyQt5",
    "..."
]
pyside2 = [
    "PySide2",
    "..."
]
pyqt6 = [
    "PyQt6",
    "..."
]
pyside6 = [
    "PySide6",
    "..."
]

$ pip install napari

$ pip install napari[pyside6]

[project]
default-optional-dependency-keys = [
    "recommended"
]

[project.optional-dependencies]
recommended = [
    "package1",
    "package2"
]
alternative = [
    "package3"
]
additional = [
    "package[recommended]",
    "package4"
]

[project]
default-optional-dependency-keys = [
    "recommended"
]

[project.optional-dependencies]
recommended = [
    "scipy",
    "..."
]
jupyter = [
    "astropy[recommended]",
    "ipywidgets",
    "..."
]

$ pip install astropy[jupyter]

$ pip install astropy[recommended, jupyter]

$ pip install package  # installs default backend and frontend
$ pip install package[]  # installs no backends or frontends
$ pip install package[backend1]  # installs backend1 and default frontend
$ pip install package[frontend2]  # installs frontend2 and default backend
$ pip install package[backend1, frontend2]  # installs backend1 and frontend2

$ pip install package  # installs default backend and frontend
$ pip install package[]  # installs no backends or frontends
$ pip install package[backend1, defaultfrontend]  # installs backend1 and default frontend
$ pip install package[defaultbackend, frontend2]  # installs frontend2 and default backend
$ pip install package[backend1, frontend2]  # installs backend1 and frontend2

不使用默认附加功能的软件包

一旦打包生态系统中的工具添加了对本 PEP 的支持，不使用默认附加功能的软件包将继续按原样工作，并且不应出现兼容性问题。

使用默认附加功能的软件包

一旦软件包开始定义默认附加功能，这些默认值将仅在实现本 PEP 的最新版本打包工具中生效，但这些软件包仍可使用旧版打包工具进行安装——主要区别在于，在使用旧版打包工具时，默认附加功能不会自动安装。

如如何教授中所述，软件包作者需要根据其用户群仔细评估何时以及如何采用默认附加功能，因为某些操作（例如将必需依赖项移动到默认附加功能）可能会导致使用旧版软件包安装程序（不支持默认附加功能）的用户出现故障。从这个意义上讲，软件包作者应注意，此功能如果以某些方式使用，可能会给用户带来向后兼容性问题，因此他们有责任确保将对用户的影响降至最低。

与打包相关的工具

最重要的向后兼容性方面与打包工具对附加功能的假设有关——具体来说，本 PEP 改变了附加功能不再仅在向依赖树添加依赖项方面具有累加性的假设，并且指定某些附加功能可能会导致安装的依赖项减少。

行为改变的一个具体示例可以在 pip 中看到：考虑一个包 package，它有一个必需的依赖项 numpy，以及一个名为 recommended 的默认额外功能，其中包括 scipy。如果用户安装 package[]，则只安装 package 和 numpy。如果用户然后执行：

$ pip freeze > requirements.txt

则 requirements.txt 将包含例如：

package==1.0.2
numpy==2.1.0

然而，如果用户然后使用以下命令从该文件安装要求：

$ pip install -r requirements.txt

然后 pip 将安装 package（其中将包含默认额外功能）以及 numpy，因此最终环境将包含 scipy。在这种特定情况下的解决方案是用户向 pip install 传递 --no-deps 以避免解析依赖树，但这里的重点是说明由于对额外功能可能产生的影响的假设发生变化，打包工具的行为可能会发生变化。

值得注意的是，最近通过的 PEP 751 定义了一种新的文件格式，旨在将来取代 pip freeze 输出和其他工具等替代方案。新文件格式的设计使得文件中的软件包在**不**解析依赖项的情况下安装，这意味着它将与本 PEP 中指定的默认附加功能完全兼容，并将避免上面提到的 pip freeze/pip install -r 问题。

软件包最终用户

应向软件包用户提供清晰的安装说明，其中显示软件包可用的附加功能及其行为方式，例如解释默认情况下将安装哪些推荐依赖项或给定的前端或后端，以及如何根据可用情况选择退出或覆盖默认值。

软件包作者

虽然定义附加功能及其相关使用规则清晰明了，但软件包作者在将其功能应用于软件包之前需要仔细考虑几个方面，以避免无意中破坏向后兼容性。

$ pip install package  # this installs package[A]
$ pip install package[B]

package1
└── package2
    └── package1

$ pip install package1[]

package1
└── package2
    └── package1[]

打包仓库维护者

需要考虑对为不同发行版（如 conda、Homebrew、Linux 软件包安装器（如 apt 和 yum）等）重新打包 Python 库的个人产生的影响。并非所有软件包发行版都有与所描述的方法一致的机制。事实上，某些发行版（如 conda）甚至没有附加功能的概念。

这里有两种情况需要考虑：

• 在手动重新打包的情况下，例如一些 conda-forge 配方，特别是当没有等效的附加功能时，默认附加功能的引入不应产生很大影响，因为已经必须手动决定包含哪些依赖项（例如，动机中提到的 astropy 软件包的 conda-forge 配方默认包含所有 recommended 依赖项，因为用户无法以其他方式明确请求它们）。
• 在以自动化方式进行重新打包的情况下，发行版维护者将需要仔细考虑如何处理默认附加功能，这可能意味着大量的工作和讨论。

像这样的 PEP 不可能详尽地考虑每种不同的软件包发行版。然而，最终，默认附加功能应被理解为软件包作者希望其软件包为大多数用户安装的方式，这应指导关于如何处理默认附加功能的决策，无论是手动还是自动。

使用元软件包进行推荐安装

使用现有的打包工具和基础设施，希望为某些用户提供最小安装，并为普通用户提供默认非最小安装（例如，包含推荐依赖项或默认后端）的软件包维护者，如果他们愿意分发两个软件包而不是一个软件包，从技术上讲已经可以实现这一点——例如 package-core 将是具有最小依赖项的主软件包，而 package 将是依赖于 package-core 并启用了可选依赖项的元软件包。

再次以动机一节中的一个具体示例为例，astropy 软件包定义了一个 recommended 附加功能，用户目前被指示在默认安装说明中安装它。原则上，可以将现有的 astropy 软件包重命名为例如 astropy-core，然后创建一个新的 astropy 软件包，它将是一个元软件包，包含以下依赖项部分：

dependencies = [
    "astropy-core[recommended]"
]

由于用户可能希望对 astropy 元软件包设置版本或版本约束（例如 astropy>5.0），因此元软件包需要遵循与核心软件包相同的版本，并且需要在依赖项部分使用严格的版本固定，例如：

version = "7.1.0"
dependencies = [
    "astropy-core[recommended]==7.1.0"
]

这个想法看起来很有吸引力，因为它在技术上已经可行。然而，在实践中，许多项目出于多种原因选择不这样做，我们现在将一一探讨。其中一些可能不适用于未来的新项目，但其中一些适用于所有项目，无论新旧。

$ pip uninstall package

取消选择附加功能的语法

主要的竞争方法之一如下：如果明确提供了任何附加功能，则不取消选择默认值，而是需要明确取消选择默认附加功能。

在这种情况下，将引入一种新的取消选择附加功能的语法，作为 PEP 508 中定义的迷你语言的扩展。如果一个软件包定义了默认附加功能，用户可以通过在附加功能名称前使用减号 (-) 来选择退出这些默认值。提议的语法更新如下：

extras_list   = (-)?identifier (wsp* ',' wsp* (-)?identifier)*

此新语法的有效示例包括，例如：

• package[-recommended]
• package[-backend1, backend2]
• package[pdf, -svg]

然而，这种方法存在两个主要问题：

• 需要定义一些规则来解释边缘情况，例如附加功能及其否定版本同时出现在同一依赖项规范中（例如 package[pdf, -pdf]）或者如果依赖项树同时包含 package[pdf] 和 package[-pdf]，而且这些规则对用户来说并不直观。
• 更重要的是，这将向依赖项规范引入新语法，这意味着如果任何软件包使用新语法定义了依赖项，它以及任何其他依赖于它的软件包将不再能通过现有打包工具安装，因此这将是一个主要的向后兼容性中断。

由于这些原因，此替代方案未包含在最终提案中。

在 extras_require 中添加一个特殊条目

一种潜在的解决方案，作为引入新的 Default-Extra 元数据字段的替代方案，是利用一个具有“特殊”名称的附加功能。

一个例子是使用一个空字符串：

Provides-Extra:
Requires-Dist: numpy ; extra == ''

其思想是，作为“空”附加功能一部分安装的依赖项只有在未指定其他附加功能时才会被安装。在 https://github.com/pypa/setuptools/pull/1503 中提出了一个实现，但发现没有办法在不破坏现有用法兼容性的情况下使其工作。例如，通过 setup.py 文件使用 Setuptools 的软件包可以执行：

setup(
    ...
    extras_require={'': ['package_a']},
)

这是有效的，并且等同于在 install_requires 中定义 package_a，因此更改空字符串的含义将破坏兼容性。

此外，不能使用其他字符串（例如 'default'）作为特殊字符串，因为所有将是向后兼容的有效附加功能名称的字符串可能已经在现有软件包中使用。

有人建议使用特殊的 Python 变量 None，但这再次是不可能的，因为尽管可以在 setup.py 文件中使用 None，但在声明性文件（例如 setup.cfg 或 pyproject.toml）中则不行，而且最终附加功能名称必须转换为软件包元数据中的字符串。拥有：

Provides-Extra: None

将与字符串“None”无法区分，而“None”可能已经作为 Python 软件包中的附加功能名称使用。如果我们修改核心元数据语法以允许非字符串的“特殊”附加功能名称，那么我们又回到了修改核心元数据规范，这并不比引入 Default-Extra 更好。

依赖工具来取消选择任何默认附加功能

取消选择附加功能的另一种选择是在打包工具层面实现。例如，pip 可以包含一个选项，例如：

$ pip install package --no-default-extras

此选项可以应用于所有或特定软件包，类似于 --no-binary 选项，例如：

$ pip install package --no-default-extras :all:

这种方法的优点是支持默认附加功能的工具也可以支持取消选择它们。这种方法将类似于 apt 工具的 --no-install-recommends 选项。

然而，这种解决方案本身并不理想，因为它不允许软件包自身指定它们不需要依赖项的一些默认附加功能。它还会给用户带来风险，如果用户在大型依赖树中禁用所有默认附加功能，可能会破坏依赖于默认附加功能的树中的软件包。

尽管如此，本 PEP 并不禁止这种方法，并且由不同打包工具的维护者决定是否要支持此类选项。它是一个至少对软件包维护者有用的标志，他们希望识别依赖树中依赖默认附加功能的位置。然而，如果它受支持，则应明确指出使用此标志不能保证功能正常的环境。