企业官网建设流程全解析

深入解析 ty 类型检查器中的循环导入处理：基于 Ruff 仓库 mdtest 回归测试的完整指南

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff

导读

循环导入（Cyclic imports）是 Python 模块系统中一个既常见又棘手的边界场景：模块 A 导入模块 B，同时模块 B（直接或间接）又导入模块 A。在静态类型检查中，循环导入既可能引发模块解析死循环，也可能导致符号类型无法确定。本文以 Ruff 仓库中 ty 类型检查器（crates/ty_python_semantic）的循环导入测试套件 cyclic.md 为骨架，逐条剖析它的回归测试用例、已知行为边界与自引用导入的解析策略，并结合ty_module_resolver、mdtest测试框架等底层源码，说明 ty 如何在不陷入模块解析环的前提下完成类型推断。读完本文，你将掌握 ty 对循环导入的四种典型场景（包内循环、通配符导入环、真实运行时循环、自引用导入）的处理结论，以及如何阅读与运行这类 Markdown 驱动的类型检查测试。

一、测试载体：mdtest 与# revealed:断言

在进入具体用例之前，先理解这些代码片段是如何被"执行"的。cyclic.md 本身不是普通文档，而是一个 mdtest 测试夹具（fixture）。mdtest 是一种以 Markdown 为载体的测试框架：每个#/##标题构成一个测试小节，小节内的 ```py 围栏代码块被解析为内嵌的 Python 源文件，行内注释（如# revealed: ...）则是对类型推断结果的断言。

• 测试的解析逻辑位于 parser.rs：一个标题小节（Section）下可以包含多个带显式文件路径（如`main.py`:）的代码块，它们共同组成一个"测试项目"；相邻的同一小节内多个无路径代码块会被合并为同一个自动命名文件mdtest_snippet.py。
• 断言的匹配逻辑位于 matcher.rs：# revealed: <类型>断言会与类型检查器产生的revealed-type诊断进行比对，要求诊断的主标注文本精确等于期望类型；# error: [规则名]断言则匹配对应 lint 规则产生的诊断。
• 测试的驱动入口在 mdtest.rs，它通过datatest_stable::harness!将resources/mdtest下所有.md文件注册为测试；每个夹具会先在内存文件系统中建立/src项目根目录、写入所有内嵌文件，再调用ty_python_semantic::Db::check_file执行完整检查（详见 lib.rs 的run_test）。

因此，cyclic.md 中每一个revealed: ...的期望值，都对应 ty 在当前仓库版本下类型推断的真实输出——这些就是可以直接验证的"实现事实"。

二、回归测试：包内循环导入（Issue 261）

文档的第一个用例针对历史 issue #261，构造了一个"包导入自身子模块"的循环：

main.py：

from foo import bar reveal_type(bar) # revealed: <module 'foo.bar'>

foo/__init__.py：

from foo import bar __all__ = ["bar"]

foo/bar/__init__.py：

# empty

这里的关键点在于：foo/__init__.py内部执行from foo import bar，把子包foo.bar绑定到bar这个名字上，而main.py又通过from foo import bar从包导入。如果解析器按"先求值foo/__init__.py全部成员再返回"的朴素思路处理，foo包在初始化过程中导入foo自身就会形成解析环。

ty 的处理结论是：bar在main.py中被揭示的类型为<module 'foo.bar'>——即from foo import bar成功地把子模块（而非子模块里某个值）绑定到了名字上。也就是说，ty 在模块尚未"完全初始化"时就能识别from foo import bar指向的是子模块foo.bar，并正确推导出模块类型，而不是报unresolved-import或陷入环。这正是该用例作为"回归测试"的价值：防止后续改动重新引入循环解析或导入解析失败。

三、回归测试：通配符导入构成的间接环（Issue 113）

第二个用例更为复杂，它把"通配符导入"与"循环导入"叠加在一起：

main.py：

from pkg.sub import A # TODO: This should be `<class 'A'>` reveal_type(A) # revealed: Divergent

pkg/outer.py：

class A: ...

pkg/sub/__init__.py：

from ..outer import * from .inner import *

