0
# Griffe
1
2
Griffe is a comprehensive Python library that extracts signatures and API information from entire Python programs. It provides both static analysis (AST parsing) and dynamic analysis (runtime inspection) capabilities to generate API documentation, detect breaking changes, and support development workflows requiring detailed code structure analysis.
3
4
## Package Information
5
6
- **Package Name**: griffe
7
- **Language**: Python
8
- **Installation**: `pip install griffe`
9
- **CLI Tool**: Available as `griffe` command-line tool
10
- **Git Support**: `pip install griffe[pypi]` for enhanced Git/PyPI integration
11
12
## Core Imports
13
14
```python
15
import griffe
16
```
17
18
Common imports for specific functionality:
19
20
```python
21
# Loading packages
22
from griffe import load, load_git, load_pypi
23
24
# CLI functions
25
from griffe import main, check, dump
26
27
# Core models
28
from griffe import Module, Class, Function, Attribute, Alias
29
30
# Analysis agents
31
from griffe import visit, inspect
32
33
# Breaking change detection
34
from griffe import find_breaking_changes, Breakage
35
36
# Docstring parsing
37
from griffe import parse, parse_auto, parse_google, parse_numpy, parse_sphinx
38
39
# Serialization
40
from griffe import JSONEncoder, json_decoder
41
```
42
43
## Basic Usage
44
45
### Loading Python Package Data
46
47
```python
48
import griffe
49
50
# Load a package from the current environment
51
package = griffe.load("requests")
52
print(f"Package: {package.name}")
53
print(f"Modules: {list(package.modules.keys())}")
54
55
# Load from specific Git reference
56
old_version = griffe.load_git("mypackage", ref="v1.0.0")
57
current_version = griffe.load("mypackage")
58
59
# Load from PyPI
60
pypi_package = griffe.load_pypi("django", "Django", "4.2.0")
61
```
62
63
### Detecting API Breaking Changes
64
65
```python
66
import griffe
67
68
# Compare two versions of a package
69
old_api = griffe.load_git("mypackage", ref="v1.0.0")
70
new_api = griffe.load("mypackage")
71
72
# Find breaking changes
73
breakages = griffe.find_breaking_changes(old_api, new_api)
74
for breakage in breakages:
75
print(f"Breaking change: {breakage}")
76
```
77
78
### CLI Usage
79
80
```bash
81
# Dump package API as JSON
82
griffe dump fastapi httpx
83
84
# Check for breaking changes
85
griffe check mypackage --verbose
86
87
# With src layout
88
griffe check --search src mypackage --verbose
89
```
90
91
## Architecture
92
93
Griffe is built around several key architectural concepts:
94
95
- **Agents**: Static analysis via `visit()` (AST parsing) and dynamic analysis via `inspect()` (runtime inspection)
96
- **Models**: Core object representations (`Module`, `Class`, `Function`, `Attribute`, `Alias`) that form the API structure
97
- **Loaders**: High-level functions (`load`, `load_git`, `load_pypi`) that orchestrate the analysis process
98
- **Extensions**: Pluggable system for custom analysis and processing during code examination
99
- **Expressions**: Abstract syntax tree representations of Python code snippets (decorators, annotations, etc.)
100
101
## Capabilities
102
103
### CLI Entry Points
104
105
Command-line interface functions that can be called from Python or as CLI commands.
106
107
```python { .api }
108
def main() -> int:
109
"""
110
Run the main griffe program.
111
112
Returns:
113
int: Exit code (0 for success)
114
"""
115
116
def check(*args, **kwargs) -> int:
117
"""
118
Check for API breaking changes between versions.
119
120
Returns:
121
int: Exit code (0 if no breaking changes)
122
"""
123
124
def dump(*args, **kwargs) -> int:
125
"""
126
Load packages and dump API data as JSON.
127
128
Returns:
129
int: Exit code (0 for success)
130
"""
131
```
132
133
[CLI Functions](./cli.md)
134
135
### Package Loading
136
137
High-level functions for loading Python packages and modules from different sources.
138
139
```python { .api }
140
def load(
141
objspec: str | Path | None = None,
142
/,
143
*,
144
submodules: bool = True,
145
try_relative_path: bool = True,
146
extensions: Extensions | None = None,
147
search_paths: Sequence[str | Path] | None = None,
148
docstring_parser: DocstringStyle | Parser | None = None,
149
docstring_options: dict[str, Any] | None = None,
150
lines_collection: LinesCollection | None = None,
151
modules_collection: ModulesCollection | None = None,
152
allow_inspection: bool = True,
153
force_inspection: bool = False,
154
store_source: bool = True,
155
find_stubs_package: bool = False,
156
resolve_aliases: bool = False,
157
resolve_external: bool | None = None,
158
resolve_implicit: bool = False,
159
) -> Object | Alias: ...
160
161
def load_git(
162
objspec: str,
163
ref: str = "HEAD",
164
*,
165
repo: str | Path = ".",
166
submodules: bool = True,
167
**load_kwargs: Any,
168
) -> Object | Alias: ...
169
170
def load_pypi(
171
package: str,
172
distribution: str,
173
version_spec: str,
174
*,
175
submodules: bool = True,
176
extensions: Extensions | None = None,
177
search_paths: Sequence[str | Path] | None = None,
178
docstring_parser: DocstringStyle | Parser | None = None,
179
docstring_options: dict[str, Any] | None = None,
180
lines_collection: LinesCollection | None = None,
181
modules_collection: ModulesCollection | None = None,
182
allow_inspection: bool = True,
183
force_inspection: bool = False,
184
find_stubs_package: bool = False,
185
) -> Object | Alias: ...
186
```
187
188
[Loaders](./loaders.md)
189
190
### Core Object Models
191
192
The primary classes representing Python API elements.
193
194
```python { .api }
195
class Object:
196
"""Base class for all Griffe objects."""
197
198
@property
199
def name(self) -> str: ...
200
201
@property
202
def path(self) -> str: ...
203
204
def serialize(self, **kwargs: Any) -> dict[str, Any]: ...
205
206
class Module(Object):
207
"""A Python module."""
208
209
@property
210
def filepath(self) -> Path | None: ...
211
212
@property
213
def modules(self) -> dict[str, Module]: ...
214
215
@property
216
def classes(self) -> dict[str, Class]: ...
217
218
@property
219
def functions(self) -> dict[str, Function]: ...
220
221
@property
222
def attributes(self) -> dict[str, Attribute]: ...
223
224
class Class(Object):
225
"""A Python class."""
226
227
@property
228
def bases(self) -> list[Expr]: ...
229
230
@property
231
def decorators(self) -> list[Decorator]: ...
232
233
@property
234
def methods(self) -> dict[str, Function]: ...
235
236
class Function(Object):
237
"""A Python function or method."""
238
239
@property
240
def parameters(self) -> Parameters: ...
241
242
@property
243
def returns(self) -> Expr | None: ...
244
245
@property
246
def decorators(self) -> list[Decorator]: ...
247
248
class Attribute(Object):
249
"""A Python attribute."""
250
251
@property
252
def annotation(self) -> Expr | None: ...
253
254
@property
255
def value(self) -> Expr | None: ...
256
257
class Alias(Object):
258
"""An alias or import reference to an object."""
259
260
@property
261
def target_path(self) -> str: ...
262
263
def resolve(self) -> Object | None: ...
264
```
265
266
[Models](./models.md)
267
268
### Analysis Agents
269
270
Static and dynamic analysis functions for extracting API information.
271
272
```python { .api }
273
def visit(
274
module: Module,
275
filepath: str | Path,
276
code: str | None = None,
277
extensions: Extensions | None = None,
278
parent: Module | None = None,
279
in_try_block: bool = False,
280
) -> Module: ...
281
282
def inspect(
283
module_name: str,
284
filepath: str | Path | None = None,
285
parent: Module | None = None,
286
) -> Module: ...
287
```
288
289
[Agents](./agents.md)
290
291
### API Breakage Detection
292
293
Functions and classes for detecting breaking changes between API versions.
294
295
```python { .api }
296
def find_breaking_changes(
297
old_object: Object,
298
new_object: Object,
299
**kwargs: Any,
300
) -> Iterator[Breakage]: ...
301
302
class Breakage:
303
"""Base class for API breakages."""
304
305
@property
306
def kind(self) -> BreakageKind: ...
307
308
@property
309
def object_path(self) -> str: ...
310
311
class ObjectRemovedBreakage(Breakage):
312
"""A public object was removed."""
313
314
class ParameterAddedRequiredBreakage(Breakage):
315
"""A required parameter was added to a function."""
316
317
class ReturnChangedTypeBreakage(Breakage):
318
"""A function's return type annotation changed."""
319
```
320
321
[Breaking Changes](./breaking-changes.md)
322
323
### Serialization
324
325
JSON encoding and decoding for Griffe objects.
326
327
```python { .api }
328
class JSONEncoder(json.JSONEncoder):
329
"""JSON encoder for Griffe objects."""
330
331
def default(self, obj: Any) -> Any: ...
332
333
def json_decoder(dct: dict[str, Any]) -> dict[str, Any] | Object:
334
"""
335
Decode Griffe objects from JSON.
336
337
Args:
338
dct: Dictionary from JSON decoder
339
340
Returns:
341
Decoded object or dictionary
342
"""
343
```
344
345
[Serialization](./serialization.md)
346
347
### Docstring Parsing
348
349
Comprehensive docstring parsing supporting multiple formats.
350
351
```python { .api }
352
def parse(
353
text: str,
354
parser: Parser | str | None = None,
355
**options: Any,
356
) -> list[DocstringSection]: ...
357
358
def parse_auto(text: str, **options: Any) -> list[DocstringSection]: ...
359
360
def parse_google(text: str, **options: Any) -> list[DocstringSection]: ...
361
362
def parse_numpy(text: str, **options: Any) -> list[DocstringSection]: ...
363
364
def parse_sphinx(text: str, **options: Any) -> list[DocstringSection]: ...
365
```
366
367
[Docstrings](./docstrings.md)
368
369
### Extensions
370
371
Extensible plugin system for custom analysis.
372
373
```python { .api }
374
class Extension:
375
"""Base class for Griffe extensions."""
376
377
def on_package_loaded(self, *, pkg: Module) -> None: ...
378
379
def on_module_loaded(self, *, mod: Module) -> None: ...
380
381
def on_class_loaded(self, *, cls: Class) -> None: ...
382
383
def on_function_loaded(self, *, func: Function) -> None: ...
384
385
def load_extensions(
386
extensions: list[LoadableExtensionType] | None = None
387
) -> Extensions: ...
388
```
389
390
[Extensions](./extensions.md)
391
392
## Types
393
394
### Core Type Aliases
395
396
```python { .api }
397
from pathlib import Path
398
from typing import Any, Sequence, IO
399
400
# Collection types
401
LinesCollection = dict[str, dict[int, str]]
402
ModulesCollection = dict[str, Module]
403
Extensions = dict[str, Extension]
404
405
# Docstring and parser types
406
DocstringStyle = str
407
ExplanationStyle = str
408
```
409
410
### Core Enumerations
411
412
```python { .api }
413
from enum import Enum
414
415
class Kind(Enum):
416
"""Object kinds."""
417
MODULE = "module"
418
CLASS = "class"
419
FUNCTION = "function"
420
ATTRIBUTE = "attribute"
421
422
class ParameterKind(Enum):
423
"""Parameter kinds."""
424
POSITIONAL_ONLY = 0
425
POSITIONAL_OR_KEYWORD = 1
426
VAR_POSITIONAL = 2
427
KEYWORD_ONLY = 3
428
VAR_KEYWORD = 4
429
430
class Parser(Enum):
431
"""Docstring parser types."""
432
AUTO = "auto"
433
GOOGLE = "google"
434
NUMPY = "numpy"
435
SPHINX = "sphinx"
436
437
class BreakageKind(Enum):
438
"""API breakage types."""
439
OBJECT_REMOVED = "object_removed"
440
PARAMETER_ADDED_REQUIRED = "parameter_added_required"
441
PARAMETER_REMOVED = "parameter_removed"
442
RETURN_CHANGED_TYPE = "return_changed_type"
443
```
444
445
### Parameter Types
446
447
```python { .api }
448
class Parameter:
449
"""A function parameter."""
450
451
def __init__(
452
self,
453
name: str,
454
annotation: Expr | None = None,
455
default: Expr | None = None,
456
kind: ParameterKind = ParameterKind.POSITIONAL_OR_KEYWORD,
457
) -> None: ...
458
459
@property
460
def name(self) -> str: ...
461
462
@property
463
def annotation(self) -> Expr | None: ...
464
465
@property
466
def default(self) -> Expr | None: ...
467
468
class Parameters:
469
"""Container for function parameters."""
470
471
def __iter__(self) -> Iterator[Parameter]: ...
472
473
def __getitem__(self, key: int | str) -> Parameter: ...
474
475
def __len__(self) -> int: ...
476
```
477
478
### Expression Types
479
480
```python { .api }
481
class Expr:
482
"""Base expression class."""
483
484
def __str__(self) -> str: ...
485
486
class ExprName(Expr):
487
"""A name expression."""
488
489
def __init__(self, name: str) -> None: ...
490
491
class ExprAttribute(Expr):
492
"""An attribute access expression like a.b."""
493
494
def __init__(self, value: Expr, attr: str) -> None: ...
495
496
class ExprCall(Expr):
497
"""A function call expression."""
498
499
def __init__(
500
self,
501
function: Expr,
502
arguments: list[Expr] | None = None,
503
) -> None: ...
504
```