如何用 mypy 和 pyright 实现“类型不兼容”的自动化断言式检查

本文介绍一种反向类型测试技巧：利用类型检查器对冗余 # type: ignore 注释的报错机制，实现类似 pytest.raises() 的“预期类型错误”断言，从而自动化验证类型提示是否足够严格。

本文介绍一种反向类型测试技巧：利用类型检查器对冗余 `# type: ignore` 注释的报错机制，实现类似 `pytest.raises()` 的“预期类型错误”断言，从而自动化验证类型提示是否足够严格。

在 Python 类型驱动开发中，我们习惯编写“正向类型测试”——例如确保 x: str = takes_a_str(“”) 不报错，以验证类型签名正确。但仅此不足以保证类型安全性：若函数误将参数注解为 Any 或返回值过于宽泛（如 union[str, int]），正向测试仍会通过，而实际已丧失类型约束力。

此时需要负向类型测试（negative type checking）：明确声明“此处 必须 报类型错误”，并让 CI/本地检查自动验证该错误确实发生。这正是 pytest.raises() 在运行时的作用，而静态类型检查器也提供了对应的机制——关键在于让类型检查器对“本应失败却强行忽略”的注释发出警告。

✅ 核心原理：滥用 # type: ignore 并触发“冗余忽略”告警

mypy 和 Pyright 均支持检测并报错「不必要的类型忽略」：

• mypy：启用 warn_unused_ignores = True（或通过 –warn-unused-ignores、–strict 启用）
• Pyright：启用 reportUnnecessaryTypeIgnoreComment = true

当某行代码本身类型安全，却添加了 # type: ignore[xxx]，类型检查器便会报错——这恰好是我们需要的“断言失败”信号。

? 实践示例

假设有如下函数：

def takes_a_str(x: str) -> str:     if x.startswith("."):         raise RuntimeError("Must not start with '.'")     return x + ";"

我们希望验证：

• ✅ takes_a_str(“”) 返回 str → 正向测试应成功
• ❌ takes_a_str(42) 参数类型错误 → 负向测试应 触发且仅触发 类型错误

1. 正向测试（无忽略，应通过）

def check_types() -> None:     result: str = takes_a_str("")  # ✅ 无错误，类型匹配

2. 负向测试（显式忽略，但应 失败 —— 即忽略被判定为冗余）

def should_fail_type_checking() -> None:     # 预期失败：str → dict 赋值不兼容 → 必须报错！     x: dict = takes_a_str("")  # type: ignore[assignment]      # 预期失败：int 传给 str 参数 → 必须报错！     takes_a_str(2)  # type: ignore[arg-type]

⚠️ 关键细节：

• 必须使用精确的错误码（如 [assignment], [arg-type]），而非泛化的 # type: ignore。否则会掩盖真实问题，等价于 pytest.raises(BaseException)，失去校验意义。
• 推荐统一使用 # type: ignore[…]（而非 # pyright: ignore[…]），因其是 PEP 484 标准语法，被所有主流类型检查器（mypy、pyright、pylance、pylama）识别，保障跨工具一致性。

⚙️ 配置与运行

mypy 配置（pyproject.toml）：

[tool.mypy] warn_unused_ignores = true # 或启用全量严格模式（推荐） # strict = true

Pyright 配置（pyrightconfig.json）：

{   "reportUnnecessaryTypeIgnoreComment": "error" }

运行检查：

mypy test_types.py     # 应在 should_fail_type_checking 中报告 "Unused 'type: ignore' comment" pyright test_types.py  # 应报告 "Unnecessary '# pyright: ignore' rule"

✅ 若上述负向测试行 未报错 → 说明类型提示过松（例如 takes_a_str 参数被误标为 Any），测试失败；
❌ 若正向测试行 意外报错 → 说明类型提示过严或存在 bug，同样失败。

? 最佳实践总结

• 命名约定：将负向测试函数命名为 test_type_errors_* 或 should_fail_*，便于识别意图；
• 粒度控制：每个 # type: ignore 对应一个明确的、不可接受的类型误用场景，避免一行多忽略；
• CI 集成：将 mypy –warn-unused-ignores 或 pyright –verifyTypes 加入 CI 流程，使“预期失败”成为可验证的构建门禁；
• 工具协同：若项目同时使用 mypy 和 pyright，优先依赖 # type: ignore[…]，无需维护两套注释。

通过这一模式，你不再依赖人工观察错误列表，而是将类型安全的“边界条件”转化为可断言、可自动化、可版本化管控的测试资产——真正实现类型即契约（Types as Contracts）。