PEP 735 – pyproject.toml 中的依赖项组

抽象

此 PEP 指定了一种将包需求存储在文件中的机制，以便它们不包含在任何构建的 项目。pyproject.toml

这适用于创建命名的依赖项组，类似于文件，启动器、IDE 和其他工具可以找到这些依赖项和 按名称标识。requirements.txt

此处定义的功能称为“依赖项组”。

赋予动机

Python 社区没有两个主要用例 标准化答案：

• 应该如何定义包的开发依赖关系？

• 应该如何为不构建的项目定义依赖关系 发行版（非包项目）？

为了支持这两种需求，有两种相似的常见解决方案 对于此提案：

• requirements.txt文件

• 套餐附加功能

这两个文件都有限制，这 标准寻求克服。requirements.txtextras

请注意，上述两个用例描述了两种不同类型的项目 本 PEP 寻求支持：

• Python 包，例如库

• 非包项目，例如数据科学项目

文件的局限性

许多项目可以定义一个或多个 iles， 并且可以将它们安排在项目根目录（例如 和 ） 或在目录中（例如 和 ）。但是，有 以这种方式使用需求文件的主要问题：requirements.txtrequirements.txttest-requirements.txtrequirements/base.txtrequirements/test.txt

没有标准化的命名约定，因此工具可以发现或 按名称使用这些文件。

requirements.txt文件不是标准化的，而是提供 选项设置为 。pip

因此，很难根据文件定义工具行为。发现或识别它们并非易事 名称，其内容可能包含包说明符和其他选项的组合。requirements.txtpip

缺乏内容标准也意味着它们是 不能移植到任何希望处理它们的替代工具。requirements.txtpip

此外，文件需要每个依赖项列表的文件。 对于某些用例，这使得依赖分组的边际成本很高， 相对于他们的利益。 更简短的声明有利于具有许多小组的项目 依赖。requirements.txt

与此相反，依赖项组是在众所周知的位置定义的 在具有完全标准化的内容中。他们不仅会有 立竿见影的效用，但它们也将作为未来的起点 标准。pyproject.toml

的局限性

extras是在表中声明的其他包元数据。它们为以下列表提供名称 作为包元数据的一部分发布的包说明符，以及 用户可以在该名称下请求，如 使用额外的安装。[project.optional-dependencies]pip install 'foo[bar]'foobar

因为是包元数据，所以当项目时它们不可用 不构建发行版（即，不是一个包）。extras

对于包的项目，是定义的通用解决方案 发展依赖性，但即使在这些情况下，它们也有 缺点：extras

• 因为 an 定义了可选的附加依赖项，所以它不是 可以在不安装当前软件包的情况下安装 AN 并且 其依赖项。extraextra

• 因为它们是用户可安装的，所以是公共接口的一部分 对于包。因为是 published，所以包开发人员经常是 关注确保他们的开发附加功能不会与 面向用户的附加功能。extrasextras

理由

此 PEP 定义了表中列表中的需求数据的存储。 选择此名称是为了匹配要素的规范名称 （“依赖组”）。[dependency-groups]

这种格式应该尽可能简单易学，具有格式 在许多情况下，与现有文件非常相似。每个列表 in 定义为包说明符的列表。为 例：requirements.txt[dependency-groups]

[dependency-groups]
test = ["pytest>7", "coverage"]

有许多文件的用例需要 不能用 PEP 508 依赖项说明符表示的数据。这样 字段在依赖项组中无效。包括许多数据和 支持的字段，例如索引服务器、哈希和路径 依赖关系，需要新的标准。该标准为新的标准留出了空间 标准和发展，但不试图支持所有有效内容。requirements.txtpiprequirements.txt

唯一的例外是文件的标志 用于将一个文件包含在另一个文件中。依赖项组支持“include” 含义相似的机制，允许一个依赖组扩展 另一个。-rrequirements.txt

依赖项组具有两个类似于文件的附加功能：requirements.txt

• 它们不会作为任何构建发行版的一部分发布

• 安装依赖项组并不意味着安装软件包的 依赖项或包本身

使用案例

以下用例被视为此 PEP 的重要目标。他们是 在用例附录中更详细地定义。

• 通过非 Python 打包构建过程部署的 Web 应用程序

• 具有未发布的开发依赖项组的库

• 具有依赖项组但没有核心包的数据科学项目

• 输入数据以生成锁文件（依赖项组通常不应 用作锁定依赖项数据的位置）

• 将数据输入到环境管理器，例如 tox、Nox 或 Hatch

• 可配置的 IDE 发现测试和 linter 要求

关于 Poetry 和 PDM 依赖组

