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
1 maintainer
Release files for griffe 0.46.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| griffe-0.46.0.tar.gz | 102.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| griffe-0.46.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 224.4 kB
Release files / griffe-0.46.0.tar.gz
| Download URL | griffe-0.46.0.tar.gz |
|---|---|
| Size | 102.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b3b913f70cad7dfe410094b180181e00fec282f60e47cf8bcce187139f099e5
|
|
BLAKE2b-256 checksum How to use checksums |
cfa50fd155c446b28df863013f60cbd43834ddf596dbba5daca61682ff614b63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.11.5
|
Release files / griffe-0.46.0-py3-none-any.whl
| Download URL | griffe-0.46.0-py3-none-any.whl |
|---|---|
| Size | 121.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7804a22aa981e442bcb3ff1365268cee590e40c6b68388075d3e1287b7d817ca
|
|
BLAKE2b-256 checksum How to use checksums |
a7d41a142e587b685ac65c490f671400fdcd66763833238b0db3150ff1811301
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.11.5
|
