Python 模块 __init__.py 中导入语句与 __all__ 用法详解

本文旨在对以下代码进行逐行逐 token 的详细解析，展示每个部分的作用和意义，帮助读者深入理解 Python 包的初始化文件如何控制导入行为与命名空间：

from .system_info import get_system_hardware_info

__all__ = ['get_system_hardware_info']  # 控制 * 导入行为

文中首先对整体代码进行概览，然后逐 token 说明每个单词或符号的作用，最后结合真实项目示例提供完整、可独立运行的源码示例。通过本文解析，读者能够清晰掌握相对导入、Python 包初始化文件与 __all__ 机制的实用场景，并在实际项目中灵活运用。(geeksforgeeks.org, geeksforgeeks.org)

代码整体概览

代码中包含两行核心内容，分别是导入语句与 __all__ 声明：

from .system_info import get_system_hardware_info

__all__ = ['get_system_hardware_info']  # 控制 * 导入行为

第一行采用相对导入的方式，将 system_info 模块中的 get_system_hardware_info 函数引入当前包命名空间。(geeksforgeeks.org, stackoverflow.com)
第二行定义了模块级别的 __all__ 列表，用于控制当用户使用 from package import * 时，哪些名字会被导入到目标命名空间。(stackoverflow.com, geeksforgeeks.org)

逐行逐 Token 详细解析

第一行：from .system_info import get_system_hardware_info

Token from

• from 是 Python 中导入语句的关键字之一，用于指示从某个模块或包中引入特定名称到当前命名空间。(geeksforgeeks.org)

• 与简单的 import module_name 不同，from module_name import name1, name2 允许只导入特定名称，避免一次性加载整个模块，提高代码清晰度。(geeksforgeeks.org)

Token .

• 在此处 . 表示“当前包”的前缀，属于 Python 中的相对导入语法(geeksforgeeks.org, stackoverflow.com)。

• 使用单个 . 表示从当前包所在目录开始查找，在包结构中能够保证引用的是同级或子级模块，而不是全局包。(geeksforgeeks.org)

Token system_info

• system_info 是一个同级模块（或子包）名称，通常对应同级目录下的 system_info.py 文件。(geeksforgeeks.org)

• 该模块负责封装获取系统硬件信息的函数与逻辑，比如 CPU、内存、磁盘等相关信息。(geeksforgeeks.org)

Token import

• import 关键字用于将指定名称从目标模块或包导入到当前命名空间。(geeksforgeeks.org)

• 在这里，import get_system_hardware_info 意味着只将该函数对象引入当前模块，而不是整个 system_info 模块，降低命名空间污染风险。(geeksforgeeks.org)

Token get_system_hardware_info

• 这是一个函数名称，定义在 system_info.py 中，其功能通常是扫描并返回系统硬件信息，如 CPU 数量、频率、内存占用等。(geeksforgeeks.org, stackoverflow.com)

• 通过直接导入该函数，用户在当前包（即 tools 包）中可以直接使用 tools.get_system_hardware_info()。(geeksforgeeks.org, stackoverflow.com)

真实世界案例 1：相对导入避免命名冲突

假设项目中存在多个同名模块，比如全局安装有一个 system_info 包，而本地又有一个 system_info.py。若直接写 import system_info，可能会导入全局包而非本地实现。
使用 from .system_info import get_system_hardware_info 确保引用的是项目本地目录下的模块，从而避免名称冲突。(stackoverflow.com, geeksforgeeks.org)

真实世界案例 2：按需导入提升性能

如果 system_info.py 中除了 get_system_hardware_info 外还有其他工具函数，直接 from .system_info import get_system_hardware_info 可以避免将那些不必要的函数或类加载进来，有助于减少内存占用与缩短启动时间。(geeksforgeeks.org, geeksforgeeks.org)

---

第二行：__all__ = ['get_system_hardware_info'] # 控制 * 导入行为

Token __all__

• 在 Python 中，__all__ 是一个特殊变量，通常定义为字符串列表，用于指定当执行 from module import * 时哪些名字可以被导入。(stackoverflow.com, geeksforgeeks.org)

• 如果模块（或包）没有定义 __all__，执行 from module import * 会默认导入所有不以下划线 _ 开头的全局名称。(geeksforgeeks.org)