现有的 Poetry 和 PDM 工具已经提供了一个功能，每个工具都调用了 “依赖组”。但是，没有任何指定集合的标准 的依赖关系，每个工具都以特定于工具的方式定义这些依赖项，在 表格的相关部分。[tool]

（PDM 还对某些依赖项组使用了附加功能，并且与该概念重叠 大量附加功能。

此 PEP 不支持 Poetry 和 PDM 的所有功能，它们与 的文件一样，支持多个非标准扩展 到常见的依赖项说明符。requirements.txtpip

此类工具应该可以使用标准化的依赖项组，例如 扩展自己的依赖组机制。 但是，定义一种新的数据格式来取代现有的 Poetry 和 PDM 解决方案不是目标。这样做需要标准化几个 这些支持的其他功能，例如路径依赖项 工具。

依赖项组不是隐藏的额外内容

依赖项组与未发布的额外内容非常相似。 但是，有两个主要特征将它们与附加功能区分开来 进一步：

• 它们支持非包项目

• 安装依赖项组并不意味着安装软件包的 依赖项（或包本身）

未来的兼容性和无效数据

依赖项组旨在在未来的 PEP 中可扩展。 但是，依赖项组也应可由多个工具使用 单个 Python 项目。 使用相同数据的多个工具，一个工具可能会实现 一个扩展依赖组的未来 PEP，而另一个则不扩展。

为了在这种情况下支持用户，此 PEP 定义并建议验证 工具仅检查它们正在使用的依赖项组的行为。 这允许使用多个工具，使用不同版本的依赖组数据， 在 中共享单个表。pyproject.toml

规范

此 PEP 在名为 的文件中定义一个新部分（表）。该表包含任意 用户定义键的数量，每个键的值都有一个列表 要求（定义见下文）。这些键必须是有效的非规范化名称， 并且必须在比较之前进行归一化。pyproject.tomldependency-groupsdependency-groups

工具应倾向于通过以下方式向用户显示原始的、非规范化的名称 违约。如果在规范化后遇到重复的名称，工具应 发出错误。

下面的要求列表可能包含字符串、表格 （Python 中的“dicts”），或字符串和表的混合。dependency-groups

要求列表中的字符串必须是有效的依赖项说明符， 如 PEP 508 中所定义。

需求列表中的表必须是有效的依赖对象说明符， 定义如下。

依赖项对象说明符

依赖项对象说明符是定义零个或多个依赖项的表。

此 PEP 仅标准化一种类型的依赖项对象说明符，即 “依赖组包括”。将来的标准中可能会添加其他类型。

依赖项组包括

Dependency Group Include 包括另一个 Dependency 的依赖项 当前依赖项组中的组。

include 被定义为一个表，只有一个键，其 value 是一个字符串，是另一个依赖项组的名称。"include"

例如，是一个 include 扩展为 依赖项组的内容。{include = "test"}test

包含被定义为与命名的内容完全等效 依赖项组，插入到当前组的包含位置。 例如，如果是一个组，并且是另一个组，则应该 评估到“依赖项组包括”展开的时间。foo = ["a", "b"]bar = ["c", {include = "foo"}, "d"]bar["c", "a", "b", "d"]

依赖项组包含可以多次指定同一包。工具 不应删除重复数据或以其他方式更改 包括。例如，给定下表：

[dependency-groups]
group-a = ["foo"]
group-b = ["foo>1.0"]
group-c = ["foo<1.0"]
all = ["foo", {include = "group-a"}, {include = "group-b"}, {include = "group-c"}]

SHOULD 的解析值为 。 工具应该完全像处理任何其他情况一样处理这样的列表。 他们被要求多次处理相同的要求 不同的版本约束。all["foo", "foo", "foo>1.0", "foo<1.0"]

依赖项组包括可能包括包含依赖项组的列表 包括，在这种情况下，这些包含也应扩展。屬地 组包含不得包含周期，如果出现以下情况，工具应报告错误 他们检测到一个循环。

Example Dependency Groups 表

下面是一个部分的示例，它使用它来 定义四个依赖项组：、、 和 ：pyproject.tomltestdocstypingtyping-test

[dependency-groups]
test = ["pytest", "coverage"]
docs = ["sphinx", "sphinx-rtd-theme"]
typing = ["mypy", "types-requests"]
typing-test = [{include = "typing"}, {include = "test"}, "useful-types"]

请注意，这些依赖项组声明都没有隐式安装 当前包、其依赖项或任何可选依赖项。 使用依赖组（如测试包）需要 用户的配置或工具链也会安装 。例如test.

$TOOL install-dependency-group testpip 
install -e .

可以使用（假设是一个支持安装的工具 依赖组）来构建测试环境。$TOOL

