Repolode
Submit
mkdocstrings

mkdocstrings/griffe

Python tool that extracts the structure and signatures of a package to generate API docs or detect breaking API changes.

View on GitHubWebsite
Stars
704
Forks
81
Open issues
41
Last commit
15 days ago

What is it?

Griffe loads Python packages and builds a structured representation of their modules, classes, functions, and signatures without running the code. The result can be serialized to JSON or navigated from Python, which makes it useful as a data source for documentation generators.

The command-line interface provides two main commands. `griffe dump` exports the API of one or more packages as JSON, while `griffe check` compares the current code against a previous version and reports breaking changes such as altered parameter kinds. It can load a baseline from a git ref or from a published PyPI release, and it supports `src` layouts.

Griffe is installable with pip or uv. Its Python API exposes `load`, `load_git`, and `find_breaking_changes` for scripting checks or building custom tooling.

Key features

  • 01Extracts Python package structure and signatures statically.
  • 02Exports the API as JSON with `griffe dump`.
  • 03Detects breaking changes with `griffe check`, including against git refs.
  • 04Can compare against releases fetched from PyPI with the pypi extra.
  • 05Provides a Python API for loading packages and finding breaking changes.

Use cases

  • Generating API reference documentation for a Python library.
  • Catching unintended signature changes in CI before a release.
  • Comparing a new release against the previous version on PyPI.
  • Building custom tooling that inspects a codebase's public API.

Quick start

  1. 1

    Install Griffe with pip

    pip install griffe
  2. 2

    Dump the JSON-serialized API of a package

    griffe dump httpx fastapi
  3. 3

    Check a package for API breaking changes

    griffe check mypackage --verbose

Things to know

  • Checking packages from PyPI requires the optional pypi extra.

Topics

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

FAQ

What is griffe?
Python tool that extracts the structure and signatures of a package to generate API docs or detect breaking API changes. Griffe loads Python packages and builds a structured representation of their modules, classes, functions, and signatures without running the code. The result can be serialized to JSON or navigated from Python, which makes it useful as a data source for documentation generators.
Is griffe free to use? What license does it have?
griffe is open source under the ISC license. Check the license terms before using it in commercial products.
Is griffe still maintained?
Actively maintained. The last commit to griffe was on Oct 23, 2026.
What can I use griffe for?
Generating API reference documentation for a Python library. Catching unintended signature changes in CI before a release. Comparing a new release against the previous version on PyPI. Building custom tooling that inspects a codebase's public API.
How do I install griffe?
Install Griffe with pip: pip install griffe Dump the JSON-serialized API of a package: griffe dump httpx fastapi Check a package for API breaking changes: griffe check mypackage --verbose
Where can I get griffe?
The source code and installation instructions are on GitHub: https://github.com/mkdocstrings/griffe

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects