From ca47f5c0d43bfe7b9cda52f8df9afdc0fdbf0226 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Mon, 5 Dec 2022 21:08:41 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20Alternate=20Form=20for=20e?= =?UTF-8?q?arly=20adopters?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- typing_doc.md | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/typing_doc.md b/typing_doc.md index b45f7d6cd..2ab93d895 100644 --- a/typing_doc.md +++ b/typing_doc.md @@ -123,6 +123,35 @@ def utcnow() -> datetime: return datetime.utcnow() ``` +## Alternate Form + +To avoid delaying adoption of this proposal until after the `doc()` function has been added to the typing module, type checkers 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. + +To use this alternate form, library authors should include the following declaration within their type stubs or source files. + +```Python +from typing import Any, Callable, Sequence, Type, TypeVar + +_T = TypeVar("_T") + + +def __typing_doc__( + *, + description: str | None = None, + deprecated: bool = False, + discouraged: bool = False, + raises: Sequence[Type[Exception]] | None = None, + extra: dict[Any, Any] | None = None, +) -> Callable[[_T], _T]: + # If used within a stub file, the following implementation can be + # replaced with "...". + return lambda a: a +``` + +And then they can use it in the same places they would use `doc()`. + +**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 A possible alternative would be to support and try to push as a standard one of the existing docstring formats. But that would only solve the standardization. @@ -135,8 +164,6 @@ Runtime behavior is still not defined. It would probably make sense to have an a For parameters, it could include the same object in the same `Annotated` type annotations. -It would probably make sense to have a way to support early adopters. The same way the [`dataclass_transform` had an "Alternate Form"](https://github.com/microsoft/pyright/blob/main/specs/dataclass_transforms.md#alternate-form). - ## Copyright This document is placed in the public domain or under the