Python项目导入路径错误排查及标准化组织方案咨询

背景 #

参考Python导入路径相关内容后，决定不通过修改PYTHONPATH或sys模块做路径hack，寻求本地、Docker等环境通用的解决方案。当前项目结构如下：

sample/
    src/
        __init__.py
        package1/
            __init__.py
            module1.py
            module2.py
            
    tests/
        unit/
            __init__.py
            test_module1.py
            test_module2.py
    setup.cfg
    setup.py

src.package1.module2中定义了demo函数，src.package1.module1中使用from module2 import demo导入该函数。本地通过python3 -m pip install -e .安装后运行module1正常，但执行python -m unittest discover -s tests/unit -p "test_*.py"时，出现ModuleNotFoundError: No module named module1错误，错误源于src.package1.module1文件。

咨询问题 #

1. 此类Python项目的最佳组织方式及导入路径管理标准是什么？
2. 当前操作中的错误点在哪里？

1. Python项目最佳组织与导入路径管理标准 #

• 采用src布局结构：你当前的src/布局是行业通用的最佳实践，能明确区分源代码与配置、测试等文件，避免根目录混乱，同时更好适配打包工具。
• 优先使用绝对导入：项目内部模块间导入，优先用完整包路径，比如from package1.module2 import demo（需确保包已通过pip安装或被Python识别），清晰且不易出错。
• 用标准工具管理依赖与打包：通过setup.py（或现代项目推荐的pyproject.toml）配合pip管理，使用pip install -e .做可编辑安装，保证本地与容器环境的一致性，无需手动修改路径。
• 测试目录独立且用绝对导入：测试文件导入源代码模块时，使用完整包路径，确保测试运行时能正确定位模块。

2. 当前操作的错误点 #

• 模块内导入方式不符合Python 3规范：src.package1.module1中使用的from module2 import demo是隐式相对导入，Python 3已不推荐这种写法，且仅当模块作为包的一部分被导入时才有效。当unittest运行时，模块可能以脚本方式被加载，此时Python会将module1.py所在目录视为顶层目录，无法识别module2。
• （次要）测试环境的包识别问题：虽然做了可编辑安装，但如果测试文件导入模块的方式有误，或unittest运行环境未正确识别已安装的包，也会加剧问题，但核心原因还是模块内的导入写法错误。

修复方法：
将module1.py中的导入改为绝对导入：

from package1.module2 import demo

或显式相对导入（更适合包内部模块间引用）：

from .module2 import demo

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