Repolode
提交项目
mkdocstrings

mkdocstrings/griffe

从 Python 包中提取结构与签名信息，用于生成 API 文档或检测破坏性接口变更的工具。

在 GitHub 查看官网
Star
704
Fork
81
未关闭 Issue
41
最近提交
15天前

这是什么？

Griffe 不执行代码，而是静态解析 Python 包，构建出模块、类、函数及其签名的结构化表示。结果可以导出为 JSON，也可以通过 Python 接口遍历，因此常被用作文档生成工具的数据来源。

命令行提供两个主要命令：`griffe dump` 将一个或多个包的 API 导出为 JSON；`griffe check` 将当前代码与旧版本对比，报告参数类型变化等破坏性改动。基线版本可以来自 git 引用，也可以直接从 PyPI 获取，并支持 `src` 目录布局。

项目可通过 pip 或 uv 安装。Python API 提供 `load`、`load_git` 和 `find_breaking_changes` 等函数，便于编写脚本或定制检查流程。

核心功能

  • 01静态提取 Python 包的结构与函数签名。
  • 02通过 `griffe dump` 将 API 导出为 JSON。
  • 03通过 `griffe check` 检测破坏性变更，可对比 git 历史版本。
  • 04安装 pypi 扩展后可直接与 PyPI 上的发布版本对比。
  • 05提供 Python 接口用于加载包并查找破坏性变更。

适用场景

  • 为 Python 库生成 API 参考文档。
  • 在发布前的 CI 中发现意外的签名变更。
  • 将新版本与 PyPI 上的上一个版本进行对比。
  • 开发检查代码库公共 API 的自定义工具。

快速上手

  1. 1

    使用 pip 安装 Griffe

    pip install griffe
  2. 2

    导出某个包的 JSON 序列化 API

    griffe dump httpx fastapi
  3. 3

    检查包的 API 破坏性变更

    griffe check mypackage --verbose

使用前须知

  • 从 PyPI 检查包需要安装可选的 pypi 额外依赖。

标签

#python#api-documentation#breaking-changes#static-analysis#developer-tools#docs#api#mkdocstrings-collector#parser#signature

常见问题

griffe 是什么？
从 Python 包中提取结构与签名信息，用于生成 API 文档或检测破坏性接口变更的工具。 Griffe 不执行代码，而是静态解析 Python 包，构建出模块、类、函数及其签名的结构化表示。结果可以导出为 JSON，也可以通过 Python 接口遍历，因此常被用作文档生成工具的数据来源。
griffe 可以免费使用吗？用的什么许可证？
griffe 以 ISC 许可证开源。用于商业产品前，请先确认许可证条款。
griffe 还在维护吗？
活跃维护中。griffe 最近一次提交是在 2026年10月23日。
griffe 适合用来做什么？
为 Python 库生成 API 参考文档。 在发布前的 CI 中发现意外的签名变更。 将新版本与 PyPI 上的上一个版本进行对比。 开发检查代码库公共 API 的自定义工具。
griffe 怎么安装和运行？
使用 pip 安装 Griffe: pip install griffe 导出某个包的 JSON 序列化 API: griffe dump httpx fastapi 检查包的 API 破坏性变更: griffe check mypackage --verbose
在哪里获取 griffe？
源代码和安装说明在 GitHub 上：https://github.com/mkdocstrings/griffe

概要由 AI 根据项目 README 生成；GitHub 数据每日更新。

相关项目