Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mkdocstrings/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.
https://github.com/mkdocstrings/griffe
api breaking-changes docs mkdocstrings-collector parser python signature
Last synced: about 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/mkdocstrings/griffe
- Owner: mkdocstrings
- License: isc
- Created: 2021-09-09T21:49:44.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-18T13:42:02.000Z (3 months ago)
- Last Synced: 2024-10-20T09:52:45.451Z (3 months ago)
- Topics: api, breaking-changes, docs, mkdocstrings-collector, parser, python, signature
- Language: Python
- Homepage: https://mkdocstrings.github.io/griffe
- Size: 17.1 MB
- Stars: 303
- Watchers: 6
- Forks: 41
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- best-of-python-dev - GitHub - 14% open · ⏱️ 23.05.2024): (Documentation)
README
# 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)
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.