针对包级别的特点

• 在包的 __init__.py 中定义 __all__，用于指定从该包导入时，哪些子模块或名称会被加载。(stackoverflow.com, geeksforgeeks.org)

• 如果省略包级别的 __all__，执行 from package import * 时，不会自动导入任何子模块，只有包内 __init__.py 中定义的名称会被加载。(stackoverflow.com)

Token =

• 赋值运算符，用于将右侧表达式的值绑定到左侧名称。

• 这里将列表 ['get_system_hardware_info'] 绑定到名称 __all__，从而明确声明可公开导出的名称。(geeksforgeeks.org)

Token ['get_system_hardware_info']

• 这是一个 Python 列表，元素为单个字符串 'get_system_hardware_info'。(geeksforgeeks.org)

• 列表中的每个字符串对应一个可公开导出的名称，当执行 from package import * 时，仅会导入列表中列出的那些名称。(stackoverflow.com, geeksforgeeks.org)

真实世界案例 3：精细化控制公共 API

在大型项目中，为了隐藏内部实现细节，仅向外部暴露必要函数或类，可以在包级别的 __init__.py 里通过 __all__ 精确声明“公开”接口。例如，一个数据分析库可能只想公开 load_data、analyze、plot，而其他内部辅助函数则不暴露。(geeksforgeeks.org, medium.com)

真实世界案例 4：安全与命名空间管理

如果不使用 __all__，from package import * 会导入包内所有公共名称，可能包含敏感或过多内容，造成潜在的命名冲突与泄露。通过显式列出安全、稳定的公共名称列表，能够在团队协作和版本发布过程中减少风险。(geeksforgeeks.org, reddit.com)

---

真实项目示例：构建 tools 包

为了将上文解析具体化，下面以一个简单的 tools 包为例，演示如何组织目录、编写 system_info.py 与 __init__.py，并通过多种方式导入使用 get_system_hardware_info 函数。

包结构

project_root/
├── tools/
│   ├── __init__.py
│   └── system_info.py
└── main.py

• project_root/：项目根目录。

• tools/：自定义的工具包目录。

• tools/system_info.py：实现系统硬件信息获取逻辑的模块。

• tools/__init__.py：包初始化文件，负责导入公共 API 并声明 __all__。

• main.py：项目入口脚本，演示如何导入并使用 tools 包。 (geeksforgeeks.org, geeksforgeeks.org)

tools/system_info.py 内容

import platform
import psutil
import json

def get_system_hardware_info() -> str:
    """
    获取系统硬件信息，返回 JSON 格式的字符串，包含 CPU、内存、磁盘等信息
    """
    info = {}

    # CPU 信息
    info['cpu_count_logical'] = psutil.cpu_count(logical=True)
    info['cpu_count_physical'] = psutil.cpu_count(logical=False)
    cpu_freq = psutil.cpu_freq()
    info['cpu_freq'] = cpu_freq._asdict() if cpu_freq else {}
    info['cpu_percent'] = psutil.cpu_percent(interval=1)

    # 内存信息
    mem = psutil.virtual_memory()
    info['memory_total'] = mem.total
    info['memory_available'] = mem.available
    info['memory_percent'] = mem.percent

    # 磁盘信息
    disks = []
    for part in psutil.disk_partitions():
        usage = psutil.disk_usage(part.mountpoint)
        disks.append({
            'device': part.device,
            'mountpoint': part.mountpoint,
            'fstype': part.fstype,
            'total': usage.total,
            'used': usage.used,
            'free': usage.free,
            'percent': usage.percent
        })
    info['disk_partitions'] = disks

    # 返回 JSON 字符串
    return json.dumps(info, indent=2, ensure_ascii=False)

• import platform：标准库 platform 可用于获取操作系统类型、Python 版本等信息（示例中未使用，但常见于扩展功能）。(geeksforgeeks.org)

• import psutil：第三方库，用于获取 CPU、内存、磁盘、网络等系统资源信息。(geeksforgeeks.org)

• import json：标准库 json 用于将字典序列化为 JSON 格式字符串。(geeksforgeeks.org)

