Python包接口控制方法详解

`__all__` 是 Python 中专为 `from ... import *` 设计的导入白名单机制，仅在包的 `__init__.py` 中明确定义字符串列表时才生效——它严格控制该语句能导入哪些名称，但对 `import package` 或 `from package import name` 等显式导入完全无效；它不是访问控制或封装工具，不阻止用户直接访问未列入的属性，也不影响运行时行为，仅作为静态提示被 IDE 和类型检查器（如 mypy、pylint）用于补全与校验；正确使用需确保 `__all__` 中每个字符串都对应当前命名空间中真实存在的、已显式导入或定义的名称，避免带点号、动态生成或跨包误用，否则将导致静默失败或破坏接口稳定性——简言之，它是清晰传达“我期望你通过 `*` 导入什么”的契约，而非强制安全围栏。

直接说结论：在 __init__.py 中定义 __all__ 列表，是唯一可靠、显式控制 from package import * 导入内容的方式；但它对 import package 或 from package import name 完全无效。

为什么 __all__ 只影响 from ... import *

Python 的 from module import * 语义明确依赖 __all__：如果模块定义了它，就只导入列表中列出的名称；没定义则导入所有不以下划线开头的公有名称。但 import package 是导入模块对象本身，from package import func 是显式按名导入——这两种行为完全绕过 __all__ 检查。

• __all__ 不是访问控制机制，不能阻止用户直接访问未列在其中的属性
• 它不改变模块的命名空间，也不影响 dir(package) 的输出（除非你重写了 __dir__）
• IDE 和静态分析工具（如 mypy、pylint）会参考 __all__ 做补全和检查，但运行时无强制力

在 __init__.py 中正确声明 __all__

必须把 __all__ 放在 __init__.py 文件顶层，并且只包含字符串——这些字符串必须对应当前模块命名空间中**实际存在的、可被直接访问的名称**。

• 错误写法：__all__ = ["my_module.func"] —— __all__ 里不能带点号，只能是本地变量名
• 正确写法：先 from .submodule import func，再 __all__ = ["func"]
• 如果想导出子模块本身（如 package.utils），要先 import .utils，再 __all__ = ["utils"]
• 避免动态生成 __all__（比如用 globals().keys() 过滤），这会让静态分析失效，也难维护

示例 mylib/__init__.py：

from .core import process_data, validate
from .utils import format_timestamp
import .models
all = [
"process_data",
"validate",
"format_timestamp",
"models",  # 注意：这里导出的是 models 模块对象，不是其内部内容
]

常见误用与坑

最常踩的三个坑都跟“想当然地以为 __all__ 能限制一切”有关：

• 在 __init__.py 里写了 __all__ = ["A"]，但忘了 from .mod import A —— 结果 A 在命名空间里根本不存在，from mylib import * 会静默失败（不报错，但 A 没导入）
• 把私有函数（如 _helper）放进 __all__ —— 这等于主动把它变成“公开接口”，后续无法安全修改或删除
• 子包的 __init__.py 没设 __all__，但父包的 __init__.py 试图通过 from .sub import * 间接控制 —— 不生效，from .sub import * 的行为由 sub/__init__.py 的 __all__ 决定

真正起作用的边界永远在 __init__.py 文件自身的执行上下文里；跨文件的导入链不会继承或传递 __all__ 约束。别指望靠它做封装隔离，它只是个“导入清单提示器”。

好了，本文到此结束，带大家了解了《Python包接口控制方法详解》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！