Python Poetry 项目构建中文件包含行为的变更解析

在Python项目构建工具Poetry从1.x升级到2.x版本的过程中，一个重要但容易被忽视的变化是关于tool.poetry.include配置项的行为变更。这个变更影响了项目打包时额外文件的包含逻辑，导致许多开发者在升级后遇到构建产物中缺少预期文件的问题。

问题背景

在Poetry 1.8.5版本中，当开发者使用tool.poetry.include配置项指定要包含的额外文件时，这些文件会被无条件地包含在构建产物中（无论是wheel包还是tar.gz包）。然而，在Poetry 2.1.1版本中，这一行为变得更加严格和一致。

行为变更细节

新版本Poetry对文件包含逻辑做了以下重要调整：

1. wheel包构建：现在只包含明确列在tool.poetry.include中的文件，不再自动包含项目目录下的其他文件

2. tar.gz包构建：保持与之前版本相同的行为，包含所有指定文件

3. 路径规范：要求include配置中的路径必须明确且完整，不能依赖隐式的文件包含

实际影响案例

以一个实际项目为例，项目结构包含：

gnwmanager/
    firmware.bin
    unlock.bin
    cli/gnw_patch/binaries/
        (一些二进制文件)

在Poetry 1.8.5下：

• 所有.bin文件都被正确包含在wheel和tar.gz包中

在Poetry 2.1.1下：

• wheel包中缺少顶层目录的.bin文件
• cli子目录下的二进制文件仍被包含
• tar.gz包中所有文件都被正确包含

解决方案

要使项目在新版Poetry下正常工作，需要在pyproject.toml中明确指定所有需要包含的文件。例如：

[tool.poetry]
include = [
    "gnwmanager/firmware.bin",
    "gnwmanager/unlock.bin",
    "gnwmanager/cli/gnw_patch/binaries/*.bin"
]

最佳实践建议

1. 显式声明：始终明确列出所有需要包含的非Python文件

2. 版本兼容：在项目文档中注明最低Poetry版本要求

3. 测试验证：在CI流程中增加构建产物内容检查

4. 模式匹配：合理使用通配符简化配置，但要确保不会遗漏重要文件

技术原理

这一变更背后的设计理念是使构建行为更加确定和可预测。旧版本中隐式的文件包含可能导致：

• 构建结果不可预测
• 可能意外包含不需要的文件
• 不同环境下构建结果不一致

新版Poetry通过严格要求显式声明，确保了构建过程的可重复性和一致性，这符合现代Python打包的最佳实践。

总结

Poetry 2.0+版本对文件包含行为的变更是向更加严格和明确的构建配置迈出的重要一步。虽然这可能导致现有项目需要调整配置，但从长远来看，这种变化提高了构建过程的可靠性和可维护性。开发者应该适应这一变化，采用显式声明的方式来管理项目中的资源文件。