Griffe

Griffe extracts the full signature, structure, and skeleton of Python programs, giving you a rich object model of a package’s modules, classes, functions, attributes, and their docstrings. It combines static analysis of source code with optional dynamic inspection to build an accurate picture of a project’s public API.

That model powers two main jobs: generating API documentation (Griffe is the collector behind mkdocstrings’ Python handler) and detecting breaking changes between versions of an API. It ships both an importable library and a griffe command-line tool for dumping a JSON-serialized API or checking two revisions for incompatibilities.

What You Get

• A complete object model of a Python package (modules, classes, functions, attributes, docstrings)
• Static analysis that inspects code without importing it, with optional dynamic fallback
• Docstring parsing for Google, NumPy, and Sphinx styles
• Breaking-change detection by diffing two versions of an API
• A griffe CLI to dump a JSON-serialized API or check revisions, plus a JSON encoder/decoder for the model

Common Use Cases

• Powering automatic API documentation as the Python collector behind mkdocstrings
• Detecting breaking changes between two releases or git revisions of a library
• Programmatically inspecting a package’s public API for tooling, linting, or code generation

Under The Hood

Architecture - Griffe is now a monorepo split into two published packages: griffelib (the core library) and griffecli (the command line), with the top-level griffe package depending on both. The core loads a package with a finder that locates modules on disk, then a static loader visits the AST to build an object model (Module/Class/Function/Attribute) enriched with docstring parsers, expressions, and type annotations; an optional dynamic path imports objects when static analysis is insufficient. A diff/merger layer compares two loaded trees to compute breaking changes, and JSON encoders serialize the model, all exposed both as an importable API and through the griffe CLI (dump/check).

Tech Stack - Pure Python (3.10+) organized under a src/ layout inside packages/griffelib and packages/griffecli. It leans on the standard library’s ast module for static analysis and ships its own docstring parsers (Google, NumPy, Sphinx) and expression model rather than heavy third-party dependencies. Packaging is PEP 621 with dynamic version and dependency resolution and a py.typed marker.

Code Quality - The griffelib package carries an extensive pytest suite (test_loader, test_diff, test_merger, test_finder, test_nodes, test_stdlib, test_expressions, test_encoders, test_git and more) including tests that load the standard library, and griffecli has its own CLI tests. Consistent, frequent releases and a high maintenance-consistency health signal reflect a well-kept codebase.

API Design - The library API is expressive yet approachable: griffe.load(“package”) returns a fully navigable object tree, and helpers exist for dumping JSON or diffing versions. The griffe CLI mirrors these with dump and check subcommands. The main learning curve is understanding the object model itself, but common tasks (load, dump, check) are one call or one command away.