From c1616eb92f3f596fad88580c31adf253c7f05c3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Mon, 28 Aug 2023 16:06:22 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Update=20Alternate=20Form,=20poi?=
=?UTF-8?q?nt=20to=20annotated-types?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
typing_doc.md | 24 +++++++++---------------
1 file changed, 9 insertions(+), 15 deletions(-)
diff --git a/typing_doc.md b/typing_doc.md
index 937aac572..c502f7b6e 100644
--- a/typing_doc.md
+++ b/typing_doc.md
@@ -210,31 +210,25 @@ def hi(to: Annotated[str, doc("The current user name")]) -> None: ...
## Alternate Form
-To avoid delaying adoption of this proposal until after the `doc()` function has been added to the typing module, type checkers and tools may support an alternative form `__typing_doc__`. This form can be defined locally without any reliance on the `typing` or `typing_extensions` modules. It allows immediate adoption of the specification by library authors. Type checkers that have not yet adopted this specification will retain their current behavior.
+Part of the formalization of this document includes writing a PEP and adding this to `typing_extensions`. That is currently an ongoing effort.
-To use this alternate form, library authors should include the following declaration within their type stubs or source files.
+By including it in `typing_extensions`, it will be usable by current versions of Python, even before this proposal is accepted and included into the Python standard library in a future version of Python (if it is ever accepted).
-```Python
-from dataclasses import dataclass
+To avoid delaying adoption, the `doc` function and `DocInfo` class are (at least temporarily) already available in [annotated-types](https://github.com/annotated-types/annotated-types).
+Early adopters can install `annotated-types` and do:
-@dataclass
-class DocInfo:
- documentation: str
+```Python
+from types import Annotated
+from annotated_types import doc
-def __typing_doc__(
- documentation: str,
-) -> DocInfo:
- return DocInfo(documentation)
-```
-And then they can use it in the same places they would use `doc()`.
+def hi(to: Annotated[str, doc("The current user name")]) -> None: ...
+```
This alternate form can be used by early adopters including libraries, linters, editors, type checkers, documentation generation tools and others.
-**Note**: this mimics and blatantly copies the pattern from the early versions of the [`dataclass_transform` specification](https://github.com/microsoft/pyright/blob/main/specs/dataclass_transforms.md#alternate-form).
-
## Rejected Ideas
### Standardize Current Docstrings