Python 包文档获取器

这个技能解决什么问题

翻 Python 包文档有三件烦心事：PyPI 项目页只告诉你包叫什么、有哪些版本，函数签名和参数说明基本不在那里；真正的 API 参考通常挂在 Read the Docs 之类的文档站点上，每个项目的结构又各不相同，想批量索引就得自己写爬虫；到了离线或网络受限的环境，连查一个函数签名都要先切回在线站点。

这个技能把「拿文档」和「读文档」拆成了两件事：先从 PyPI 元数据 API 与 Read the Docs API 拉取文档源，再用 ast 模块解析源码、用 pydoc 做运行时内省，把函数签名、docstring 和类型提示提取出来，最终落成一份可以离线查阅的索引。

它是怎么工作的

整体流程可以分成三个阶段：

• 拉取文档源：调用 PyPI 元数据 API 获取包的基本信息与文档地址，再走 Read the Docs API 拿到结构化的文档内容。
• 静态解析：用 ast 直接解析模块源码树，不需要导入包就能拿到函数签名和类型注解。
• 运行时内省：对当前环境里已经可以导入的模块走 pydoc 路径，补上静态解析拿不到的 docstring。

两条路径是互补的：ast 速度快，且不要求依赖真的装进环境；pydoc 能拿到作者写在文档字符串里的原始意图。

适用边界与注意点

• 静态解析看不到运行期才生成的信息，装饰器改写过的签名也会缺失，这类情况需要 pydoc 路径兜底。
• 内省这一步要求依赖在当前环境可导入，导入失败就什么都拿不到。
• 两个 API 都是上游服务，包名不存在、或文档没有托管在 Read the Docs 时会直接失败，调用方要自己处理异常。
• 提取结果只覆盖函数签名、docstring 与类型提示，不会生成教程性质的长文。