如何在pyproject.toml管理的Python库中排除tests/docs文件夹出wheel包

原因分析 #

• 包发现规则的局限性：你配置的include/exclude是setuptools的包发现规则，仅针对可导入的Python包（即带__init__.py的目录）。tests和docs不属于可导入包范畴，所以这套规则无法过滤它们。
• 隐性配置冲突：即使关闭了include-package-data = false，如果项目存在旧的setup.py/setup.cfg残留配置，或者触发了setuptools的默认数据文件识别逻辑，仍可能把tests/docs纳入wheel。
• sdist转wheel的遗留问题：如果wheel是从sdist包构建的，sdist默认会包含项目根目录下多数文件（除非有过滤规则），这也会导致多余目录混入wheel。

解决方法 #

1. 全局排除不需要的目录 #

在pyproject.toml的[tool.setuptools]区块下添加全局exclude字段，覆盖包发现规则的范围限制：

[tool.setuptools]
include = ["sepal_ui*"]
exclude = ["docs*", "tests*"]
include-package-data = false

这里的exclude是全局级别，会过滤所有非包目录和文件，直接排除tests/docs。

2. 明确指定需要保留的数据文件 #

如果需要保留部分数据文件但排除tests/docs，通过[tool.setuptools.data-files]仅声明必要内容，未提及的目录会被自动排除：

[tool.setuptools.data-files]
# 示例：仅包含sepal_ui下的静态资源
"sepal_ui/static" = ["sepal_ui/static/**/*"]

3. 清理旧配置残留 #

• 删除项目中可能存在的MANIFEST.in文件（如果之前用过）。
• 移除已废弃的setup.py和setup.cfg，避免新旧配置冲突。

验证方式 #

构建wheel后，用以下命令解压检查内容：

wheel unpack your-package-version.whl

内容的提问来源于stack exchange，提问作者Pierrick Rambaud