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

With pip:

pip install griffe

With pipx:

python3.8 -m pip install --user pipx
pipx install griffe

Usage

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 Dumping data section for more examples.

Or 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

See the API breakage section for more examples.

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 data section for more examples.

Todo

Extensions
- Post-processing extensions
- Third-party libraries we could provide support for:
  - Django support
  - Marshmallow support
  - Pydantic support
Docstrings parsers
- epydoc
- New Markdown-based format? For graceful degradation
Serializer:
- Flat JSON
API diff:
- Mechanism to cache APIs? Should users version them, or store them somewhere (docs)?
- Ability to return warnings (things that are not backward-compatibility-friendly)
- List of things to consider for warnings
  - Multiple positional-or-keyword parameters
  - Public imports in public modules
  - Private things made public through imports/assignments
  - Too many public things? Generally annoying. Configuration?
- Ability to compare two APIs to return breaking changes
- List of things to consider for breaking changes
  - Changed position of positional only parameter
  - Changed position of positional or keyword parameter
  - Changed type of parameter
  - Changed type of public module attribute
  - Changed return type of a public function/method
  - Added parameter without a default value
  - Removed keyword-only parameter without a default value, without **kwargs to swallow it
  - Removed positional-only parameter without a default value, without *args to swallow it
  - Removed positional-or_keyword argument without a default value, without *args and **kwargs to swallow it
  - Removed public module/class/function/method/attribute
  - All of the previous even when parent is private (could be publicly imported or assigned somewhere), and later be smarter: public assign/import makes private things public!
  - Inheritance: removed, added or changed base that changes MRO

Release files for griffe 0.36.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for griffe 0.36.4
File	Size	Uploaded
griffe-0.36.4.tar.gz	126.0 kB	Sep 28, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for griffe 0.36.4
File	Interpreter	ABI	Platform	Reset
griffe-0.36.4-py3-none-any.whl 110.1 kB Sep 28, 2023	Python 3	none	any	Details

Total release size: 236.1 kB

Release files / griffe-0.36.4.tar.gz

Download URL	griffe-0.36.4.tar.gz
Size	126.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`7b5968f5cc6446637ed0d3ded9de07d6a928f10ccb24116b1dd843635bf1994a`
BLAKE2b-256 checksum How to use checksums	`60fed4ba772d92882e6240bfaadb0c13a771e68108cce8e8c682af2dc45a337e`
Upload date	Sep 28, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.11.5`

Release files / griffe-0.36.4-py3-none-any.whl

Download URL	griffe-0.36.4-py3-none-any.whl
Size	110.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4e37a723891fa774fafdd67240571801a1d90d0236562c178707e5c37fb3ebe2`
BLAKE2b-256 checksum How to use checksums	`a9e95f3a9189cfe80c39e79c6bf12336fccc647956c25e4c3e8a7923f41595c6`
Upload date	Sep 28, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.11.5`