Ruff Ty 类型系统解析Python 作用域中未绑定Unbound名称的推断规则与诊断【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 Ruff 仓库中 ty 类型检查器即ty_python_semanticcrate的 Markdown 驱动测试套件 unbound.md 为主体系统讲解 Python 各类作用域模块、类、函数中未绑定名称unbound name的语义类作用域属性回退规则、函数局部变量遮蔽全局、条件赋值产生的可能未绑定状态以及由此触发的unresolved-reference、possibly-missing-attribute两类诊断。读完本文你将能看懂 ty 类型检查器在名解析name resolution上的设计取舍理解reveal_type测试注释的写法并能把这些规则直接迁移到日常 Python 类型标注与静态检查实践中。背景mdtest 与reveal_type断言本仓库的 ty 类型检查器采用文档即测试literate testing的方式维护语义规范crates/ty_python_semantic/resources/mdtest/scopes/目录下的每个 Markdown 文件都是一个测试套件其中的py代码块会被写入内存文件系统并实际执行类型检查然后逐条匹配代码注释中的断言。测试入口见 crates/ty_python_semantic/tests/mdtest.rs它通过datatest_stable把resources/mdtest下所有.md文件注册为测试用例。断言共两类详见 crates/ty_test/README.md# revealed: 类型必须与reveal_type(...)诊断输出的类型展示完全一致例如# revealed: Literal[2]、# revealed: int、# revealed: Unknown# error: [规则码]断言该行会产生指定规则码的诊断可附加文本匹配# error: Some text或列号# error: 8 [rule-code]。运行全部 mdtest 的方式cargo test -p ty_python_semantic -- mdtest # 或使用带 watch 模式的 Python 运行器 uv run crates/ty_python_semantic/mdtest.pyunbound.md全文由 6 个测试组成完整覆盖了类作用域、全局作用域、函数局部作用域中的未绑定语义下面逐一展开。类作用域中的未绑定名称名称查找回退全局类属性不回退测试Unbound class variable展示了类作用域名解析的核心规则def coinflip() - bool: return True flag coinflip() x 1 class C: y x if flag: x 2 # error: [possibly-missing-attribute] Attribute x may be missing on class C reveal_type(C.x) # revealed: int reveal_type(C.y) # revealed: int这里同时演示了两条规则类体内的名称引用load会回退到全局作用域y x中的x在本类作用域尚未定义但模块顶层存在x 1因此直接解析为全局的int。这与 Python 运行时行为一致——类体执行时内部名称查找遵循 LEGBLocal、Enclosing、Global、Built-in规则。类属性的访问attribute access不会回退到全局C.x是对类C属性x的查找。由于x 2只在if flag:分支内执行flag 是动态布尔值检查器无法静态确认属性x是可能缺失的因此触发possibly-missing-attribute诊断。注意reveal_type(C.x)的类型仍然显示为int——即当绑定存在时的类型诊断只是提醒运行时可能抛AttributeError。从源码看possibly-missing-attribute的报告点位于 crates/ty_python_semantic/src/types/infer/builder.rs#L11017-L11022 的infer_attribute_expression路径当成员查找命中可能未定义PossiblyUndefined分支时先报告该诊断再返回type_when_bound绑定成立时的类型这一设计保证了报错但不中断类型推断。包围作用域中可能未绑定的变量被视为已绑定测试Possibly unbound in class and global scope说明当类体读取的变量在其包围作用域中只是可能未绑定时ty 会选择乐观处理不报未绑定错误def coinflip() - bool: return True if coinflip(): x abc class C: if coinflip(): x 1 # Possibly unbound variables in enclosing scopes are considered bound. y x reveal_type(C.y) # revealed: int | strx在模块顶层条件赋值为str在类体内又条件赋值为int。y x读取的x从两个来源合并推断为int | str联合类型。关键点是尽管两条赋值都是条件性的ty 仍将x视为已绑定只是把两种可能类型取并集。这与下一小节对比强烈——同样是条件赋值C.x的属性访问却会触发possibly-missing-attribute因为属性查找不存在回退到全局的兜底它关心的是属性集合本身是否完备。类内多分支声明仍可能缺失属性测试Possibly unbound in class scope with multiple declarations进一步确认即使类体内存在多个声明分支只要没有静态确定的分支必然执行属性访问依然报possibly-missing-attributedef coinflip() - bool: return True class C: if coinflip(): x: int 1 elif coinflip(): x: str abc # error: [possibly-missing-attribute] reveal_type(C.x) # revealed: int | str这里两个分支分别把x声明为int和str类型推断正常合并为int | strrevealed: int | str但任何一个分支都可能不执行因此属性x仍可能缺失诊断照发。注意本例中if ... elif是互斥分支int | str恰好是两个分支类型的并集——ty 的合并策略是保守的并集不尝试对分支互斥性做精细切分。函数局部作用域中的未绑定名称有定义的局部未绑定变量不回退全局测试Unbound function local演示了与类作用域相反的规则x 1 def f(): # error: [unresolved-reference] # revealed: Unknown reveal_type(x) x 2 # revealed: Literal[2] reveal_type(x)模块顶层有x 1但函数f内部存在x的绑定x 2。在 Python 语义中函数体内的赋值语句使整个函数作用域内的x都成为局部变量——即使读取发生在赋值之前。因此第一个reveal_type(x)读取的是尚未初始化的局部变量ty 报告unresolved-referenceNamexused when not defined类型为Unknown第二个reveal_type(x)读取赋值后的局部变量类型精确为Literal[2]模块顶层的x 1完全不参与解析因为局部绑定切断了与全局的联系。这正是局部遮蔽全局local shadowing在类型层面上的体现。诊断报告点位于 crates/ty_python_semantic/src/types/infer/builder.rs#L10306-L10315 的infer_name_load名解析返回LookupError::Undefined时调用report_unresolved_reference并回退为Type::unknown()避免级联报错。未导入reveal_type的便捷回退不覆盖未绑定局部变量测试Unbound function local named reveal_type是一处巧妙的边界测试def f(): reveal_type(1) # error: [unresolved-reference] reveal_type lambda value: valuety 为了测试便利把reveal_type伪装成内置函数见 crates/ty_test/README.md不导入直接使用会额外发出一条未导入即使用的提示诊断。但这里的reveal_type在函数体内被赋值reveal_type lambda value: value因此它成了局部未绑定变量。便捷回退只在名解析完全找不到该名称时生效绝不替代未绑定局部变量——所以reveal_type(1)报的是unresolved-reference而不是被当作内置函数解析。这一测试确保回退逻辑的优先级正确已存在哪怕未初始化的绑定优先于合成/内置回退。跨作用域行为的总结与设计启示结合unbound.md与同目录的 global.md、nonlocal.md可以把 ty 的未绑定规则归纳为一张对照表场景名称解析行为诊断类体内读取未定义名称回退到全局作用域无正常解析类属性访问但类内无必然赋值返回绑定存在时的类型possibly-missing-attribute包围作用域中的名称可能未绑定被类体读取取各可能类型并集视为已绑定无函数内存在绑定绑定前读取视为未初始化局部回退为Unknownunresolved-reference未导入的reveal_type遇上同名局部绑定不触发便捷回退unresolved-reference设计上的核心取舍值得注意回退方向相反类作用域的名称读取回退全局乐观函数作用域一旦存在局部绑定就彻底切断全局悲观报错。这忠实还原了 Python 语言本身的行为差异。可能未绑定不等于未绑定只要存在绑定来源哪怕条件性ty 就返回联合类型而非Unknown只有完全找不到绑定来源时才报unresolved-reference。这避免了大量级联错误——assignment/unbound.md 中的x foo示例明确说明当根因是未绑定的foo时对x不再重复报错x仅推断为Unknown这是宁可保守、避免噪音的策略。诊断与推断解耦possibly-missing-attribute与unresolved-reference都遵循报告错误但继续返回可用类型的模式使检查器在报错的同时仍能完成后续的类型传播。若想深入了解相关语义可继续阅读同目录的 class_implicit_attrs.md类隐式属性、dunder_class.mddunder 名称、annotate_global.md全局名称的注解以及global/nonlocal关键字对未绑定判定影响的完整测试套件。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ruff Ty 类型系统解析：Python 作用域中未绑定（Unbound）名称的推断规则与诊断
Ruff Ty 类型系统解析Python 作用域中未绑定Unbound名称的推断规则与诊断【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 Ruff 仓库中 ty 类型检查器即ty_python_semanticcrate的 Markdown 驱动测试套件 unbound.md 为主体系统讲解 Python 各类作用域模块、类、函数中未绑定名称unbound name的语义类作用域属性回退规则、函数局部变量遮蔽全局、条件赋值产生的可能未绑定状态以及由此触发的unresolved-reference、possibly-missing-attribute两类诊断。读完本文你将能看懂 ty 类型检查器在名解析name resolution上的设计取舍理解reveal_type测试注释的写法并能把这些规则直接迁移到日常 Python 类型标注与静态检查实践中。背景mdtest 与reveal_type断言本仓库的 ty 类型检查器采用文档即测试literate testing的方式维护语义规范crates/ty_python_semantic/resources/mdtest/scopes/目录下的每个 Markdown 文件都是一个测试套件其中的py代码块会被写入内存文件系统并实际执行类型检查然后逐条匹配代码注释中的断言。测试入口见 crates/ty_python_semantic/tests/mdtest.rs它通过datatest_stable把resources/mdtest下所有.md文件注册为测试用例。断言共两类详见 crates/ty_test/README.md# revealed: 类型必须与reveal_type(...)诊断输出的类型展示完全一致例如# revealed: Literal[2]、# revealed: int、# revealed: Unknown# error: [规则码]断言该行会产生指定规则码的诊断可附加文本匹配# error: Some text或列号# error: 8 [rule-code]。运行全部 mdtest 的方式cargo test -p ty_python_semantic -- mdtest # 或使用带 watch 模式的 Python 运行器 uv run crates/ty_python_semantic/mdtest.pyunbound.md全文由 6 个测试组成完整覆盖了类作用域、全局作用域、函数局部作用域中的未绑定语义下面逐一展开。类作用域中的未绑定名称名称查找回退全局类属性不回退测试Unbound class variable展示了类作用域名解析的核心规则def coinflip() - bool: return True flag coinflip() x 1 class C: y x if flag: x 2 # error: [possibly-missing-attribute] Attribute x may be missing on class C reveal_type(C.x) # revealed: int reveal_type(C.y) # revealed: int这里同时演示了两条规则类体内的名称引用load会回退到全局作用域y x中的x在本类作用域尚未定义但模块顶层存在x 1因此直接解析为全局的int。这与 Python 运行时行为一致——类体执行时内部名称查找遵循 LEGBLocal、Enclosing、Global、Built-in规则。类属性的访问attribute access不会回退到全局C.x是对类C属性x的查找。由于x 2只在if flag:分支内执行flag 是动态布尔值检查器无法静态确认属性x是可能缺失的因此触发possibly-missing-attribute诊断。注意reveal_type(C.x)的类型仍然显示为int——即当绑定存在时的类型诊断只是提醒运行时可能抛AttributeError。从源码看possibly-missing-attribute的报告点位于 crates/ty_python_semantic/src/types/infer/builder.rs#L11017-L11022 的infer_attribute_expression路径当成员查找命中可能未定义PossiblyUndefined分支时先报告该诊断再返回type_when_bound绑定成立时的类型这一设计保证了报错但不中断类型推断。包围作用域中可能未绑定的变量被视为已绑定测试Possibly unbound in class and global scope说明当类体读取的变量在其包围作用域中只是可能未绑定时ty 会选择乐观处理不报未绑定错误def coinflip() - bool: return True if coinflip(): x abc class C: if coinflip(): x 1 # Possibly unbound variables in enclosing scopes are considered bound. y x reveal_type(C.y) # revealed: int | strx在模块顶层条件赋值为str在类体内又条件赋值为int。y x读取的x从两个来源合并推断为int | str联合类型。关键点是尽管两条赋值都是条件性的ty 仍将x视为已绑定只是把两种可能类型取并集。这与下一小节对比强烈——同样是条件赋值C.x的属性访问却会触发possibly-missing-attribute因为属性查找不存在回退到全局的兜底它关心的是属性集合本身是否完备。类内多分支声明仍可能缺失属性测试Possibly unbound in class scope with multiple declarations进一步确认即使类体内存在多个声明分支只要没有静态确定的分支必然执行属性访问依然报possibly-missing-attributedef coinflip() - bool: return True class C: if coinflip(): x: int 1 elif coinflip(): x: str abc # error: [possibly-missing-attribute] reveal_type(C.x) # revealed: int | str这里两个分支分别把x声明为int和str类型推断正常合并为int | strrevealed: int | str但任何一个分支都可能不执行因此属性x仍可能缺失诊断照发。注意本例中if ... elif是互斥分支int | str恰好是两个分支类型的并集——ty 的合并策略是保守的并集不尝试对分支互斥性做精细切分。函数局部作用域中的未绑定名称有定义的局部未绑定变量不回退全局测试Unbound function local演示了与类作用域相反的规则x 1 def f(): # error: [unresolved-reference] # revealed: Unknown reveal_type(x) x 2 # revealed: Literal[2] reveal_type(x)模块顶层有x 1但函数f内部存在x的绑定x 2。在 Python 语义中函数体内的赋值语句使整个函数作用域内的x都成为局部变量——即使读取发生在赋值之前。因此第一个reveal_type(x)读取的是尚未初始化的局部变量ty 报告unresolved-referenceNamexused when not defined类型为Unknown第二个reveal_type(x)读取赋值后的局部变量类型精确为Literal[2]模块顶层的x 1完全不参与解析因为局部绑定切断了与全局的联系。这正是局部遮蔽全局local shadowing在类型层面上的体现。诊断报告点位于 crates/ty_python_semantic/src/types/infer/builder.rs#L10306-L10315 的infer_name_load名解析返回LookupError::Undefined时调用report_unresolved_reference并回退为Type::unknown()避免级联报错。未导入reveal_type的便捷回退不覆盖未绑定局部变量测试Unbound function local named reveal_type是一处巧妙的边界测试def f(): reveal_type(1) # error: [unresolved-reference] reveal_type lambda value: valuety 为了测试便利把reveal_type伪装成内置函数见 crates/ty_test/README.md不导入直接使用会额外发出一条未导入即使用的提示诊断。但这里的reveal_type在函数体内被赋值reveal_type lambda value: value因此它成了局部未绑定变量。便捷回退只在名解析完全找不到该名称时生效绝不替代未绑定局部变量——所以reveal_type(1)报的是unresolved-reference而不是被当作内置函数解析。这一测试确保回退逻辑的优先级正确已存在哪怕未初始化的绑定优先于合成/内置回退。跨作用域行为的总结与设计启示结合unbound.md与同目录的 global.md、nonlocal.md可以把 ty 的未绑定规则归纳为一张对照表场景名称解析行为诊断类体内读取未定义名称回退到全局作用域无正常解析类属性访问但类内无必然赋值返回绑定存在时的类型possibly-missing-attribute包围作用域中的名称可能未绑定被类体读取取各可能类型并集视为已绑定无函数内存在绑定绑定前读取视为未初始化局部回退为Unknownunresolved-reference未导入的reveal_type遇上同名局部绑定不触发便捷回退unresolved-reference设计上的核心取舍值得注意回退方向相反类作用域的名称读取回退全局乐观函数作用域一旦存在局部绑定就彻底切断全局悲观报错。这忠实还原了 Python 语言本身的行为差异。可能未绑定不等于未绑定只要存在绑定来源哪怕条件性ty 就返回联合类型而非Unknown只有完全找不到绑定来源时才报unresolved-reference。这避免了大量级联错误——assignment/unbound.md 中的x foo示例明确说明当根因是未绑定的foo时对x不再重复报错x仅推断为Unknown这是宁可保守、避免噪音的策略。诊断与推断解耦possibly-missing-attribute与unresolved-reference都遵循报告错误但继续返回可用类型的模式使检查器在报错的同时仍能完成后续的类型传播。若想深入了解相关语义可继续阅读同目录的 class_implicit_attrs.md类隐式属性、dunder_class.mddunder 名称、annotate_global.md全局名称的注解以及global/nonlocal关键字对未绑定判定影响的完整测试套件。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考