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.

:warning: Work in progress!

Requirements

griffe requires Python 3.7 or above.

To install Python 3.7, I recommend using pyenv.

# install pyenv
git clone https://github.com/pyenv/pyenv ~/.pyenv

# setup pyenv (you should also put these three lines in .bashrc or similar)
export PATH="${HOME}/.pyenv/bin:${PATH}"
export PYENV_ROOT="${HOME}/.pyenv"
eval "$(pyenv init -)"

# install Python 3.7
pyenv install 3.7.12

# make it available globally
pyenv global system 3.7.12

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 command:

$ griffe httpx fastapi
[
  {
    "name": "httpx",
    ...
  }
]

See the Usage section for more examples.

With Python:

from griffe.loader import GriffeLoader

griffe = GriffeLoader()
fastapi = griffe.load_module("fastapi")

See the Usage section for more examples.

Todo

Visitor/Inspector:
- Labels
  - Attribute: ?
  - Function: ?
  - Class: ?
  - Module: ?
- Merging inherited members into class. Needs to be able to post-process classes, and to compute their MRO (C3Linearization, see docspec/pydocspec issues).
- Merging __init__ method's docstring into class' docstring (could be an extension)
- Support for typing.overload decorator. We'll probably need to add an overloads attribute to Function, to store the list of @overload-decorated functions, because currently different members of a same object cannot have the same names.
- Support for wildcard imports
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:
- Mecanism 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 base, or added/changed base that changes MRO

Release files for griffe 0.8.0

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.8.0
File	Size	Uploaded
griffe-0.8.0.tar.gz	60.5 kB	Jan 2, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for griffe 0.8.0
File	Interpreter	ABI	Platform	Reset
griffe-0.8.0-py3-none-any.whl 60.3 kB Jan 2, 2022	Python 3	none	any	Details

Total release size: 120.8 kB

Release files / griffe-0.8.0.tar.gz

Download URL	griffe-0.8.0.tar.gz
Size	60.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`2aa10c1e20c4ff495620fd1f64d0b3d43c4a8056597ea0adb375035d371539f6`
BLAKE2b-256 checksum How to use checksums	`32ddbc07e7e6b53772e9c44c34a18ca7e4ceb99b58bfb2c2f72f7913e3f0d303`
Upload date	Jan 2, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.6.0 importlib_metadata/4.10.0 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9`

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

Download URL	griffe-0.8.0-py3-none-any.whl
Size	60.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`39f138cca216e105ee33642e7a80c337ba52f061f8dd0c7998cbd1a1ed1dac40`
BLAKE2b-256 checksum How to use checksums	`9bb7f6ce5c399327b9cf0e4d3e68a84902e53e6b49f313d85d4c416ce7c26a53`
Upload date	Jan 2, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.6.0 importlib_metadata/4.10.0 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9`