griffe

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."

• User guide
• Contributor guide
• API reference

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.