用 pytest 的 diff-assert-rewrite.py 对比断言重写前后差异从单行片段到跨版本行为比对【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest导读diff-assert-rewrite.py是 pytest 仓库在 scripts 目录下新增的一个贡献者工具脚本用于把一段 Python 代码片段的断言重写assertion rewriting结果以 diff 形式直观展示出来——比较对象可以是原始源码、当前 checkout工作区src/的重写结果也可以是任意已发布 pytest 版本的重写结果。它服务于 pytest 自身的贡献者与核心开发者当断言重写逻辑发生行为变化、修复或回归时可以用它快速定位差异、验证跨 Python 版本与跨 pytest 版本的一致性。读完本文你将掌握该脚本的全部命令行用法、退出码语义以及它背后基于ast与uv的实现原理和断言重写的底层工作机制。一、这个工具从何而来一条 changelog 记录背后的完整工具本次主题的源头是仓库中的一条 changelog 记录 changelog/14921.contrib.rst其完整内容如下Addedscripts/diff-assert-rewrite.py, which diffs the assert-rewritten form of a snippet between the plain source, this checkout and released pytest versions.在 pytest 的 changelog 体系中contrib类型表示影响贡献者体验的变更例如运行测试、构建文档、搭建开发环境相关的内容见 changelog/README.rst 中对各类型文件的定义。也就是说这个脚本不是给普通 pytest 用户使用的而是给 pytest 贡献者、以及研究断言重写机制的人使用的开发工具。但它的价值不止于内部工具它把一个复杂的语言变换过程断言重写变成了可交互、可复现、可比较的观察窗口任何想深入理解 pytest 断言重写原理的人都可以直接使用。二、断言重写这个工具要观察的核心对象要理解diff-assert-rewrite.py在对比什么先要理解 pytest 的断言重写机制。pytest 为了让一条简单的assert语句失败时能输出详细的表达式求值信息例如assert a b失败时展示a与b的具体值会在导入测试模块时改写其中的assert语句——这被称为 assertion rewriting。核心实现位于 src/_pytest/assertion/rewrite.pyAssertionRewritingHook同文件第 67 行起是一个 PEP 302/PEP 451 元路径导入钩子在模块导入阶段拦截assert并进行改写rewrite_asserts(mod, source, ...)rewrite.py是重写的入口函数它会调用AssertionRewriter(...).run(mod)AssertionRewriter.run()rewrite.py负责在模块顶部插入py_builtins、pytest_ar等辅助导入并遍历 AST 找到所有ast.Assert节点逐个改写AssertionRewriter.visit_Assert()同文件第 820 行起是单个断言节点的变换逻辑。重写后缓存的.pyc文件也会被标记为 pytest 专属PYTEST_TAG与PYC_TAILrewrite.py用于区分普通缓存与 pytest 重写后的缓存。你可以在测试 testing/test_assertrewrite.py 中看到最直接的调用方式——其中的rewrite(src)辅助函数test_assertrewrite.py正是ast.parse后调用rewrite_asserts的最小复现与diff-assert-rewrite.py内嵌的 worker 逻辑完全一致def rewrite(src: str) - ast.Module: tree ast.parse(src) rewrite_asserts(tree, src.encode()) return treediff-assert-rewrite.py的独特之处在于它把这一过程可视化了——对同一段源码分别做重写再把结果以 unified diff 呈现出来。三、脚本全貌参数、支持的三类对比对象与退出码diff-assert-rewrite.py的完整源码位于 scripts/diff-assert-rewrite.py入口为main()diff-assert-rewrite.py。以下是其全部命令行参数整理为速查表参数含义默认值file位置参数可选要重写的文件路径缺省时从 stdin 读取-c, --code用命令行内联代码片段代替文件无--left左侧对比对象plain、worktree或一个 pytest 版本号plain--right右侧对比对象取值同--leftworktree--format输出格式sourceast.unparse还原的源码或astast.dump的结构树source--python用指定 Python 版本如3.14运行两侧当前解释器--no-color关闭颜色高亮- 红色 / 绿色 / 青色关闭tty 自动着色三类对比对象对应文档字符串中的 spec 概念plain原始源码不经过任何重写。这一侧只做解析不做变换mode plainworktree当前 checkout 的src/目录下的实现即本仓库正在开发的 pytest 版本。通过把仓库根目录的src/注入PYTHONPATH来确保加载的是当前工作区代码而非已安装版本已发布版本号如8.3.4按需通过uv run --with pytestVERSION拉取并运行对应 pytest 版本的重写逻辑可用于对比新实现与旧版本行为的差异。退出码语义两侧结果一致时输出left and right agree on the format form并以 0 退出两侧有差异时输出 unified diff 并以 1 退出见 diff-assert-rewrite.py。这使得该脚本可以很方便地嵌入到 CI、脚本或 pre-commit 流程中做断言重写的一致性检查。输入来源位置参数文件、-c内联代码、stdin 三选一优先级为--code 文件 stdin源码会被写入临时目录中的snippet.py再交给两侧的 worker 处理。四、四种典型用法实战脚本文档字符串diff-assert-rewrite.py给出了四种典型场景全部可以直接在仓库根目录运行。4.1 查看一段代码被重写成了什么plain vs worktreepython scripts/diff-assert-rewrite.py -c assert (x : f()) and (x : False)这是最常用的形式左边是原始源码plain右边是当前工作区 pytest 的重写结果worktree以源码形式输出。例如上面这条涉及海象运算符walrus和and短路逻辑的断言重写后会被拆解成对子表达式的逐步求值、并记录中间值diff 会清楚展示每个and/or分支如何被转换成带解释信息的调用。输出示例大致形如--- plain worktree -1 1,13 -assert (x : f()) and (x : False) import builtins as py_builtins import _pytest.assertion.rewrite as pytest_ar py_builtins.AssertionError( pytest_ar.format_explanation( (x : f()) and (x : False) \n \n where x ...) )具体换行与中间变量形式会随 pytest 版本演进以实际输出为准。4.2 对比当前实现与某个已发布版本的差异跨版本行为比对python scripts/diff-assert-rewrite.py --left 8.3.4 testing/example.py这一用法把左侧换成已发布的 pytest8.3.4右侧仍是当前工作区。当某次重构改动重写逻辑后可以用它验证对一个测试文件整体重写后的结果是否与旧版一致从而发现无意的行为回归——这正是本 changelog 记录要解决的痛点之一。注意此时左侧 pytest 通过uv run --with pytest8.3.4在独立环境中运行。4.3 用 AST 形式对比当源码形式掩盖了差异时python scripts/diff-assert-rewrite.py --left 8.3.4 --format ast -c assert a b--format ast让两侧输出ast.dump(tree, indent2)的结构树而非还原后的源码。当重写结果在源码层面看起来一样、但 AST 结构不同例如节点类型、字段、lineno、辅助导入的别名细节不同时只有 AST 级对比才能暴露差异。4.4 固定解释器版本避免语法差异污染对比python scripts/diff-assert-rewrite.py --left 8.3.4 --python 3.14 example.py脚本文档字符串特别强调了一个陷阱两侧应该运行在同一个解释器上。因为uv run默认可以为已发布 pytest 挑选一个 Python而worktree用的是当前脚本所在解释器两者语法能力例如新语法特性是否被ast支持不同时差异会看起来像重写器变了。因此凡是涉及 pytest 版本对比的场景都建议用--python X.Y显式固定解释器版本diff-assert-rewrite.py。五、实现原理一个脚本如何远程运行任意 pytest 版本这个脚本的实现值得单独拆解它展示了 Python 开发工具中一种优雅的模式内嵌 worker 源码 子进程隔离 按需依赖注入。5.1 内嵌 worker一段以字符串形式存在的重写执行器脚本内部定义了一个名为_WORKER的多行字符串diff-assert-rewrite.py它在被考察的 pytest 环境内部运行完成读取文件 → 解析 AST → 重写 → 输出四个步骤fmt, mode, path sys.argv[1:4] source open(path, rb).read() tree ast.parse(source) if mode rewrite: from _pytest.assertion.rewrite import rewrite_asserts rewrite_asserts(tree, source) ast.fix_missing_locations(tree) print(ast.unparse(tree) if fmt source else ast.dump(tree, indent2))注意这里的from _pytest.assertion.rewrite import rewrite_asserts由于每个 worker 子进程运行在指定的 pytest 环境中worktree的PYTHONPATH指向仓库src/版本侧则由uv run --with pytestVERSION提供它导入到的rewrite_asserts就天然是该环境对应的实现——这正是同一段 worker 代码、不同重写实现得以实现的关键。5.2 启动策略三条不同的子进程命令spawn()函数diff-assert-rewrite.py根据 spec 决定如何启动 workerplain/worktree直接用当前解释器sys.executable -c _WORKER运行其中worktree额外设置PYTHONPATH为仓库根目录下的src/env os.environ | {PYTHONPATH: str(repo / src)}并依赖--project携带 pytest 的依赖项发布版本走uv run通道按需动态安装uv run --no-project --with pytestVERSION -- python -c _WORKER ...。这是脚本在文档字符串中要求环境中存在 uv 的原因——找不到uv时脚本会以清晰的错误信息退出diff-assert-rewrite.py。5.3 并发收集与 diff 输出collect()diff-assert-rewrite.py会先等待两侧全部结束再统一汇报避免某一侧 worker 比源码临时目录更长寿任何一侧非零退出都会把其 stderr 透传并以错误退出。随后用标准库difflib.unified_diff生成统一 diff并依据行首字符-//进行颜色高亮。整个脚本只依赖 Python 标准库与uv没有额外第三方依赖。六、如何验证与扩展使用脚本的核心逻辑与 pytest 自身的测试可以互相印证。在 testing/test_assertrewrite.py 中rewrite()辅助函数test_assertrewrite.py演示了最小重写调用getmsg()test_assertrewrite.py展示了重写 → 编译 → 执行 → 提取失败信息的完整链路是理解重写产物如何服务于错误消息的绝佳示例测试中大量使用AssertionRewritingHook例如第 1264、1868 行等处的构造与断言验证导入钩子的行为。如果你在开发 pytest 时修改了重写逻辑可以按下面的流程自查先跑一个冒烟对比确认基本行为未变python scripts/diff-assert-rewrite.py -c assert a b对包含多种断言形态的测试文件做整体比对确认与目标发布版本一致python scripts/diff-assert-rewrite.py --left 8.3.4 --python 3.13 testing/example.py如果源码形式看不出差异再用 AST 格式深挖python scripts/diff-assert-rewrite.py --left 8.3.4 --format ast -c assert (x : f()) and (x : False)运行前提需要仓库环境可执行python指向当前解释器以及安装了uv用于按需拉取发布版本仅在对比版本时必需。脚本不会修改仓库中任何文件仅向 stdout 输出 diff。结语diff-assert-rewrite.py是一个小而完整的贡献者工具它以一条 changelog 记录的形式进入仓库却同时承载了断言重写可视化跨 pytest 版本行为比对跨 Python 版本语法一致性检查三重能力。对普通用户而言它是理解 src/_pytest/assertion/rewrite.py 中rewrite_asserts/AssertionRewriter工作原理的最直观入口对贡献者而言它是修改重写逻辑前后不可或缺的回归检查工具。结合 testing/test_assertrewrite.py 中的测试辅助函数你可以把重写后长什么样、哪里变了变成一条可复现、可审计的验证链路。【免费下载链接】pytestThe pytest framework makes it easy to write small tests, yet scales to support complex functional testing项目地址: https://gitcode.com/GitHub_Trending/py/pytest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
