Ruff 类型检查器 ty 中的reveal_type类型揭示机制与undefined-reveal修复决策全解【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文围绕 Ruff 仓库中ty类型检查器的 mdtest 测试文档 reveal_type.md 展开系统讲解reveal_type在 ty 中的工作方式从基础用法、免导入的便捷回退机制到undefined-reveal警告在不同 Python 版本、依赖声明、运行时模块状态下给出或不给出自动导入修复的完整决策逻辑并结合ty_python_semantic的源码实现印证每个行为背后的判断条件。读完本文你将能够准确解释 ty 为何、在何种环境下为未导入的reveal_type提供from typing import reveal_type或from typing_extensions import reveal_type的修复建议并理解其修复为何被标记为“unsafe fix”。一、reveal_type的定位与基本用法reveal_type用于在代码的某个位置检查一个表达式的推断类型常用于调试和理解类型检查器如何推断类型out-of-band 调试辅助不参与业务逻辑。ty 的 mdtest 文档以如下环境声明为前提Python 3.11[environment] python-version 3.111.1 标准导入用法最直接的方式是从typing_extensions3.11 也可从typing导入后调用用行内# revealed:注释断言揭示结果from typing_extensions import reveal_type reveal_type(1) # revealed: Literal[1]使用全限定名同样有效import typing_extensions typing_extensions.reveal_type(1) # revealed: Literal[1]1.2 返回值即参数类型reveal_type的返回类型就是其参数类型因此可以用assert_type验证其透传行为from typing_extensions import assert_type def _(x: int): y reveal_type(x) # revealed: int assert_type(y, int)从源码看reveal_type揭示本身是一条独立诊断report_revealed_type在 function.rs 中以DiagnosticId::RevealedType、Severity::Info上报并把首个实参的类型显示revealed_type.display(db, env).preserve_long_unions()作为主标注附加到实参 span 上。ty 的 mdtest 断言机制中# revealed: X注释正是用来匹配这条revealed-type信息而# error: [revealed-type] X则只匹配该诊断本身——两者差异在“TYPE_CHECKING块”一节中会被专门利用。二、免导入回退undefined-reveal警告2.1 行为定义ty 允许在不导入reveal_type的情况下直接调用它——即便这样在运行时必然抛出NameError。类型检查器会照常揭示类型但额外发出一条undefined-reveal警告在满足条件时该诊断还会附带一条把导入语句加进文件的修复。该 lint 的元数据声明在 diagnostic.rs自0.0.1-alpha.1起处于 stable 状态默认级别为Warn其面向用户的文档即 undefined-reveal.md指出核心风险是运行时NameError。最小示例Python 3.11 环境# snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]ty 输出的诊断形如warning[undefined-reveal]: reveal_type used without importing it -- src/mdtest_snippet.py:2:1 | 2 | reveal_type(1) # error: [revealed-type] Literal[1] | ^^^^^^^^^^^ info: This is allowed for debugging convenience but will fail at runtime help: Import reveal_type from typing | 1 | # snapshot: undefined-reveal 2 from typing import reveal_type 3 | reveal_type(1) # error: [revealed-type] Literal[1] | note: This is an unsafe fix and may change runtime behavior2.2 回退在源码中的位置回退逻辑集中在类型推断器 builder.rs 的infer_unimported_reveal_type_fallback当一个裸名字表达式在常规查找中NotFound时推断器尝试该回退——仅当名字恰好是reveal_type时才返回typing_extensions模块中reveal_type符号的Place经 place.rs 的typing_extensions_symbol查询从而让调用“看起来”解析成功、揭示照常进行。关键在于上报条件同文件 L10486-L10488if !self.in_stub() !self.is_in_type_checking_block(self.scope(), name) { report_undefined_reveal(self.context, name); }即只有既不在 stub 文件、也不在TYPE_CHECKING块内时才发undefined-reveal警告——这与后文“在类型检查块中”“在 stub 文件中”两节的行为一一对应因为这两种位置不存在运行时失败风险。2.3 修复建议的生成report_undefined_revealdiagnostic.rs在发出诊断后调用typing_module_for_fix(context, reveal_type, PythonVersion::PY311)决定修复来源模块一旦确定模块就通过 importer 生成一条强制from ... import reveal_type形式的导入编辑源码注释说明因为reveal_type当前未绑定强制from导入可以避免引入一个可能被遮蔽的模块名也避免在发诊断期间触发额外的类型推断查询。修复被登记为Fix::unsafe_edit——因为它会改变运行时行为从NameError变为可运行所以诊断附带 “This is an unsafe fix and may change runtime behavior” 的 note。三、导入修复的来源模块如何决策typing_module_for_fixdiagnostic.rs是理解整份文档所有场景分支的钥匙其判断顺序为版本阈值目标版本 ≥ 3.11 时选typing标准库原生提供reveal_type否则选typing_extensions模块可解析且是“已知模块”用SemanticModel::resolve_module解析该模块解析结果必须真正对应标准库/typing_extensions本体resolved.is_known(db, module)本地同名模块遮蔽时会失败直接依赖检查仅typing_extensions分支当前文件所属项目必须直接声明了对应发行版的依赖is_direct_dependency间接依赖父项目声明、传递依赖不满足运行时导出检查仅typing_extensions分支用resolve_real_shadowable_module找到真实的运行时模块而非 typeshed 捆绑 stub再用imported_symbol(...).place.is_definitely_bound()确认该安装的版本实际导出了reveal_type。源码注释直接点破原因“捆绑 stub 可能导出已安装 backport 并不提供的成员仅凭依赖声明不足以支撑运行时导入”。文档中也专门解释了第 4 点的背景Typeshed 中typing_extensions的 stub 在这里并不可信——它错误地声称typing_extensions.reveal_type一直存在。四、场景逐一对照修复何时出现、何时被拒绝以下所有场景均出自 reveal_type.md环境配置中的[dependency-metadata]是 mdtest 用来模拟真实项目依赖关系发行版、模块归属、依赖分组等的测试装置。4.1 Python 3.10、无依赖元数据[environment] python-version 3.10# snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]3.10 下reveal_type必须来自typing_extensions没有依赖元数据就无法建立“项目直接依赖typing_extensions”这一事实因此诊断只有警告、没有 help/fixwarning[undefined-reveal]: reveal_type used without importing it -- src/mdtest_snippet.py:2:1 | 2 | reveal_type(1) # error: [revealed-type] Literal[1] | ^^^^^^^^^^^ info: This is allowed for debugging convenience but will fail at runtime4.2 Python 3.10 直接依赖typing_extensions环境声明为“直接依赖”的最小完整配置[environment] python-version 3.10 python /.venv [dependency-metadata] projects [{ path /src, dependencies [extensions] }] [dependency-metadata.distributions] extensions { name typing-extensions } [dependency-metadata.module-owners] typing_extensions [extensions]运行时可用当 venv 的 site-packages 中的typing_extensions.py确实定义了该函数# /.venv/path-to-site-packages/typing_extensions.py def reveal_type(value): return valuemain.py# snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]诊断给出help: Import reveal_type from typing_extensions修复文本为from typing_extensions import reveal_type并带 unsafe fix note对应上面 4 步决策全部通过。过旧的运行时模块若已安装的typing_extensions.py中没有reveal_type即使它被声明为直接依赖、且 typeshed 捆绑 stub 里“有”这个函数则不满足运行时导出检查决策第 4 步不提供任何导入修复诊断只剩 warning info。运行时模块缺失仅声明依赖并不证明库已安装当 site-packages 中没有typing_extensions运行时源码、只有 typeshed stub 可用时同样不提供修复。这印证了源码中“依赖声明 stub 导出”不能替代“真实运行时模块确实导出成员”的双重校验。4.3 间接依赖父项目的声明不覆盖嵌套项目[environment] python-version 3.10 python /.venv [dependency-metadata] projects [ { path /src, dependencies [extensions] }, { path /src/member, dependencies [] }, ] [dependency-metadata.distributions] extensions { name typing-extensions } [dependency-metadata.module-owners] typing_extensions [extensions]即使 venv 里的typing_extensions提供reveal_type嵌套项目/src/member自身没有声明依赖member/main.py中的reveal_type(1)就不会得到修复——“父项目的依赖声明不适用于嵌套项目”。这解释了源码中is_direct_dependency(db, context.program_file(), resolved)以“当前文件所属项目”为判定主体。4.4 依赖分组dependency group包代码与测试文件的差异[environment] python-version 3.10 python /.venv [dependency-metadata] projects [{ path /src, distribution app, group-dependencies [extensions] }] [dependency-metadata.distributions] app { name app, editable-path /src } extensions { name typing-extensions } [dependency-metadata.module-owners] app [app] typing_extensions [extensions]规则是安装在被发行包之外的文件可以使用依赖分组带来的直接依赖而包代码本身不能依赖这些分组。于是app/__init__.py包代码editable-path 即/src中的reveal_type(1)无修复仅 warningtests/test_app.py包外测试文件中的reveal_type(1)给出from typing_extensions import reveal_type的修复unsafe fix note 附后。两个文件用同一个# snapshot: undefined-reveal名称各断言一次分别锁定两种输出形态。4.5 本地模块遮蔽typing_extensions[environment] python-version 3.10 python /.venv [dependency-metadata] projects [{ path /src, dependencies [extensions] }] [dependency-metadata.distributions] extensions { name typing-extensions } [dependency-metadata.module-owners] typing_extensions [extensions]venv 里typing_extensions正常提供reveal_type但项目根目录还有一个本地空的typing_extensions.py遮蔽了它。此时即使类型检查使用捆绑 stubfrom typing_extensions import reveal_type在运行时命中的是本地空模块导入必然失败——决策第 2/4 步失败不提供修复。文档同时点明语义声明依赖并不等于“导入能真正到达它”。4.6 被参数遮蔽的导入别名from typing import reveal_type as reveal def f(reveal: int): # snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]导入的别名reveal被函数参数遮蔽后裸reveal_type仍未绑定回退机制照常工作并给出警告但诊断不会提议“用被遮蔽的别名替换reveal_type”即不输出任何把reveal_type改写成reveal(...)的建议因为那只会生成运行时同样失败的代码。诊断仅有 warning info无 help。五、特殊代码位置TYPE_CHECKING块、stub 文件与不可达代码5.1TYPE_CHECKING块中不报undefined-revealTYPE_CHECKING块内的代码运行时永不执行未导入的reveal_type在那里不可能引发NameError因此警告被抑制from typing import TYPE_CHECKING import typing if TYPE_CHECKING: reveal_type(1) # error: [revealed-type] Literal[1] def nested() - None: reveal_type(nested) # error: [revealed-type] nested if typing.TYPE_CHECKING: reveal_type(True) # error: [revealed-type] Literal[True]注意typing.TYPE_CHECKING这种属性访问形式同样被识别。测试文档此处刻意使用# error: [revealed-type]断言而非# revealed:断言并给出了精确理由# revealed:断言在核对揭示类型的同时会吞掉undefined-reveal错误而# error: [revealed-type]不会顺带匹配undefined-reveal——这样一旦出现意外的undefined-reveal警告测试会直接失败。这与源码中if !self.in_stub() !self.is_in_type_checking_block(...)的门控条件互为印证。5.2 stub 文件中不报undefined-reveal.pyi文件永不执行同理不警告reveal_type(1) # error: [revealed-type] Literal[1]这里同样用# error: [revealed-type]而非# revealed:断言确保意外的undefined-reveal不会被静默吞掉。5.3 不可达代码中仍然有效reveal_type在静态判定为不可达的分支如if False:、if 1 1 ! 2:中也能工作导入与否两种情形均如此from typing_extensions import reveal_type import typing_extensions if False: reveal_type(1) # revealed: Literal[1] typing_extensions.reveal_type(1) # revealed: Literal[1] if 1 1 ! 2: reveal_type(1) # revealed: Literal[1] typing_extensions.reveal_type(1) # revealed: Literal[1]未导入版本if False: reveal_type(1) # revealed: Literal[1] if 1 1 ! 2: reveal_type(1) # revealed: Literal[1]这条能力在源码中有专门处理不可达区域内推断器会把外部定义的符号推断为Never从而让常规调用链走不到揭示逻辑builder.rs 因此加了一个特判——当调用结果类型为Type::Never时直接按名字reveal_type或xxx.reveal_type点路径识别该调用是typing.reveal_type然后照常对首参执行report_revealed_type。六、验证方式与相关测试上述 mdtest 文档由仓库内的 mdtest 框架crates/mdtest驱动执行文档中的[environment]/[dependency-metadata]TOML 块构造临时项目环境# revealed:、# error: [revealed-type]注释与# snapshot:块分别驱动行内断言与快照比对reveal_type.md的每条行为包括“不给修复”的场景都是被持续回归的。除文档测试外ty_python_semantic还有专门的单元测试覆盖修复的健壮性tests.rs 的undefined_reveal_fix_updates_after_source_changes验证在修改导入与行尾风格后重新检查同一文件undefined-reveal修复仍能正确更新对两条reveal_type各产出单一导入编辑。此外LSP 侧的行为也有端到端快照佐证例如 code_action_undefined_reveal.snap 展示了 IDE 中该修复作为 code action 的呈现importer 一侧的 API 文档importer.rs也明确以undefined-reveal诊断为前提来描述其导入生成接口。七、小结场景undefined-reveal警告导入修复修复来源已导入reveal_type无——3.11、未导入有有typing3.10、无依赖元数据有无—3.10、直接依赖且运行时导出reveal_type有有typing_extensions3.10、直接依赖但运行时模块过旧/缺失有无—3.10、仅间接依赖父项目声明有无—3.10、依赖分组包外测试文件有有typing_extensions3.10、依赖分组包代码有无—3.10、本地模块遮蔽typing_extensions有无—别名被参数遮蔽有不提议改写为别名无—TYPE_CHECKING块内 /.pyi文件无——不可达代码依上述规则依上述规则揭示仍正常发出可以总结为三条主线其一reveal_type的揭示能力与导入状态解耦——ty 通过未导入回退typing_extensions.reveal_type符号 不可达代码特判保证揭示在任何位置可用其二修复建议以“运行时真的能跑通”为唯一标准版本、依赖归属、运行时导出三层校验层层收窄其三警告本身只对“运行时可能执行”的位置生效非 stub、非TYPE_CHECKING块。理解这套机制后你既能正确使用reveal_type调试类型推断也能预期 ty 在不同工程结构下给出的修复行为。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ruff 类型检查器 ty 中的 `reveal_type`：类型揭示机制与 `undefined-reveal` 修复决策全解
Ruff 类型检查器 ty 中的reveal_type类型揭示机制与undefined-reveal修复决策全解【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文围绕 Ruff 仓库中ty类型检查器的 mdtest 测试文档 reveal_type.md 展开系统讲解reveal_type在 ty 中的工作方式从基础用法、免导入的便捷回退机制到undefined-reveal警告在不同 Python 版本、依赖声明、运行时模块状态下给出或不给出自动导入修复的完整决策逻辑并结合ty_python_semantic的源码实现印证每个行为背后的判断条件。读完本文你将能够准确解释 ty 为何、在何种环境下为未导入的reveal_type提供from typing import reveal_type或from typing_extensions import reveal_type的修复建议并理解其修复为何被标记为“unsafe fix”。一、reveal_type的定位与基本用法reveal_type用于在代码的某个位置检查一个表达式的推断类型常用于调试和理解类型检查器如何推断类型out-of-band 调试辅助不参与业务逻辑。ty 的 mdtest 文档以如下环境声明为前提Python 3.11[environment] python-version 3.111.1 标准导入用法最直接的方式是从typing_extensions3.11 也可从typing导入后调用用行内# revealed:注释断言揭示结果from typing_extensions import reveal_type reveal_type(1) # revealed: Literal[1]使用全限定名同样有效import typing_extensions typing_extensions.reveal_type(1) # revealed: Literal[1]1.2 返回值即参数类型reveal_type的返回类型就是其参数类型因此可以用assert_type验证其透传行为from typing_extensions import assert_type def _(x: int): y reveal_type(x) # revealed: int assert_type(y, int)从源码看reveal_type揭示本身是一条独立诊断report_revealed_type在 function.rs 中以DiagnosticId::RevealedType、Severity::Info上报并把首个实参的类型显示revealed_type.display(db, env).preserve_long_unions()作为主标注附加到实参 span 上。ty 的 mdtest 断言机制中# revealed: X注释正是用来匹配这条revealed-type信息而# error: [revealed-type] X则只匹配该诊断本身——两者差异在“TYPE_CHECKING块”一节中会被专门利用。二、免导入回退undefined-reveal警告2.1 行为定义ty 允许在不导入reveal_type的情况下直接调用它——即便这样在运行时必然抛出NameError。类型检查器会照常揭示类型但额外发出一条undefined-reveal警告在满足条件时该诊断还会附带一条把导入语句加进文件的修复。该 lint 的元数据声明在 diagnostic.rs自0.0.1-alpha.1起处于 stable 状态默认级别为Warn其面向用户的文档即 undefined-reveal.md指出核心风险是运行时NameError。最小示例Python 3.11 环境# snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]ty 输出的诊断形如warning[undefined-reveal]: reveal_type used without importing it -- src/mdtest_snippet.py:2:1 | 2 | reveal_type(1) # error: [revealed-type] Literal[1] | ^^^^^^^^^^^ info: This is allowed for debugging convenience but will fail at runtime help: Import reveal_type from typing | 1 | # snapshot: undefined-reveal 2 from typing import reveal_type 3 | reveal_type(1) # error: [revealed-type] Literal[1] | note: This is an unsafe fix and may change runtime behavior2.2 回退在源码中的位置回退逻辑集中在类型推断器 builder.rs 的infer_unimported_reveal_type_fallback当一个裸名字表达式在常规查找中NotFound时推断器尝试该回退——仅当名字恰好是reveal_type时才返回typing_extensions模块中reveal_type符号的Place经 place.rs 的typing_extensions_symbol查询从而让调用“看起来”解析成功、揭示照常进行。关键在于上报条件同文件 L10486-L10488if !self.in_stub() !self.is_in_type_checking_block(self.scope(), name) { report_undefined_reveal(self.context, name); }即只有既不在 stub 文件、也不在TYPE_CHECKING块内时才发undefined-reveal警告——这与后文“在类型检查块中”“在 stub 文件中”两节的行为一一对应因为这两种位置不存在运行时失败风险。2.3 修复建议的生成report_undefined_revealdiagnostic.rs在发出诊断后调用typing_module_for_fix(context, reveal_type, PythonVersion::PY311)决定修复来源模块一旦确定模块就通过 importer 生成一条强制from ... import reveal_type形式的导入编辑源码注释说明因为reveal_type当前未绑定强制from导入可以避免引入一个可能被遮蔽的模块名也避免在发诊断期间触发额外的类型推断查询。修复被登记为Fix::unsafe_edit——因为它会改变运行时行为从NameError变为可运行所以诊断附带 “This is an unsafe fix and may change runtime behavior” 的 note。三、导入修复的来源模块如何决策typing_module_for_fixdiagnostic.rs是理解整份文档所有场景分支的钥匙其判断顺序为版本阈值目标版本 ≥ 3.11 时选typing标准库原生提供reveal_type否则选typing_extensions模块可解析且是“已知模块”用SemanticModel::resolve_module解析该模块解析结果必须真正对应标准库/typing_extensions本体resolved.is_known(db, module)本地同名模块遮蔽时会失败直接依赖检查仅typing_extensions分支当前文件所属项目必须直接声明了对应发行版的依赖is_direct_dependency间接依赖父项目声明、传递依赖不满足运行时导出检查仅typing_extensions分支用resolve_real_shadowable_module找到真实的运行时模块而非 typeshed 捆绑 stub再用imported_symbol(...).place.is_definitely_bound()确认该安装的版本实际导出了reveal_type。源码注释直接点破原因“捆绑 stub 可能导出已安装 backport 并不提供的成员仅凭依赖声明不足以支撑运行时导入”。文档中也专门解释了第 4 点的背景Typeshed 中typing_extensions的 stub 在这里并不可信——它错误地声称typing_extensions.reveal_type一直存在。四、场景逐一对照修复何时出现、何时被拒绝以下所有场景均出自 reveal_type.md环境配置中的[dependency-metadata]是 mdtest 用来模拟真实项目依赖关系发行版、模块归属、依赖分组等的测试装置。4.1 Python 3.10、无依赖元数据[environment] python-version 3.10# snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]3.10 下reveal_type必须来自typing_extensions没有依赖元数据就无法建立“项目直接依赖typing_extensions”这一事实因此诊断只有警告、没有 help/fixwarning[undefined-reveal]: reveal_type used without importing it -- src/mdtest_snippet.py:2:1 | 2 | reveal_type(1) # error: [revealed-type] Literal[1] | ^^^^^^^^^^^ info: This is allowed for debugging convenience but will fail at runtime4.2 Python 3.10 直接依赖typing_extensions环境声明为“直接依赖”的最小完整配置[environment] python-version 3.10 python /.venv [dependency-metadata] projects [{ path /src, dependencies [extensions] }] [dependency-metadata.distributions] extensions { name typing-extensions } [dependency-metadata.module-owners] typing_extensions [extensions]运行时可用当 venv 的 site-packages 中的typing_extensions.py确实定义了该函数# /.venv/path-to-site-packages/typing_extensions.py def reveal_type(value): return valuemain.py# snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]诊断给出help: Import reveal_type from typing_extensions修复文本为from typing_extensions import reveal_type并带 unsafe fix note对应上面 4 步决策全部通过。过旧的运行时模块若已安装的typing_extensions.py中没有reveal_type即使它被声明为直接依赖、且 typeshed 捆绑 stub 里“有”这个函数则不满足运行时导出检查决策第 4 步不提供任何导入修复诊断只剩 warning info。运行时模块缺失仅声明依赖并不证明库已安装当 site-packages 中没有typing_extensions运行时源码、只有 typeshed stub 可用时同样不提供修复。这印证了源码中“依赖声明 stub 导出”不能替代“真实运行时模块确实导出成员”的双重校验。4.3 间接依赖父项目的声明不覆盖嵌套项目[environment] python-version 3.10 python /.venv [dependency-metadata] projects [ { path /src, dependencies [extensions] }, { path /src/member, dependencies [] }, ] [dependency-metadata.distributions] extensions { name typing-extensions } [dependency-metadata.module-owners] typing_extensions [extensions]即使 venv 里的typing_extensions提供reveal_type嵌套项目/src/member自身没有声明依赖member/main.py中的reveal_type(1)就不会得到修复——“父项目的依赖声明不适用于嵌套项目”。这解释了源码中is_direct_dependency(db, context.program_file(), resolved)以“当前文件所属项目”为判定主体。4.4 依赖分组dependency group包代码与测试文件的差异[environment] python-version 3.10 python /.venv [dependency-metadata] projects [{ path /src, distribution app, group-dependencies [extensions] }] [dependency-metadata.distributions] app { name app, editable-path /src } extensions { name typing-extensions } [dependency-metadata.module-owners] app [app] typing_extensions [extensions]规则是安装在被发行包之外的文件可以使用依赖分组带来的直接依赖而包代码本身不能依赖这些分组。于是app/__init__.py包代码editable-path 即/src中的reveal_type(1)无修复仅 warningtests/test_app.py包外测试文件中的reveal_type(1)给出from typing_extensions import reveal_type的修复unsafe fix note 附后。两个文件用同一个# snapshot: undefined-reveal名称各断言一次分别锁定两种输出形态。4.5 本地模块遮蔽typing_extensions[environment] python-version 3.10 python /.venv [dependency-metadata] projects [{ path /src, dependencies [extensions] }] [dependency-metadata.distributions] extensions { name typing-extensions } [dependency-metadata.module-owners] typing_extensions [extensions]venv 里typing_extensions正常提供reveal_type但项目根目录还有一个本地空的typing_extensions.py遮蔽了它。此时即使类型检查使用捆绑 stubfrom typing_extensions import reveal_type在运行时命中的是本地空模块导入必然失败——决策第 2/4 步失败不提供修复。文档同时点明语义声明依赖并不等于“导入能真正到达它”。4.6 被参数遮蔽的导入别名from typing import reveal_type as reveal def f(reveal: int): # snapshot: undefined-reveal reveal_type(1) # error: [revealed-type] Literal[1]导入的别名reveal被函数参数遮蔽后裸reveal_type仍未绑定回退机制照常工作并给出警告但诊断不会提议“用被遮蔽的别名替换reveal_type”即不输出任何把reveal_type改写成reveal(...)的建议因为那只会生成运行时同样失败的代码。诊断仅有 warning info无 help。五、特殊代码位置TYPE_CHECKING块、stub 文件与不可达代码5.1TYPE_CHECKING块中不报undefined-revealTYPE_CHECKING块内的代码运行时永不执行未导入的reveal_type在那里不可能引发NameError因此警告被抑制from typing import TYPE_CHECKING import typing if TYPE_CHECKING: reveal_type(1) # error: [revealed-type] Literal[1] def nested() - None: reveal_type(nested) # error: [revealed-type] nested if typing.TYPE_CHECKING: reveal_type(True) # error: [revealed-type] Literal[True]注意typing.TYPE_CHECKING这种属性访问形式同样被识别。测试文档此处刻意使用# error: [revealed-type]断言而非# revealed:断言并给出了精确理由# revealed:断言在核对揭示类型的同时会吞掉undefined-reveal错误而# error: [revealed-type]不会顺带匹配undefined-reveal——这样一旦出现意外的undefined-reveal警告测试会直接失败。这与源码中if !self.in_stub() !self.is_in_type_checking_block(...)的门控条件互为印证。5.2 stub 文件中不报undefined-reveal.pyi文件永不执行同理不警告reveal_type(1) # error: [revealed-type] Literal[1]这里同样用# error: [revealed-type]而非# revealed:断言确保意外的undefined-reveal不会被静默吞掉。5.3 不可达代码中仍然有效reveal_type在静态判定为不可达的分支如if False:、if 1 1 ! 2:中也能工作导入与否两种情形均如此from typing_extensions import reveal_type import typing_extensions if False: reveal_type(1) # revealed: Literal[1] typing_extensions.reveal_type(1) # revealed: Literal[1] if 1 1 ! 2: reveal_type(1) # revealed: Literal[1] typing_extensions.reveal_type(1) # revealed: Literal[1]未导入版本if False: reveal_type(1) # revealed: Literal[1] if 1 1 ! 2: reveal_type(1) # revealed: Literal[1]这条能力在源码中有专门处理不可达区域内推断器会把外部定义的符号推断为Never从而让常规调用链走不到揭示逻辑builder.rs 因此加了一个特判——当调用结果类型为Type::Never时直接按名字reveal_type或xxx.reveal_type点路径识别该调用是typing.reveal_type然后照常对首参执行report_revealed_type。六、验证方式与相关测试上述 mdtest 文档由仓库内的 mdtest 框架crates/mdtest驱动执行文档中的[environment]/[dependency-metadata]TOML 块构造临时项目环境# revealed:、# error: [revealed-type]注释与# snapshot:块分别驱动行内断言与快照比对reveal_type.md的每条行为包括“不给修复”的场景都是被持续回归的。除文档测试外ty_python_semantic还有专门的单元测试覆盖修复的健壮性tests.rs 的undefined_reveal_fix_updates_after_source_changes验证在修改导入与行尾风格后重新检查同一文件undefined-reveal修复仍能正确更新对两条reveal_type各产出单一导入编辑。此外LSP 侧的行为也有端到端快照佐证例如 code_action_undefined_reveal.snap 展示了 IDE 中该修复作为 code action 的呈现importer 一侧的 API 文档importer.rs也明确以undefined-reveal诊断为前提来描述其导入生成接口。七、小结场景undefined-reveal警告导入修复修复来源已导入reveal_type无——3.11、未导入有有typing3.10、无依赖元数据有无—3.10、直接依赖且运行时导出reveal_type有有typing_extensions3.10、直接依赖但运行时模块过旧/缺失有无—3.10、仅间接依赖父项目声明有无—3.10、依赖分组包外测试文件有有typing_extensions3.10、依赖分组包代码有无—3.10、本地模块遮蔽typing_extensions有无—别名被参数遮蔽有不提议改写为别名无—TYPE_CHECKING块内 /.pyi文件无——不可达代码依上述规则依上述规则揭示仍正常发出可以总结为三条主线其一reveal_type的揭示能力与导入状态解耦——ty 通过未导入回退typing_extensions.reveal_type符号 不可达代码特判保证揭示在任何位置可用其二修复建议以“运行时真的能跑通”为唯一标准版本、依赖归属、运行时导出三层校验层层收窄其三警告本身只对“运行时可能执行”的位置生效非 stub、非TYPE_CHECKING块。理解这套机制后你既能正确使用reveal_type调试类型推断也能预期 ty 在不同工程结构下给出的修复行为。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考