Python Poetry 2.0 版本中文件包含机制的重要变更解析

Python Poetry 项目在 2.0 版本中对文件包含机制进行了重大重构，这一变更影响了使用 poetry-core 作为构建后端的项目打包行为。本文将深入分析这一变更的技术细节及其影响。

变更背景

在 Poetry 2.0 版本之前，项目的文件包含机制存在一些不一致性，导致某些非Python文件可能被意外包含在构建的wheel包中。这种包含行为有时会导致安装后文件冲突，特别是当多个包包含相同名称的非Python文件时。

变更内容

2.0 版本对文件包含机制进行了以下重要调整：

1. 更严格的默认包含规则：现在默认情况下，只有Python包和模块会被自动包含在构建结果中
2. 显式声明非Python文件：任何需要包含的非Python文件必须通过pyproject.toml中的include字段显式声明
3. 格式区分：可以针对不同分发格式(sdist和wheel)分别指定包含规则

影响分析

这一变更导致以下行为变化：

1. 测试文件：项目中的测试目录和文件默认不再包含在构建结果中
2. 文档文件：README、LICENSE等文档文件需要显式声明
3. 数据文件：项目附带的数据文件必须明确指定

迁移建议

对于受此变更影响的项目，可以采取以下解决方案：

1. 明确声明包含文件：在pyproject.toml中使用include字段显式声明需要包含的文件
2. 格式区分：对于只需要在源码分发中包含的文件，可以仅指定sdist格式
3. 路径映射：使用path和format参数精确控制文件的包含行为

最佳实践

建议项目维护者：

1. 仔细审查构建结果，确保所有必需文件都被正确包含
2. 为不同类型的文件(文档、测试、数据等)建立清晰的包含策略
3. 考虑不同分发格式(sdist和wheel)的不同需求

这一变更虽然可能导致一些现有项目的构建行为发生变化，但从长远来看，它提供了更清晰、更可控的文件包含机制，有助于提高Python包的分发质量和可靠性。