| Name | annotated-doc JSON |
| Version |
0.0.2
JSON |
| download |
| home_page | None |
| Summary | Document parameters, class attributes, return types, and variables inline, with Annotated. |
| upload_time | 2025-10-22 18:38:52 |
| maintainer | None |
| docs_url | None |
| author | Sebastián Ramírez |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Annotated Doc
Document parameters, class attributes, return types, and variables inline, with `Annotated`.
## Installation
```bash
pip install annotated-doc
```
Or with `uv`:
```Python
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:
```Python
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:
```Python
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")]
```
## Who Uses This
This was made for:
* [FastAPI](https://fastapi.tiangolo.com/)
* [Typer](https://typer.tiangolo.com/)
* [SQLModel](https://sqlmodel.tiangolo.com/)
* [Asyncer](https://asyncer.tiangolo.com/)
## 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](https://github.com/tiangolo)) originally wanted for this to be part of the Python standard library (in [PEP 727](https://peps.python.org/pep-0727/)), 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, and its users.
## License
This project is licensed under the terms of the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "annotated-doc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Sebasti\u00e1n Ram\u00edrez",
"author_email": "Sebasti\u00e1n Ram\u00edrez <tiangolo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c4/92/2974dba489541ed4af531d00a4df075bc3a455557d3b54fd6932c51c95cc/annotated_doc-0.0.2.tar.gz",
"platform": null,
"description": "# Annotated Doc\n\nDocument parameters, class attributes, return types, and variables inline, with `Annotated`.\n\n## Installation\n\n```bash\npip install annotated-doc\n```\n\nOr with `uv`:\n\n```Python\nuv add annotated-doc\n```\n\n## Usage\n\nImport `Doc` and pass a single literal string with the documentation for the specific parameter, class attribute, return type, or variable.\n\nFor example, to document a parameter `name` in a function `hi` you could do:\n\n```Python\nfrom typing import Annotated\n\nfrom annotated_doc import Doc\n\ndef hi(name: Annotated[str, Doc(\"Who to say hi to\")]) -> None:\n print(f\"Hi, {name}!\")\n```\n\nYou can also use it to document class attributes:\n\n```Python\nfrom typing import Annotated\n\nfrom annotated_doc import Doc\n\nclass User:\n name: Annotated[str, Doc(\"The user's name\")]\n age: Annotated[int, Doc(\"The user's age\")]\n```\n\n## Who Uses This\n\nThis was made for:\n\n* [FastAPI](https://fastapi.tiangolo.com/)\n* [Typer](https://typer.tiangolo.com/)\n* [SQLModel](https://sqlmodel.tiangolo.com/)\n* [Asyncer](https://asyncer.tiangolo.com/)\n\n## Reasons not to use `annotated-doc`\n\nYou are already comfortable with one of the existing docstring formats, like:\n\n* Sphinx\n* numpydoc\n* Google\n* Keras\n\nYour team is already comfortable using them.\n\nYou prefer having the documentation about parameters all together in a docstring, separated from the code defining them.\n\nYou care about a specific set of users, using one specific editor, and that editor already has support for the specific docstring format you use.\n\n## Reasons to use `annotated-doc`\n\n* No micro-syntax to learn for newcomers, it\u2019s **just Python** syntax.\n* **Editing** would be already fully supported by default by any editor (current or future) supporting Python syntax, including syntax errors, syntax highlighting, etc.\n* **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.\n* **Deduplication of information**: the name of a parameter would be defined in a single place, not duplicated inside of a docstring.\n* **Elimination** of the possibility of having **inconsistencies** when removing a parameter or class variable and **forgetting to remove** its documentation.\n* **Minimization** of the probability of adding a new parameter or class variable and **forgetting to add its documentation**.\n* **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.\n* **Access** to the documentation string for each symbol at **runtime**, including existing (older) Python versions.\n* A more formalized way to document other symbols, like type aliases, that could use Annotated.\n* **Support** for apps using FastAPI, Typer and others.\n* **AI Accessibility**: AI tools will have an easier way understanding each parameter as the distance from documentation to parameter is much closer.\n\n## History\n\nI ([@tiangolo](https://github.com/tiangolo)) originally wanted for this to be part of the Python standard library (in [PEP 727](https://peps.python.org/pep-0727/)), but the proposal was withdrawn as there was a fair amount of negative feedback and opposition.\n\nThe conclusion was that this was better done as an external effort, in a third-party library.\n\nSo, 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, and its users.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Document parameters, class attributes, return types, and variables inline, with Annotated.",
"version": "0.0.2",
"project_urls": {
"Changelog": "https://github.com/fastapi/annotated-doc/release-notes.md",
"Documentation": "https://github.com/fastapi/annotated-doc",
"Homepage": "https://github.com/fastapi/annotated-doc",
"Issues": "https://github.com/fastapi/annotated-doc/issues",
"Repository": "https://github.com/fastapi/annotated-doc"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bdeecc5109cdd46a6ccd3d923db3c5425383abe51b5c033647aad1b5e2452e82",
"md5": "afcee667b8f1e9d24df35f62702bdd84",
"sha256": "2188cb99e353fcb5c20f23b8bc6f5fa7c924b213fac733d4b44883f9edffa090"
},
"downloads": -1,
"filename": "annotated_doc-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "afcee667b8f1e9d24df35f62702bdd84",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4056,
"upload_time": "2025-10-22T18:38:51",
"upload_time_iso_8601": "2025-10-22T18:38:51.240289Z",
"url": "https://files.pythonhosted.org/packages/bd/ee/cc5109cdd46a6ccd3d923db3c5425383abe51b5c033647aad1b5e2452e82/annotated_doc-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c4922974dba489541ed4af531d00a4df075bc3a455557d3b54fd6932c51c95cc",
"md5": "7be4ea2803fdfb0aeece7b4486bedc3d",
"sha256": "f25664061aee278227abfaec5aeb398298be579b934758c16205d48e896e149c"
},
"downloads": -1,
"filename": "annotated_doc-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "7be4ea2803fdfb0aeece7b4486bedc3d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4452,
"upload_time": "2025-10-22T18:38:52",
"upload_time_iso_8601": "2025-10-22T18:38:52.597709Z",
"url": "https://files.pythonhosted.org/packages/c4/92/2974dba489541ed4af531d00a4df075bc3a455557d3b54fd6932c51c95cc/annotated_doc-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 18:38:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fastapi",
"github_project": "annotated-doc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "annotated-doc"
}
