Griffe is a Python library (current version 2.0.2) that provides signatures for entire Python programs. It extracts the structure, frame, and skeleton of a project, enabling tasks like API documentation generation and detection of breaking API changes. The library maintains a regular release cadence, with frequent updates including bug fixes, features, and occasional deprecations or breaking changes between major versions.
Install & Compatibility
Where this runs
tested against v2.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 0.252s · 19.4MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 1.9s · import 0.231s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
griffe
✓ import griffe
✗ from griffe._internal import some_private_module
Griffe exposes its public API directly in the top-level 'griffe' module. Importing from internal or private modules (e.g., '_internal' or those starting with an underscore) is not guaranteed to be stable and can break across minor versions, as seen with the '_griffe' package refactoring in 1.11.1.
This quickstart demonstrates how to use `griffe.load` to extract API information from a Python module. It creates a temporary Python file, loads its structure into Griffe's data models, and then prints basic information about the extracted function and class.
import griffe
import os
# Create a dummy Python file for demonstration
with open('my_dummy_module.py', 'w') as f:
f.write('def my_function(param1: str, param2: int = 0) -> str:\n """A dummy function."""\n return f"{param1}-{param2}"\n\nclass MyClass:\n """A dummy class."""\n def __init__(self, name: str):\n self.name = name\n\n def greet(self) -> str:\n """Greets by name."""\n return f"Hello, {self.name}"\n')
# Load the module's API data
# Griffe will try to find sources and fall back to introspection if not found
# Using the current directory as a search path
package = griffe.load("my_dummy_module", search_paths=['.'])
# Access a module, class, or function
print(f"Package name: {package.name}")
my_function = package["my_function"]
print(f"Function: {my_function.name}, Parameters: {[p.name for p in my_function.parameters]}")
my_class = package["MyClass"]
print(f"Class: {my_class.name}, Methods: {[m.name for m in my_class.members.values() if m.is_function]}")
# Clean up the dummy file
os.remove('my_dummy_module.py')
griffe --version
Debug
Known issues
breakingVersion 2.0.0 removed several previously deprecated public APIs, including `ExportedName`, `infer_docstring_style`, `parse_auto`, `parse_google`, `parse_numpy`, `parse_sphinx`, `assert_git_repo`, `get_latest_tag`, `get_repo_root`, and `tmp_worktree`.fixReview the 2.0.0 changelog for a complete list of removed APIs. Replace usage of these deprecated functions/objects with their current equivalents, or remove dependencies on them.
affects: >=2.0.0
deprecatedThe signature of the `on_alias` event changed in version 1.14.0. It changed from `on_alias(self, *, node: AST | ObjectNode, alias: Alias, agent: Visitor | Inspector, **kwargs)` (an analysis event) to `on_alias(self, *, alias: Alias, loader: GriffeLoader, **kwargs)` (a load event).fixUpdate custom handlers or extensions that interact with the `on_alias` event to match the new signature `on_alias(self, *, alias: Alias, loader: GriffeLoader, **kwargs)`.
affects: >=1.14.0
gotchaInternal packages and modules, particularly those starting with an underscore (e.g., `_griffe`), may be refactored or moved without prior deprecation. Version 1.11.1 moved the private `_griffe` package under `griffe._internal`.fixAvoid importing from or relying on undocumented internal modules or packages. Stick to the public API exposed directly under the `griffe` top-level module to ensure forward compatibility. If you must use internals, pin your `griffe` version tightly.
affects: <1.11.1 relying on internals
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'griffe.enumerations'
The `griffe.enumerations` module was removed in `griffe` 1.x as part of breaking changes to the library's API.
fixDowngrade `griffe` to a version prior to the breaking change (e.g., `pip install griffe==0.48`) or update your code to use the current API of `griffe` if an alternative exists.
ModuleNotFoundError: No module named 'griffe.dataclasses'
This error often occurs when a project relies on an older structure of `griffe`, specifically `griffe.dataclasses`, which was refactored or removed in `griffe` 1.0.0 and subsequent versions.
fixPin `griffe` to a compatible version for your project or its dependencies (e.g., `pip install 'griffe<1.0.0'` or `griffe==0.48`) or update your project's code to align with `griffe`'s current API.
ModuleNotFoundError: No module named 'griffe'
The `griffe` library is not installed in the Python environment where the code is being executed.
fixInstall the `griffe` package using your package manager (e.g., `pip install griffe`).
griffe._internal.exceptions.AliasResolutionError: Could not resolve alias ...
`griffe` encountered an alias it could not resolve, often due to the use of wildcard imports (`from module import *`), undeclared `__all__` variables, or name shadowing between modules and members.
fixTo fix this, avoid wildcard imports, explicitly define `__all__` in your modules to declare the public API, and prevent name shadowing where a module and a member within its parent package share the same name.
Audit
Dependencies
No dependency data recorded yet.