Python 包 API 表面映射器

解决什么问题

Python 包的公开 API 往往散落在源码、类型存根与运行时入口之间：手写文档容易过时，IDE 提示只看得到当前环境装上的部分，而很多第三方包缺少统一、带类型注解的参考页。当你在多项目里复用同一个库时，很难快速确认某个函数是否属于公开接口、参数有哪些类型约束、哪些实现只是内部细节。

技能如何工作

Python 包 API 表面映射器围绕静态解析与运行时内省两条路径构建 API 表面：

• 使用 ast 模块解析包源码，识别模块级定义、类、方法与函数签名，区分 __all__、双下划线名称与常规公开对象。
• 借助 importlib 进行导入内省，按实际加载结果核对可用名称、默认值与部分运行时才能确定的接口形状。
• 结合 mypy 存根（.pyi）中的类型注解，把参数、返回值、可选性等约束写入参考文档，而不是只罗列名称。
• 最终生成面向包使用场景的 API 参考，帮助开发者判断“可以调用什么”“类型上应如何约束”“哪些属于私有实现”。

适用边界与注意点

• 更擅长静态可解析的 Python 包；对运行时动态生成、装饰器大面积改写或依赖 C 扩展反射的 API，可能漏掉部分行为。
• 类型信息强依赖包是否提供 .pyi 存根；没有存根时，注解可能只覆盖源码中显式写出的部分。
• 映射结果适合作为工程参考与评审依据，但不应替代真实调用、文档站点与版本兼容性测试。
• 若包的公开接口以约定（例如命名规范、重导出策略）维护，需要结合项目自身约定一起解读。