griffe 0.28.0

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

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

• Visitor/Inspector:
  • Merging inherited members into class. Needs to be able to post-process classes, and to compute their MRO (C3Linearization, see docspec/pydocspec issues).
• 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
  • JSON schema
• 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