Pyright类型检查器中的导入符号解析问题分析

在Python静态类型检查工具Pyright的最新版本中，出现了一个关于导入符号解析的bug。这个问题主要影响使用部分类型存根(partial stubs)的项目，特别是当存根文件中缺少顶层__init__.py定义时。

问题现象

当项目中同时安装原始库和对应的部分类型存根时，Pyright 1.1.395和1.1.396版本会错误地报告"unknown import symbol"错误。具体表现为：从库的顶层__init__.py导入符号时，即使该符号在原始库中明确定义，类型检查器也会报错。

以tortoise-orm库为例，当执行from tortoise import Tortoise时，Pyright会错误地提示"Tortoise"是未知的导入符号，尽管这个类确实存在于库的__init__.py文件中。

问题根源

经过Pyright开发团队的分析，这个bug源于一个关于部分类型存根支持的内部重构。在最近的版本更新中，团队将部分存根支持分离到了一个独立服务中，但在命令行版本的Pyright中未能正确创建这个服务。

部分类型存根是一种常见的类型提示实践，它允许开发者只对库的一部分提供类型信息，其余部分则依赖类型检查器从原始Python代码中推断。Pyright通常能够很好地处理这种情况，但在这次重构后，命令行版本失去了正确处理部分存根的能力。

技术背景

Python的类型检查器在处理导入时通常会遵循以下优先级：

1. 首先查找类型存根文件(.pyi)
2. 如果找不到存根，则回退到原始Python文件(.py)
3. 对于部分存根的情况，需要合并存根和原始文件中的类型信息

在这个bug中，Pyright错误地忽略了原始Python文件中的定义，即使对应的存根文件中没有提供该符号的类型信息。

解决方案

Pyright团队在1.1.397版本中修复了这个问题。修复的核心是确保命令行版本也能正确初始化部分存根支持服务，恢复了对部分存根场景的正确处理能力。

对于遇到此问题的用户，解决方案很简单：升级到Pyright 1.1.397或更高版本。可以通过以下命令升级：

pip install --upgrade pyright

最佳实践

为了避免类似问题，建议开发者在类型存根项目中：

1. 尽量提供完整的类型存根，特别是对于公共API的顶层模块
2. 在CI/CD流程中固定类型检查工具的版本
3. 当使用部分存根时，明确记录哪些模块有存根，哪些依赖原始代码的类型推断

这个bug的发现和修复过程也展示了开源协作的优势，用户能够及时反馈问题，开发团队能够快速响应并修复，最终使整个Python类型检查生态系统更加健壮。