__all__ 是界定 python 模块 public api 的核心机制，显式声明可导出的名称以承诺向后兼容；未列入者默认私有，即使无下划线也不得依赖。
Python 模块的 public API 怎么划边界
模块接口稳定性，本质是「哪些东西能放心用、哪些改了也不算破环」。关键不在文档写没写“稳定”，而在代码里怎么显式区隔：__all__ 是最轻量也最有效的信号——它不光控制 from module import *，更是对调用方的明确承诺：列表里的名字，只要 major 版本不变，就不删不重命名。
常见错误现象：__all__ 漏写、写成字符串（应为字符串列表）、或把内部工具函数也塞进去；更隐蔽的是没设 __all__，结果用户依赖了 _helper() 这种带下划线的函数，一升级就报 AttributeError。
实操建议：
产品介绍微趣能 Weiqn 开源免费的微信公共账号接口系统。MVC框架框架结构清晰、易维护、模块化、扩展性好，性能稳定强大核心－梦有多大核心就有多大，轻松应对各种场景！微趣能系统 以关键字应答为中心 与内容素材库 文本 如图片 语音 视频和应用各类信息整体汇集并且与第三方应用完美结合，强大的前后台管理；人性化的界面设计。开放API接口－灵活多动的API，万名开发者召集中。Weiqn 系统开发者AP
-
__all__必须显式声明，且只包含真正要暴露的函数、类、常量名 - 所有未列在
__all__中的顶层名字，默认视为私有（哪怕没加下划线） - 如果模块导出子模块（如
pkg.submod），__all__里得写"submod"，不能靠import submod自动暴露
版本升级时如何判断是否破坏兼容性
Python 没有编译期 ABI 检查，所以破坏常发生在运行时：参数顺序变、默认值删、返回类型变、抛错逻辑改。核心判断依据只有一个：签名（signature） + 行为（behavior） 是否对已有调用保持 silent 兼容。
立即学习“Python免费学习笔记（深入）”；
使用场景：发 v2.0 前做兼容性审计，不是看 diff，而是看老代码能否不改一行就跑通。
实操建议：
- 用
inspect.signature()对比新旧函数的参数名、顺序、默认值、*args/**kwargs存在性 - 检查文档中标注为 “deprecated” 的项，在下一个 major 版必须移除，不能拖
- 避免“看似安全”的改动：比如把
def f(x, y)改成def f(*, x, y)—— 调用f(1, 2)立刻失败
为什么 __version__ 和 __author__ 不该进 __all__
这些是元信息，不是接口。放进 __all__ 会导致 from mod import * 把它们导入到用户命名空间，污染作用域，还可能和用户变量冲突（比如用户自己定义了 __version__）。
性能影响虽小，但语义混乱：接口稳定性承诺的是“调用契约”，不是“模块元数据可见性”。__version__ 可以随时改格式（如从字符串变成 packaging.version.Version 对象），这不属于 breaking change。
实操建议：
-
__version__、__author__、__doc__这类全大写双下划线变量，一律不进__all__ - 需要读取版本时，教用户用
importlib.metadata.version("modname")或直接mod.__version__，而不是依赖from mod import *
动态生成的接口（如 getattr、__getattr__）怎么保稳定
这类接口天生难静态分析，用户可能写 mod.some_dynamic_thing 并当成稳定 API 用。一旦你改了 __getattr__ 的规则，或删了底层映射表，就是静默 break。
容易踩的坑：用 __getattr__ 实现插件式 API（如自动加载子模块），却没文档化哪些名字合法；或把调试用的动态属性（如 _debug_info）也响应了，结果被用户依赖。
实操建议：
- 凡走
__getattr__的访问，必须在 docstring 里明确列出支持的名字模式（如 “匹配r'^v\d+\.\d+$'的版本号字符串”） - 避免在
__getattr__里抛AttributeError以外的异常——否则用户hasattr()判断会意外中断 - 如果动态行为随配置变化（如环境变量开关），务必在文档中强调“此接口稳定性受
MOD_ENABLE_X控制”
接口稳定性的难点从来不在语法约束，而在于人怎么理解“这个东西我能不能放心用”。一个没写进 __all__ 的函数，即使文档里写了“推荐使用”，用户用了，你删掉它，就是 breaking change —— 无论你有没有标 deprecated。
