Python Poetry 2.0.0 版本中include指令行为变更解析

Python Poetry 2.0.0 版本发布后，用户在使用include指令时可能会遇到一个重要的行为变更。本文将详细解析这一变更的背景、影响及解决方案。

问题现象

在Poetry 2.0.0版本之前，项目中的include指令会默认将指定文件包含在sdist(源码分发)和wheel(二进制分发)两种格式中。例如以下配置：

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

这种写法在旧版本中会同时将证书文件包含在源码包和二进制包中。但在2.0.0版本后，这种行为发生了变化，这些文件默认不再被包含在wheel包中。

变更背景

Poetry 2.0.0版本对include指令的行为进行了规范化调整，使其行为更加明确和一致。这一变更是为了：

1. 提高构建行为的可预测性
2. 让开发者更清晰地控制文件包含的范围
3. 避免意外包含不必要的文件到wheel包中

解决方案

要解决这个问题，需要明确指定文件应该包含在哪种分发格式中。新的配置方式如下：

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

这种显式声明的方式虽然稍显冗长，但提供了更精确的控制能力。

临时解决方案

如果暂时无法修改配置，可以通过锁定poetry-core版本的方式回退到旧行为：

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

但建议尽快迁移到新的配置方式，以获得更好的兼容性和可维护性。

最佳实践

1. 对于需要同时包含在源码和二进制包中的文件，明确指定两种格式
2. 对于仅需包含在源码包中的文件(如测试文件)，可以只指定sdist格式
3. 定期检查构建结果，确保所有必需文件都被正确包含

这一变更虽然带来了短暂的适配成本，但从长远来看，它使项目的构建配置更加清晰和可维护。开发者现在可以更精确地控制哪些文件出现在哪种分发包中，避免了不必要的文件泄露或缺失。