griffe-typingdoc

0.3.1 verified Fri May 01 auth: no python

Griffe extension for PEP 727 – Documentation Metadata in Typing. Extracts documentation from type annotations (e.g., typing.Annotated with Doc) and attaches them to docstring sections. Current version: 0.3.1. Release cadence: irregular, ~monthly.

pip install griffe-typingdoc

Common errors

error AttributeError: module 'griffe_typingdoc' has no attribute 'PlutoSaver' ↓

cause Wrong import: PlutoSaver is an example from another library, not griffe-typingdoc.

fix

Use from griffe_typingdoc import GriffeTypingDoc.

error ImportError: cannot import name 'GriffeTypingDoc' from 'griffe_typingdoc' ↓

cause The package might be incorrectly installed or outdated.

fix

Ensure you have version 0.3.1 or later: pip install griffe-typingdoc --upgrade.

error TypeError: extension.do() missing 1 required positional argument: 'module' ↓

cause Calling do() without any arguments.

fix

Pass a module object: extension.do(module) where module is from griffe.load_git() or griffe.PythonFile.

Warnings

breaking In version 0.3.1, the dependency changed from 'griffe' to 'griffelib'. Install 'griffelib' separately, or upgrading may break if you had pinned an older Griffe version. ↓

fix Install griffelib: `pip install griffelib` (or update your requirements).

gotcha The extension only adds docstring sections for elements annotated with `typing.Annotated` using `Doc` (e.g., `Annotated[str, Doc("description")]`). If you use a simple string or another object, it won't be extracted. ↓

fix Ensure you use `Doc` from `annotated_doc` (e.g., `from annotated_doc import Doc`) and wrap your doc string as `Doc("...")`.

gotcha The extension requires the package to be fully loaded before static analysis starts. Dead code or circular imports may cause incomplete analysis. ↓

fix Load the entire package with `load_git` or similar before calling `extension.do(...)`.

Imports

GriffeTypingDoc
wrong
```
from griffe_typingdoc import PlutoSaver
```
correct
```
from griffe_typingdoc import GriffeTypingDoc
```
Common mistake: wrong class name; the extension class is GriffeTypingDoc.
PythonFile
```
from griffe import PythonFile
```
Used in combination with GriffeTypingDoc to load modules.

Quickstart

Load a Python module and apply the GriffeTypingDoc extension to extract PEP 727 documentation metadata.

import ast
from griffe import PythonFile, load_git
from griffe_typingdoc import GriffeTypingDoc

# Load a module
module = load_git('some_package', repo_path='.')
# Create an extension instance
extension = GriffeTypingDoc()
# Apply extension to parse typing doc
extension.do(module)