“partially initialized module”是循环导入的铁证，即Python加载模块Y时未完成初始化，另一模块却尝试访问其未定义内容；可用延迟导入快速验证，治本需提取公共逻辑至第三方模块。
看到“partially initialized module”就停，这是循环导入的铁证
只要 traceback 里出现 ImportError: cannot import name 'X' from partially initialized module 'Y'，基本不用往下看了——100% 是循环导入。这不是模块没装、路径不对或拼写错误，而是 Python 在加载过程中卡在了模块初始化半途。它已经把 Y 放进 sys.modules，但还没执行完顶层代码，这时另一个模块回头去访问 Y 里还没定义的东西，就崩了。
这种报错往往只在特定导入顺序下触发：直接运行 a.py 没事，但从 c.py 导入 a 就炸；或者测试时正常，一加新模块就出问题。别怀疑环境或版本，先盯住那句 partially initialized。
用延迟导入（import in function）快速验证和绕过
最轻量、见效最快的验证方式：把疑似循环链上的 import 语句从模块顶部挪到具体函数内部。比如 b.py 里原本在开头 import a，改成只在真正要用 a 的函数里再 import a：
def do_something_with_a():
import a # ← 这里才导入，避开模块级加载时机
return a.some_function()
如果这么改后错误消失，基本锁定是循环导入。这不是最终解法，但能立刻让业务跑起来，同时帮你确认哪两个模块在互相拉扯。
- 只对“被依赖方”做延迟导入（即被
cannot import name报错的那个模块），不是所有import都要动 - 注意函数内导入的变量作用域：它只在该函数内可用，别在函数外试图引用
a - 如果函数里还用了类型提示（如
def f(x: a.SomeClass)），得用字符串字面量或from __future__ import annotations
用 python -v 看清 import 实际加载路径和卡点
python -v -c "import your_main_module" 会逐行打印每一个 import 动作，包括成功、失败、跳过和重用缓存的记录。循环导入的卡点通常出现在某次 import 后没有后续日志，或者反复在两个模块之间来回跳转。
关键看三类输出：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
-
import 'a' #→ 表示开始加载a -
import 'b' #→ 接着加载b - 然后突然中断，或出现
import 'a' # previously loaded→ 这就是循环入口，b又回头找a，但此时a还没初始化完
这个命令不依赖你的代码是否捕获异常，也不受 try/except 干扰，是观察 Python 底层加载行为最干净的方式。
提取公共逻辑到第三个模块是最干净的长期解法
延迟导入只是绕开，治本得拆耦。典型场景是 models.py 和 utils.py 互相 import：前者定义类，后者想用类做校验；后者又提供工具函数，前者想在 __init__ 里调用。
做法很简单：新建一个 shared.py（或 core.py），把双方都依赖的东西放进去：
- 数据结构（如
BaseModel、枚举、常量） - 基础工具函数（不依赖
models或utils其他部分） - 类型定义（
from typing import TYPE_CHECKING+if TYPE_CHECKING:块里导入仅用于提示的模块）
然后 models.py 和 utils.py 都只导入 shared，不再彼此直连。这个动作看似多建一个文件，实则把隐式依赖显性化，后续加新模块也更容易复用。
真正难的不是发现循环，而是意识到：那个你一直放在模块顶层、觉得“反正要用就提前导进来”的 import，可能正是整个调用链里最脆弱的一环。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
