如何在不合并文件的情况下解决Python循环导入问题

文件结构 #

- ./
    - child.py
    - parent.py
    - main.py

child.py 代码 #

from dataclasses import dataclass
from parent import Parent

@dataclass
class Child:
    name: str

    def get_mother(self) -> Parent:
        # 模拟从数据库查询...
        return Parent(
            name="Jane",
            children=[
                Child(self.name),
                Child("Alice"),
                Child("Bob"),
            ],
        )

parent.py 代码 #

from dataclasses import dataclass

from child import Child


@dataclass
class Parent:
    name: str
    children: list[Child]

main.py 代码 #

from dataclasses import dataclass

from child import Child

if __name__ == "__main__":
    Charles = Child("Charles")
    print(f"{Charles}'s mother is {Charles.get_mother()}")

问题 #

运行main.py会抛出循环导入异常，尝试将所有文件中的from xx import XX改为import xx仍无法解决；合并parent.py和child.py可解决问题，但并非理想方案。请问如何在不合并文件的情况下解决该循环导入问题？

运行异常信息 #

原导入方式的异常 #

python main.py

Traceback (most recent call last):
  File "d:\circular_import\main.py", line 3, in <module>
    from child import Child

修改导入方式后的异常 #

python main.py

Traceback (most recent call last):
  File "d:\circular_import\main.py", line 3, in <module>
    import child
  File "d:\circular_import\child.py", line 3, in <module>
    import parent
  File "d:\circular_import\parent.py", line 7, in <module>
    class Parent:
  File "d:\circular_import\parent.py", line 9, in Parent
    children: list[child.Child]
AttributeError: partially initialized module 'child' has no attribute 'Child' (most likely due to a circular import)

合并文件后的运行结果 #

python main.py

Child(name='Charles')'s mother is Parent(name='Jane', children=[Child(name='Charles'), Child(name='Alice'), Child(name='Bob')])

可行解决方案 #

1. 使用字符串类型注解+函数内延迟导入 #

这种方法利用Python对字符串类型注解的支持，避免模块加载时解析依赖，同时将导入移到函数内部，延迟到运行时再加载：

修改parent.py：

from dataclasses import dataclass

@dataclass
class Parent:
    name: str
    children: list["Child"]  # 用字符串代替直接引用类

# 可选：模块末尾补全导入，让类型检查工具正常识别
from child import Child
Parent.__annotations__["children"] = list[Child]

修改child.py：

from dataclasses import dataclass

@dataclass
class Child:
    name: str

    def get_mother(self) -> "Parent":  # 字符串注解避免提前解析
        # 模拟从数据库查询...
        from parent import Parent  # 函数内部延迟导入
        return Parent(
            name="Jane",
            children=[
                Child(self.name),
                Child("Alice"),
                Child("Bob"),
            ],
        )

2. 利用TYPE_CHECKING常量拆分导入与类型检查 #

TYPE_CHECKING是typing模块中的常量，仅在类型检查工具（如mypy）运行时为True，运行时为False，可以用来分离类型注解的导入和运行时逻辑：

修改parent.py：

from dataclasses import dataclass
from typing import List, TYPE_CHECKING

# 仅在类型检查时导入，运行时跳过
if TYPE_CHECKING:
    from child import Child

@dataclass
class Parent:
    name: str
    children: List["Child"]  # 字符串注解配合类型检查导入

修改child.py：

from dataclasses import dataclass
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from parent import Parent

@dataclass
class Child:
    name: str

    def get_mother(self) -> "Parent":
        from parent import Parent  # 函数内部延迟导入
        return Parent(
            name="Jane",
            children=[
                Child(self.name),
                Child("Alice"),
                Child("Bob"),
            ],
        )

3. 拆分公共类型到中间模块 #

创建一个中间模块（如models/common.py），将两个类的基础定义或类型引用统一管理，不过这种方式更适合复杂项目，简单场景前两种方法更轻便。

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