pkg/sub/inner.py：

from pkg.sub import A

分析这里的依赖图：

• pkg/sub/__init__.py通过from ..outer import *导入A（来自pkg/outer.py）；
• 随后它又通过from .inner import *导入inner导出的名字；
• 而inner.py本身又from pkg.sub import A——即pkg.sub在初始化中途又被inner反向引用。

于是形成环：pkg.sub→pkg.outer/pkg.sub.inner→pkg.sub。同时__init__.py里的通配符导入意味着需要先确定inner的公共成员集合，而inner的类型推断又依赖pkg.sub自身的名字绑定。

ty 在当前仓库中的输出是revealed: Divergent，且文档明确留了 TODO："This should be<class 'A'>"。这说明：

1. 该场景不会导致崩溃或模块解析死循环（这是本测试的最低防线）；
2. 但当前推断出的类型是一个"分歧（Divergent）"的占位结果——在from ..outer import *与from .inner import *相互交织且inner反向依赖pkg.sub时，ty 无法稳定收敛出精确的A类型，便以Divergent保守收场。

从源码结构看，Divergent属于 ty 在循环求值无法收敛时的兜底类型：在 lib.rs 中定义了TAINTED_CYCLES = 3，即前若干轮迭代产生的"被污染"结果会被丢弃，以避免把不稳定的中间值并进最终类型；当递归求值反复进入同一环时，相关代码路径会给出保守结果。这个用例正是把该边界行为显式固化下来，供后续修复 issue #113 时对照参考。

四、真实循环：运行时失败的场景

文档专门用一个小节记录"Actual cycle"——一个在真实 Python 运行时会直接失败的循环：

main.py：

from module import x reveal_type(x) # revealed: Unknown

module.py：

# error: [unresolved-import] from module import x

这里module.py在自身顶层执行from module import x：模块尚未完成初始化便引用自己，Python 运行时必然抛出错误。ty 的处理策略是分层的：

• 类型检查器给出诊断：module.py中的自引用导入被标记为# error: [unresolved-import]，即 ty 主动报告"无法解析的导入"——这是对真实运行时失败的事前预警；
• 对导入方保持宽容：main.py中reveal_type(x)的结果是Unknown。文档明确指出，"理想情况下我们应在此处发出诊断；目前我们只确保这不会导致模块解析环"。

也就是说，ty 当前把"真实循环"当作已知的精度缺口（不报错、但也不推断具体类型），把防死循环作为底线目标。这体现了静态检查器面对运行时异常模块的一种务实取舍：宁可类型未知，不可进程卡死。从 resolve.rs 的实现看，模块解析器对与builtins构成导入环的内置模块（如types、typing_extensions）做了"不可遮蔽"的特殊处理，而对一般模块则依赖 Salsa 查询图的循环求值机制来安全收敛。

五、嵌套作用域内的自引用from导入

文档接下来验证的是一个容易误报的场景：在函数体内写from <自身模块> import <名字>。

main.py：

def foo() -> int: return 0 def bar() -> int: from main import foo return foo()

断言隐藏在代码行为中：这个测试没有revealed断言，也没有# error:注释，其"通过"条件就是不产生任何诊断。文档原文明确指出：函数体中的from <self> import <name>应当从模块的全局作用域解析该名字，而不触发循环。

这里的语义要点是：from main import foo位于bar的函数体内部，只有调用bar时才会执行；此时模块main早已完成初始化，foo已绑定到全局作用域。因此它和"模块顶层自引用导入"（第四节）性质完全不同——后者在模块初始化中途执行，必然失败；前者延迟到调用期，完全合法。ty 需要区分这两种上下文，避免把合法的嵌套自引用误判为循环。此用例关联 issue #2596，作为该行为的回归保护。

六、正常的自引用导入：typeshed 的sys模式

最后一种场景是"合法且常见"的自引用导入：某些模块会在顶层import自身。文档以 typeshed 中的sys为例说明，这种写法必须被正常支持：

module/__init__.py：

import module # self-referential import from module.sub import x

module/sub.py：

x: int = 1

main.py：

from module import x reveal_type(x) # revealed: int

