griffe 0.2.0

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

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.8 or above.

To install Python 3.8, 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 - 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 (loading data, no serialization)
    • sync: ~60 KLoC/s, ~330 files/s
    • async: ~100 KLoC/s, ~550 files/s
• Loader/Visitor:
  • Docstrings
    • Line numbers
    • Parsing: see below
  • Labels
  • 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
    • Arguments
    • 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.
  • Data (variables/attributes)
    • Docstrings
    • Value
  • Name resolution
    • Per-object scope
    • Load external packages resursively (inheritance)
    • 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
    • New Markdown-based format? For graceful degradation
• Serializer:
  • JSON
    • Nested
    • Flat