Poetry项目中的include指令行为变更解析

背景介绍

在Python包管理工具Poetry的最新版本2.0.0中，对pyproject.toml文件中的include指令行为进行了重要变更。这一变更影响了项目打包时如何包含非Python文件的方式，特别是对于需要包含证书文件等资源文件的项目。

问题现象

在Poetry-core 2.0.0版本之前，开发者可以通过简单的路径列表形式指定需要包含的文件：

include = ["certificates/pem", "certificates/key"]

这种配置方式会将指定的证书文件自动包含在构建的wheel和sdist包中。然而，升级到2.0.0版本后，这种简化的配置方式不再有效，导致证书文件不会被包含在最终构建的包中。

变更原因

这一行为变更是Poetry团队为了提供更明确的文件包含控制而引入的。新版本要求开发者显式指定每个文件应该包含在哪种类型的包中（wheel或sdist），从而避免意外包含或不包含文件的情况。

解决方案

根据官方变更说明，正确的配置方式应改为对象格式，明确指定每个文件的包含格式：

include = [
    { path = "certificates/pem", format = ["sdist", "wheel"] },
    { path = "certificates/key", format = ["sdist", "wheel"] }
]

这种配置方式更加明确，允许开发者精细控制哪些文件应该包含在源代码分发包(sdist)和二进制分发包(wheel)中。

临时解决方案

对于需要快速解决问题的开发者，可以暂时将poetry-core版本锁定在2.0.0之前：

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

最佳实践建议

1. 对于新项目，建议直接使用新的对象格式配置方式
2. 升级现有项目时，应该检查所有include配置并进行相应修改
3. 考虑为不同类型的资源文件创建单独的配置块，提高可读性
4. 在CI/CD流程中加入包内容验证步骤，确保关键文件被正确包含

总结

Poetry 2.0.0对include指令的变更虽然带来了短暂的适配成本，但提供了更清晰、更可控的文件包含机制。开发者应该及时更新项目配置，采用新的对象格式来指定包含文件，以确保项目构建的可靠性和一致性。这一变更也体现了Python打包工具向更明确、更可预测的行为发展的趋势。