Python跨文件循环依赖场景下如何正确添加类型注解？

原单文件可运行代码 #

以下代码在单个文件中可正常执行，输出结果为1：

from __future__ import annotations

class A(object):
    def __init__(self, val: int):
        self.val = val

    @property
    def b(self) -> B:
        return B(self)

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

a = A(val=1)
print(a.b.a.val)

拆分多文件后的循环导入问题 #

将A、B类拆分到不同文件后，出现循环导入错误：

文件uv_dataset.cvbnhxx.b2.py #

from uv_dataset.cvbnhxx.a2 import A

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

文件uv_dataset.cvbnhxx.a2.py #

from uv_dataset.cvbnhxx.b2 import B

class A(object):
    def __init__(self, val: int):
        self.val = val

    @property
    def b(self) -> B:
        return B(self)

a = A(val=1)
print(a.b.a.val)

运行时报错：

ImportError: cannot import name 'B' from partially initialized module 'uv_dataset.cvbnhxx.b2' (most likely due to a circular import) (/home/noam.s/src/uv_metadata/uv_dataset/cvbnhxx/b2.py)

解决方案 #

通过类型检查时导入和运行时延迟导入结合的方式解决：

修改后的a2.py #

from __future__ import annotations
from typing import TYPE_CHECKING

# 仅类型检查工具运行时执行此导入，避免模块加载时循环导入
if TYPE_CHECKING:
    from uv_dataset.cvbnhxx.b2 import B

class A(object):
    def __init__(self, val: int):
        self.val = val

    @property
    def b(self) -> B:
        # 运行时实际调用方法时才导入B，此时模块已加载完成
        from uv_dataset.cvbnhxx.b2 import B
        return B(self)

a = A(val=1)
print(a.b.a.val)

修改后的b2.py #

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from uv_dataset.cvbnhxx.a2 import A

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

关键说明 #

1. TYPE_CHECKING常量：来自typing模块，运行时取值为False，仅在类型检查工具（如mypy）工作时为True。将对方类的导入放在该条件块中，既满足类型注解需求，又不会触发模块加载时的循环导入。
2. from __future__ import annotations：Python 3.7+支持，让所有类型注解以字符串形式存储，模块加载时不会立即解析注解中的类名，避免因前向引用导致的导入错误。
3. 运行时延迟导入：在需要创建对方类实例的方法内部才执行导入，确保模块加载阶段不会互相依赖。

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