ruff/ty 类型检查器 shadowed-type-variable 诊断规则深度解析【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff导读本文围绕 ruff 仓库Astral 推出的 Rust 类型检查器 ty 所在的 monorepo中shadowed-type-variable这一类型诊断规则展开。它负责检测嵌套泛型类或泛型函数中内层类型变量与外层作用域已绑定的类型变量同名即遮蔽的写法。读完本文你将掌握该规则的触发场景、typing spec 依据、从源码到测试的全链路实现原理以及如何复现与规避此类错误。输出文章ruff/ty 类型检查器 shadowed-type-variable 诊断规则深度解析导读shadowed-type-variable是 ruff 仓库中 ty 类型检查器提供的一条静态诊断规则用于检测嵌套的泛型类或泛型函数中内层类型变量TypeVar / ParamSpec / TypeVarTuple遮蔽外层作用域已绑定类型变量的写法。这种写法会让代码含义变得混乱并被 typing spec 明确禁止。读完本文你将掌握该规则的完整触发场景、typing spec 依据、从诊断定义到推断器触发再到快照测试的源码级实现链路以及对应的修正方案。规则速览它做什么、为什么重要规则的核心行为可以用一句话概括来自规则文档检查嵌套泛型类或泛型函数中遮蔽了外层作用域类型变量的类型变量Checks for type variables in nested generic classes or functions that shadow type variables from an enclosing scope。其触发原因在文档中也有明确说明Shadowing type variables makes the code confusing and is disallowed by the typing spec即可读性风险同一个名字T在内层作用域被重新绑定为另一个含义不同的类型变量读者以及人类审阅者很难区分某个T到底指代哪个绑定规范禁止Python typing 官方规范typing spec 的 Generics 章节明确不允许嵌套作用域复用外层类型变量名。从 ty 源码中的规则注册信息crates/ty_python_semantic/src/types/diagnostic.rs#L1280-L1287可以看到更精确的元数据declare_lint! { #[doc include_str!(../../resources/lint_docs/shadowed-type-variable.md)] pub(crate) static SHADOWED_TYPE_VARIABLE { summary: detects type variables that shadow type variables from outer scopes, status: LintStatus::stable(0.0.20), default_level: Level::Error, } }要点解读字段值含义summarydetects type variables that shadow type variables from outer scopes一句话概括规则职责statusstable(0.0.20)自 ty 0.0.20 起作为稳定规则存在default_levelLevel::Error默认严重级别为 Error即默认配置下直接报错而非仅告警#[doc include_str!(...)]引入本文对应的 lint 文档规则文档与源码声明通过include_str!绑定保证文档与实现同源这也解释了为什么诊断信息以error[shadowed-type-variable]的形式呈现它本身就是一条默认级别的错误诊断。触发场景官方示例与边界情况官方最小示例规则文档给出的最小复现shadowed-type-variable.md[environment] python-version 3.12class Outer[T]: # T is already used by Outer class Inner[T]: ... # error # T is already used by Outer def methodT - T: # error return x这里有两种典型的违规形态泛型类嵌套泛型类Outer[T]内部再定义Inner[T]内层的T遮蔽了外层的T泛型类内定义泛型方法Outer[T]的方法method[T]再次使用T遮蔽类级类型变量。两种写法都会让T在内层作用域中名存实亡——表面上看起来像是同一个类型变量实际上内层已经是一个全新的、与外层无关的绑定。类中方法可用不同类型变量合法的对照写法是内层使用全新的名字class Outer[T]: class Inner[S]: ... # OKS 与外层 T 不同 def methodU - U: # OKU 与外层 T 不同 return x这一点在 crates/ty_python_semantic/resources/mdtest/generics/scoping.md 的快照测试中反复出现class Ok1[S]、def okS都是被允许的对照用例。函数嵌套函数同样触发规则不局限于类也覆盖嵌套函数场景def fT - None: def okS - None: ... # OK # error: [shadowed-type-variable] def badT - None: ...TypeVarTuple 与 ParamSpec 同样受检规则覆盖全部三类类型参数。ty 的测试中就有 TypeVarTuple 的复现scoping.mddef outer*Ts - None: def ok*Us - None: ... # OK # snapshot: shadowed-type-variable def bad*Ts - None: ...对应的快照输出为error[shadowed-type-variable]: Generic function bad uses TypeVarTuple Ts already bound by an enclosing scope -- src/mdtest_snippet.py:5:9 | 5 | def bad*Ts - None: ... | ^^^ Ts used in function definition here | ::: src/mdtest_snippet.py:1:5 | 1 | def outer*Ts - None: | ------------------------------ TypeVarTuple Ts is bound in this enclosing scopeParamSpec 的同类案例见 crates/ty_python_semantic/resources/mdtest/generics/legacy/classes.md诊断信息会明确写出uses ParamSpecPalready bound by an enclosing scope。基类中引用外层类型变量也会触发还有一种容易被忽略的形态嵌套泛型类在其基类列表中引用了外层已绑定的类型变量。快照测试 scoping.md 快照.snap) 中的用例from typing import Iterable class C[T]: class Ok1[S]: ... # error: [shadowed-type-variable] class Bad1[T]: ... # error: [shadowed-type-variable] class Bad2(Iterable[T]): ...注意Bad2(Iterable[T])内层类并没有声明类型参数但它的基类Iterable[T]引用了外层C的T。ty 会输出两条独立诊断分别指向Bad1[T]的声明位置和Bad2基类中T的使用位置说明该检查既针对显式重新声明也针对基类位置对同名类型变量的隐式引用。Legacy 语法typing.TypeVar同样受检该检查对 PEP 695 语法和 legacyTypeVar语法一视同仁。在 legacy/variables.md 的测试与快照 variables.md 快照.snap) 中用Q TypeVar(Q)定义的 legacy 类型变量同样会触发shadowed-type-variable诊断文案为Generic classBaduses type variableQalready bound by an enclosing scope。诊断信息解析如何读懂报错诊断报告由 crates/ty_python_semantic/src/types/diagnostic.rs#L4853-L4903 中的report_shadowed_type_variable函数生成其消息模板为Generic {kind} {name} uses {typevar_kind} {typevar_name} already bound by an enclosing scope模板中的参数来自触发场景kindclass或function指明违规的是嵌套泛型类还是泛型函数name该类/函数的名字如Bad1、badtypevar_kind按类型变量种类生成的称谓映射逻辑为LegacyTypeVar/Pep695TypeVar/TypingSelf/Pep613Alias→type variableLegacyParamSpec/Pep695ParamSpec→ParamSpecLegacyTypeVarTuple/Pep695TypeVarTuple→TypeVarTupletypevar_name发生遮蔽的类型变量名如T、P、Ts。诊断同时包含两类标注annotationprimary annotation指向内层定义中使用该名字的位置消息为{typevar_name} used in {kind} definition heresecondary annotation通过other_typevar回溯外层绑定定位外层类/函数的签名或类头消息为{other_typevar_kind} {typevar_name} is bound in this enclosing scope注意此处首字母大写如Type variable/ParamSpec/TypeVarTuple。因此快照中会看到这种上下呼应的排版——外层绑定点用-标记内层使用点用^标记读者可以一眼看清遮蔽链。源码实现诊断从哪里触发规则本身是一个检查点实际触发点分布在类型推断器infer的构建阶段按对象类型分为两处。泛型函数的检查在函数推断构建器 crates/ty_python_semantic/src/types/infer/builder/function.rs#L562-L587 中推断完函数字面量后立即执行// Check that the functions own type parameters dont shadow // type variables from enclosing scopes (by name). if let Some(type_params) function.type_params { let current_scope self.scope().file_scope_id(db); for type_param in type_params.iter() { let param_name type_param.name(); for enclosing in enclosing_generic_contexts(self.db(), self.index, current_scope) { if let Some(other_typevar) enclosing.binds_named_typevar(db, param_name.id) { let kind match type_param { ast::TypeParam::TypeVar(_) TypeVarKind::Pep695TypeVar, ast::TypeParam::ParamSpec(_) TypeVarKind::Pep695ParamSpec, ast::TypeParam::TypeVarTuple(_) TypeVarKind::Pep695TypeVarTuple, }; report_shadowed_type_variable( self.context, param_name.id, function, function.name.id, function.name.range(), kind, other_typevar, ); } } } }关键逻辑按名字匹配by name遍历函数声明的每个type_params对外层每个enclosing_generic_contexts(...)调用binds_named_typevar(db, name)判断外层是否已绑定同名类型变量类型参数三种形态TypeVar、ParamSpec、TypeVarTuple分别映射到对应的TypeVarKind并作为诊断的类型称谓一旦命中立即报告内层任意一个类型参数与外层任意一个泛型上下文中的类型变量同名即触发。泛型类的检查类级检查在后续推断阶段 crates/ty_python_semantic/src/types/infer/builder/post_inference/static_class.rs#L980-L1021逻辑分两轮// Check that the classs own type parameters dont shadow // type variables from enclosing scopes (by name). if let Some(generic_context) class.generic_context(db) { for self_typevar in generic_context.variables(db) { let name self_typevar.typevar(db).name(db); for enclosing in enclosing_generic_contexts(db, index, parent) { if let Some(other_typevar) enclosing.binds_named_typevar(db, name) { report_shadowed_type_variable( context, name, class, class_node.name.id, class.header_range(db), self_typevar.kind(db), other_typevar, ); } } } } // Check that the classs base classes dont reference type // variables from enclosing scopes (by identity). for base_typevar in class.typevars_referenced_in_bases(db) { let typevar base_typevar.typevar(db); for enclosing in enclosing_generic_contexts(db, index, parent) { if let Some(other_typevar) enclosing.binds_typevar(db, typevar) { report_shadowed_type_variable( context, typevar.name(db), class, class_node.name.id, class.header_range(db), base_typevar.kind(db), other_typevar, ); } } }两轮检查的分工恰好对应上文的两类触发形态按名字检查自身类型参数内层类声明的类型变量名与外层泛型上下文中的同名变量冲突对应class Bad1[T]按身份检查基类引用内层类基类中引用的类型变量在外层上下文已被绑定对应class Bad2(Iterable[T])——注意这里调用的是binds_typevar按变量身份而非binds_named_typevar按名字。整个过程的共同前提是enclosing_generic_contexts枚举所有外层泛型作用域因此任意层级泛型函数嵌套泛型类、泛型类嵌套泛型方法、泛型函数嵌套泛型函数等的遮蔽都会被覆盖与官方文档中 enclosing scope 的表述一致。测试体系快照如何验证行为ty 使用 mdtest 驱动测试源实现见 crates/mdtest/src/lib.rs在 Markdown 文档的代码块中内嵌# error: [shadowed-type-variable]或# snapshot: shadowed-type-variable指令由测试框架收集诊断并与.snap快照对比。相关测试资产分布在资产路径覆盖内容PEP 695 泛型类crates/ty_python_semantic/resources/mdtest/generics/pep695/classes.md类方法遮蔽类级类型变量PEP 695 泛型函数crates/ty_python_semantic/resources/mdtest/generics/pep695/functions.md嵌套函数遮蔽外层函数类型变量作用域规则专章crates/ty_python_semantic/resources/mdtest/generics/scoping.md函数套函数、TypeVarTuple、方法套类等组合场景Legacy 语法类crates/ty_python_semantic/resources/mdtest/generics/legacy/classes.mdTypeVar/ParamSpeclegacy 写法Legacy 类型变量crates/ty_python_semantic/resources/mdtest/generics/legacy/variables.mdlegacyTypeVar的遮蔽检查快照样例类中类crates/ty_python_semantic/resources/mdtest/snapshots/scoping.md_-Scoping_rules_for_ty…-Nested_formal_typeva…-Generic_class_within…(711fb86287c4d87b).snap.snap)含Bad1/Bad2(Iterable[T])的完整诊断排版快照样例函数中类crates/ty_python_semantic/resources/mdtest/snapshots/scoping.md_-Scoping_rules_for_ty…-Nested_formal_typeva…-Generic_function_wit…(f58a51442a16371e).snap.snap)泛型函数内嵌套泛型函数快照样例方法中类crates/ty_python_semantic/resources/mdtest/snapshots/scoping.md_-Scoping_rules_for_ty…-Nested_formal_typeva…-Generic_method_withi…(c19e9277cf9fafb5).snap.snap)泛型方法内嵌套泛型类快照样例legacy 遮蔽crates/ty_python_semantic/resources/mdtest/snapshots/variables.md_-Legacy_type_variable…-Type_variables-Shadowing_checks_use…(7e6bb178099059fe).snap.snap)legacyTypeVar的同名遮蔽以泛型类嵌套泛型类的快照为例完整快照.snap)可以看到完整诊断排版error[shadowed-type-variable]: Generic class Bad1 uses type variable T already bound by an enclosing scope -- src/mdtest_snippet.py:6:11 | 3 | class C[T]: | - Type variable T is bound in this enclosing scope 4 | class Ok1[S]: ... 5 | # error: [shadowed-type-variable] 6 | class Bad1[T]: ... | ^^^^ T used in class definition here同一快照还验证了Bad2(Iterable[T])的独立诊断其 primary 标注覆盖整个基类表达式Iterable[T]与源码中按身份检查基类引用的第二轮检查一一对应。修复建议与最佳实践触发该规则时最直接的修复是给内层作用域换一个语义独立的名字遵循一个作用域一个名字的原则# 反例触发 shadowed-type-variable class Outer[T]: class Inner[T]: ... # error def methodT: # error return x # 正例 class Outer[T]: class Inner[S]: ... # 内层类使用新名字 S def methodU - U: return x # 内层方法使用新名字 U同理适用于嵌套函数与 TypeVarTuple / ParamSpecdef outer*Ts - None: def bad*Ts - None: ... # error def good*Us - None: ... # OK在维护既有代码时可借助诊断中的 secondary annotation 快速定位外层绑定点确认冲突来源后重命名内层变量即可。由于该规则默认级别为Error见 diagnostic.rs 中default_level: Level::Error它属于需要主动修复的硬性错误而不是可忽略的提示。总结shadowed-type-variable是 ty 类型检查器中针对泛型作用域卫生scope hygiene的一条默认 Error 级诊断。它依据 typing spec 对嵌套泛型作用域的限制按名字检查类/函数自身声明的类型参数、按身份检查基类中的类型变量引用覆盖 PEP 695 与 legacy 两种语法以及 TypeVar / ParamSpec / TypeVarTuple 三类类型参数。从规则注册declare_lint!、触发点function.rs 与 static_class.rs、诊断排版report_shadowed_type_variable到 mdtest 快照scoping.md 及其.snap整条链路在仓库中完整可查方便开发者对照学习或在此基础上扩展新的泛型相关诊断。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考