解析流程：

1. module/__init__.py顶层import module把模块自身绑定到module名字上——这在运行时是合法的（模块对象已存在），ty 需要把它当作普通的模块绑定，而非循环错误；
2. 随后from module.sub import x从子模块导入x，绑定其类型int；
3. main.py中reveal_type(x)精确得到int。

这个用例的断言价值在于：自引用导入既不能触发循环检测，也不能导致导入未解析。对比第四节可知，ty 对"自引用"的处理是区分绑定目标的：绑定模块自身（import module）安全；绑定模块自身尚未定义的成员（from module import x且 x 未定义）才会报unresolved-import。这也是sys、os等标准库模块（以及依赖它们自引用的 typeshed 桩文件）能被正确类型检查的前提。

七、从源码理解循环防护的底层机制

综合上述用例，可以归纳出 ty 处理循环导入的三道防线：

1. 模块解析层：Salsa 查询图天然免疫纯查询环。ty 的模块解析基于 Salsa 数据库（见 resolve.rs 中的resolve_module_query），模块名被 intern 为ModuleNameIngredient参与增量查询。Salsa 对循环查询会以"循环初始值"（cycle_initial）安全返回，避免递归爆栈——这也是文档反复强调"确保不产生模块解析环"的工程基础。

2. 类型推断层：CycleDetector与收敛保护。类型层面存在专门的循环检测设施 cyclic.rs。其中的TypeIdentity为函数字面量、NewType、递归类型别名、协议、TypedDict等"可递归"的构造提供稳定的身份标识；CycleDetector维护活跃递归栈，一旦发现相同身份的项目再次进入，就返回配置好的保守回退值（fallback），从而把type Growing[T] = T | Growing[list[T]]这类无限增长的递归类型安全截断。配合TAINTED_CYCLES（见 lib.rs）对早期不稳定迭代结果的丢弃，最终输出要么精确类型，要么Divergent/Unknown等保守结果。

3. 诊断层：unresolved-import作为运行时失败的先导信号。对"真实循环"（第四节），ty 选择在自引用未定义成员处报告unresolved-import诊断，而不是崩溃或死循环——把运行时必然发生的失败提前暴露给开发者。

八、如何运行与扩展这套测试

如果你想把 cyclic.md 中的用例跑起来，可以按以下方式执行：

# 运行 ty_python_semantic 的全部 mdtest 夹具（含 cyclic.md） cargo test -p ty_python_semantic --test mdtest # 只运行与 "cyclic" 相关的用例：通过 MDTEST_TEST_FILTER 过滤测试名 MDTEST_TEST_FILTER='cyclic' cargo test -p ty_python_semantic --test mdtest # 单独运行某一具体用例（测试名由标题层级拼接而成） MDTEST_TEST_FILTER='Cyclic imports - Regression tests - Issue 261' \ cargo test -p ty_python_semantic --test mdtest

测试失败时，mdtest.rs 会打印出"期望 vs 实际"的 diff，并提示可用MDTEST_TEST_FILTER精确定位；若某个用例包含# snapshot断言，还可通过MDTEST_UPDATE_SNAPSHOTS=1自动更新内联快照（详见 lib.rs 对这几个环境变量的说明）。

需要特别说明的测试前提：所有代码块都写入内存文件系统的/src项目根，模块名以/src为搜索路径起点解析（见 lib.rs），因此from foo import bar实际解析的是夹具内foo/目录对应的包结构——这是理解revealed结果为何与"文件路径"一一对应的前提。

结语

通过 cyclic.md 这组用例可以看到，ty 对循环导入的立场可以概括为四句话：合法的包内/子模块循环要能解析出精确类型；通配符与循环叠加时可退化为Divergent但绝不崩溃；真实运行时循环要给出unresolved-import诊断；合法的自引用（含 typeshed 模式）必须完全支持。这套行为由模块解析层、类型推断层的循环检测与诊断层共同保证，并通过 mdtest 这种"Markdown 即测试"的方式固化下来，为后续修复 issue #113、#261、#2596 等遗留问题提供了清晰的回归基线。

【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff