解决Python中分叉库嵌套子模块的循环导入错误

项目目录结构 #

src/
├── script1.py
├── script2.py
└── doctr/
    ├── api
    ├── demo
    ├── docs
    ├── doctr/
    │   ├── contrib
    │   ├── datasets
    │   ├── file_utils.py
    │   ├── __init__.py
    │   ├── io
    │   ├── models
    │   ├── transforms
    │   ├── utils
    │   └── version.py

问题现象 #

在脚本中执行from doctr.doctr.models import ocr_predictor导入模块时，触发循环导入错误，错误信息如下：

ImportError: cannot import name 'VOCABS' from partially initialized module 'doctr.datasets' (most likely due to a circular import) (src/doctr/doctr/datasets/init.py)

已尝试的方案 #

• 在子模块根目录（src/doctr/）创建__init__.py文件，无效果
• 修改外层doctr目录名称，问题依旧

解决思路 #

1. 合并嵌套模块层级 #

当前嵌套的doctr/doctr结构会造成Python模块命名空间混乱，是引发问题的关键诱因。建议将内层doctr/doctr下的所有文件和目录直接移动到外层doctr/目录下，调整后的结构如下：

src/
├── script1.py
├── script2.py
└── doctr/
    ├── api
    ├── demo
    ├── docs
    ├── contrib
    ├── datasets
    ├── file_utils.py
    ├── __init__.py
    ├── io
    ├── models
    ├── transforms
    ├── utils
    └── version.py

调整后导入语句改为from doctr.models import ocr_predictor，既简化路径又避免命名冲突。

2. 使用延迟导入规避初始化冲突 #

如果无法调整目录结构，可将导入操作放在函数内部执行，避免模块初始化阶段的循环引用：

def run_ocr():
    # 仅在函数内部导入，推迟模块初始化时机
    from doctr.doctr.models import ocr_predictor
    predictor = ocr_predictor()
    # 后续业务逻辑

3. 修复子模块内部循环依赖 #

打开src/doctr/doctr/datasets/__init__.py，检查VOCABS的定义与导入逻辑：

• 确认是否存在models和datasets模块互相导入的情况
• 将交叉引用的内容抽取到独立的工具模块（如utils），让两个模块都从工具模块导入共享内容，打破循环链

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