在Hatch项目中实现单文件Python包的PEP 561类型提示支持

在Python打包和分发过程中，类型提示支持是一个重要特性。PEP 561定义了如何分发类型信息，通常通过在包中包含一个空的py.typed标记文件来实现。然而，对于单文件Python包（即整个包只包含一个.py文件），如何正确实现这一机制可能会遇到一些挑战。

问题背景

传统Python包通常采用模块化目录结构，包含__init__.py文件。但对于小型项目或工具库，开发者可能更倾向于使用单文件结构，直接将.py文件放在项目根目录。当这样的单文件包需要支持类型提示时，按照PEP 561规范，需要包含py.typed文件，但直接添加会导致类型检查器（如Pylance）发出"stub not found"警告。

解决方案

Hatch构建系统提供了灵活的配置选项来解决这个问题。核心思路是通过构建配置将单文件包转换为标准的包结构，同时保留类型提示支持。具体实现如下：

1. 使用force-include指令：将根目录的.py文件强制包含为包内的__init__.py
2. 同时包含py.typed文件：确保类型标记文件被正确放置在包目录中

示例配置如下：

[tool.hatch.build.targets.wheel.force-include]
"minesweeper.py" = "minesweeper/__init__.py"
"py.typed" = "minesweeper/py.typed"

实现原理

这种配置方式实际上在构建过程中完成了以下转换：

1. 将根目录的minesweeper.py重映射为minesweeper/__init__.py
2. 将根目录的py.typed文件放入minesweeper子目录
3. 最终生成的wheel包将包含标准的Python包结构

这样既满足了PEP 561对类型提示支持的要求，又保持了开发时的单文件简洁性。

注意事项

1. 导入路径变化：使用此方法后，导入路径会从import minesweeper变为from minesweeper import minesweeper，需要在代码中相应调整
2. IDE支持：某些IDE可能需要重新加载项目才能正确识别新的包结构
3. 兼容性：此方法适用于Hatch构建系统，其他构建工具可能需要不同的配置方式

替代方案

如果不想改变导入路径，也可以考虑以下方法：

1. 直接使用包结构：创建minesweeper目录，将主文件作为__init__.py
2. 混合结构：保留根目录的.py文件作为入口，同时创建包含py.typed的包目录

结论

通过Hatch的构建配置，开发者可以灵活地在单文件包结构中实现PEP 561类型提示支持。这种方法既保持了开发时的简洁性，又满足了类型检查器的要求，是小型Python库开发的实用技巧。