该错误源于模块循环依赖导致的部分初始化，解决方法包括延迟导入、合并模块或拆出接口层。延迟导入将import移入函数内；合并模块适用于强耦合文件；拆接口层则通过抽象协议解耦职责分明的模块。
ImportError: cannot import name 'X' from partially initialized module 这类错误不是模块没找到，而是 Python 解释器在加载过程中卡住了——模块 A 正在初始化，这时被模块 B 导入；而模块 B 又依赖模块 A 里还没定义完的某个名字，于是直接报错。
根本原因在于 Python 的模块加载是顺序执行 + 单次缓存：一个模块第一次被 import 时，解释器会逐行执行其代码，同时把模块对象放进 sys.modules。如果中途又触发对它的再次导入（哪怕只是想取一个类或函数），而此时模块体还没跑完，就会撞上“部分初始化”状态。
延迟导入：把 import 挪进函数里
最轻量、见效最快的解法，适合调用不频繁、且只在特定路径下才需要依赖的场景。
- 错误写法：
from module_b import func_b写在模块顶部，一导入就触发循环 - 正确写法：把导入语句挪到具体使用它的函数内部，比如
def handle_event(): from module_b import func_b; return func_b() - 注意：不能用于模块级变量赋值或
__all__声明，因为那些必须在模块加载时就确定 - 副作用：每次调用函数都会查一次
sys.modules，但开销极小；真正影响的是可读性——读者得翻到函数里才知道依赖在哪
合并模块：当两个模块本就强耦合时
如果 module_a.py 和 module_b.py 总是一起改、一起测、互相调用深度嵌套，那它们大概率不该是两个文件。
立即学习“Python免费学习笔记（深入）”；
- 典型信号：git log 显示这两个文件总被同一 commit 修改；IDE 提示“Move class to another module”反复弹窗
- 操作很简单：把两个文件内容剪切到一个新文件（如
core_types.py），然后统一更新所有外部引用 - 好处不仅是解决循环导入，还能减少 import 行数、避免 IDE 警告、让类型检查（mypy）更准
- 风险：如果已有其他模块只依赖其中某一个，合并后它们会意外获得“不需要的”符号，需检查
__all__或重导出控制可见性
拆出接口层：用第三个模块打破循环
当 A 和 B 确实职责不同、但又必须交互时，硬合并反而破坏内聚。这时引入一个中间层是最干净的解法。
- 新建
interfaces.py，只放抽象基类或类型别名，比如class UserProtocol: ...或ConfigDict = Dict[str, Any] - A 和 B 都只导入这个轻量接口模块，不再直接互引
- 实际实现仍留在各自模块里，只是把“依赖声明”从具体实现降级为协议
- 特别适合搭配类型提示：mypy 能检查协议兼容性，而运行时完全无成本
- 注意：不要在
interfaces.py里写逻辑或实例化对象，否则它自己可能变成新的循环中心
真正容易被忽略的是：循环导入往往不是孤立错误，而是设计气味（code smell）。比如你发现要靠延迟导入才能让测试跑通，或者每次加个新字段就得同步改三个模块的 import —— 那问题不在 import 语句本身，而在模块边界划错了地方。重构比打补丁更能省下下周的时间。
