METADATA 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145
  1. Metadata-Version: 2.4
  2. Name: annotated-doc
  3. Version: 0.0.4
  4. Summary: Document parameters, class attributes, return types, and variables inline, with Annotated.
  5. Author-Email: =?utf-8?q?Sebasti=C3=A1n_Ram=C3=ADrez?= <tiangolo@gmail.com>
  6. License-Expression: MIT
  7. License-File: LICENSE
  8. Classifier: Intended Audience :: Information Technology
  9. Classifier: Intended Audience :: System Administrators
  10. Classifier: Operating System :: OS Independent
  11. Classifier: Programming Language :: Python :: 3
  12. Classifier: Programming Language :: Python
  13. Classifier: Topic :: Internet
  14. Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
  15. Classifier: Topic :: Software Development :: Libraries :: Python Modules
  16. Classifier: Topic :: Software Development :: Libraries
  17. Classifier: Topic :: Software Development
  18. Classifier: Typing :: Typed
  19. Classifier: Development Status :: 4 - Beta
  20. Classifier: Intended Audience :: Developers
  21. Classifier: Programming Language :: Python :: 3 :: Only
  22. Classifier: Programming Language :: Python :: 3.8
  23. Classifier: Programming Language :: Python :: 3.9
  24. Classifier: Programming Language :: Python :: 3.10
  25. Classifier: Programming Language :: Python :: 3.11
  26. Classifier: Programming Language :: Python :: 3.12
  27. Classifier: Programming Language :: Python :: 3.13
  28. Classifier: Programming Language :: Python :: 3.14
  29. Project-URL: Homepage, https://github.com/fastapi/annotated-doc
  30. Project-URL: Documentation, https://github.com/fastapi/annotated-doc
  31. Project-URL: Repository, https://github.com/fastapi/annotated-doc
  32. Project-URL: Issues, https://github.com/fastapi/annotated-doc/issues
  33. Project-URL: Changelog, https://github.com/fastapi/annotated-doc/release-notes.md
  34. Requires-Python: >=3.8
  35. Description-Content-Type: text/markdown
  36. # Annotated Doc
  37. Document parameters, class attributes, return types, and variables inline, with `Annotated`.
  38. <a href="https://github.com/fastapi/annotated-doc/actions?query=workflow%3ATest+event%3Apush+branch%3Amain" target="_blank">
  39. <img src="https://github.com/fastapi/annotated-doc/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Test">
  40. </a>
  41. <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/annotated-doc" target="_blank">
  42. <img src="https://coverage-badge.samuelcolvin.workers.dev/fastapi/annotated-doc.svg" alt="Coverage">
  43. </a>
  44. <a href="https://pypi.org/project/annotated-doc" target="_blank">
  45. <img src="https://img.shields.io/pypi/v/annotated-doc?color=%2334D058&label=pypi%20package" alt="Package version">
  46. </a>
  47. <a href="https://pypi.org/project/annotated-doc" target="_blank">
  48. <img src="https://img.shields.io/pypi/pyversions/annotated-doc.svg?color=%2334D058" alt="Supported Python versions">
  49. </a>
  50. ## Installation
  51. ```bash
  52. pip install annotated-doc
  53. ```
  54. Or with `uv`:
  55. ```Python
  56. uv add annotated-doc
  57. ```
  58. ## Usage
  59. Import `Doc` and pass a single literal string with the documentation for the specific parameter, class attribute, return type, or variable.
  60. For example, to document a parameter `name` in a function `hi` you could do:
  61. ```Python
  62. from typing import Annotated
  63. from annotated_doc import Doc
  64. def hi(name: Annotated[str, Doc("Who to say hi to")]) -> None:
  65. print(f"Hi, {name}!")
  66. ```
  67. You can also use it to document class attributes:
  68. ```Python
  69. from typing import Annotated
  70. from annotated_doc import Doc
  71. class User:
  72. name: Annotated[str, Doc("The user's name")]
  73. age: Annotated[int, Doc("The user's age")]
  74. ```
  75. The same way, you could document return types and variables, or anything that could have a type annotation with `Annotated`.
  76. ## Who Uses This
  77. `annotated-doc` was made for:
  78. * [FastAPI](https://fastapi.tiangolo.com/)
  79. * [Typer](https://typer.tiangolo.com/)
  80. * [SQLModel](https://sqlmodel.tiangolo.com/)
  81. * [Asyncer](https://asyncer.tiangolo.com/)
  82. `annotated-doc` is supported by [griffe-typingdoc](https://github.com/mkdocstrings/griffe-typingdoc), which powers reference documentation like the one in the [FastAPI Reference](https://fastapi.tiangolo.com/reference/).
  83. ## Reasons not to use `annotated-doc`
  84. You are already comfortable with one of the existing docstring formats, like:
  85. * Sphinx
  86. * numpydoc
  87. * Google
  88. * Keras
  89. Your team is already comfortable using them.
  90. You prefer having the documentation about parameters all together in a docstring, separated from the code defining them.
  91. 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.
  92. ## Reasons to use `annotated-doc`
  93. * No micro-syntax to learn for newcomers, it’s **just Python** syntax.
  94. * **Editing** would be already fully supported by default by any editor (current or future) supporting Python syntax, including syntax errors, syntax highlighting, etc.
  95. * **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.
  96. * **Deduplication of information**: the name of a parameter would be defined in a single place, not duplicated inside of a docstring.
  97. * **Elimination** of the possibility of having **inconsistencies** when removing a parameter or class variable and **forgetting to remove** its documentation.
  98. * **Minimization** of the probability of adding a new parameter or class variable and **forgetting to add its documentation**.
  99. * **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.
  100. * **Access** to the documentation string for each symbol at **runtime**, including existing (older) Python versions.
  101. * A more formalized way to document other symbols, like type aliases, that could use Annotated.
  102. * **Support** for apps using FastAPI, Typer and others.
  103. * **AI Accessibility**: AI tools will have an easier way understanding each parameter as the distance from documentation to parameter is much closer.
  104. ## History
  105. 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.
  106. The conclusion was that this was better done as an external effort, in a third-party library.
  107. 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.
  108. ## License
  109. This project is licensed under the terms of the MIT license.