为何Python系统包会导入本地模块？实例解析与版本冲突担忧

问题场景 #

你遇到的是典型的Python模块命名与标准库冲突的问题：当你创建了名为email.py的脚本并导入smtplib时，smtplib尝试导入email.utils，但Python的导入机制优先找到了你的本地email.py而非标准库的email包，导致报错。

复现代码与错误如下：

~$ python -V
Python 3.11.5
~$ cat email.py
print("I AM BEING IMPORTED")
import smtplib

~$ python email.py
I AM BEING IMPORTED
I AM BEING IMPORTED
Traceback (most recent call last):
  File "/home/dh/email.py", line 2, in <module>
    import smtplib
  File "/usr/local/src/Python-3.11.5/Lib/smtplib.py", line 47, in <module>
    import email.utils
ModuleNotFoundError: No module named 'email.utils'; 'email' is not a package

原因解析 #

Python的导入路径（sys.path）中，当前工作目录的优先级高于标准库路径。当执行import email时，Python会先在当前目录查找email.py或email包，找到后就会停止搜索，因此标准库的email包被你的脚本“屏蔽”了。

针对未来冲突的预防方案 #

如果担心未来Python新增的标准库模块与你项目深层的本地模块冲突，可以采用以下几种实践：

• 给本地模块添加专属命名空间：不要直接使用顶级模块名，而是将所有业务模块放在一个自定义的根包下，比如把你的email.py改成myapp/email.py，导入时用from myapp import email。这样即使Python新增同名顶级模块，也不会和你的子模块冲突。
• 采用src布局管理项目：将项目代码放在src目录下，比如src/myapp/，通过setup.py或pyproject.toml安装项目。这种布局下，你的模块只会以myapp.xxx的形式被导入，不会出现在sys.path的顶级位置，从根源避免命名冲突。
• 避免使用通用模块名：尽量不用json.py、http.py这类容易和标准库/第三方库重名的文件名，改用更具业务特异性的名字，比如user_email.py、order_json.py。
• 跟踪Python版本更新：每次Python发布新版本时，查看官方文档的新增模块列表，提前在项目中排查是否有同名模块，及时重命名规避冲突。
• 使用绝对导入：在项目代码中尽量使用绝对导入（比如from myapp.utils import xxx）而非相对导入，同时避免在脚本中修改sys.path，防止打乱默认的导入优先级。

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