Python 类型检查器众多，库维护者该如何抉择？

所有文章

2026 年：

• 现在真的要运行五个类型检查器吗？
• Pyrefly v1.0 发布！
• 类型正确，代码错误：类型检查器捕获的惊人错误
• 将 Pyrefly 类型检查添加到你的智能循环中
• Python 类型检查器比较：速度和内存使用情况
• 如何在语言服务器中支持笔记本
• 通过删除未注释代码实现 100% 类型覆盖
• 塑造 Pyrefly 的 Pyre 经验教训
• Python 类型检查器比较：类型规范一致性
• pandas 的公共 API 现在已实现类型完整！
• Python 类型检查器比较：空容器推断
• Pyrefly 捆绑的第三方存根
• 让 Pyrefly 诊断速度提升 18 倍
• 4 种 Pyrefly 类型缩小模式让类型检查更直观

2025 年：

• 借助 Pyrefly 新的 Pydantic 集成轻松完成数据验证
• Pyrefly 测试版发布！
• 将 NumPy 的类型完整度得分提升至近 90%
• 用 Pyrefly 让你的 Python IDE 焕然一新
• 为何如今的 Python 开发者热衷于类型提示
• 介绍 Pyrefly - 一款全新的 Python 类型检查器和 IDE 体验工具

现在真的要运行五个类型检查器吗？

2026 年 6 月 3 日，阅读时长 6 分钟。Marco Gorelli，Quansight Labs 提出疑问：Mypy、Pyrefly、Pyright、ty、Zuban，未来可能还会有更多……库维护者该如何应对呢？简而言之，优先在测试套件中尽可能多地运行类型检查器，至少在源代码中运行一个。

最重要的类型检查（以及为何你可能搞错了重点）

很多包在类型检查方面存在错误做法，常见的是在源代码上运行类型检查器，却让测试代码保持无类型状态，这种做法本末倒置。假设维护一个 Python 包，用户真正关心的是公共 API 以及与它交互的体验。在内部源代码上运行类型检查器主要测试内部逻辑，而用户使用哪种类型检查器不由开发者决定。通过在测试套件中尽可能多地运行类型检查器，可确保包的公共 API 能让更多用户顺利使用。

Polars 的故事

Polars 是一个现代数据框库，自 2020 年推出后在数据科学领域掀起热潮。作为重度用户，希望让其开发者体验更好。将 Pyrefly 添加到 Polars 的持续集成任务中遇到一些障碍，Pyrefly 通常比 mypy 更严格，实例化变量时需重写部分代码或添加更明确的类型注释，还发现了一些错误，多数错误的修复随 v1 版本发布。以 `DataType.__eq__` 函数为例，为满足多个类型检查器，代码中出现大量类型忽略注释，代码库易被污染。与其让所有内部代码通过多个类型检查器检查，不如先测试主要类型检查器与库的公共 API 配合情况，这样更有用且简单。以 `DataType.__eq__` 的测试代码为例，mypy、Pyrefly、Pyright、ty、Zuban 对其进行类型检查时都未报告错误，说明它们对公共 API 的效果达成一致。让 Pyrefly 在整个 Polars 测试套件上运行相对轻松，也在探索在其源代码中使用 Pyrefly，但这是一项更大的工作，需逐步解决。

那我的源代码呢？为什么会有这么多类型检查器？

类型规范概述了类型检查器应遵循的标准规则，但有些方面较模糊，不同类型检查器会做出不同设计决策。有些类型检查器严格，会产生误报但保护免受潜在错误；有些更宽松，允许逐步添加类型信息。在对源代码进行类型检查时，需考虑在严格和宽松之间找到平衡点。Pyrefly 不仅严格（可配置），而且速度快、符合规范，是不错的选择。若在项目中使用遇到问题可报告。

总结

如今有 5 个备受关注的 Python 类型检查器：mypy、Pyrefly、Pyright、ty、Zuban。库维护者在源代码上运行这 5 个检查器会带来过多维护工作，还会让代码充斥类型忽略注释。将精力花在在测试中运行多个类型检查器上更有价值，可测试用户与库交互时的类型检查效果。

社区与支持

可加入 Discord、在 Github 上提交问题、参加办公时间。

法律声明

包含隐私政策、使用条款、数据政策、Cookie 政策。