Python Poetry 2.0.0 版本中 `poetry run` 命令的格式参数问题解析

问题背景

在 Python 生态系统中，Poetry 是一个广受欢迎的依赖管理和打包工具。最新发布的 Poetry 2.0.0 版本引入了一个关键性变更，导致在使用 poetry run 命令执行脚本时会出现 KeyError: 'format' 错误。

问题表现

当用户尝试通过 poetry run 命令运行项目中的脚本时，系统会抛出以下错误：

KeyError: 'format'

错误追踪显示问题出现在 poetry/core/masonry/utils/module.py 文件的第 79 行，当尝试访问 package["format"] 时，由于该键不存在而引发异常。

技术分析

这个问题的根源在于 Poetry 2.0.0 对包格式处理逻辑的变更。在项目配置的 pyproject.toml 文件中，packages 部分需要明确指定 format 参数。在旧版本中，Poetry 会默认处理格式参数，但在新版本中变为强制要求。

解决方案

目前有两种可行的解决方案：

1. 显式指定格式参数：在 pyproject.toml 的 packages 部分明确添加 format 参数

packages = [
    { include = "somepackage", format = ["sdist", "wheel"] }
]

2. 等待官方修复：Poetry 开发团队已经意识到这个问题，可能会在后续版本中恢复默认值处理逻辑或提供更友好的错误提示。

影响范围

这个问题会影响所有使用 Poetry 2.0.0 版本且满足以下条件的项目：

• 使用 poetry run 命令执行脚本
• 在 pyproject.toml 中定义了 packages 部分但没有显式指定 format 参数

最佳实践建议

为了避免类似问题，建议开发者在升级到 Poetry 2.0.0 时：

1. 仔细检查项目配置文件中所有包定义
2. 为每个包明确指定格式参数
3. 在持续集成环境中添加版本兼容性测试
4. 关注 Poetry 项目的更新日志和已知问题列表

总结

Poetry 2.0.0 引入的这个变更虽然带来了一些兼容性问题，但也促使开发者更明确地定义项目配置。理解这个问题的本质有助于开发者更好地使用 Poetry 工具链，并为未来可能的类似变更做好准备。