Skip to main content

Annotated Doc

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

Test Coverage Package version Supported Python versions

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:

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.

Metadata

Release files for annotated-doc 0.0.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for annotated-doc 0.0.7
File Size Uploaded Provenance Actions
annotated_doc-0.0.7.tar.gz 10.8 kB Without provenance Details for annotated_doc-0.0.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for annotated-doc 0.0.7
File Interpreter ABI Platform Actions
annotated_doc-0.0.7-py3-none-any.whl Python 3 none any Details for annotated_doc-0.0.7-py3-none-any.whl

Total release size: 16.1 kB

Release files / annotated_doc-0.0.7.tar.gz

Download URL annotated_doc-0.0.7.tar.gz
Size 10.8 kB
Tags Source
SHA-256 checksum
How to use checksums
0a30ef8f5322a4173720ae6712dc9a5e58f5a19868f3f167b4b5778db066c2b5
BLAKE2b-256 checksum
How to use checksums
0b7dbdbf3062e5dae31da8b3de1e3269110beb93d268df4a7f6d22b167c6cee0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / annotated_doc-0.0.7-py3-none-any.whl

Download URL annotated_doc-0.0.7-py3-none-any.whl
Size 5.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6bc31bbbec6dfaaedc1676dbc11dbda96fe22a2b5c400e9ebad113fec44a9dc6
BLAKE2b-256 checksum
How to use checksums
5eb19530d6bee606979d54501adcc767d958a38929827f11a524b0d93429d2ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for annotated-doc 0.0.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page