python工程结构及模块导入最佳实践

原文链接：https://www.cnblogs.com/harrymore/p/15989783.html

1. 工程结构

参考了一些博主和项目经验，总结出的一套比较通用的结构，如下：

FastPro/
|-- scripts/
|   |— run.sh
|-- logs/
|   |-- 2022-3-10.log
|-- src/
|   |-- tests/
|   |   |-- __init__.py
|   |   |-- test_main.py|   |-- main.py

|   |-— config.py
|-- docs/
|   |-- data_api.md

|   |-- syscfg.yaml
|-- setup.py
|-- requirements.txt
|—- README.md

scripts: 也可以命名为bin，存放一些可执行文件，如脚本，我一般用来存放项目的启停管理脚本。

logs: 存放日志文件。

src: 存放python源码，入口文件最好命名为main.py。网上也有建议不要直接命名为src的，因为我是使用vscode作为编辑器，一些补全和高亮代码等插件在寻找路径的时候会默认将src添加到路径中，如果用其他名字的话需要修改配置。

src/tests：存放单元测试脚本。

docs: 存放文档和配置文件。

setup.py: 项目安装脚本。

requirements.txt: 项目依赖。

README.md: 项目说明文件。

2. 模块导入的常见问题

在开发过程中，同事经常会反映找不到模块的问题。其实大部分是因为没有理解python的模块搜索路径。

关于模块搜索路径：

在执行python脚本的时候，当一个模块被导入的时候，解释器首先会去找内置模块，如果找不到再去sys.path的值中寻找是否有该模块。sys.path是一个环境变量，默认包括以下路径：

被调用脚本所在目录。
PATHONPATH目录：具体是PATHONPATH环境变量中配置的目录，是第二个被搜索的目录，Python会从左到右搜索PATHONPATH环境变量中设置的所有目录。
标准链接库目录：Python按照标准模块的目录，是在安装Python时自动创建的目录，譬如sitepackages。
路径文件中的路径：

在模块搜索目录中（脚本所在目录,…/sitepackages目录等），创建路径文件，后缀名为.pth，该文件每一行都是一个有效的目录。Python会读取路径文件中的内容，每行都作为一个有效的目录，加载到模块搜索路径列表中。简而言之，当路径文件存放到搜索路径中时，其作用和PYTHONPATH环境变量的作用相同。

一般在一些复杂的项目中，有些模块引用到其他项目的模块，有的人往往用.pth去添加搜索路径，但是这种做法是有问题的，问题在于不知道另外一个项目什么时候会被改动过。试过有同事把.pth放在标准库所在的sitepackges目录，有个模块突然就报错了，后面才发现引用了另外一个项目，那个项目又修改了一些东西。更好的办法是将子模块都放到当前的项目中。

说回搜索路径，正常情况下，项目入口为main.py，相当于把项目路径”FastPro/src” 加到搜索路径了，这个时候其他的模块都按照这个路径去导入模块即可：

main.py:

import sys
print("file:{},sys.path:{}".format(__file__, sys.path))
from mod1.my_api import print_date

if __name__ == "__main__":
    print_date()

my_api.py:

import config

def print_date():
    print("today is: ", config.start_date)

config.py:

start_date = "2022-3-10 11:59:35"

运行：python main.py，输出：

file:main.py, sys.path:[‘D:\\1-Work\\python_src\\python_egn\\src’, ‘…’, 此处省略多个路径]

today is: 2022-3-10 11:59:35

其中__file__为当前文件路径，后面会用到。

如果这个时候，如果my_api.py由另外一个人撰写，他想测试他的函数是否能够正常运行，直接在本文件进行测试：

import sys

print("file:{},sys.path:{}".format(__file__, sys.path))

import config

def print_date():
    print("today is: ", config.start_date)

if __name__ == "__main__":
    print_date()

在src目录下，运行：python python mod1/my_api.py

发现报错：

file:mod1/my_api.py,sys.path:['D:\\1-Work\\python_src\\python_egn\\src\\mod1',‘…’, 此处省略多个路径]
Traceback (most recent call last):
File "mod1/my_api.py", line 3, in <module>
import config
ModuleNotFoundError: No module named 'config'

可以发现搜索路径是在src/mod1，因此在这个目录下并没有发现config模块。

机智的小伙伴，可能会试着通过相对导入路径去导入上层的模块：

from ..config import start_date

如果这么做你会发现报另外一个错误：

ValueError: attempted relative import beyond top-level package

主要原因是越过当前目录，去找上级目录的包了，这样造成了报错。但是事情又不是这么简单，关于相对导入，其实python做得挺复杂的，譬如它有点像相对路径，但是不能引用不是包的目录；相对导入只适用于在合适的包中的模块，在顶层的脚本的简单模块中，它们将不起作用。这里不作展开，详情可以参考：使用相对路径名导入包中子模块。

聪明的做法是把测试逻辑全部放在tests模块中，譬如在tests目录中创建一个专门测试mod1模块的测试脚本：

test_mod1.py:

import sys
import os 
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from mod1.my_api import print_date

if __name__ == "__main__":
    print_date()