Python跨子目录导入失效求助：如何兼容内外调用场景？

一、不同目录调用表现不同的原因 #

1. 绝对导入（from utils.text_modification import ...）的问题 #

当你在sheetnum_classification目录内运行classify_sheetnum.py时，Python的当前工作目录是sheetnum_classification，它会优先在这个目录下查找utils包，所以导入成功。但从外层testing-framework目录调用时，当前工作目录变成了testing-framework，Python只会在这个目录和系统sys.path路径里找模块，找不到utils，因此报ModuleNotFoundError。

2. 相对导入（from .utils.text_modification import ...）的问题 #

相对导入是基于当前模块的包结构来定位的。如果直接在sheetnum_classification目录下运行classify_sheetnum.py，Python会把它当作顶层脚本（而非包的一部分），此时不允许使用相对导入，所以报错；而从外层导入时，classify_sheetnum.py是作为sheetnum_classification包的一个模块被加载，相对导入能正确识别包内的路径，因此生效。

二、兼容内部测试与外部调用的解决方案 #

方法1：将项目封装为可安装的包（推荐） #

这是Python项目的标准做法，能彻底解决路径问题：

1. 在testing-framework目录下创建setup.py文件，内容如下：

from setuptools import setup, find_packages

setup(
    name="sheetnum_classification",
    version="0.1",
    packages=find_packages()
)

2. 进入testing-framework目录，执行开发模式安装命令：

pip install -e .

这个命令会把sheetnum_classification包添加到Python的模块搜索路径中。
3. 修改classify_sheetnum.py中的导入语句为基于包的绝对导入：

from sheetnum_classification.utils.text_modification import TextModifications

4. 内部测试与外部调用统一使用包名导入：
   • 内部tests.ipynb：from sheetnum_classification.classify_sheetnum import ...
   • 外层ClassifySheetNumbers.ipynb：from sheetnum_classification.classify_sheetnum import ...
   • 如果需要直接运行classify_sheetnum.py，在文件末尾添加测试代码后，用以下命令运行（需在testing-framework目录下）：

     python -m sheetnum_classification.classify_sheetnum
     

方法2：临时修改sys.path（仅适合临时测试） #

在classify_sheetnum.py的开头添加以下代码，强制将sheetnum_classification目录加入模块搜索路径：

import sys
from pathlib import Path

# 获取当前文件所在的目录（sheetnum_classification）
current_package_dir = Path(__file__).parent
sys.path.append(str(current_package_dir))

之后不管在哪运行，from utils.text_modification import ...的导入都能生效，但这种方法不够规范，长期使用容易引发路径冲突。

方法3：统一使用相对导入+规范运行方式 #

1. 在classify_sheetnum.py中保留相对导入：

from .utils.text_modification import TextModifications

2. 内部运行时，不要直接执行python classify_sheetnum.py，而是回到testing-framework目录，用模块方式运行：

python -m sheetnum_classification.classify_sheetnum

3. 外层调用时，直接用包名导入：

from sheetnum_classification.classify_sheetnum import ...

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