这也允许在不使用 将项目安装为包：docs

$TOOL install-dependency-group docs

包构建

构建后端不得在构建的发行版中包含依赖组数据，因为 包元数据。这意味着 sdists 中的 PKG-INFO 和 wheels 中的 METADATA 不包含任何包含依赖项组的可引用字段。

在动态元数据的评估中使用依赖组是有效的，sdist 中包含的文件自然仍会包含该表。但是，表内容不是 已发布包的接口。pyproject.toml[dependency-groups]

安装依赖项组

支持依赖项组的工具有望提供新的选项和 允许用户从依赖项组安装的接口。

没有定义用于表示包的依赖组的语法，对于两个 原因：

• 引用第三方的依赖组是无效的 来自 PyPI 的包（因为数据被定义为未发布）

• 不保证有依赖组的当前包 - 部分 其目的是支持非包项目

例如，用于安装依赖项组的可能的 pip 接口 将：

pip install --dependency-groups=test,typing

请注意，这只是一个示例。此 PEP 未声明任何要求 了解工具如何支持依赖项组的安装。

验证和兼容性

支持依赖项组的工具可能需要在使用数据之前对其进行验证。 但是，实现此类验证行为的工具应小心允许 用于将来对此规范的扩展，以便它们不会不必要地发出 存在新语法时出现错误或警告。

工具在评估或处理无法识别的数据时应出错 依赖项组。

工具不应急切地验证所有依赖项的列表内容 组。

这意味着在存在以下数据的情况下，大多数工具将允许 要使用的组，并且仅在该组 使用：foobar

[dependency-groups]
foo = ["pyparsing"]
bar = [{set-phasers-to = "stun"}]

参考实现

以下参考实现打印依赖项的内容 组为 stdout，换行符分隔。 因此，输出是有效数据。requirements.txt

import re
import sys
import tomllib
from collections import defaultdict

from packaging.requirements import Requirement

def _normalize_name(name: str) -> str:
    return re.sub(r"[-_.]+", "-", name).lower()
    
def _normalize_group_names(dependency_groups: dict) -> dict:
    original_names = defaultdict(list)
    normalized_groups = {}

    for group_name, value in dependency_groups.items():
        normed_group_name = _normalize_name(group_name)
        original_names[normed_group_name].append(group_name)
        normalized_groups[normed_group_name] = value

    errors = []
    for normed_name, names in original_names.items():
        if len(names) > 1:
            errors.append(f"{normed_name} ({', '.join(names)})")
    if errors:
        raise ValueError(f"Duplicate dependency group names: {', '.join(errors)}")

    return normalized_groups
    
def _resolve_dependency_group(
    dependency_groups: dict, group: str, past_groups: tuple[str] = ()
) -> list[str]:
    if group in past_groups:
        raise ValueError(f"Cyclic dependency group include: {group} -> {past_groups}")

    if group not in dependency_groups:
        raise LookupError(f"Dependency group '{group}' not found")

    raw_group = dependency_groups[group]
    if not isinstance(raw_group, list):
        raise ValueError(f"Dependency group '{group}' is not a list")

    realized_group = []
    for item in raw_group:
        if isinstance(item, str):
            # packaging.requirements.Requirement parsing ensures that this is a valid
            # PEP 508 Dependency Specifier
            # raises InvalidRequirement on failure
            Requirement(item)
            realized_group.append(item)
        elif isinstance(item, dict):
            if tuple(item.keys()) != ("include",):
                raise ValueError(f"Invalid dependency group item: {item}")

            include_group = _normalize_name(next(iter(item.values())))
            realized_group.extend(
                _resolve_dependency_group(
                    dependency_groups, include_group, past_groups + (group,)
                )
            )
        else:
            raise ValueError(f"Invalid dependency group item: {item}")

    return realized_group
    
def resolve(dependency_groups: dict, group: str) -> list[str]:
    if not isinstance(dependency_groups, dict):
        raise TypeError("Dependency Groups table is not a dict")
    if not isinstance(group, str):
        raise TypeError("Dependency group name is not a str")
    return _resolve_dependency_group(dependency_groups, group)
    
if __name__ == "__main__":
    with open("pyproject.toml", "rb") as fp:
        pyproject = tomllib.load(fp)

    dependency_groups_raw = pyproject["dependency-groups"]
    dependency_groups = _normalize_group_names(dependency_groups_raw)
    print("\n".join(resolve(pyproject["dependency-groups"], sys.argv[1])))

向后兼容性

在撰写本文时，文件中的命名空间未使用。由于顶级命名空间是 仅供 packaging.python.org 规定的标准使用， 不应有直接的向后兼容性问题。dependency-groupspyproject.toml

