python pyright

从Python开发者的角度看Pyright：一个被低估的类型检查工具

做Python开发这些年，类型检查这事儿一直挺有意思。早期大家觉得动态类型是Python的“优势”，后来随着代码规模增长，越来越多的人开始拥抱类型注解。而说到类型检查工具，Pyright常常被忽略——可能是因为它出自微软，也可能是因为它和VSCode绑定得太紧密。但说真的，Pyright的定位和设计思路，其实比很多人想象的要更值得琢磨。

它到底是什么

Pyright是一个Python类型检查器，用TypeScript写的。这个背景很有意思——一个Python工具，核心语言却是TypeScript。这意味着什么？意味着它的运行不依赖Python运行时，启动速度极快。日常感受就是，你在编辑器里改完一行代码，几乎瞬间就能看到类型错误提示。对比其他工具可能需要等几百毫秒甚至更久，这种即时反馈在写大项目时差别很明显。

另外，Pyright从设计上就是“静态”的，它不执行Python代码，只分析源码的抽象语法树和类型注解。这听起来像是缺点，但实际用起来反而省心——不用考虑运行时环境、不用装第三方包的特定版本，拉下来就能跑。对于CI/CD这种环境，特别友好。

它能做什么

最基础的功能不用说，检查类型注解是否一致。比如你写了个函数，参数标注为int，结果传了个字符串进去，Pyright会标红。但它的能力远不止这些。

它支持泛型、重载、条件类型，甚至能处理一些复杂的类型推断。举个例子，如果你定义了一个接收Union[int, str]的函数，然后返回值的类型会根据输入的不同而不同，Pyright能分析出具体分支的类型，而不是简单地把返回值标成Union。这种推断能力在很多场景下可以省去大量冗余的类型注解。

另一个常用的场景是逐步迁移旧代码。Pyright可以配置“严格模式”和“基础模式”，你可以在新代码上严格检查，同时对旧代码放宽松，一点一点把类型注解补上。这种渐进式的支持，对很多遗留项目来说，比一刀切地要求完全类型化要现实得多。

怎么使用

Pyright分两种方式：作为命令行工具，或者作为VSCode的插件（也就是Pylance的核心）。命令行工具直接用pip install pyright安装，然后运行pyright your_project.py就能看到所有类型错误。更常见的用法是在项目根目录放一个pyrightconfig.json配置文件：

{"include":["src"],"exclude":["tests"],"strict":["src/new_module"],"typeCheckingMode":"basic"}

这个配置的意思是，只检查src目录，排除tests，但在src/new_module下启用严格模式。这种方式比用命令行参数要灵活得多。

如果你在用VSCode，Pylance默认就集成了Pyright的类型检查能力。设置里搜索python.analysis.typeCheckingMode，可以选off、basic、strict。很多人一开始选basic，然后慢慢发现约束不够，最后切到strict。

最佳实践

不是所有代码都需要严格的类型检查。Pyright的强项在于它提供了灵活的粒度控制。一个实际的做法是：对核心业务逻辑启用严格模式，对工具类、测试代码、临时脚本用基本模式甚至关闭检查。这样既保护了核心代码的质量，又不会让类型注解变成无谓的负担。

另外，类型注解的数量和质量之间需要平衡。有很多人为了消除Pyright的报错，加了一堆不必要的Any或者cast，反而让代码更难读。更合理的做法是，先明确自己项目中有哪些“类型边界”——比如外部API的返回值、用户输入、数据库记录——在这些边界处做严格的类型约束，其他内部的类型传递可以适当放宽。

还有一个容易被忽视的点：Pyright的配置文件和requirements.txt一样，应该纳入版本控制。这样团队内部所有人都用同一套风格和严格程度，避免出现“我本地没报错，你那边一堆红”的情况。

和同类技术对比

说到Python类型检查，绕不开mypy。mypy出道更早，社区更成熟，很多第三方库的类型存根（stub）都是围绕mypy写的。但mypy有个致命弱点：慢。尤其是代码量大了以后，每次全量检查都要等几秒甚至十几秒。而Pyright启动几乎不花时间，增量检查更是秒出结果。

从错误信息上看，mypy的报错有时候很“模糊”——它会告诉你类型不匹配，但不会告诉你具体哪里不匹配。Pyright的报错更具体，甚至能高亮不匹配的那一小段代码。这听起来是小事，但调试的时候省的时间绝对不止一点半点。

另一个工具是pytype，来自Google。pytype的独到之处在于它可以“推断”类型——即使你完全没有类型注解，它也能根据代码的使用方式来推测可能的类型。但缺点是推测结果不一定准，而且运行速度比mypy还慢。pytype现在基本处于维护状态，新功能很少，不太推荐用在生产项目上。

至于VS Code内置的Pylance，它本质上就是Pyright的封装，加了一些编辑器特有的功能（比如自动补全、跳转定义）。不用太纠结选哪个——如果你用VS Code，直接用Pylance就行，底层是一样的。

总的来说，Pyright在速度、错误提示质量、配置灵活性上都有明显优势。如果硬要说缺点，一个是它的文档比较零散，有时候要翻源码才能搞清楚某个配置项的具体行为；另一个是它和Python生态的绑定不够紧密——比如有些自定义类型或者元编程技法，Pyright可能处理得不如mypy成熟。但这些缺点在大多数日常场景下都可以接受。

说到底，选择哪个工具取决于项目规模、团队习惯、以及对速度的敏感程度。如果是一个几万行代码的长期项目，值得在Pyright上花点时间配置好。如果只是写写脚本玩一玩，那其实什么类型检查工具都不需要，动态类型才是真正的自由。