• 定义 get_system_hardware_info 函数，内部分别获取 CPU、内存、磁盘等指标，并封装到字典 info 内，然后将其以 JSON 格式字符串返回。(geeksforgeeks.org)

• 示例代码展示了如何通过 psutil.cpu_freq()._asdict() 获取 CPU 频率信息并转换为字典格式。(geeksforgeeks.org)

该模块可以独立运行并在终端中打印信息，也可以被其他模块导入复用。(geeksforgeeks.org)

tools/__init__.py 内容

from .system_info import get_system_hardware_info

__all__ = ['get_system_hardware_info']  # 控制 * 导入行为

• from .system_info import get_system_hardware_info：相对导入，将同级模块 system_info 中的函数导入到包根命名空间。这样使用时可以写 tools.get_system_hardware_info()。(geeksforgeeks.org, stackoverflow.com)

• __all__ = ['get_system_hardware_info']：声明当用户执行 from tools import * 时，只导入名称 get_system_hardware_info，而不加载其他未在列表中的名称（若有）。(stackoverflow.com, geeksforgeeks.org)

main.py 内容

# coding: utf-8

# 直接导入包，调用时需要指定完整路径
import tools

if __name__ == '__main__':
    # 使用工具包中的函数获取系统硬件信息
    info_json = tools.get_system_hardware_info()
    print('系统硬件信息 (JSON 格式)：')
    print(info_json)

    # 演示使用 from ... import 方式
    from tools import get_system_hardware_info as get_info
    print('\n使用别名导入后的系统硬件信息：')
    print(get_info())

• import tools：导入 tools 包时，会执行 tools/__init__.py，因而 get_system_hardware_info 函数会被加载到 tools 命名空间。(geeksforgeeks.org)

• tools.get_system_hardware_info()：调用相对导入的函数，获取并打印系统信息。(geeksforgeeks.org)

• from tools import get_system_hardware_info as get_info：显式导入包中的指定函数，并为其起别名 get_info，然后调用。(geeksforgeeks.org)

• 由于 __all__ 声明了 get_system_hardware_info，即使使用 from tools import * 也只会导入该函数。(stackoverflow.com, geeksforgeeks.org)

完整项目示例可复制到本地目录，并安装 psutil（命令：pip install psutil），然后运行 python main.py 验证功能。(geeksforgeeks.org, geeksforgeeks.org)

---

总结

通过对以上两行代码的逐行逐 token 分析与真实项目示例，本文深入阐明了以下要点：

• 相对导入 (from .module import name)：

  • 单个 . 表示从当前包开始查找，保证引用的是项目本地模块，避免与全局包同名冲突。(stackoverflow.com, geeksforgeeks.org)

  • 相对导入可以提高代码可维护性，并且在重构项目结构时更安全。(geeksforgeeks.org, geeksforgeeks.org)

• __init__.py 的作用：

  • 标记目录为 Python 包，使得解释器能够识别并加载该目录下的模块。(geeksforgeeks.org)

  • 可以在其中编写包级别初始化代码或聚合多个子模块的 API。(geeksforgeeks.org, discuss.python.org)

• __all__ 机制：

  • 在模块或包级别声明可公开导出的名称列表，主要用于控制 from module_or_package import * 导入行为。(stackoverflow.com, geeksforgeeks.org)

  • 仅列出在 __all__ 中的名称会被导入到调用方的命名空间，从而避免内部实现细节泄露。(geeksforgeeks.org, medium.com)

  • 如果省略包级别的 __all__，执行 from package import * 时不会自动导入任何子模块，只有 __init__.py 中明确列出的名称会被加载。(stackoverflow.com, discuss.python.org)

• 示例实战：

  • 通过 tools/system_info.py 定义硬件信息获取逻辑，tools/__init__.py 中按需导入并声明 __all__，main.py 演示多种导入方式，有助于读者快速掌握包级别初始化与导入机制。(geeksforgeeks.org, geeksforgeeks.org)

理解上述概念后，读者可以在构建自己的 Python 包或库时，合理利用相对导入与 __all__，实现更清晰、可维护的项目结构，并根据实际需求精确控制公共 API 的暴露，避免命名冲突与无意间泄露内部实现细节。(geeksforgeeks.org, geeksforgeeks.org)