安全隐患

此 PEP 引入了用于指定依赖关系的新语法和数据格式 项目中的信息。但是，它没有引入新指定的 用于处理或解决依赖关系的机制。

因此，除了任何 可能已用于安装依赖项的工具 - 即恶意的 可以在此处指定依赖项，就像在文件中指定依赖项一样。requirements.txt

如何教这个

此功能应使用其规范名称“依赖项组”来引用。

基本用法形式应作为典型数据的变体进行教学。标准依赖项说明符 （PEP 508） 可以是 已添加到命名列表。而不是要求 pip 从文件安装，而是安装 pip 或相关的工作流工具 从命名的依赖项组。requirements.txtrequirements.txt

对于新的 Python 用户，可以直接教他们创建一个包含其依赖组的部分，类似于他们如何 目前被教导使用文件。 这也允许新的 Python 用户了解文件 无需了解包构建。 只有表而没有其他表的文件 是有效的。pyproject.tomlrequirements.txtpyproject.tomlpyproject.toml[dependency-groups]

对于新用户和有经验的用户，依赖项组包含将需要 被解释。对于有使用经验的用户，这可以是 描述为 的类似物。对于新用户，应该告诉他们 include 允许一个依赖项组扩展另一个依赖项组。类似配置 接口和 Python 方法可用于解释 通过类比的想法。requirements.txt-rlist.extend

被拒绝的想法

为什么不将每个依赖组定义为一个表？

如果我们的目标是允许将来的扩展，那么定义每个依赖项 group作为一个子表，从而使我们能够将未来的键附加到每个组， 允许最大的未来灵活性。

然而，它也使结构嵌套得更深，因此更难 教和学。这个 PEP 的目标之一是成为一个简单的替代品 适用于许多用例。requirements.txt

为什么不定义一个特殊的字符串语法来扩展依赖项说明符呢？

该规范的早期草案定义了依赖关系的语法形式 组包含和路径依赖关系。

但是，这种方法存在三个主要问题：

• 它使必须教授的字符串语法复杂化，超出了 PEP 508

• 生成的字符串始终需要从 PEP 508 中消除歧义 说明符，使实现复杂化

为什么不允许更多非 PEP 508 依赖项说明符？

在讨论中出现了几个需要更具表现力的用例 比 PEP 508 可能实现的说明符。

“路径依赖关系”，指的是本地路径，并引用了[project.dependencies]

但是，这些功能没有现成的标准（除了 的实现细节的事实标准）。pip

因此，尝试在此 PEP 中包含这些功能会导致 范围显着扩大，以尝试标准化这些不同的功能 和行为。pip

特别注意尝试使 可编辑的装置，如 PEP 660 所表达的那样。 但是，尽管可编辑安装的创建是标准化的 后端，可编辑行为对于安装程序来说不是标准化的。 在此 PEP 中包含可编辑内容要求任何支持工具都允许 安装可编辑文件。pip install -e

因此，尽管 Poetry 和 PDM 为其中一些功能提供了语法， 目前，它们被认为不够标准化，无法纳入 依赖项组。

为什么表没有命名为 ， ， ...？

这个概念有很多可能的名称。 它必须与现有的 和 表一起存在，并且可能还有一个新的依赖项表（在撰写本文时，PEP 725，它 定义表，正在进行中）。[project.dependencies][project.optional-dependencies][external][external]

[run]是早期讨论中的主要提案，但其建议的用法 以一组运行时依赖项为中心。这个 PEP 明确 概述了多组依赖项，这使得 适当的拟合 – 这不仅仅是特定运行时的依赖项数据 context，但适用于多个上下文。[run]

[project.dependency-groups]会提供一个很好的平行于 和 ，但有 非一揽子项目的主要缺点。 需要定义多个键，例如 和 。使用此名称需要重新定义表以允许不存在这些键，否则将施加要求 在非包项目上定义和使用这些键。推而广之，它将 有效地要求任何非打包项目都允许将自己视为一个 包。[project.dependencies][project.optional-dependencies][project]nameversion[project]

为什么pip的计划实施不够充分？

PIP 目前在路线图上有一个功能，可以添加一个 –only-deps 标志。 此标志旨在允许用户安装包依赖项和附加功能 无需安装当前软件包。

它不满足非一揽子项目的需求，也不允许 安装一个没有包依赖项的额外内容。

为什么<环境管理器>不是一个解决方案？

tox、Nox 和 Hatch 等现有环境管理器已经具备 能够将内联依赖项列为其配置数据的一部分。 这满足了许多开发依赖需求，并且清楚地关联了依赖 具有可以运行的相关任务的组。 这些机制是好的，但还不够。

