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

Metadata

Release files for griffe 0.27.5

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.27.5
File	Size	Uploaded	Provenance
griffe-0.27.5.tar.gz	101.9 kB	May 12, 2023	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for griffe 0.27.5
File	Interpreter	ABI	Platform	Reset
griffe-0.27.5-py3-none-any.whl 89.1 kB May 12, 2023 Without provenance	Python 3	none	any	Details

Total release size: 191.0 kB

Release files / griffe-0.27.5.tar.gz

Download URL	griffe-0.27.5.tar.gz
Size	101.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`96fbc7a264bdb32b4da227bed6a16f2509e028a12d7471dbb48c2785bb01817f`
BLAKE2b-256 checksum How to use checksums	`7c28a2e67f2959883a10f75353dc8d187a9f0c4c10167181906258b67517300c`
Upload date	May 12, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.11.0`

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

Download URL	griffe-0.27.5-py3-none-any.whl
Size	89.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`15b48fc3cebfc1c1a1a2f6e8177f6644a4a54517322e08e224fdf671454b34d7`
BLAKE2b-256 checksum How to use checksums	`7c560841db4f56f2002f78946cb4030e32d254e3233fb41b3540f891aeda4def`
Upload date	May 12, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.11.0`

Security for griffe 0.27.5

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.