你真的需要同时运行五种 Python 类型检查器吗？

背景

Python 生态中的静态类型检查领域正经历一场“军备竞赛”。目前，Mypy、Pyrefly、Pyright、ty 和 Zuban 等五种主要的类型检查器（Type Checkers）正受到广泛关注。对于库维护者（Library Maintainers）而言，面对如此多的工具，一个令人焦虑的问题随之浮现：是否应该在自己的代码库中同时运行所有这些检查器？

这种多重检查的需求不仅增加了维护负担，还可能导致代码库被大量的类型忽略注释（type-ignore comments）和工作区变通方案所污染。Hacker News 上的一篇热门讨论及随后的深度博客文章指出，许多维护者在这一问题上陷入了误区，将精力错误地分配在了内部代码而非公共 API 上。

核心内容

被颠倒的优先级：公共 API 才是核心

文章开篇即指出一个普遍存在的错误做法：许多 Python 包在持续集成（CI）中对内部源代码运行类型检查，却对测试代码（Test Suite）不进行类型检查。作者认为这种做法本末倒置。

作为库的用户，你并不关心维护者内部使用 ruff 还是 black 进行格式化，也不关心他们如何排序导入或选择 pytest 还是 unittest。这些内部开发实践对用户毫无影响。用户真正关心的是**公共 API（Public API）**以及他们与 API 交互时的体验。

当你在内部源代码上运行类型检查器时，你主要是在测试内部逻辑。这固然重要，但用户使用的类型检查器可能与维护者不同。因此，通过在测试套件上运行尽可能多的类型检查器，可以确保你的公共 API 对尽可能多的用户友好且无类型错误。

Polars 案例研究：Pyrefly 的挑战与启示

以现代数据帧库 Polars 为例，作者作为其重度用户，希望提升其开发者体验。如果 Polars 的类型定义准确，用户将获得更好的自动补全、文档支持以及针对特定类型 bug 的保护。为了将 Pyrefly 加入 Polars 的 CI 流程，作者进行了深入调查：

1. 严格性与兼容性：Pyrefly 通常比 Mypy 更严格，导致需要重写部分代码或在变量实例化时添加更明确的类型注解。
2. 工具 Bug：作者遇到了 Pyrefly 的一些 Bug，但令人鼓舞的是，绝大多数修复已随备受期待的 v1 版本发布。
3. 维护成本权衡：虽然发现了一个中等优先级的 Bug 使得投入值得，但作者质疑是否值得为另外三个类型检查器重复这一过程。

代码污染的现实：DataType.__eq__ 的困境

为了说明多重检查带来的代码污染，文章分析了 Polars 中 DataType.__eq__ 函数的实现。在 Python 中，__eq__ 方法预期返回 bool，但 Polars 的实现根据输入可能返回 pl.Expr 或 bool，这需要重载（Overloads）。

为了同时满足 Mypy、Pyrefly、Pyright 和 ty 的要求，代码中不得不堆砌大量的类型忽略注释：

@overload # type: ignore[override]
def __eq__( # pyrefly: ignore[bad-override]
    self, other: pl.DataTypeExpr
) -> pl.Expr: ...

@overload
def __eq__(self, other: PolarsDataType) -> bool: ...

def __eq__(self, other: pl.DataTypeExpr | PolarsDataType) -> pl.Expr | bool: # ty: ignore[invalid-method-override] # pyright: ignore[reportIncompatibleMethodOverride]

短短 7 行代码中出现了 4 种不同类型的忽略注释。这种代码库不仅难以维护，也违背了类型检查的初衷。

正确的做法：通过测试验证公共 API

与其让内部代码经受多种检查器的折磨，不如优先测试公共 API 是否能被主流类型检查器正确解析。这更容易实现，因为只需确保库按预期使用时无类型错误即可。

在 Polars 的案例中，针对 DataType.__eq__ 的测试如下：

DTYPE_TEMPORAL_UNITS: Final[frozenset[TimeUnit]] = frozenset(["ns", "us", "ms"])

def test_dtype_time_units() -> None:
    # check (in)equality behaviour of temporal types that take units
    for time_unit in DTYPE_TEMPORAL_UNITS:
        assert pl.Datetime == pl.Datetime(time_unit)
        assert pl.Duration == pl.Duration(time_unit)
        assert pl.Datetime(time_unit) == pl.Datetime
        assert pl.Duration(time_unit) == pl.Duration

令人欣慰的是，Mypy、Pyrefly、Pyright、ty 和 Zuban 都能顺利通过此测试，未报告任何错误。这表明，尽管检查器对内部实现细节的看法可能不同，但在公共 API 的行为上它们是一致的。这正是用户所关心的。

Polars 团队成功地将 Pyrefly 运行在完整的测试套件上，且过程相对无痛。对于内部开发，他们也在逐步探索使用 Pyrefly，但这被视为一项更大的工程。

为什么会有这么多类型检查器？

Python 类型规范（typing spec）规定了一套标准规则，但在某些模糊地带（如用户未充分指定类型信息时），不同的检查器做出了不同的设计决策：

• 严格模式：尽可能严格，即使产生误报（False-positives），也要最大程度地防止潜在 Bug。
• 宽松模式：更加宽容，允许用户逐步向代码库添加类型信息。

在源代码检查方面，维护者需要决定自己在“严格 vs 宽松”光谱上的位置。Pyrefly 不仅严格（可配置），而且速度快且符合规范，是一个极佳的选择。如果遇到任何问题，建议向社区报告，以便所有用户受益。

关键要点

• 优先检查测试套件：库维护者应将运行多种类型检查器的精力优先投入到测试套件中，而非内部源代码。
• 公共 API 是用户焦点：用户只关心公共 API 的类型安全性，内部实现细节（如格式化、测试框架选择）对用户无影响。
• 避免代码污染：同时适配多种严格程度不同的检查器会导致源代码中充斥大量的 # type: ignore 注释和工作区变通方案，降低代码可读性和可维护性。
• 一致性验证：不同的检查器可能在内部实现上有分歧，但在公共 API 的行为上通常达成一致。通过测试验证 API 兼容性是更高效的策略。
• 当前主流工具：目前值得关注的 Python 类型检查器主要包括 Mypy、Pyrefly、Pyright、ty 和 Zuban。
• 逐步内部迁移：在确保公共 API 兼容后，可逐步在内部源代码中引入更严格的检查器（如 Pyrefly），以改善开发体验，但这应作为增量工程进行。

意义与影响

这篇文章为 Python 库维护者提供了一套务实的策略，以应对日益复杂的类型检查生态。它纠正了“类型检查等于检查所有代码”的直觉性误解，强调了用户视角的重要性。

1. 降低维护门槛：通过建议将多重检查集中在测试套件上，文章帮助维护者避免了因适配不同检查器规范而导致的代码混乱，降低了长期维护成本。
2. 提升用户体验：确保公共 API 在多种检查器下均无错误，直接提升了下游用户在使用自动补全、IDE 支持和静态分析时的体验，减少了因类型不匹配导致的运行时错误。
3. 促进工具生态健康发展：通过区分“内部实现”与“公共契约”，文章鼓励维护者选择最适合自身团队规范的检查器用于内部开发，同时利用多种工具验证公共接口的通用性，从而在工具多样性和代码质量之间找到平衡。

总之，面对五种主流类型检查器的现状，维护者无需恐慌性地全部运行于源代码中，而应采取“测试驱动的类型验证”策略，以最小的维护成本获得最大的用户价值。