Poetry项目依赖管理：project.dependencies与tool.poetry.dependencies的协同工作机制

核心机制解析

在Python包管理工具Poetry的最新版本(v2+)中，依赖管理存在两个关键配置区块：[project.dependencies]和[tool.poetry.dependencies]。这两个区块并非简单的替代关系，而是具有明确的职责划分：

1. 元数据主导原则
   project.dependencies作为基础依赖声明，会直接参与项目构建过程。该区块定义的依赖关系将被写入最终的构建产物（如wheel或sdist包）中，成为项目公开声明的依赖规范。

2. 锁定文件增强机制
   tool.poetry.dependencies作为补充配置，仅在生成lock文件时发挥作用。其主要功能是为project.dependencies中声明的依赖提供附加信息（如本地路径、开发模式等），这些增强信息不会出现在最终构建产物中。

典型应用场景

本地依赖的特殊处理

当项目需要引用本地开发中的依赖包时，推荐采用以下配置模式：

[project]
dependencies = [
    "oc_s3",  # 基础声明
]

[tool.poetry.dependencies]
oc_s3 = {path = "oc_shared/oc_s3", develop = true}  # 补充开发模式信息

这种配置方式既保证了构建时的兼容性（其他用户安装时仍可通过PyPI获取标准版本），又为本地开发提供了便利。

版本约束的灵活管理

对于需要精确控制的依赖关系：

[project]
dependencies = [
    "numpy>=1.20",  # 公开声明的宽松约束
]

[tool.poetry.dependencies]
numpy = "==1.23.5"  # 开发环境锁定特定版本

常见误区与解决方案

1. 配置失效问题
   开发者常误以为两个区块可以独立工作。实际上，tool.poetry.dependencies必须与project.dependencies中的包名严格对应才能生效。

2. 路径依赖的特殊性
   纯project.dependencies区块不支持本地路径依赖的直接声明，这是设计上的限制而非缺陷。必须通过组合配置实现。

3. 环境隔离策略
   开发专用依赖（如测试框架）应使用tool.poetry.group.dev.dependencies而非混入主依赖配置，这符合Python打包规范的最佳实践。

版本演进说明

从Poetry v1到v2的变革中，项目逐渐向PEP 621标准靠拢。这种双配置机制既保持了向后兼容，又为未来完全过渡到标准格式预留了空间。建议新项目优先采用project.dependencies作为主声明，仅将tool.poetry.dependencies用于必要的特殊情况处理。

理解这一设计哲学，开发者就能更高效地组织项目依赖，在标准化与灵活性之间取得平衡。