1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
# Griffe
[](https://github.com/mkdocstrings/griffe/actions?query=workflow%3Aci)
[](https://mkdocstrings.github.io/griffe/)
[](https://pypi.org/project/griffe/)
[](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im)
<img src="https://raw.githubusercontent.com/mkdocstrings/griffe/main/logo.svg" alt="Griffe logo, created by François Rozet" width="200" align="right">
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](https://mkdocstrings.github.io/griffe/guide/users/)
- [Contributor guide](https://mkdocstrings.github.io/griffe/guide/contributors/)
- [API reference](https://mkdocstrings.github.io/griffe/reference/api/)
## Installation
```bash
pip install griffe
```
With [`uv`](https://docs.astral.sh/uv/):
```bash
uv tool install griffe
```
## Usage
### Dump JSON-serialized API
**On the command line**, pass the names of packages to the `griffe dump` command:
```console
$ griffe dump httpx fastapi
{
"httpx": {
"name": "httpx",
...
},
"fastapi": {
"name": "fastapi",
...
}
}
```
See the [Serializing chapter](https://mkdocstrings.github.io/griffe/guide/users/serializing/) for more examples.
### Check for API breaking changes
Pass a relative path to the `griffe check` command:
```console
$ 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:
```console
$ 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](https://mkdocstrings.github.io/griffe/insiders/)
and requires that you install Griffe with the `pypi` extra:
```bash
pip install griffe[pypi]
```
The command syntax is:
```bash
griffe check package_name -b project-name==2.0 -a project-name==1.0
```
See the [Checking chapter](https://mkdocstrings.github.io/griffe/guide/users/checking/) for more examples.
### Load and navigate data with Python
**With Python**, loading a package:
```python
import griffe
fastapi = griffe.load("fastapi")
```
Finding breaking changes:
```python
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](https://mkdocstrings.github.io/griffe/guide/users/loading/) for more examples.
|
