用途:修复 ty、make typing、make check-repo 检测到的类型检查错误,适用于本地运行、CI 或 PR 日志中出现 typing 报错的场景。
输入:已知的待检查模块或目录目标;可选的 make typing 或 CI 报错输出。
主要流程与能力:先从失败输出中提取出错文件或模块路径,没有则运行 make typing;选取覆盖失败点的最小目标,用 ty check --respect-ignore-files --exclude '**/_pb' <target> 获得聚焦基线;按类别分类错误(签名注解缺失或错误、联合类型属性访问、宽泛联合返回、mixin/protocol self 类型、动态属性、第三方 stub 缺口)后再修复。
修复优先级:优先用 isinstance()、if x is None、hasattr() 收窄联合类型;用局部变量帮助 ty 跨闭包追踪收窄;拆分中间类型为宽泛联合的链式调用;从源头修正错误注解;为未注解属性补充类型;对返回类型随输入变化的方法使用 @overload;让容器类泛型化;mixin 用 self 加 Protocol;对动态模块属性用 TypeGuard 函数;动态模型/配置属性用 getattr()/setattr();cast() 作最后手段,仅对第三方 stub 缺陷使用带具体错误码的 # type: ignore。
关键规则:禁止用 assert 做类型收窄(python -O 会剥离),应改为 if ...: raise;TypeGuard 必须直接用于 if 条件,且从 _typing 直接导入;不要用 getattr(torch, "backend") 访问动态设备后端;不要用条件继承,应注解 self;共享 Protocol 与类型别名放在 src/transformers/_typing.py,type-only 符号在 if TYPE_CHECKING 下导入,使用 from future import annotations。
验证:重跑同一目标的 ty check,重跑 make typing,必要时运行 make check-repo 并确保运行时行为不变、相关测试通过;新增类型检查区域时同步更新 Makefile 中的 ty_check_dirs。限制:资料未提供价格、平台与效果信息。