Python Poetry文档常见技术问题： **如何正确配置pyproject.toml依赖？**

Question

**技术问题：如何正确区分与配置 `pyproject.toml` 中的 `dependencies`、`dev-dependencies` 和 `optional-dependencies`？** 在使用 Python Poetry 管理项目依赖时，开发者常对 `pyproject.toml` 中的 `dependencies`、`dev-dependencies` 和 `optional-dependencies` 的用途与使用场景产生混淆。例如，是否应将测试工具或构建工具放入 `dev-dependencies`？如何为不同环境（如开发、生产、测试）定义可选依赖？如何确保依赖项正确安装而不遗漏或冗余？这些问题可能导致依赖管理混乱，影响项目的构建与部署。本文将详解各类依赖的用途及配置方式，帮助开发者规范依赖管理。

Answer 1

1. `pyproject.toml` 中的依赖类型概述

在使用 Python Poetry 管理项目依赖时，`pyproject.toml` 文件是核心配置文件之一。它支持三种主要依赖类型：

• dependencies：项目运行所需的主依赖项。
• dev-dependencies：仅在开发和测试阶段需要的依赖。
• optional-dependencies：可选功能或环境所需的依赖。

正确区分这三类依赖，有助于优化项目构建、部署和测试流程。

2. 依赖类型详解与使用场景

2.1 `dependencies` —— 主依赖

这些是项目正常运行所必需的依赖项，无论是在开发、测试还是生产环境中。

[dependencies]
requests = "^2.28.1"
flask = "^2.2.2"

示例说明：

• `requests`：用于发送 HTTP 请求。
• `flask`：用于构建 Web 应用。

2.2 `dev-dependencies` —— 开发与测试依赖

这类依赖仅在开发和测试阶段使用，例如代码格式化工具、静态检查工具、测试框架等。

[dev-dependencies]
pytest = "^7.2.0"
black = "^22.10.0"
mypy = "^0.991"

示例说明：

• `pytest`：用于执行单元测试。
• `black`：用于代码格式化。
• `mypy`：用于类型检查。

2.3 `optional-dependencies` —— 可选依赖

当项目支持多个可选功能或环境时，可以使用 `optional-dependencies` 来定义。例如：

[optional-dependencies]
test = ["pytest", "coverage"]
docs = ["sphinx", "sphinx-rtd-theme"]
mysql = ["mysqlclient"]

使用方式：

• poetry install --with test：安装测试相关依赖。
• poetry install --with docs：安装文档构建依赖。
• poetry install --with mysql：安装 MySQL 支持库。

3. 依赖管理的最佳实践

3.1 明确划分依赖类型

依赖类型	用途	安装命令
dependencies	项目运行时必须	poetry install
dev-dependencies	开发和测试阶段需要	poetry install --dev
optional-dependencies	可选功能或环境所需	poetry install --with <group>

3.2 使用可选依赖分组管理多环境配置

例如，你可以为不同环境定义不同的可选依赖组：

[optional-dependencies]
prod = ["gunicorn"]
dev = ["uvicorn", "fastapi"]
test = ["pytest", "coverage"]

安装方式：

• 生产环境：poetry install --with prod
• 开发环境：poetry install --with dev
• 测试环境：poetry install --with test

3.3 避免依赖冗余与遗漏

• 定期使用 poetry show --unused 检查未使用的依赖。
• 使用 poetry lock --no-update 生成锁定文件，确保依赖版本一致。
• CI/CD 环境中应使用 poetry install --no-dev 避免安装开发依赖。

4. 依赖管理流程图示意

graph TD
    A[开始] --> B[定义 dependencies]
    B --> C[定义 dev-dependencies]
    C --> D[定义 optional-dependencies]
    D --> E[选择安装方式]
    E --> F{是否为生产环境?}
    F -- 是 --> G[poetry install --no-dev]
    F -- 否 --> H[poetry install --dev]
    G --> I[完成]
    H --> I