Python跨包导入模块报错及项目结构最佳实践咨询

先解决你的导入报错问题 #

你遇到的No module named 'src'错误，核心原因是Python解释器找不到src这个包——当直接运行test/testFunction1.py时，Python会把当前脚本所在的test目录加入搜索路径（sys.path），但不会自动把上层的repo目录加进去，因此无法定位到src。

临时快速解决有两种方式：

1. 在testFunction1.py开头添加代码，手动把repo目录加入搜索路径：

   import sys
   from pathlib import Path
   sys.path.append(str(Path(__file__).parent.parent))
   

   之后就能正常使用from src import function1。
2. 切换到repo目录下运行测试脚本：

   cd repo
   python -m test.testFunction1
   

   这种方式会把repo作为根目录加入搜索路径，自然能找到src包。

规范的Python项目结构最佳实践 #

对于小型到中型Python项目，推荐遵循以下结构（适配你的需求调整）：

repo/
├── src/
│   ├── mypackage/  # 用项目名作为核心包名，不要把src当作功能包
│   │   ├── __init__.py
│   │   └── function1.py
│   └── __init__.py  # 可空，也可用来声明包的对外接口
├── tests/  # 用复数形式tests，符合社区通用习惯
│   ├── __init__.py
│   └── test_function1.py  # 文件名用小写加下划线，符合PEP8规范
├── pyproject.toml  # 项目配置文件，替代传统setup.py管理依赖与构建
└── README.md

关键规范要点 #

• 包命名：源码目录下的核心包用项目名称（比如mypackage），src仅作为收纳源码的容器目录，不是实际功能包。
• 命名规范：模块名、测试文件名统一用小写加下划线，符合PEP8编码规范。
• 导入方式：测试文件中从项目核心包导入模块，比如在test_function1.py中：

  from mypackage.function1 import your_function  # 导入具体函数/类，避免用*
  

• 项目可安装配置：添加pyproject.toml配置项目可安装性，示例如下：

  [build-system]
  requires = ["setuptools>=61.0"]
  build-backend = "setuptools.build_meta"
  
  [project]
  name = "mypackage"
  version = "0.1.0"
  packages = ["src/mypackage"]
  package_dir = {"": "src"}
  

  在repo目录下运行pip install -e .，将项目安装为可编辑模式，之后无论在哪个目录都能直接导入mypackage，测试脚本也能正常运行。

规范的测试运行方式 #

推荐使用pytest作为测试框架（先通过pip install pytest安装），在repo目录下直接运行：

pytest tests/ -v

它会自动识别测试文件，且能正确定位项目包。

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