Poetry项目目录名与包名不一致问题的解决方案

问题背景

在使用Poetry 2.0.1版本构建Python项目时，开发者遇到了一个常见问题：项目目录名称与包名称不一致导致的构建失败。这个问题在Poetry的早期版本中已有相关讨论，但在迁移到Poetry 2.x版本后，由于配置格式的变化，问题再次出现。

问题现象

项目结构如下：

pythonProject/
     my_package/
         __init__.py

开发者希望使用"a_nice_name"作为包名，但实际代码存放在"my_package"目录中。在pyproject.toml中使用[project]表配置时，构建过程会失败，错误提示找不到"a-nice-name"对应的文件/目录。

技术分析

配置格式变更

Poetry 2.x版本引入了对PEP 621标准的支持，推荐使用[project]表替代传统的[tool.poetry]表。然而，packages配置项并不属于PEP 621标准的一部分，它仍然是Poetry特有的配置。

构建机制差异

当使用[project]表时，Poetry会严格遵循PEP 621规范进行构建。构建器会尝试查找与项目名称匹配的包目录（将连字符转换为下划线），而不会自动应用packages配置。

解决方案

推荐方案

1. 保持传统配置方式：继续使用[tool.poetry]表，这是最稳定的解决方案
2. 调整项目结构：将目录名称改为与包名一致（如"a_nice_name"）

配置示例

[tool.poetry]
name = "a_nice_name"
version = "0.0.1"
packages = [{ include = "my_package" }]

[build-system]
requires = ["poetry-core==2.0.1"]
build-backend = "poetry.core.masonry.api"

注意事项

1. 虽然poetry check会提示使用[project]表的警告，但对于非标准配置项，暂时仍需使用传统方式
2. 未来Poetry可能会提供更好的解决方案来处理这种特殊情况
3. 在迁移配置时，不应盲目将所有配置项移动到[project]表中

总结

Poetry 2.x版本在向标准化迈进的过程中，带来了一些配置上的变化。对于目录名与包名不一致这种特殊情况，目前仍需使用传统的[tool.poetry]配置方式。开发者需要理解Poetry配置项的分类，区分哪些属于PEP 621标准，哪些是Poetry特有的扩展功能，才能正确配置项目。