一文搞懂 python __init__.py 文件

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

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中定义变量、函数或类，可在包的多个模块间共享。

---

二、执行顺序示例

假设包结构如下：

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__ 和共享包级变量：

包结构

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

文件内容

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

# 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 (排序算法)

# mypackage/algorithms/sorting.py

def quick_sort(arr):
    """快速排序实现"""
    pass

def bubble_sort(arr):
    """冒泡排序实现"""
   pass

3. searching.py (搜索算法)

# mypackage/algorithms/searching.py

def binary_search(arr, target):
    """二分查找实现"""
    pass

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

# 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模块)

# 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 (包主初始化)

# 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

使用示例

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

# 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，可使包结构更清晰、导入更便捷，同时实现代码逻辑的封装与复用。