griffe

Griffe supports several official extensions maintained by the mkdocstrings organization. These extensions provide specialized support for third-party libraries (like Pydantic), Python standard library features (like PEP 727 or PEP 702), or specific documentation styles (like Sphinx comments).

| Extension | Description |
| --------- | ----------- |
| [`autodocstringstyle`](official/autodocstringstyle.md) | Set docstring style to `auto` for external packages. |
| [`inherited-docstrings`](official/inherited-docstrings.md) | Inherit docstrings from parent classes. |
| [`public-redundant-aliases`](official/public-redundant-aliases.md) | Mark objects imported with redundant aliases as public. |
| [`public-wildcard-imports`](official/public-wildcard-imports.md) | Mark wildcard imported objects as public. |
| [`pydantic`](official/pydantic.md) | Support for [Pydantic](https://docs.pydantic.dev/latest/) models. |
| [`runtime-objects`](official/runtime-objects.md) | Access runtime objects corresponding to each loaded Griffe object through their `extra` attribute. |
| [`sphinx`](official/sphinx.md) | Parse [Sphinx](https://www.sphinx-doc.org/)-comments above attributes (`#:`) as docstrings. |
| [`typing-doc`](official/typingdoc.md) | Support for [PEP 727](https://peps.python.org/pep-0727/)'s [`typing.Doc`][typing_extensions.Doc], "Documentation in Annotated Metadata". |
| [`warnings-deprecated`](official/warnings-deprecated.md) | Support for [PEP 702](https://peps.python.org/pep-0702/)'s [`warnings.deprecated`][], "Marking deprecations using the type system". |

A public API is the interface through which developers interact with your software (modules, classes, functions, etc.). In Python, distinguishing public objects from internal ones is a matter of communication and convention, as the language does not strictly prevent access to internal objects.

Key components of a public API include:

• Module layout
• Functions and their signatures
• Classes (including inheritance), methods, and signatures
• Module or class attributes (types and values)
• Exceptions raised (crucial for users to catch errors)
• CLI options and logger names

Best Practices:

• Communicate clearly: Explicitly define what is public and what is subject to unnotified changes.
• Use Deprecation Periods: When changing a public object, provide a period where the old version still works but emits deprecation warnings.
• Automate Verification: Use tools like Griffe to automate checks around your public API to ensure you don't accidentally break it.

Griffe builds enhanced ASTs called Expressions for type annotations, decorators, and values. Unlike standard Python ast objects, Griffe expressions:

• Flatten attributes (e.g., a.b.c is a single attribute).
• Attach a parent object to names, allowing resolution to a full path within the current scope.

These expressions enable downstream tools like mkdocstrings to handle cross-references and allow developers to build robust extensions for analyzing decorators and dataclasses.

from griffe import temporary_visited_module
from rich.pretty import pprint

code = """
    from dataclasses import dataclass
    from random import randint

    @dataclass
    class Bar:
        baz: int

    def get_some_baz() -> int:
        return randint(0, 10)

    foo: Bar = Bar(baz=get_some_baz())
"""

with temporary_visited_module(code) as module:
    pprint(module["foo"].annotation)
    pprint(module["foo"].value)

To improve usability and documentation clarity, follow these two principles:

1. Use Unique and Meaningful Names: Avoid names that require module context to understand (e.g., use docstring_warning instead of just warning). Unique names prevent users from needing to use aliases (import x as y) when importing multiple objects.
2. Expose Objects in a Single Location: Avoid exposing the same object in multiple places (e.g., both in package.module and package). This removes ambiguity for users and helps documentation generators correctly identify the canonical reference path.

Best Practices for Single Location

• If using a hidden layout: The object should only exist in the top-level __init__.py.
• If using a public layout: Declare the object in its specific module and do not re-export it in the top-level __init__.py.
• If you must use the top-level: Make the source module private (e.g., _module.py) to signal it is not a public entry point.