`__all__` 是一个**特殊的模块级（module-level）字符串列表**，用于**显式声明该模块通过 `from module import *` 语句时，允许被导入的公共名称（public names）**。 > ✅ 简单说：`__all__` 是模块作者写的“白名单”，告诉 Python：“当别人用 `from mymodule import *` 时，**只暴露这些名字**，其余全部隐藏”。 它**不是魔术方法**（不带括号、不被调用、不参与任何协议），而是一个**约定俗成的、被 Python 解释器和工具链（如 IDE、linter、文档生成器）尊重的特殊变量**。 --- ### 🔍 一、`__all__` 的基本语法与作用机制 #### ✅ 语法 ```python # mymodule.py __all__ = ['func_a', 'ClassB', 'CONST_X'] # 必须是字符串列表/元组 def func_a(): return "A" class ClassB: pass CONST_X = 42 # ❌ 这些不会被 from ... import * 导入（即使它们是 public） def _helper(): # 下划线开头 → 按惯例私有 pass INTERNAL_VAR = "secret" # 未在 __all__ 中 → 不导出 # ✅ 即使没在 __all__ 中，但若没加下划线，仍可能被 * 导入（见下文“默认行为”） def public_but_not_in_all(): pass ``` #### ✅ 使用效果 ```python # main.py from mymodule import * print(func_a()) # ✅ OK — 在 __all__ 中 print(ClassB()) # ✅ OK print(CONST_X) # ✅ OK # print(_helper()) # ❌ NameError: name '_helper' is not defined # print(INTERNAL_VAR) # ❌ NameError # print(public_but_not_in_all) # ❌ NameError（即使它是 public！因为不在 __all__ 中） ``` > ⚠️ 关键点：`__all__` **只影响 `from module import *`**；它对 `import module`、`from module import name` **完全无影响**： > ```python > import mymodule > print(mymodule.public_but_not_in_all) # ✅ 完全可以访问！ > > from mymodule import public_but_not_in_all > print(public_but_not_in_all()) # ✅ 也可以直接导入 > ``` --- ### 📜 二、`__all__` 的默认行为（即未定义 `__all__` 时） 如果模块**没有定义 `__all__`**，Python 对 `from module import *` 的处理规则是： 1. **过滤掉所有以下划线 `_` 开头的名称**（即 `_helper`, `_internal_var`）→ 视为“私有”，不导入； 2. **导入所有不以下划线开头的模块级名称**（函数、类、变量、常量等）； 3. **但会跳过由 `import` 语句导入的名称**（除非显式赋值），例如： ```python # mymodule.py （无 __all__） import os from math import pi def func(): ... CONST = 100 _private = "no" # from mymodule import * 会导入：func, CONST, pi（来自 math） # 但不会导入：os（因为只是 import os，未赋值给本地名），也不会导入 _private ``` ✅ 所以：`__all__` 的核心价值是——**打破默认的“所有非下划线名都可导入”的隐式规则，实现精确控制**。 --- ### 🛡️ 三、为什么强烈推荐显式定义 `__all__`？ | 原因 | 说明 | 示例风险 | |------|------|-----------| | ✅ **明确 API 边界** | 清晰告诉用户“哪些是稳定、受支持的公共接口”，哪些是内部实现细节（即使没加 `_`） | 若 `helper_util()` 是临时调试函数，未加 `_` 也未进 `__all__`，就不会意外泄露给用户 | | ✅ **防止意外导入污染命名空间** | `*` 导入本就危险（命名冲突、难以追踪来源）；`__all__` 是最后一道防线 | `from numpy import *` 会覆盖内置 `sum`，而 `from mylib import *` 若没 `__all__` 可能导入几十个未测试的函数 | | ✅ **提升工具链体验** | IDE（PyCharm、VS Code）自动补全、Sphinx 文档生成、mypy 类型检查均依赖 `__all__` 判断“什么是公共 API” | 未定义 `__all__` → Sphinx 可能文档化所有函数（包括私有），mypy 可能对未导出名报错 | | ✅ **支持重构安全** | 你可以放心重命名/删除 `__all__` 之外的函数，只要不破坏导出列表，就是向后兼容的 | `__all__ = ['load_config']` → 你可把内部 `parse_yaml()` 改成 `parse_toml()`，不影响用户 | > 💡 **最佳实践**： > - 所有**对外发布的库模块**（尤其是 `__init__.py`）**必须定义 `__all__`**； > - `__all__` 应按**字母序或逻辑分组**排列，便于维护； > - 避免在 `__all__` 中包含动态生成的名称（如 `globals().keys()`），破坏静态可分析性。 --- ### 🧩 四、`__all__` 在包（package）中的典型用法（`__init__.py`） 最常见场景：控制 `from mypackage import *` 或 `from mypackage import X` 的入口。 ```python # mypackage/__init__.py from .core import Engine, run_simulation from .utils import validate_input, format_output from .models import ModelA, ModelB # ✅ 显式导出：用户 from mypackage import * 只看到这些 __all__ = [ 'Engine', 'run_simulation', 'validate_input', 'format_output', 'ModelA', 'ModelB', ] # ❌ 不导出子模块本身（避免 from mypackage import core） # __all__ += ['core', 'utils', 'models'] # ← 一般不这么做 ``` 此时： - `from mypackage import *` → 导入 `Engine`, `run_simulation`, ...（6 个） - `from mypackage import core` → ❌ 报错（`core` 不在 `__all__` 中，且 `__init__.py` 没 `import core as core`） - `from mypackage.core import Engine` → ✅ 仍可直接导入（`__all__` 不限制此方式） > ✅ 进阶技巧：用 `__all__` 实现“扁平化 API”： > ```python > # mypackage/__init__.py > from .submodule1 import func1, func2 > from .submodule2 import ClassX > __all__ = ['func1', 'func2', 'ClassX'] # 用户无需知道它们在哪个子模块 > ``` --- ### ⚠️ 五、重要注意事项与常见误区 | 误区 | 正确理解 | 代码示例 | |------|-----------|------------| | ❌ `__all__` 控制 `import module` 行为 | ✅ **完全无关**。`import mymodule` 总是导入整个模块对象 | `import mymodule; mymodule._private_func()` 依然可调用 | | ❌ `__all__` 能让名字“真正私有”（运行时不可访问） | ✅ **不能**。它只是 `import *` 的过滤器，不提供封装或访问控制 | `from mymodule import *` 不导入 `_helper`，但 `import mymodule; mymodule._helper()` 仍可调用 | | ❌ `__all__` 中的名字必须已定义（否则报错） | ✅ **不会报错**，但会导致 `ImportError`（`name is not defined`） | `__all__ = ['missing']` → `from m import *` 时抛 `ImportError: cannot import name 'missing'` | | ❌ 字符串必须与变量名完全一致（区分大小写、拼写） | ✅ **必须完全一致**！`'MyClass'` ≠ `'myclass'` | `class MyClass: ...` → `__all__ = ['MyClass']` ✅；`['myclass']` ❌ | | ❌ 可以在函数内或 `if` 块中定义 `__all__` | ✅ **必须是模块顶层的全局变量**，且最好放在文件顶部附近 | `if True: __all__ = [...]` → ❌ 不被识别为 `__all__`（CPython 实现限制） | --- ### 🧪 六、验证 `__all__` 是否生效的小技巧 ```python # 在交互式环境或测试中 import mymodule print(mymodule.__all__) # 查看定义内容 print([x for x in dir(mymodule) if not x.startswith('_')]) # 所有非私有名 # 对比两者，确认是否严格一致 ``` 也可用 `help(mymodule)` 查看文档，现代工具（如 VS Code）悬停时会高亮 `__all__` 导出项。 --- ### ✅ 总结：`__all__` 是什么？一句话定位 > `__all__` 是 Python 模块中一个**由开发者显式声明的字符串列表**，它**唯一且明确地定义了 `from module import *` 所能导入的名称集合**，是构建清晰、稳定、可维护公共 API 的**关键约定和工程实践**，而非运行时强制访问控制机制。 它虽简单（只是一行列表），却是专业 Python 库开发的**标志性基础设施**——就像交通信号灯：不强制你停车，但明确定义了“谁可以通行”。 ---