首先，它们没有满足非一揽子项目的需求。

其次，没有其他工具用于访问这些数据的标准。这 对 IDE 和 Dependabot 等高级工具有影响，这些工具无法支持 与这些依赖项组深度集成。（例如，在撰写本文时 Dependabot 不会标记固定在文件中的依赖项。tox.ini

未解决的问题

依赖项组是否可以包含，反之亦然？

一个争论的话题是依赖组应该如何（或是否）与 交互。[project.dependencies][project.optional-dependencies]

可以添加一个额外的依赖对象说明符，用于将 或 数据包含在 依赖项组。但是，此规范的目标是 依赖项组应始终可解析为包列表 无需使用构建后端。因此，包含或需要 要仔细定义动态依赖关系。[project.dependencies][project.optional-dependencies][project.dependencies][project.optional-dependencies]

以相反方向运行的包含 – 包含依赖项组引用的列表，可能重用依赖项 组包含对象作为机制 - 也是可能的，但存在 不同的挑战。这样的添加会在表中引入新的语法，起初并非所有工具都支持这种语法。[project.dependencies][project]

附录A：非Python语言的现有技术

本节主要提供信息，用于记录其他 语言生态系统也解决了类似的问题。

JavaScript 和

在 JavaScript 社区中，包包含规范配置和 data 文件，范围类似于 。pyproject.tomlpackage.json

控制依赖关系数据中的两个键：和 。的作用实际上是相同的 如 中 ，声明 包的直接依赖项。package.json"dependencies""devDependencies""dependencies"[project.dependencies]pyproject.toml

数据

依赖项数据声明为包名称的映射 到版本说明符。package.json

版本说明符支持可能的版本、范围和 其他值，类似于 Python 的 PEP 440 版本说明符。

例如，下面是一个部分文件，声明了一些 依赖：package.json

{    "dependencies": {    
       "@angular/compiler": "^17.0.2",        
       "camelcase": "8.0.0",        
       "diff": ">=5.1.0 <6.0.0"    
    }
}

符号的使用是声明包的范围 owner，用于组织拥有的包。 因此声明一个名为 grouped 的包 在所有权下。@"@angular/compiler"compilerangular

引用 URL 和本地路径的依赖关系

依赖项说明符支持 URL 和 Git 存储库的语法，类似于 到 Python 打包中的规定。

可以使用 URL 代替版本号。 使用时，它们隐式引用包源代码的压缩包。

Git 存储库也可以类似地使用，包括对 committish 的支持 说明符。

与 PEP 440 不同，NPM 允许使用本地路径来打包源代码 依赖项的目录。当这些数据添加到 via 标准命令，路径规范化为 相对路径，从包含 的目录中取出，并带有前缀 跟。例如，以下部分包含一个 对当前目录的同级目录的引用：package.jsonnpm install --savepackage.jsonfile:package.json

{  
  "dependencies": {     
     "my-package": "file:../foo" 
  }
}

官方 NPM 文档指出，本地路径依赖项“不应”发布到公共包中 存储库，但没有说明固有的有效性或无效性 已发布包中的此类依赖项数据。

数据

package.json允许包含名为 的第二节，其格式与 相同。 默认情况下，不会安装中声明的依赖项 当从软件包存储库安装软件包时（例如，作为 依赖项正在解析），但在 包含 ."devDependencies""dependencies""devDependencies"npm installpackage.json

正如支持 URL 和本地路径一样，."dependencies""devDependencies"

和

另外还有两个相关的部分，其中有 关联。package.json

"peerDependencies"以与 相同的格式声明依赖项列表，但表示这些依赖项是兼容性 声明。 例如，以下数据声明与包版本 2 兼容："dependencies"foo

{  
  "peerDependencies": {   
       "foo": "2.x"  
  }
}

"optionalDependencies"声明一个依赖项列表，这些依赖项应为 如果可能，则安装，但如果是 不能利用的。它还使用与 相同的映射格式。"dependencies"

“peerDependenciesMeta”

"peerDependenciesMeta"是允许额外控制的部分 关于如何对待。"peerDependencies"

可以通过将包设置为本部分来禁用有关缺少依赖项的警告，如以下示例所示：optional

{  
  "peerDependencies": {    
      "foo": "2.x"   
  },    
  "peerDependenciesMeta": {  
        "foo": {      
              "optional": true       
        }    
   }
}

和

该命令支持两个选项，以及 它可以控制是否安装“prod”、“dev”、“optional”或“peer”依赖项。npm install--omit--include

“prod”名称是指 下列出的依赖项。"dependencies"

