Ruff ty 类型检查器如何将pytest.fail识别为终止语句基于 mdtest 外部依赖测试的深入解析【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 Ruff 仓库中类型检查器 tycrates/ty_python_semantic的 mdtest 测试文件 pytest.md 为核心讲解如何通过「Markdown 即测试」框架验证第三方库函数的控制流语义——具体来说就是确认pytest.fail(...)被当作**终止语句terminal statement**处理从而让后续代码被判定为不可达unreachable。读完本文你将掌握 mdtest 的 TOML 环境配置语法、外部依赖锁定机制以及 ty 底层基于可达性约束reachability constraints与Never/NoReturn类型实现终止语句分析的原理。一、pytest.md 是什么一个「外部依赖」驱动的 mdtest 测试在 Ruff 仓库中crates/ty_python_semantic/resources/mdtest/目录下的每一个 Markdown 文件都是一个类型推断 / 类型检查测试套件由crates/ty_python_semantic/tests/mdtest.rs集成测试基于datatest_stableharness驱动执行对目录内所有*.md文件运行mdtest。其中 external/ 子目录专门存放依赖真实第三方包的测试pytest、numpy、pydantic、sqlalchemy、strawberry 等。pytest.md 就是其中之一它并不测试 Ruff 的 lint 规则而是验证ty 在分析调用第三方库pytest.fail时能否正确推断其返回值类型为Never从而把调用点之后的语句判定为不可达。注意该目录下的测试只有在显式开启外部依赖--enable-external/MDTEST_EXTERNAL1时才会运行因为它需要uv实际安装 pytest 才能获取其类型信息。二、测试文件逐段解读配置、用例与断言2.1 TOML 配置块声明 Python 环境与外部依赖pytest.md 的开头是一个toml语言标记的 fenced 代码块这是 mdtest 的配置节[environment] python-version 3.13 python-platform linux [project] dependencies [pytest9.0.1]各配置项的作用可对照 crates/ty_test/README.md 的 Testing with external dependencies 一节配置项含义说明[environment].python-version目标 Python 版本带有外部依赖的测试必须指定参与包解析如本测试锁定3.13[environment].python-platform目标平台同样为外部依赖解析所必需例如linux、win32等[project].dependencies第三方依赖列表推荐使用锁定精确版本以保证可复现例如pytest9.0.1配置具有层次继承语义配置块会应用到其所在 Markdown 小节及其所有嵌套小节子小节可以用新的toml块覆盖父级配置。参见 mdtest_config.md 中的 Overwriting 与 Overwriting affects children 用例。当测试声明依赖后mdtest 框架会依次执行在临时目录创建pyproject.toml将同名.lock文件即 pytest.lock复制过去运行uv sync --locked安装依赖将虚拟环境site-packages中的已安装包拷入测试的内存文件系统配置类型检查器使用这些包该功能要求系统安装并配置了uv。pytest.lock 是 uv 生成的锁文件从中可以看到完整的依赖树pytest9.0.1依赖colorama仅 win32、iniconfig、packaging、pluggy、pygments且requires-python 3.13.*与 TOML 配置中的版本/平台声明一一对应。这正是保证不同机器与 CI 上测试结果可复现的关键机制。2.2 测试用例识别pytest.fail为终止语句pytest.md 的正文部分标题为## pytest.fail意图说明文字是Make sure that we recognizepytest.failcalls as terminal:import pytest def some_runtime_condition() - bool: return True def test_something(): if not some_runtime_condition(): pytest.fail(Runtime condition failed) no_error_here_this_is_unreachable这个测试的核心断言是**「没有错误」——注意pytest.fail(...)之后那行no_error_here_this_is_unreachable是一个未定义的名字**若 ty 不能识别pytest.fail是终止语句那么if分支失败时程序会继续执行到这一行于是会报出unresolved-reference未解析引用类诊断测试失败因为 ty 正确地认识到pytest.fail返回Never等同于NoReturn该调用之后的代码路径不可达no_error_here_this_is_unreachable永远不会被执行因此不产生任何诊断测试通过。这正是整个文档的灵魂用缺失的诊断来断言控制流语义。这种写法在 mdtest 中非常常见例如 terminal_statements.md 中大量用例的注释 The absence of a diagnostic confirms that this code is unreachable. 表达了同样的思想。三、底层原理ty 如何判定一个调用是终止语句3.1 终止语句与控制流分析所谓终止语句terminal statement是指该语句执行后控制流不会以正常方式继续例如return、break、continue、raise以及调用一个返回Never/NoReturn的函数如sys.exit()、pytest.fail()。为什么这很重要terminal_statements.md 的 Introduction 给出了直观例子在def f(cond: bool) - str: if cond: x test else: raise ValueError return x中else分支以raise终止因此return x只在cond为真时可达x虽然只在真分支绑定也总是有定义的不应报possibly-unresolved-reference。反之若某分支以return/raise终止则该分支在终止语句之前对变量做的绑定对分支之后或合并点之后的代码是不可见的。3.2 可达性约束Kleene 三值逻辑ty 在语义索引构建阶段记录可达性约束reachability constraints把某条语句能否从作用域起点到达建模为约束条件其实现位于 reachability.rs。每个约束求值结果有三种可能always-true恒真必然可达、always-false恒假必然不可达、ambiguous不可静态判定。顺序控制流嵌套if用三元 AND合并约束汇合控制流if/elif/else合并用三元 OR合并约束else分支记录取反约束~test对无法静态分析的分支点例如for循环是否进入循环体显式记录ambiguous避免错误地把循环后代码判为恒可达。当一个分支以终止语句结束如 pytest.md 中if真分支内的pytest.fail(...)该分支的可达性即为always-false在汇合点做三元 OR 时t OR always-false t于是分支之后的代码可达性只取决于其余分支从而不可达绑定被正确消除。3.3 返回Never/NoReturn的调用即终止语句terminal_statements.md 的 Calls to functions returningNever/NoReturn 一节系统性验证了这一机制可以视为 pytest.md 的通用化版本from typing import NoReturn import sys def f() - NoReturn: sys.exit(1)无隐式返回声明返回NoReturn的函数体若以sys.exit(1)结尾不报隐式返回None的invalid-return-type诊断类型收窄def g(x: int | None): if x is None: sys.exit(1); reveal_type(x) # revealed: int—— 调用NoReturn函数的分支终止x被收窄为int模块/类作用域分支内的终止调用会移除该分支的绑定reveal_type(value) # revealed: Literal[1]其中unreachable赋值被丢弃无条件终止调用后reveal_type(continuing_value) # revealed: Never重载与泛型仅当匹配到返回Never的重载时才视为终止如stop_if_int(1)终止、stop_if_int(safe)不终止泛型函数的类型变量被解析为Never时同样视为终止identity(exit())可调用对象与__call__C()()与C().die()均返回NoReturn同样被视为终止异步函数await stop()async且返回NoReturn与同步调用等价视为终止。这些用例共同说明调用返回Never的函数与return/raise一样是终止语句。pytest.fail之所以天然具备这一性质正是因为 pytest 将其签名声明为返回Neverpytest.fail(reason, pytraceTrue) - NoReturnty 通过外部依赖解析读取到该签名后即可在调用点推导出终止性。3.4 pytest.fail 测试在其中的位置结合上述机制pytest.md 的价值在于它是第三方真实库的端到端验证——不是手工 mock 的NoReturn函数而是让 ty 通过 uv 安装真实的 pytest 9.0.1从其类型信息中发现pytest.fail返回Never它验证了外部依赖解析module resolution site-packages 发现与终止语句分析的集成是否正常它用不可达代码不报错这一负向断言确认控制流分析没有漏报。四、如何运行与复现这类测试4.1 命令行运行方式方式一cargo 直接运行所有 mdtest含外部依赖需要加环境变量# 运行全部 mdtest不含外部依赖 cargo test -p ty_python_semantic -- mdtest # 显式开启外部依赖会安装 pytest 等包 MDTEST_EXTERNAL1 cargo test -p ty_python_semantic --test mdtest mdtest__external方式二使用 Python 运行器mdtest.py带 watch 模式见 mdtest.py# 只运行 external 目录下的测试含 pytest.md并自动更新 lockfile uv run crates/ty_python_semantic/mdtest.py -e external/ # 仅运行 pytest.md 这一个文件 uv run crates/ty_python_semantic/mdtest.py external/pytest.md -emdtest.py内部逻辑先用cargo test --package ty_python_semantic --no-run --testmdtest编译出 mdtest 可执行文件再以MDTEST_EXTERNAL1开启外部依赖、MDTEST_UPGRADE_LOCKFILES默认升级 lockfile可用--no-lockfile-upgrades关闭、MDTEST_UPDATE_SNAPSHOTS默认更新内联快照可用--no-snapshot-updates关闭等环境变量运行测试。watch 模式下Markdown、Rust 源码或 vendored typeshed 变化都会触发对应测试重跑或自动重编译。4.2 断言语法速览mdtest 的断言是行尾 Python 注释详见 crates/ty_test/README.md# revealed: Literal[...]—— 配合reveal_type(x)断言推断出的类型与注释文本完全一致# error: [rule-code]—— 断言该行产生指定规则代码的诊断pytest.md中没有用到因为它的断言恰好是无诊断# error: 8 [rule-code] some text—— 可进一步限定列号与消息文本。五、从测试到能力这一机制对真实开发者的意义对使用 Ruff / ty 的开发者而言pytest.fail被识别为终止语句意味着更准确的未定义引用检测在if分支中调用pytest.fail()后继续访问该分支外定义的变量不会出现误报的可能未定义诊断更好的类型收窄调用NoReturn函数的分支终止后联合类型会被正确收窄如x: int | None在if x is None: pytest.fail(...)之后收窄为int静态可达性pytest.fail之后的死代码dead code可以被可靠识别便于后续提供更丰富的不可达代码分析该方向已有规划参见 terminal_statements.md 末尾 Bindings after a terminal statement are unreachable 一节的说明。六、小结pytest.md 虽只有 27 行却是理解 Ruff 类型检查器 ty 三方面能力的绝佳入口mdtest 测试框架Markdown 即测试TOML 声明环境与依赖# revealed:/# error:注释断言外部依赖由 uv .lock文件保证可复现外部依赖集成真实安装 pytest 并读取其类型信息端到端验证第三方库语义终止语句分析基于 reachability.rs 的可达性约束Kleene 三值 AND/OR将返回Never/NoReturn的调用含pytest.fail、sys.exit、identity(exit())、await异步NoReturn函数等与return/raise/break/continue同等对待实现不可达代码消除与类型收窄。如果你希望继续深入建议依次阅读 terminal_statements.md终止语句的完整用例矩阵、reachability.rs约束建模实现以及 crates/ty_test/README.mdmdtest 格式的完整规范即可完整掌握 ty 控制流分析的设计与验证体系。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 10:14:11 · 阅读 1.2k Ruff ty 类型检查器如何将 `pytest.fail` 识别为终止语句：基于 mdtest 外部依赖测试的深入解析
Ruff ty 类型检查器如何将pytest.fail识别为终止语句基于 mdtest 外部依赖测试的深入解析【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff本文以 Ruff 仓库中类型检查器 tycrates/ty_python_semantic的 mdtest 测试文件 pytest.md 为核心讲解如何通过「Markdown 即测试」框架验证第三方库函数的控制流语义——具体来说就是确认pytest.fail(...)被当作**终止语句terminal statement**处理从而让后续代码被判定为不可达unreachable。读完本文你将掌握 mdtest 的 TOML 环境配置语法、外部依赖锁定机制以及 ty 底层基于可达性约束reachability constraints与Never/NoReturn类型实现终止语句分析的原理。一、pytest.md 是什么一个「外部依赖」驱动的 mdtest 测试在 Ruff 仓库中crates/ty_python_semantic/resources/mdtest/目录下的每一个 Markdown 文件都是一个类型推断 / 类型检查测试套件由crates/ty_python_semantic/tests/mdtest.rs集成测试基于datatest_stableharness驱动执行对目录内所有*.md文件运行mdtest。其中 external/ 子目录专门存放依赖真实第三方包的测试pytest、numpy、pydantic、sqlalchemy、strawberry 等。pytest.md 就是其中之一它并不测试 Ruff 的 lint 规则而是验证ty 在分析调用第三方库pytest.fail时能否正确推断其返回值类型为Never从而把调用点之后的语句判定为不可达。注意该目录下的测试只有在显式开启外部依赖--enable-external/MDTEST_EXTERNAL1时才会运行因为它需要uv实际安装 pytest 才能获取其类型信息。二、测试文件逐段解读配置、用例与断言2.1 TOML 配置块声明 Python 环境与外部依赖pytest.md 的开头是一个toml语言标记的 fenced 代码块这是 mdtest 的配置节[environment] python-version 3.13 python-platform linux [project] dependencies [pytest9.0.1]各配置项的作用可对照 crates/ty_test/README.md 的 Testing with external dependencies 一节配置项含义说明[environment].python-version目标 Python 版本带有外部依赖的测试必须指定参与包解析如本测试锁定3.13[environment].python-platform目标平台同样为外部依赖解析所必需例如linux、win32等[project].dependencies第三方依赖列表推荐使用锁定精确版本以保证可复现例如pytest9.0.1配置具有层次继承语义配置块会应用到其所在 Markdown 小节及其所有嵌套小节子小节可以用新的toml块覆盖父级配置。参见 mdtest_config.md 中的 Overwriting 与 Overwriting affects children 用例。当测试声明依赖后mdtest 框架会依次执行在临时目录创建pyproject.toml将同名.lock文件即 pytest.lock复制过去运行uv sync --locked安装依赖将虚拟环境site-packages中的已安装包拷入测试的内存文件系统配置类型检查器使用这些包该功能要求系统安装并配置了uv。pytest.lock 是 uv 生成的锁文件从中可以看到完整的依赖树pytest9.0.1依赖colorama仅 win32、iniconfig、packaging、pluggy、pygments且requires-python 3.13.*与 TOML 配置中的版本/平台声明一一对应。这正是保证不同机器与 CI 上测试结果可复现的关键机制。2.2 测试用例识别pytest.fail为终止语句pytest.md 的正文部分标题为## pytest.fail意图说明文字是Make sure that we recognizepytest.failcalls as terminal:import pytest def some_runtime_condition() - bool: return True def test_something(): if not some_runtime_condition(): pytest.fail(Runtime condition failed) no_error_here_this_is_unreachable这个测试的核心断言是**「没有错误」——注意pytest.fail(...)之后那行no_error_here_this_is_unreachable是一个未定义的名字**若 ty 不能识别pytest.fail是终止语句那么if分支失败时程序会继续执行到这一行于是会报出unresolved-reference未解析引用类诊断测试失败因为 ty 正确地认识到pytest.fail返回Never等同于NoReturn该调用之后的代码路径不可达no_error_here_this_is_unreachable永远不会被执行因此不产生任何诊断测试通过。这正是整个文档的灵魂用缺失的诊断来断言控制流语义。这种写法在 mdtest 中非常常见例如 terminal_statements.md 中大量用例的注释 The absence of a diagnostic confirms that this code is unreachable. 表达了同样的思想。三、底层原理ty 如何判定一个调用是终止语句3.1 终止语句与控制流分析所谓终止语句terminal statement是指该语句执行后控制流不会以正常方式继续例如return、break、continue、raise以及调用一个返回Never/NoReturn的函数如sys.exit()、pytest.fail()。为什么这很重要terminal_statements.md 的 Introduction 给出了直观例子在def f(cond: bool) - str: if cond: x test else: raise ValueError return x中else分支以raise终止因此return x只在cond为真时可达x虽然只在真分支绑定也总是有定义的不应报possibly-unresolved-reference。反之若某分支以return/raise终止则该分支在终止语句之前对变量做的绑定对分支之后或合并点之后的代码是不可见的。3.2 可达性约束Kleene 三值逻辑ty 在语义索引构建阶段记录可达性约束reachability constraints把某条语句能否从作用域起点到达建模为约束条件其实现位于 reachability.rs。每个约束求值结果有三种可能always-true恒真必然可达、always-false恒假必然不可达、ambiguous不可静态判定。顺序控制流嵌套if用三元 AND合并约束汇合控制流if/elif/else合并用三元 OR合并约束else分支记录取反约束~test对无法静态分析的分支点例如for循环是否进入循环体显式记录ambiguous避免错误地把循环后代码判为恒可达。当一个分支以终止语句结束如 pytest.md 中if真分支内的pytest.fail(...)该分支的可达性即为always-false在汇合点做三元 OR 时t OR always-false t于是分支之后的代码可达性只取决于其余分支从而不可达绑定被正确消除。3.3 返回Never/NoReturn的调用即终止语句terminal_statements.md 的 Calls to functions returningNever/NoReturn 一节系统性验证了这一机制可以视为 pytest.md 的通用化版本from typing import NoReturn import sys def f() - NoReturn: sys.exit(1)无隐式返回声明返回NoReturn的函数体若以sys.exit(1)结尾不报隐式返回None的invalid-return-type诊断类型收窄def g(x: int | None): if x is None: sys.exit(1); reveal_type(x) # revealed: int—— 调用NoReturn函数的分支终止x被收窄为int模块/类作用域分支内的终止调用会移除该分支的绑定reveal_type(value) # revealed: Literal[1]其中unreachable赋值被丢弃无条件终止调用后reveal_type(continuing_value) # revealed: Never重载与泛型仅当匹配到返回Never的重载时才视为终止如stop_if_int(1)终止、stop_if_int(safe)不终止泛型函数的类型变量被解析为Never时同样视为终止identity(exit())可调用对象与__call__C()()与C().die()均返回NoReturn同样被视为终止异步函数await stop()async且返回NoReturn与同步调用等价视为终止。这些用例共同说明调用返回Never的函数与return/raise一样是终止语句。pytest.fail之所以天然具备这一性质正是因为 pytest 将其签名声明为返回Neverpytest.fail(reason, pytraceTrue) - NoReturnty 通过外部依赖解析读取到该签名后即可在调用点推导出终止性。3.4 pytest.fail 测试在其中的位置结合上述机制pytest.md 的价值在于它是第三方真实库的端到端验证——不是手工 mock 的NoReturn函数而是让 ty 通过 uv 安装真实的 pytest 9.0.1从其类型信息中发现pytest.fail返回Never它验证了外部依赖解析module resolution site-packages 发现与终止语句分析的集成是否正常它用不可达代码不报错这一负向断言确认控制流分析没有漏报。四、如何运行与复现这类测试4.1 命令行运行方式方式一cargo 直接运行所有 mdtest含外部依赖需要加环境变量# 运行全部 mdtest不含外部依赖 cargo test -p ty_python_semantic -- mdtest # 显式开启外部依赖会安装 pytest 等包 MDTEST_EXTERNAL1 cargo test -p ty_python_semantic --test mdtest mdtest__external方式二使用 Python 运行器mdtest.py带 watch 模式见 mdtest.py# 只运行 external 目录下的测试含 pytest.md并自动更新 lockfile uv run crates/ty_python_semantic/mdtest.py -e external/ # 仅运行 pytest.md 这一个文件 uv run crates/ty_python_semantic/mdtest.py external/pytest.md -emdtest.py内部逻辑先用cargo test --package ty_python_semantic --no-run --testmdtest编译出 mdtest 可执行文件再以MDTEST_EXTERNAL1开启外部依赖、MDTEST_UPGRADE_LOCKFILES默认升级 lockfile可用--no-lockfile-upgrades关闭、MDTEST_UPDATE_SNAPSHOTS默认更新内联快照可用--no-snapshot-updates关闭等环境变量运行测试。watch 模式下Markdown、Rust 源码或 vendored typeshed 变化都会触发对应测试重跑或自动重编译。4.2 断言语法速览mdtest 的断言是行尾 Python 注释详见 crates/ty_test/README.md# revealed: Literal[...]—— 配合reveal_type(x)断言推断出的类型与注释文本完全一致# error: [rule-code]—— 断言该行产生指定规则代码的诊断pytest.md中没有用到因为它的断言恰好是无诊断# error: 8 [rule-code] some text—— 可进一步限定列号与消息文本。五、从测试到能力这一机制对真实开发者的意义对使用 Ruff / ty 的开发者而言pytest.fail被识别为终止语句意味着更准确的未定义引用检测在if分支中调用pytest.fail()后继续访问该分支外定义的变量不会出现误报的可能未定义诊断更好的类型收窄调用NoReturn函数的分支终止后联合类型会被正确收窄如x: int | None在if x is None: pytest.fail(...)之后收窄为int静态可达性pytest.fail之后的死代码dead code可以被可靠识别便于后续提供更丰富的不可达代码分析该方向已有规划参见 terminal_statements.md 末尾 Bindings after a terminal statement are unreachable 一节的说明。六、小结pytest.md 虽只有 27 行却是理解 Ruff 类型检查器 ty 三方面能力的绝佳入口mdtest 测试框架Markdown 即测试TOML 声明环境与依赖# revealed:/# error:注释断言外部依赖由 uv .lock文件保证可复现外部依赖集成真实安装 pytest 并读取其类型信息端到端验证第三方库语义终止语句分析基于 reachability.rs 的可达性约束Kleene 三值 AND/OR将返回Never/NoReturn的调用含pytest.fail、sys.exit、identity(exit())、await异步NoReturn函数等与return/raise/break/continue同等对待实现不可达代码消除与类型收窄。如果你希望继续深入建议依次阅读 terminal_statements.md终止语句的完整用例矩阵、reachability.rs约束建模实现以及 crates/ty_test/README.mdmdtest 格式的完整规范即可完整掌握 ty 控制流分析的设计与验证体系。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考