Python包跨模块导入冲突：如何兼顾主程序运行与单独测试？

问题场景 #

文件夹结构：

person-package
|- __init__.py
|- person.py
|- person_manager.py
main.py

初始导入逻辑 #

• person_manager.py中导入person.py：

  import person as x
  

• main.py中导入person_manager.py：

  import person_package.person_manager as x
  

报错情况 #

1. 运行main.py时，出现：

   ModuleNotFoundError: No module named 'person'
   

2. 将person_manager.py的导入改为相对导入后：

   from . import person as x
   

   直接运行person_manager.py会报错：

   ImportError: attempted relative import with no known parent package
   

   无法单独测试person_manager.py。

优雅解决方法 #

方案1：绝对导入+模块方式运行测试 #

在person_manager.py中使用绝对导入，同时保留单独测试入口：

# person_manager.py
from person_package import person as x

# 单独测试逻辑
def test_person_manager():
    # 示例测试代码
    print("测试person_manager功能正常")

if __name__ == "__main__":
    test_person_manager()

优势：

• 运行main.py时，绝对导入能正常识别person模块
• 单独测试时，用模块方式运行而非直接执行脚本：

  python -m person_package.person_manager
  

  这种方式会自动把person-package的父目录加入Python路径，确保绝对导入生效，同时执行测试代码。

方案2：路径判断临时调整（快速测试用） #

如果不想用模块方式运行，可在person_manager.py开头添加路径判断，仅在直接运行脚本时临时调整Python路径：

# person_manager.py
import sys
from pathlib import Path

# 判断是否为直接运行脚本
if __name__ == "__main__":
    # 将当前文件的父目录的上级目录加入路径
    sys.path.append(str(Path(__file__).parent.parent))

# 使用绝对导入
from person_package import person as x

# 测试逻辑
def test_person_manager():
    print("测试person_manager功能正常")

if __name__ == "__main__":
    test_person_manager()

这种方式支持直接运行python person-package/person_manager.py，但仅适合本地临时测试，不建议在生产代码中依赖。

方案3：安装为可编辑包（长期开发推荐） #

对于长期维护的项目，最优雅的方式是通过配置文件将包安装为可编辑模式，让Python全局识别person_package：

1. 在项目根目录（与main.py同级）创建pyproject.toml：

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "person_package"
   version = "0.1.0"
   

2. 用pip安装为可编辑模式：

   pip install -e .
   

完成后，无论运行main.py、直接执行person_manager.py，还是在任意位置导入person_package下的模块，都能正常工作，彻底解决导入冲突。

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