小问题大隐患:如何正确设置 Python 项目的入口文件?

今天在公众号粉丝群里面,有一位同学提到了 Python 找不到模块的问题:

问题涉及到的代码结构和代码截图如下:

这个问题的解决方法非常简单,就是把start.py文件从bin文件夹移出来就好了。

但如果对这个问题进一步分析,可以看到更多问题。

在我以前的文章:为什么Python代码能运行但是PyCharm给我画红线?中,我讲到了工作区(Workdir)对代码的影响。PyCharm、VSCode 识别的工作区,可能并不等于你直接在终端窗口运行.py文件时候的工作区。

今天这个问题本质上也是工作区导致的问题。 这个同学的项目根目录是MY_API,所以他使用的编辑器VSCode 就会默认把MY_API当做工作区。所以,当他在start.py文件中写上from lib.interface import server时,VScode 并不会给他标记红色波浪线。因为从 VSCode 的视角看,lib文件夹确实就是在工作区下面的。

但是,当他在 VSCode 里面运行这个start.py文件时,Python 是从bin文件夹下面运行的。此时,Python 会把bin文件夹当做工作区。在工作区里面就只有这一个start.py文件,所以当然找不到lib文件夹。

如果仅仅从技术上来说,你非要导入 bin 文件夹的父文件夹下面的其他模块,也并不困难,我在一日一技:导入父文件夹中的模块并读取当前文件夹内的资源一文中讲到了具体的做法。

但问题在于,你不应该这样做。你不应该把项目的入口文件,放到项目内部很深的文件夹中。

所谓入口文件,就是要首先经过它,才能到达其他的文件。当你拿到一个 Python 项目,你只需要首先从入口文件开始阅读代码,根据入口文件调用的模块,一路看下去,你就能读到它的所有实现逻辑。

但如果大家经常逛 Github,就会发现,有些人可能是被其他垃圾语言污染了思想,他的 Python 项目,根目录有五六个文件夹和七八个.py文件。你拿到这个项目的时候,你甚至不知道,当你想运行这个代码的时候,python3 xxx.py应该运行哪个文件。你多方打听,或者看了半天文档,才知道,哦,原来入口文件在com/xx/yy/zz/script/run.py

当你打开这个run.py文件,你发现它的顶部,文件导入的代码写的是from ../../../../aaa import bbb

简直是神经病写法。我知道有些垃圾语言流行这样写。但现在你用的是 Python,学聪明一点,别那样写。

对于一个 Python 项目来说,入口文件应该始终在最外层。例如:

当你要启动这个项目的时候,直接在最外层python3 main.py,就能把它启动起来。在main.py里面,你可以导入其他模块,然后调用其他模块里面的类或者函数。

这样做的好处是什么?这样做,你是在项目的根目录启动的这个项目,所以你的工作区就是项目的根目录。那么你在任何一个.py文件里面都可以很容易地基于工作区导入任意其他文件。例如,你现在在models/mongo-util/mongob_helper.py文件中,你想导入utils/abc.py中的time_format()函数,那么,你只需要这样写就可以了。

1
from utils.abc import time_format

你根本不可能出现需要导入父文件夹中的某个模块的情况。

只有工具脚本,才需要单独使用一个文件夹来存放,然后调用父文件夹中的其他文件。例如,我现在有一个工具脚本,它每天晚上0点会读写 MongoDB,清理无效数据,那么此时,我可以在根目录单独创建一个scripttools或者bin文件夹,然后把工具脚本放进去,例如:

在这个工具脚本里面,你可能会调用models/mongo-util/mongob_helper.py文件中的某个函数。这种情况下,你调用父文件夹中的内容是可以接受的。但这毕竟只是工具脚本。

可能还有同学要问,那如果我的项目是一个 Python 的包,它本身没有入口文件怎么办呢?这个时候,你可以把这个包的__init__.py当做它的入口文件。大家可以参考我在 GitHub - kingname/GeneralNewsExtractor: 新闻网页正文通用抽取器 Beta 版.的代码组织结构。在项目根目录留下一个example.py文件,用来演示如何调用这个包。而这个包本身的代码,是在一个叫做gne的文件夹中的。这个gne文件夹是一个包,它的入口文件在__init__.py中。

各位,当你写代码的时候,你先想一想,如果别人拿到了你的代码,想要梳理一下这个项目的逻辑,在不询问你的情况下,怎么让他知道应该从哪个文件开始读?应该按什么顺序读?他能不能轻易地看到数据在你的代码中是怎么运转的?

谢乾坤 | Kingname wechat
第一时间获取最新文章更新,请订阅我的微信公众号:未闻Code