一文搞懂 python __init__.py 文件

多年大厂经验，努力构建 通俗易懂的、好玩的编程语言教程。 欢迎关注！你会有如下收益：

1. 了解大厂经验
2. 拥有和大厂相匹配的技术等

希望看什么，评论或者私信告诉我！

一、背景

python __init__.py 文件用过很多次了，一直没有系统性的总结一下，今天又用到了，刚好，好好总结一下

要知道在Python中，__init__.py文件是定义**包（Package）**的核心组件，它负责将目录转换为Python可识别的包结构

---

一、__init__.py的核心作用

1. 标识目录为Python包
   即使为空文件，目录中包含__init__.py也会被Python视为包（适用于Python 3.3之前的版本；3.3+支持"命名空间包"，无需此文件）。

2. 初始化包级代码
   当包被导入时，__init__.py中的代码会自动执行（例如：初始化变量、连接数据库）。

3. 控制模块导入

   • 批量导入：简化用户导入路径（例：from mypackage import func 而非 from mypackage.module import func）。
   • 定义__all__：指定from package import *时导入哪些模块。
   • 隐藏内部实现：可在__init__.py中导入公共接口，隐藏内部模块。

4. 共享包级变量/函数
   在__init__.py中定义变量、函数或类，可在包的多个模块间共享。

---

二、执行顺序示例

假设包结构如下：

lua

体验AI代码助手

代码解读

复制代码

mypackage/ ├── __init__.py # (1) ├── module1.py └── subpackage/ ├── __init__.py # (2) └── module2.py # (4)

当执行 import mypackage.subpackage.module2 时：

1. 先执行外层包初始化：mypackage/__init__.py (1)
2. 再执行子包初始化：mypackage/subpackage/__init__.py (2)
3. 最后导入目标模块：module2.py (4)

注意：导入过程中父包的__init__.py必然先于子包/模块执行。

---

三、进阶用法示例

下面通过一个完整的代码示例，演示如何在 __init__.py 中实现模块导入控制、定义 __all__ 和共享包级变量：

包结构

txt

体验AI代码助手

代码解读

复制代码

mypackage/ ├── __init__.py # 包初始化文件 ├── api.py # 公共API模块 ├── utils.py # 内部工具模块 └── algorithms/ ├── __init__.py # 子包初始化 ├── sorting.py # 排序算法 └── searching.py # 搜索算法

文件内容

1. utils.py (内部工具，不希望直接暴露)

python

体验AI代码助手

代码解读

复制代码

# mypackage/utils.py def log_info(message): """内部日志工具""" print(f"[INFO] {message}") def validate_input(data): """输入验证工具""" if not data: raise ValueError("输入数据不能为空") return True

2. sorting.py (排序算法)

python

体验AI代码助手

代码解读

复制代码

# mypackage/algorithms/sorting.py def quick_sort(arr): """快速排序实现""" pass def bubble_sort(arr): """冒泡排序实现""" pass

3. searching.py (搜索算法)

python

体验AI代码助手

代码解读

复制代码

# mypackage/algorithms/searching.py def binary_search(arr, target): """二分查找实现""" pass

4. algorithms/__init__.py (控制子包的导入)

python

体验AI代码助手

代码解读

复制代码

# mypackage/algorithms/__init__.py # 1. 批量导入 - 仅暴露公共API from .sorting import quick_sort as qsort from .searching import binary_search as bsearch # 2. 定义__all__ - 控制通配符导入 __all__ = ["qsort", "bsearch"] # 3. 共享子包级函数 def get_algorithm_version(): return "Algorithms v1.2.3"

5. api.py (公共API模块)

python

体验AI代码助手

代码解读

复制代码

# mypackage/api.py # 导入共享包级工具 from .utils import log_info, validate_input # 导入算法子包 from .algorithms import qsort, bsearch def process_data(data): """公共API - 处理数据""" # 使用共享工具 log_info("开始处理数据") validate_input(data) # 使用算法 sorted_data = qsort(data) index = bsearch(sorted_data, data[0]) log_info(f"处理完成，找到索引: {index}") return index

6. __init__.py (包主初始化)

python

体验AI代码助手

代码解读

复制代码

# mypackage/__init__.py # 1. 批量导入 - 简化用户导入路径 # 用户只需: from mypackage import process_data from .api import process_data # 2. 定义__all__ - 控制通配符导入 __all__ = ["process_data", "config", "show_version"] # 3. 隐藏内部实现 - 只暴露公共接口 # 内部模块不直接暴露 # 4. 共享包级变量/函数 # 包级配置 config = { "debug": False, "max_items": 1000 } def show_version(): """获取包版本""" return "mypackage v1.0.0" # 5. 共享子包功能 (通过子包的__init__.py) from .algorithms import get_algorithm_version

使用示例

用户代码 (简化导入路径)

python

体验AI代码助手

代码解读

复制代码

# 1. 直接使用包级函数 from mypackage import process_data, config, show_version data = [5, 2, 8, 3, 1] config["debug"] = True # 修改共享配置 print(f"Package version: {show_version()}") result = process_data(data) print(f"Result index: {result}") # 2. 使用子包功能 from mypackage.algorithms import qsort, get_algorithm_version print(f"Algorithm version: {get_algorithm_version()}") sorted_list = qsort([4, 2, 7, 1, 3]) print(f"Sorted list: {sorted_list}") # 3. 使用通配符导入 from mypackage import * # 只能导入 __all__ 中定义的内容 # process_data, config, show_version 可用 # utils, sorting 等内部模块不可直接访问

关键点说明

1. 导入路径简化

   • mypackage/__init__.py 导入 api.process_data → 用户直接 from mypackage import process_data
   • 用户无需知道函数在哪个具体模块

2. __all__ 控制

   • 主包中定义了 __all__ = ["process_data", "config", "show_version"]
   • 使用 from mypackage import * 时只导入这些成员
   • 子包同理：只暴露 qsort 和 bsearch

3. 隐藏内部实现

   • utils.py 是内部工具模块，用户无法直接访问
   • 算法实现细节封装在子模块中，只暴露简化接口

4. 共享包级资源

   • 变量：config 在包中共享
   • 函数：show_version() 包级函数
   • 子包共享：get_algorithm_version() 在算法子包中定义，主包中直接使用

5. 子包集成

   • 算法子包有自己的 __init__.py
   • 重命名导出 (quick_sort → qsort)
   • 控制子包级别的通配符导入

通过合理使用 __init__.py 可以创建:

• 更简洁的用户接口
• 更好的封装和模块化
• 共享的包级资源
• 可控的导入行为
• 清晰的架构分层

四、Python 3.3+的变化

• 命名空间包（Namespace Packages）：
  允许无__init__.py的目录作为包（通过多个路径组合包），但显式编写__init__.py仍是组织代码的最佳实践。
• 仍需要__init__.py的场景：
  初始化代码、定义__all__、简化导入路径等需求。

---

五、总结

特点	说明
执行时机	包被导入时立即执行，父包先于子包
核心用途	初始化包、简化导入、定义包接口、共享资源
现代项目实践	即使Python 3.3+支持命名空间包，显式使用__init__.py仍推荐用于非简单场景

通过合理利用__init__.py，可使包结构更清晰、导入更便捷，同时实现代码逻辑的封装与复用。