绝对导入在pytest中生效但直接用Python运行时失败的问题

一、调整项目结构让直接运行脚本生效 #

直接运行python project_name/tests/test.py报错的核心原因是：Python会把test.py所在的project_name/tests目录当成顶层模块路径，而非外层的/project_name，因此找不到project_name这个包；而pytest会自动将项目根目录（/project_name）加入sys.path，所以能正常运行。

无需修改sys.path或PYTHONPATH的情况下，有两种合规的调整方式：

1. 调整测试目录位置到项目根目录 #

将tests目录从project_name子目录中移出，放到项目根目录下，最终结构如下：

/project_name/
├── project_name/
│   ├── __init__.py
│   └── utils/
│       └── __init__.py
└── tests/
    └── test.py

此时在/project_name目录下运行python tests/test.py，Python会将当前目录（项目根目录）作为顶层路径，绝对导入（比如import project_name.utils）就能正常识别。

2. 以模块方式运行包内测试脚本 #

如果要保留tests在project_name子目录内，不要直接运行脚本文件，而是用Python的模块运行方式：

python -m project_name.tests.test

这种方式会自动将项目根目录（/project_name）加入sys.path，完全符合绝对导入规范，无需额外配置。

二、PEP8关于脚本放置的规范与导入写法 #

PEP8没有强制的脚本位置规则，但有明确的最佳实践：

• 可执行脚本：建议放在项目根目录的独立目录中（比如bin/或scripts/），不要嵌入到主包（project_name/）内部，避免混淆包结构与脚本运行路径。
• 测试脚本：标准做法是放在项目根目录的tests/目录下，与主包同级，既保持主包的纯净性，也方便测试框架自动识别。

关于导入语句的编写：

• 始终遵循绝对导入规范，使用import project_name.module或from project_name.module import xxx的格式，只要项目根目录在Python的sys.path中（通过模块方式运行、pytest自动添加、或安装包后），就能正常导入。
• 对于根目录scripts/下的脚本，直接用绝对导入即可；若要更稳妥，也可以用python -m scripts.script_name的模块方式运行。

内容的提问来源于stack exchange，提问作者q.Then