Pyright类型系统中float与int的隐式转换问题解析

在Python静态类型检查工具Pyright中，处理JSON数据结构类型时可能会遇到一个有趣的现象：当定义递归类型别名时，float类型会自动包含int类型，这可能导致类型提示显示出现"幽灵"int类型。

类型系统设计原理

Python的类型系统中，float类型实际上隐式包含了int类型。这是Python类型规范中的特殊设计，因为在实际运行时，整数可以自动提升为浮点数而不会丢失精度。Pyright作为类型检查器，严格遵循这一规范。

问题重现场景

考虑以下JSON数据结构的类型定义：

type JSONAny = JSONScalar | JSONArray | JSONObject
type JSONScalar = str | bool | float | None
type JSONArray = list[JSONAny]
type JSONObject = dict[str, JSONAny]

def unwrap_singles(obj: JSONAny) -> JSONAny:
    while isinstance(obj, dict) and len(obj) == 1:
        obj = next(iter(obj.values()))
    return obj

在这个例子中，虽然JSONScalar明确定义为str | bool | float | None，但在类型检查时，float会被自动扩展为float | int。

类型显示行为分析

Pyright在显示类型时会尝试重建类型别名，但由于int是通过float隐式引入的，不属于原始类型别名定义的一部分，因此会单独显示出来。这导致了：

1. 在IDE悬停提示中看到意外的"| int"
2. 使用reveal_type()时，输出结果中int出现在顶层联合类型中，但嵌套结构中的float没有展开

解决方案与最佳实践

为了使类型提示更加清晰和一致，建议在定义JSONScalar时显式包含int类型：

type JSONScalar = str | bool | float | int | None

这样做有以下好处：

1. 消除IDE提示中的意外int类型
2. 使reveal_type()的输出保持内部一致性
3. 更准确地表达实际接受的类型范围
4. 提高代码可读性和维护性

类型系统设计思考

这个现象反映了静态类型检查与Python动态特性之间的平衡。Pyright的设计选择体现了：

1. 对Python类型规范的严格遵守
2. 在类型别名重建时的保守策略
3. 对用户显式意图的尊重

理解这一机制有助于开发者更好地利用类型系统，编写出类型更安全、更易维护的Python代码。