Poetry项目中的include与exclude规则变更解析

背景介绍

在Python打包工具Poetry的核心组件poetry-core从1.x升级到2.0版本后，用户发现了一个关于文件包含规则的重大变更。这个变更影响了项目中文件打包的行为，特别是当同一个文件同时匹配include和exclude规则时的处理逻辑。

问题现象

在poetry-core 1.x版本中，如果一个文件同时匹配include和exclude规则，include规则会优先，文件会被包含在最终的包中。但在2.0版本中，这种行为发生了变化，exclude规则会优先，导致文件被排除。

技术细节分析

旧版行为(1.x)

在poetry-core 1.x版本中，文件包含逻辑采用"包含优先"的策略：

1. 首先应用include规则，标记要包含的文件
2. 然后应用exclude规则，但不会覆盖已经被include规则标记的文件
3. 最终结果：同时匹配的文件会被包含

新版行为(2.0+)

poetry-core 2.0引入了更严格的打包控制：

1. 采用"排除优先"的策略
2. 任何匹配exclude规则的文件都会被排除，即使它也匹配include规则
3. 新增了format字段，可以明确指定文件适用于wheel还是sdist格式

解决方案

对于需要确保特定文件被打包的情况，推荐使用新的格式指定语法：

[tool.poetry]
include = [
    { path = "src/project/foo.py", format = ["wheel"] },
    { path = "docs/*", format = ["sdist"] }
]

这种语法提供了更精细的控制：

• 可以明确指定文件适用于哪种打包格式(wheel/sdist)
• 避免了include/exclude规则冲突带来的不确定性
• 使打包行为更加可预测和可控

最佳实践建议

1. 明确指定格式：对于关键文件，总是使用{path, format}对象语法而非简单路径
2. 检查冲突：定期检查项目中是否存在同时匹配include和exclude规则的文件
3. 版本兼容：如果项目需要支持poetry-core 1.x和2.x，考虑在文档中注明版本要求
4. 测试验证：在CI流程中加入打包结果验证，确保关键文件被正确包含

总结

poetry-core 2.0的这一变更反映了Python打包生态向更严格、更明确的方向发展。虽然这带来了短暂的兼容性问题，但从长远来看，它使打包行为更加可预测，减少了隐式规则带来的困惑。开发者应该适应这一变化，采用新的语法来确保项目的稳定打包。