Griffe

Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API.

Griffe, pronounced "grif" (/ɡʁif/), is a french word that means "claw", but also "signature" in a familiar way. "On reconnaît bien là sa griffe."

Installation

pip install griffe

With uv:

uv tool install griffe

Usage

Dump JSON-serialized API

On the command line, pass the names of packages to the griffe dump command:

$ griffe dump httpx fastapi
{
  "httpx": {
    "name": "httpx",
    ...
  },
  "fastapi": {
    "name": "fastapi",
    ...
  }
}

See the Serializing chapter for more examples.

Check for API breaking changes

Pass a relative path to the griffe check command:

$ griffe check mypackage --verbose
mypackage/mymodule.py:10: MyClass.mymethod(myparam):
Parameter kind was changed:
  Old: positional or keyword
  New: keyword-only

For src layouts:

$ griffe check --search src mypackage --verbose
src/mypackage/mymodule.py:10: MyClass.mymethod(myparam):
Parameter kind was changed:
  Old: positional or keyword
  New: keyword-only

It's also possible to directly check packages from PyPI.org (or other indexes configured through PIP_INDEX_URL). This feature is available to sponsors only and requires that you install Griffe with the pypi extra:

pip install griffe[pypi]

The command syntax is:

griffe check package_name -b project-name==2.0 -a project-name==1.0

See the Checking chapter for more examples.

Load and navigate data with Python

With Python, loading a package:

import griffe

fastapi = griffe.load("fastapi")

Finding breaking changes:

import griffe

previous = griffe.load_git("mypackage", ref="0.2.0")
current = griffe.load("mypackage")

for breakage in griffe.find_breaking_changes(previous, current):
    ...

See the Loading chapter for more examples.

mkdocstrings / griffe