默认情况下，执行时将安装所有四个组 针对源代码树，但这些选项可用于控制安装 更准确地说是行为。 此外，这些值可以在文件中声明，允许 用于控制安装行为的每用户和每个项目配置。npm install.npmrc

红宝石和红宝石

Ruby 项目可能旨在也可能不打算在 Ruby 生态系统。事实上，人们的期望是该语言的大多数用户都这样做 不想生产宝石，也没有兴趣生产自己的包装。 许多教程没有涉及如何生成包，工具链也从未触及 需要为支持的用例打包用户代码。

Ruby 将需求规范拆分为两个单独的文件。

• Gemfile：仅支持以下形式的需求数据的专用文件 依赖项组

• <package>.gemspec：用于声明包 （gem） 元数据的专用文件

提供命令的工具是主界面 用于使用数据。bundlerbundleGemfile

该工具负责通过命令从数据构建 Gem。gem.gemspecgem build

Gem文件 & 捆绑包

Gemfile 是 Ruby 文件 包含包含在任意数量的声明中的指令。 指令也可以在声明之外使用，其中 case 它们形成一个隐式未命名的依赖项组。gemgroupgemgroup

例如，以下列表作为项目依赖项。 所有其他依赖项都列在组下：Gemfilerails

source '

gem 'rails'

group :test do
  gem 'rspec'
end

group :lint do
  gem 'rubocop'
end

group :docs do
  gem 'kramdown'  
  gem 'nokogiri'
end

如果用户使用这些数据执行，则所有组都 安装。用户可以通过创建或修改捆绑器配置来取消选择组 中 ，手动或通过 CLI 进行。例如。bundle install.bundle/configbundle config set --local without 'lint:docs'

根据上述数据，无法排除 gem 的顶级用途或按名称引用该隐含分组。'rails'

Gemspec 和打包的依赖项数据

gemspec 文件是 包含 Gem：：Specification 实例声明的 ruby 文件。

一个中只有两个字段与包依赖项数据有关。 这些是 和 . 对象还提供用于添加依赖项的方法 动态地，包括（这会添加运行时依赖项）。Gem::Specificationadd_development_dependencyadd_runtime_dependencyGem::Specificationadd_dependency

这是该文件的变体，删除了许多字段或 缩短以简化：rails.gemspec

version = '7.1.2'

Gem::Specification.new do |s|
  s.platform    = Gem::Platform::RUBY  
  s.name        = "rails"  
  s.version     = version  
  s.summary     = "Full-stack web application framework."  
  
  s.license = "MIT"  
  s.author   = "David Heinemeier Hansson"
    
  s.files = ["README.md", "MIT-LICENSE"]
  
  # shortened from the real 'rails' project  
  s.add_dependency "activesupport", version  
  s.add_dependency "activerecord",  version  
  s.add_dependency "actionmailer",  version  
  s.add_dependency "activestorage", version  
  s.add_dependency "railties",      version
end

请注意，没有使用 . 其他一些主流的主要软件包（例如）不使用开发 其 gem 中的依赖关系。add_development_dependencyrubocop

其他项目也使用此功能。例如，利用 开发依赖项，在其中包含以下规范：kramdownRakefile

s.add_dependency "rexml"
s.add_development_dependency 'minitest', '~> 5.0'
s.add_development_dependency 'rouge', '~> 3.0', '>= 3.26.0'
s.add_development_dependency 'stringex', '~> 1.5.1'

开发依赖项的目的只是声明一个隐式组， 作为 的一部分，然后可以由 使用 。.gemspecbundler

有关完整的详细信息，请参阅 有关 Gemfiles 的文档中的指令。 但是，通过示例可以最好地理解开发依赖项和/使用之间的集成。gemspecbundler.gemspecGemfilebundle

Gemspec 开发依赖项示例

考虑以下以 和 的形式进行的简单项目。 文件：Gemfile.gemspeccool-gem.gemspec

Gem::Specification.new do |s|
  s.author = 'Stephen Rosen'  
  s.name = 'cool-gem'  
  s.version = '0.0.1'  
  s.summary = 'A very cool gem that does cool stuff'  
  s.license = 'MIT'  
  
  s.files = []  
  
  s.add_dependency 'rails'  
  s.add_development_dependency 'kramdown'
end

以及：Gemfile

source '
 
gemspec

指令 in 声明对本地的依赖 package， ，在本地可用文件中定义。它还隐式地将所有开发依赖项添加到依赖项中 名为 的组。gemspecGemfilecool-gemcool-gem.gemspecdevelopment

因此，在这种情况下，指令等价于 内容如下：gemspecGemfile

gem 'cool-gem', :path => '.'

