管理依赖

管理依赖 #

依赖组 #

Poetry 提供了一种通过组来组织依赖的方式。例如，您可能有一些仅在测试项目或构建文档时才需要的依赖。

要声明一个新的依赖组，请使用 tool.poetry.group.<group> 部分，其中 <group> 是您的依赖组的名称（例如，test）。

[tool.poetry.group.test]  # This part can be left out

[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

注意

所有依赖项必须彼此兼容，因为它们将在安装时被解析，无论它们是否需要安装（参见安装组依赖）。

可以将依赖组视为与依赖项关联的标签：它们不会影响依赖项是否默认被解析和安装，它们只是以逻辑方式组织依赖项的一种方式。

注意

在 tool.poetry.dependencies 中声明的依赖项属于隐式 main 组。

[tool.poetry.dependencies]  # main dependency group
httpx = "*"
pendulum = "*"
[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

注意

除了隐式 main 组之外，依赖组只能包含您在开发过程中需要的依赖项。只能使用 Poetry 安装它们。

要声明一组依赖项，这些依赖项在运行时为项目添加额外的功能，请使用extras。最终用户可以使用 pip 安装 Extras。

注意

关于定义 dev 依赖组的说明

从 Poetry 1.2.0 开始，定义 dev 依赖组的正确方法如下

[tool.poetry.group.dev.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

从 Poetry 1.2.0 开始，这种组表示法是首选，在早期版本中不可用。为了与旧版本的 Poetry 向后兼容，在 dev-dependencies 部分中声明的任何依赖项都将自动添加到 dev 组中。因此，上述表示法和以下表示法是等效的

# Poetry pre-1.2.x style, understood by Poetry 1.0–1.2
[tool.poetry.dev-dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

Poetry 将逐渐放弃 dev-dependencies 表示法，该表示法很快将被弃用，因此建议将您现有的开发依赖项迁移到新的 group 表示法。

可选组 #

可以将依赖组声明为可选。当您有一组仅在特定环境中或出于特定目的才需要的依赖项时，这样做是有意义的。

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

可以使用 install 命令的 --with 选项，除了默认依赖项之外，还可以安装可选组。

poetry install --with docs

警告

可选组依赖项仍然会与其他依赖项一起解析，因此应特别注意确保它们彼此兼容。

向组添加依赖项 #

add 命令是向组添加依赖项的首选方法。这可以通过使用 --group (-G) 选项来完成。

poetry add pytest --group test

如果组不存在，它将被自动创建。

安装组依赖项 #

默认情况下，执行 poetry install 时，将安装所有非可选组中的依赖项。

注意

项目的默认依赖项集包括在 tool.poetry.dependencies 中定义的隐式 main 组，以及所有未明确标记为可选组的组。

可以使用 --without 选项排除一个或多个组

poetry install --without test,docs

您还可以选择加入可选组，方法是使用 --with 选项

poetry install --with docs

警告

当一起使用时，--without 优先于 --with。例如，以下命令将只安装可选 test 组中指定的依赖项。

poetry install --with test,docs --without docs

最后，在某些情况下，您可能只想安装特定组的依赖项，而不安装默认的依赖项集。为此，可以使用 --only 选项。

poetry install --only docs

注意

如果您只想安装项目的运行时依赖项，可以使用 --only main 表示法

poetry install --only main

注意

如果您想安装项目根目录，而不安装其他依赖项，可以使用 --only-root 选项。

poetry install --only-root

从组中删除依赖项 #

remove 命令支持 --group 选项，用于从特定组中删除包

poetry remove mkdocs --group docs

同步依赖项 #

Poetry 支持所谓的依赖项同步。依赖项同步确保 poetry.lock 文件中锁定的依赖项是环境中唯一的依赖项，并删除任何不必要的依赖项。

这可以通过使用 install 命令的 --sync 选项来完成

poetry install --sync

--sync 选项可以与任何与依赖项组相关的选项结合使用，以将环境与特定组同步。请注意，额外的依赖项是单独的。任何未选择安装的额外依赖项始终会被删除，无论 --sync 的值如何。

poetry install --without dev --sync
poetry install --with docs --sync
poetry install --only dev

注意

--sync 选项替换了 --remove-untracked 选项，该选项现在已弃用。

分层可选组 #

当您省略 --sync 选项时，您可以安装任何可选组的子集，而不会删除已安装的组。这在多阶段 Docker 构建中非常有用，例如，您可以在不同的构建阶段多次运行 poetry install。