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.

⚠️ Work in progress!

Requirements

Griffe requires Python 3.8 or above.

# 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 - bash)"

# install Python 3.8
pyenv install 3.8.12

# make it available globally
pyenv global system 3.8.12

Installation

With pip:

python3.8 -m pip install griffe

With pipx:

python3.8 -m pip install --user pipx

pipx install --python python3.8 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

• Design:
  • Navigable trees (nodes and data)
  • Extension system
  • Performance
• Loader/Visitor:
  • Docstrings
    • Line numbers
    • Parsing: see below
  • Labels
    • Attribute: ?
    • Function: ?
    • Class: ?
    • Module: ?
  • Modules
  • Classes
    • Bases (parent classes)
    • 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
    • Decorators
  • Functions
    • Parameters
    • Return annotation (names, constants, attributes)
    • Decorators
    • 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.
  • Attributes (variables/constants)
    • Docstrings
    • Value
  • Name resolution
    • Per-object scope
    • Load external packages resursively (indirections/aliases)
    • Resolve everything that is an ast.Name
    • Resolve names inside more complex expressions? Calls, exprs, etc.
  • Lines collection (lines for each module)
• Extension system
  • Node-visiting extensions
  • Post-processing extensions
• Docstrings parsers
  • Structured format
  • Styles
    • Google
    • RST
    • Numpy
    • epydoc
    • New Markdown-based format? For graceful degradation
• Serializer:
  • JSON
    • Nested
    • Flat
• 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