Python __init__.py 文件详解

在 Python 的模块化体系中，init.py 是包（Package）结构中不可或缺的文件。它虽然看似只是一个空文件，但却承担着'标识、初始化与封装'的关键作用，是连接模块与包、工程化与抽象化的重要桥梁。

一、包与模块的关系

在理解 init.py 之前，必须先理解包（Package）与模块（Module）的区别与联系。

模块（module）：一个以 .py 结尾的 Python 文件，如 math.py、os.py。

包（package）：一个包含多个模块的文件夹，用于组织更复杂的代码结构。

一个最小的包应至少包含：

mypackage/
    __init__.py
    module1.py
    module2.py

说明：

在早期的 Python 版本中，没有 init.py 的文件夹不会被识别为包。从 Python 3.3 起，虽然技术上允许隐式命名空间包，但在绝大多数项目中仍建议显式编写 init.py，以确保结构清晰和兼容性良好。

二、init.py 的三大作用

（1）标识包的存在

Python 在导入模块时，会根据模块搜索路径（sys.path）查找对应文件。如果某个目录中包含 init.py，解释器就会将它视为一个包（Package）。

目录结构示例：

mypackage/
    __init__.py
    mathutils.py

导入示例：

import mypackage.mathutils

若缺少 init.py，旧版本解释器将无法识别 mypackage 为可导入的包。

（2）初始化包环境

当包被导入时，init.py 文件中的代码会自动执行一次，用于完成包级别的初始化工作。

例如：

• 导入常用子模块；
• 定义包级变量；
• 执行一次性配置；
• 打印导入提示或版本信息。

示例：

# mypackage/__init__.py
print("mypackage 正在加载...")
version = "1.0.0"

import mypackage
# 输出：mypackage 正在加载...
print(mypackage.version)

提示：

不要在 init.py 中放置与导入无关的耗时逻辑，否则会拖慢整个包的加载速度。

（3）定义包的公共接口（封装与导出）

包往往包含多个内部模块，但用户不必直接访问这些模块。

init.py 可以用来选择性地公开接口，让外部只看到对外暴露的部分。

目录结构：

mypackage/
    __init__.py
    mathutils.py
    stringutils.py

mathutils.py

 ():
     a + b