Annotated Doc

Document parameters, class attributes, return types, and variables inline, with Annotated.

Installation

pip install annotated-doc

Or with uv:

uv add annotated-doc

Usage

Import Doc and pass a single literal string with the documentation for the specific parameter, class attribute, return type, or variable.

For example, to document a parameter name in a function hi you could do:

from typing import Annotated

from annotated_doc import Doc

def hi(name: Annotated[str, Doc("Who to say hi to")]) -> None:
    print(f"Hi, {name}!")

You can also use it to document class attributes:

from typing import Annotated

from annotated_doc import Doc

class User:
    name: Annotated[str, Doc("The user's name")]
    age: Annotated[int, Doc("The user's age")]

The same way, you could document return types and variables, or anything that could have a type annotation with Annotated.

Who Uses This

annotated-doc was made for:

• FastAPI
• Typer
• SQLModel
• Asyncer

annotated-doc is supported by griffe-typingdoc, which powers reference documentation like the one in the FastAPI Reference.

Reasons not to use annotated-doc

You are already comfortable with one of the existing docstring formats, like:

• Sphinx
• numpydoc
• Google
• Keras

Your team is already comfortable using them.

You prefer having the documentation about parameters all together in a docstring, separated from the code defining them.

You care about a specific set of users, using one specific editor, and that editor already has support for the specific docstring format you use.

Reasons to use annotated-doc

• No micro-syntax to learn for newcomers, it’s just Python syntax.
• Editing would be already fully supported by default by any editor (current or future) supporting Python syntax, including syntax errors, syntax highlighting, etc.
• Rendering would be relatively straightforward to implement by static tools (tools that don't need runtime execution), as the information can be extracted from the AST they normally already create.
• Deduplication of information: the name of a parameter would be defined in a single place, not duplicated inside of a docstring.
• Elimination of the possibility of having inconsistencies when removing a parameter or class variable and forgetting to remove its documentation.
• Minimization of the probability of adding a new parameter or class variable and forgetting to add its documentation.
• Elimination of the possibility of having inconsistencies between the name of a parameter in the signature and the name in the docstring when it is renamed.
• Access to the documentation string for each symbol at runtime, including existing (older) Python versions.
• A more formalized way to document other symbols, like type aliases, that could use Annotated.
• Support for apps using FastAPI, Typer and others.
• AI Accessibility: AI tools will have an easier way understanding each parameter as the distance from documentation to parameter is much closer.

History

I (@tiangolo) originally wanted for this to be part of the Python standard library (in PEP 727), but the proposal was withdrawn as there was a fair amount of negative feedback and opposition.

The conclusion was that this was better done as an external effort, in a third-party library.

So, here it is, with a simpler approach, as a third-party library, in a way that can be used by others, starting with FastAPI and friends.

License

This project is licensed under the terms of the MIT license.