__all__仅控制from module import *的导入范围，不提供访问控制；它是向用户声明公共API的约定，影响IDE补全、文档生成和类型检查，但无法阻止显式导入或点号访问。
__all__ 只影响 from module import * 的行为
很多人误以为 __all__ 能限制所有导入方式，其实它只对 from module import * 生效。直接 import module 后用 module.func，或 from module import func 都完全不受 __all__ 约束——Python 解释器根本不会检查它。
这意味着：__all__ 是一种“礼貌性声明”，不是访问控制机制。它的实际作用是告诉使用者：“这些是模块作者明确推荐的公共接口”，同时让 IDE、文档生成工具（如 Sphinx）和静态分析器（如 mypy）能更准确地识别导出内容。
定义 __all__ 的常见错误写法
最常踩的坑是把 __all__ 放错位置或类型不对：
-
__all__必须是模块顶层的list或tuple，且元素必须是字符串 —— 写成__all__ = [my_func]（变量名未加引号）会直接报NameError - 在
if __name__ == "__main__":块里定义__all__无效，它必须在模块全局作用域 - 动态生成时（比如遍历
dir()过滤），容易漏掉双下划线方法或引入私有名，不推荐
正确写法示例：
def public_func():
return "ok"
<p>def _private_helper():
return 42</p><p>class PublicClass:
pass</p><p><strong>all</strong> = ["public_func", "PublicClass"] # 字符串列表，不含 _private_helper
</p>
与 from ... import ... 的组合行为
当模块 A 定义了 __all__ = ["foo"]，而模块 B 执行 from A import *，B 中只会得到 foo；但若 B 写的是 from A import foo, _private_helper，即使 _private_helper 不在 __all__ 里，也能成功导入并使用。
更隐蔽的问题出现在子模块重导出场景：
- 如果
pkg/__init__.py中写from .submod import func但没把func加入自己的__all__，那么from pkg import *就不会包含func - 要实现“透传导出”，得显式写
__all__ = ["func"]或__all__ = submod.__all__（前提是 submod 本身定义了__all__）
__all__ 对打包和类型检查的实际影响
虽然运行时不强制，但在工程实践中它直接影响下游体验：
- PyPI 包发布时，
__all__是pyright和mypy推断模块公共 API 的主要依据；缺省时工具可能把所有顶层名称都当作可导出项，导致误报“未声明的导入” - 打包成 wheel 后，IDE 的自动补全（如 VS Code 的 Pylance）依赖
__all__缩小候选范围，否则会列出大量内部函数和测试变量 - 如果模块用了
__getattr__实现懒加载，__all__还需手动维护，否则from mod import *无法触发懒加载逻辑
所以别把它当成可选装饰——只要模块有明确的对外接口边界，__all__ 就该和函数、类一起被写进源码，且每次增删接口时同步更新。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