group :development do
  gem 'kramdown'
end

附录 B：Python 中的现有技术

在没有任何依赖组的先前标准的情况下，两个已知的工作流 PDM 和 Poetry 等工具定义了自己的解决方案。

本节将主要关注这两种工具作为现有技术的案例 关于 Python 中依赖组的定义和使用。

项目是包

PDM 和 Poetry 都将它们支持的项目视为包。 这允许他们使用标准元数据并与之交互 满足他们的一些需求，并允许他们支持安装 “当前项目”，使用其构建后端进行构建和安装。pyproject.toml

实际上，这意味着 Poetry 和 PDM 都不支持非打包项目。

非标准依赖项说明符

PDM 和 Poetry 通过附加功能扩展了 PEP 508 依赖项说明符 不属于任何共享标准。 但是，这两种工具使用的方法略有不同。

PDM 支持通过以下语法指定本地路径和可编辑安装 看起来像一组参数。例如，以下内容 依赖项组包含一个处于可编辑模式的本地包：pip install

[tool.pdm.dev-dependencies]
mygroup = ["-e file:///${PROJECT_ROOT}/foo"]

这声明了一个依赖项组，其中包含一个本地可编辑项 从目录安装。mygroupfoo

Poetry 将依赖项组描述为表，将包名称映射到 说明符。例如，与上述示例相同的配置可能会在 Poetry 下显示如下：mygroup

[tool.poetry.group.mygroup]
foo = { path = "foo", editable = true }

PDM 将自己限制为字符串语法，而 Poetry 引入了 描述依赖关系。

安装和引用依赖项组

PDM 和 Poetry 都具有特定于工具的安装依赖项支持 组。由于这两个项目都支持自己的锁定文件格式，因此它们还 两者都能够透明地使用依赖项组名称来引用 添加到该组的锁定依赖项数据。

但是，这两个工具的依赖项组都不能从其他工具本机引用 、 或 . 例如，尝试在 下安装依赖项组需要 对 PDM 或 Poetry 的显式调用，以解析它们的依赖项数据并执行 相关安装步骤。toxnoxpiptox

附录 C：使用案例

Web 应用程序

Web 应用程序（例如 Django 或 Flask 应用程序）通常不需要构建一个 分发版，但将其源代码捆绑并交付到部署工具链。

例如，源代码存储库可以将 Python 打包元数据定义为 以及容器化或其他生成管道元数据 （， 等）。 Python 应用程序是通过将整个存储库复制到 构建上下文，安装依赖项，并将结果捆绑为计算机 图像或容器。Dockerfile

此类应用程序具有用于构建的依赖项组，但也具有用于 linting 的依赖项组， 测试等在实践中，今天，这些应用程序通常将自己定义为 包，以便能够使用打包工具和机制，例如 管理其依赖项组。但是，它们在概念上不是包， 用于以 SDIST 或轮式格式分发。extras

依赖项组允许这些应用程序定义其各种依赖项 不依赖打包元数据，也不试图表达他们的 包装方面的需求。

图书馆

库是构建发行版（sdist 和 wheel）的 Python 包，并且 将它们发布到 PyPI。

对于库，依赖项组表示 定义开发依赖关系组，具有重要优势 如上所述。extras

库可以定义允许测试和 类型检查，因此依赖于库自身的依赖项（如 在 中指定）。testtyping[project.dependencies]

其他开发需求可能根本不需要安装软件包。为 例如，依赖项组可能有效且安装速度更快，而无需 该库，因为它只安装 、 或 等工具。lintblackruffflake8

lint环境也可能是值得关注的宝贵位置 IDE 或编辑器支持。有关此类的更完整描述，请参阅下面的案例 用法。test

下面是一个示例 Dependency Groups 表，它可能适用于 图书馆：

[dependency-groups]
test = ["pytest<8", "coverage"]
typing = ["mypy==1.7.1", "types-requests"]
lint = ["black", "flake8"]
typing-test = [{include = "typing"}, "pytest<8"]

请注意，这些都没有隐式安装库本身。 因此，任何环境管理工具链都有责任 需要时安装适当的依赖项组和库， 就像 的情况一样。test

数据科学项目

数据科学项目通常采用逻辑集合的形式 用于处理和分析数据的脚本和实用程序，使用通用的 工具链。组件可以以 Jupyter Notebook 格式 （ipynb） 定义， 但依赖于相同的通用核心实用程序集。

在这样的项目中，没有要构建或安装的包。因此，目前不提供任何依赖解决方案 管理或声明。pyproject.toml

对于这样的项目来说，能够定义至少一个专业是很有价值的 依赖项的分组。例如：

