Hatch构建工具：如何创建空轮子包的最佳实践

在Python包管理中，有时我们需要创建所谓的"空轮子"包（empty wheel package）。这类包通常被称为"元包"（meta package），它们本身不包含任何实际代码，主要作用是集中管理依赖关系。本文将详细介绍如何使用Hatch构建工具高效地创建这类特殊包。

元包的应用场景

元包在Python生态中有着广泛的应用，常见的场景包括：

1. 插件集合包：例如myapp-plugins，它仅依赖myapp-plugin-foo、myapp-plugin-bar等实际插件包
2. 版本兼容包：为不同Python版本提供统一的入口
3. 依赖分组：将相关依赖分组管理，简化用户安装

传统方法的局限性

开发者最初可能会尝试以下配置方式：

[tool.hatch.build.targets.wheel]
only-include = []

或者：

[tool.hatch.build.targets.wheel]
packages = []

但这些方法往往无法达到预期效果，因为构建系统内部通常使用真值检查而非显式检查配置是否存在。

Hatch的解决方案

Hatch提供了专门的bypass-selection选项来完美解决这个问题。该选项会绕过默认的文件选择逻辑，直接创建一个不包含任何文件的轮子包。

推荐配置如下：

[tool.hatch.build.targets.wheel]
bypass-selection = true

实现原理

当启用bypass-selection时，Hatch构建系统会：

1. 完全跳过文件收集阶段
2. 不将任何源代码或资源文件包含在最终的wheel包中
3. 仅保留包的元数据（如依赖关系）
4. 生成符合PEP 427标准的空wheel文件

注意事项

1. 该选项与文件选择相关的其他选项（如only-include、packages等）互斥
2. 空wheel包仍需包含有效的pyproject.toml或setup.py来定义元数据
3. 安装后，包目录中仅包含*.dist-info目录，不包含任何实际模块

最佳实践建议

对于元包开发，建议：

1. 明确定义所有依赖关系
2. 在包描述中清楚说明这是元包
3. 考虑添加适当的分类器（如Framework :: Plugin）
4. 确保版本号与依赖包保持同步

通过使用Hatch的bypass-selection功能，开发者可以轻松创建专业级的元包，既满足了依赖管理的需求，又避免了包含不必要的文件。