pytest在test collection阶段因循环导入中断，本质是模块顶层import触发“partially initialized module”错误，导致采集失败且无行号提示；需用python -c验证可导入性，并通过TYPE_CHECKING、函数内导入或字符串注解解决。
pytest 因循环导入导致测试发现失败，本质不是循环导入本身报错，而是 ImportError 或 ModuleNotFoundError 在 test collection 阶段就中断了整个扫描流程——此时你根本看不到测试函数，也收不到具体行号提示。
为什么 pytest 会在收集阶段就卡住循环导入？
pytest 在 import 测试模块时，会递归解析其所有顶层 import 语句。如果 my_module.py 导入 my_utils.py，而后者又在顶层又反向导入 my_module（哪怕只是类型提示里写了），Python 就会在构建模块对象图时抛出 ImportError: cannot import name 'X' from partially initialized module 'my_module'。这个错误发生在 import 未完成时，pytest 不会继续收集，直接退出。
- 它和运行时的循环导入不同：运行时可能靠延迟导入（如函数体内 import）绕过；但 pytest 收集阶段只执行模块顶层代码，没机会延迟
- 常见诱因是类型提示中用了未定义的类名，比如
def foo(x: MyClass) -> None:，而MyClass来自另一个尚未完全初始化的模块 -
from __future__ import annotations能缓解，但仅对 Python ≥ 3.7 有效，且不解决运行时仍需 import 的场景（如 pytest 夹具或 fixture 中实际用到该类型）
如何快速定位哪个 import 触发了循环？
别猜，用最原始但最可靠的方式验证：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 在终端中，cd 到项目根目录，运行
python -c "import src.my_package.my_module"—— 如果这里就报错，说明问题不在 pytest，而在模块自身可导入性 - 如果报错信息含
partially initialized module，基本锁定为循环导入；若只是ModuleNotFoundError，优先查sys.path和包结构 - 临时在疑似出问题的模块顶部加
import sys; print(__name__, sys.modules.keys())，观察 import 链中哪个模块反复出现或缺失
绕过循环导入的三种实操方案
目标不是“修复”循环（有时业务逻辑上合理），而是让 pytest 能顺利 import 并完成收集：
立即学习“Python免费学习笔记（深入）”；
- 把类型提示移到
if TYPE_CHECKING:块内：from typing import TYPE_CHECKING; if TYPE_CHECKING: from .my_module import MyClass。这样 runtime 不执行 import，只在 mypy 或 IDE 类型检查时生效 - 将循环依赖的 import 移到函数/方法内部（非顶层）：
def process(): from .my_other_module import helper; return helper()。pytest 收集时不执行函数体，自然跳过 - 改用字符串形式的类型注解：
def foo(x: "MyClass") -> None:。Python 3.7+ 默认启用from __future__ import annotations后，所有注解都变成字符串，彻底规避 import 时机问题
容易被忽略的隐性条件
即使改了类型提示，如果模块里还有其他顶层 import 涉及相同模块（比如 import my_other_module 用于常量或配置），循环依然存在。真正可靠的判断标准只有一个：在相同工作目录下，python -c "import your_module" 必须成功返回，且无任何异常输出。任何“看起来能跑”的侥幸，都会在 CI 或换环境时重现失败。
