如何调整Python包子模块结构以解决循环导入错误？

问题背景 #

包结构如下：

clairvoyance
|-- __init__.py
|-- bayesian
|   |-- __init__.py
|   `-- bayesian.py
|-- legacy
|   |-- __init__.py
|   `-- legacy.py
|-- utils
|   |-- __init__.py
|   `-- utils.py
`-- visuals
    |-- __init__.py
    `-- visuals.py

相关文件内容：

• clairvoyance/__init__.py：

__version__ = "2024.6.17"

from . import bayesian
from . import legacy
from . import utils
from . import visuals

• 各子模块的__init__.py均为from .[模块名] import *格式。

相对导入情况：

• utils.py无导入；
• bayesian.py包含from ..utils import *；
• legacy.py包含from ..utils import *和from ..visuals import *；
• visuals.py包含from ..utils import *。

报错信息：

ImportError: cannot import name 'bayesian' from partially initialized module 'clairvoyance' (most likely due to a circular import) (/Users/jolespin/miniconda3/envs/soothsayer_env/lib/python3.9/site-packages/clairvoyance/__init__.py)

问题分析 #

虽然没有直接的模块互导循环，但顶层__init__.py的导入顺序和子模块的依赖关系结合，形成了隐式的初始化顺序冲突：

1. 顶层先导入bayesian，bayesian依赖utils，此时触发utils导入；
2. 接着导入legacy，legacy依赖visuals，触发visuals导入，visuals又依赖已初始化的utils；
3. 整个过程中顶层clairvoyance模块尚未完成全部导入，当子模块的导入逻辑回溯到顶层时，就会出现“部分初始化”的错误。

解决方案 #

方案1：调整顶层导入顺序 #

优先导入被依赖的模块，确保所有依赖项在使用前完成初始化。修改clairvoyance/__init__.py：

__version__ = "2024.6.17"

# 先导入无依赖的utils
from . import utils
# 导入被legacy依赖的visuals
from . import visuals
# 导入仅依赖utils的bayesian
from . import bayesian
# 最后导入依赖utils和visuals的legacy
from . import legacy

方案2：延迟导入 #

将子模块的依赖导入移至函数/方法内部，而非模块顶部。例如修改legacy.py：

# 移除顶部的from ..visuals import *

def some_function_using_visuals():
    from ..visuals import *
    # 后续使用visuals的代码

方案3：优化子模块__init__.py导入 #

避免通配符导入，改为明确导入需要的对象，减少潜在冲突。例如bayesian/__init__.py：

from .bayesian import BayesianModel, some_bayesian_function  # 替换为实际需导出的对象

内容的提问来源于stack exchange，提问作者O.rka