虽然 Ruff 和 flake8-annotations 等标准 Python 静态检查工具通常仅要求为函数参数和返回类型提供类型提示,但 Gawain 会强制要求代码库中的每个变量、参数和类属性都包含注解。该工具旨在消除对 `dict[str, Any]` 等通用类型的依赖,它能在毫秒内识别缺失的注解,为那些更倾向于显式声明而非 Python 原生推断的开发者提供更严格的类型安全层。

,

超越函数签名

大多数 Python 类型检查工作流依赖于验证函数是否具有返回类型和参数注解的工具。Gawain 将这一要求扩展到代码的内部逻辑中,标记那些缺乏显式类型声明的变量。

显示 Python 变量和类属性类型注解的代码列表。
Gawain 在代码库中强制执行的显式类型声明示例。github.com

此截图展示了 Gawain 验证的特定类型注解和变量声明。

例如,如果像 `PORT = 8080` 这样的常量未被标注为 `Final[int]`,或者如果一个类属性在没有在类体中进行相应声明的情况下被赋值,Gawain 将报告错误。

机制与集成

Gawain 通过首先扫描源代码中的“存在性”错误(即缺失的注解)来充当类型完整性的守门人。只有在所有要求的提示都存在后,它才会继续使用 `ty` 或 `pyrefly` 等后端运行完整的类型检查。

用户可以在“obvious”模式(允许未注解的字面量,例如 `count = 0` 和容器字面量)和“strict”模式(要求每一个赋值操作都必须有注解)之间进行选择。

性能与权衡

CPython 3.14 标准库的中位数检查时间: gawain, obvious mode 0.46 s; gawain, strict mode 0.36 s; ruff --select ANN 0.35 s; flake8-annotations 11.4 s
CPython 3.14 标准库的中位数检查时间github.com

由 HN Digest 根据 github.com 报告的数据绘制;数值按源文件显示。

该工具专为高性能分析而构建,利用 `ruff_python_parser` 来实现快速结果。在针对 CPython 3.14 标准库的测试中,Gawain 在“obvious”模式下仅用约 0.46 秒就完成了检查。