[dependency-groups]
main = ["numpy", "pandas", "matplotlib"]

但是，各种脚本可能还需要具有其他 支持工具。项目甚至可能具有冲突或不兼容的工具，或者 不同组件的工具版本，因为它们会随着时间的推移而变化。

请考虑以下更精细的配置：

[dependency-groups]
main = ["numpy", "pandas", "matplotlib"]
scikit = [{include = "main"}, "scikit-learn==1.3.2"]
scikit-old = [{include = "main"}, "scikit-learn==0.24.2"]

这将 和 定义为 的两个相似变体 通用的依赖项套件，拉入不同版本以适应不同的脚本。scikitscikit-oldscikit-learn

此 PEP 仅定义这些数据。它没有正式确定任何机制。 数据科学项目（或任何其他类型的项目）来安装依赖项 进入已知环境或将这些环境与各种 脚本。这种数据组合留给工具作者来说是一个问题 解决，也许最终标准化。

锁文件生成

在 Python 生态系统中有许多工具可以生成锁文件 今天。PDM 和 Poetry 各自使用自己的锁文件格式和 pip-tools 生成具有版本引脚和哈希的文件。requirements.txt

依赖项组不是存储锁定文件的合适位置，因为它们缺乏 许多必要的功能。最值得注意的是，它们无法存储哈希值，这 大多数Lockfile用户认为是必不可少的。

但是，依赖项组是生成锁定文件的工具的有效输入。 此外，PDM 和 Poetry 都允许使用依赖组名称（在其 依赖组的概念）用于指代其锁定的变体。

因此，请考虑一个生成锁定文件的工具，此处称为 。 它可能按如下方式使用：$TOOL

$TOOL lock --dependency-group=test
$TOOL install --dependency-group=test --use-locked

这样的工具需要做的就是确保其锁文件数据记录 名称，以支持此类用法。test

不保证依赖组的相互兼容性。例如 上面的数据科学示例显示了 的冲突版本。 因此，串联安装多个锁定的依赖项组可能需要 该工具应用其他约束或生成其他锁定文件数据。 这些问题被认为超出了本 PEP 的范围。scikit-learn

举两个示例来说明如何锁定组合：

• 工具可能要求为任何 组合被视为有效

• Poetry 实现了所有依赖组相互的要求 兼容，并且仅生成一个锁定版本。（这意味着它找到一个 解决方案，而不是解决方案的集合或矩阵。

Environment Manager 输入

tox、Nox 和 Hatch 中的常见用法是将一组依赖项安装到 测试环境。

例如，在 下，可以定义类型检查依赖关系 内嵌：tox.ini

[testenv:typing]
deps =  
  pyright    
  useful-types
commands = pyright src/

这种组合在有限的范围内提供了理想的开发人员体验 上下文。在相关环境管理器下，依赖项是 测试环境所需的命令与需要的命令一起声明 这些依赖项。它们不会像那样在包元数据中发布，并且对于需要它们来构建 相关环境。extras

依赖项组通过有效地“提升”这些用法来应用此类用法 需求数据从工具特定位置转换为更广泛可用的位置 一。在上面的示例中，只能访问声明的 依赖。在支持依赖项组的实现下，相同 数据可能在依赖项组中可用：tox

[dependency-groups]
typing = ["pyright", "useful-types"]

然后，可以在多种工具下使用数据。例如，might 实现支持作为，替换上面的用法。toxdependency_groups = typingdeps

为了使依赖组成为 环境管理器，环境管理器将需要支持处理 依赖项组与它们支持内联依赖项声明的方式类似。

IDE 和编辑器对需求数据的使用

IDE 和编辑器集成可能受益于常规或可配置名称 用于集成的依赖项组的定义。

至少有两种已知的场景对编辑器或 IDE 能够发现项目未发布的依赖项：

• 测试：VS Code 等 IDE 支持 GUI 界面，用于运行特定的 测试

• linting：编辑器和 IDE 通常支持 linting 和自动格式化 突出显示或自动更正错误的集成

这些情况可以通过定义传统的组名（如 、 和 ）或定义配置机制来处理 允许选择依赖项组。testlintfix

例如，以下声明上述三个 组：pyproject.toml

[dependency-groups]
test = ["pytest", "pytest-timeout"]
lint = ["flake8", "mypy"]
fix = ["black", "isort", "pyupgrade"]

本 PEP 不试图标准化此类名称或保留它们 使用。IDE 可以标准化或允许用户配置所使用的组名 用于各种目的。

此声明允许项目作者了解适当的工具 以便与该项目的所有编辑者共享项目。

版权

本文档位于公共领域或 CC0-1.0-通用许可证，以更宽松者为准。

The End