Python为互引用跨包类添加类型提示出现循环导入错误如何解决

你的操作遇到问题的核心原因是没有区分运行时导入和静态类型检查导入的差异：

• 直接在b.py中导入A会触发循环导入：Python运行时加载模块是同步执行的，a.py加载时会先导入b.py的B，而b.py如果反过来导入a.py的A，两个模块都在等待对方完成加载，就会抛出导入错误。
• 用NewType的方案无法解决问题：NewType是运行时生效的类型封装，定义A_type必须依赖已经加载完成的A类，你要在b.py中使用A_type还是得从a模块导入，本质还是没解决运行时的循环依赖问题。

两种通用方案都可以实现类型提示、同时避免循环导入，VS Code默认的Pylance类型检查器都能完美支持，获得自动补全能力：

方案1（推荐）：使用TYPE_CHECKING常量+延迟注释 #

Python 3.7及以上版本可以用from __future__ import annotations将所有类型注释转为字符串延迟求值，配合typing.TYPE_CHECKING常量实现仅类型检查阶段导入：
修改后的b.py代码如下：

from __future__ import annotations
from typing import TYPE_CHECKING

# 此代码块仅在静态类型检查时执行，运行时不会执行，不会触发循环导入
if TYPE_CHECKING:
    from a import A  # 如果是包结构就写从包顶级导入，比如from my_package import A

class B():
    def __init__(self, data, a_instance: A):
        self.data = data
        self.a = a_instance

这个方案的优势是类型提示写起来和普通类型没有区别，可读性最好。

方案2：直接使用字符串字面量类型注释 #

如果你的Python版本低于3.7，不需要额外导入任何内容，直接把类型提示写成字符串形式即可：
修改后的b.py代码如下：

class B():
    # 用字符串包裹A，类型检查器可以识别，运行时不会解析导入
    def __init__(self, data, a_instance: 'A'):
        self.data = data
        self.a = a_instance

这个方案不需要额外导入，兼容性更好。

针对你补充的实际场景：类定义在_a.py、_b.py，__init__.py负责导出类的结构，只需要把TYPE_CHECKING块里的导入路径改成从包的顶级导入即可，比如你的包名叫my_package，就写from my_package import A，类型检查器会自动匹配__init__.py中导出的A类，运行时不会触发导入逻辑，不会有循环问题。

内容的提问来源于stack exchange，提问作者Zilou