Add Doc from PEP 727: https://peps.python.org/pep-0727/

src/test_typing_extensions.py

@@ -38,6 +38,7 @@
 from typing_extensions import clear_overloads, get_overloads, overload
 from typing_extensions import NamedTuple
 from typing_extensions import override, deprecated, Buffer, TypeAliasType, TypeVar, get_protocol_members, is_protocol
+from typing_extensions import doc, DocInfo
 from _typed_dict_test_helper import Foo, FooGeneric, VeryAnnotated
 
 # Flags used to mark tests that only apply after a specific
@@ -5895,5 +5896,20 @@ class MyAlias(TypeAliasType):
                 pass
 
 
+class DocTests(BaseTestCase):
+    def test_annotation(self):
+
+        def hi(to: Annotated[str, doc("Who to say hi to")]) -> None: pass
+
+        hints = get_type_hints(hi, include_extras=True)
+        doc_info = hints["to"].__metadata__[0]
+        self.assertEqual(doc_info.documentation, "Who to say hi to")
+        self.assertIsInstance(doc_info, DocInfo)
+
+    def test_repr(self):
+        doc_info = doc("Who to say hi to")
+        self.assertEqual(repr(doc_info), "DocInfo('Who to say hi to')")
+
+
 if __name__ == '__main__':
     main()

src/typing_extensions.py

@@ -60,6 +60,8 @@
     'clear_overloads',
     'dataclass_transform',
     'deprecated',
+    'doc',
+    'DocInfo',
     'get_overloads',
     'final',
     'get_args',
@@ -2809,6 +2811,44 @@ def get_protocol_members(tp: type, /) -> typing.FrozenSet[str]:
             return frozenset(tp.__protocol_attrs__)
         return frozenset(_get_protocol_attrs(tp))
 
+if hasattr(typing, "doc"):
+    doc = typing.doc
+    DocInfo = typing.DocInfo
+else:
+    class DocInfo:
+        """Container for documentation information as returned by ``doc()``.
+
+        It is expected this class wouldn't be manually created but instead returned
+        by ``doc()`` inside of type annotations using ``Annotated``.
+
+        The ``documentation`` attribute contains the documentation string passed
+        to ``doc()``.
+        """
+        def __init__(self, documentation: str):
+            self.documentation = documentation
+
+        def __repr__(self) -> str:
+            return f"DocInfo({self.documentation!r})"
+
+    def doc(documentation: str) -> DocInfo:
+        """Define the documentation of a type annotation using ``Annotated``, to be
+         used in class attributes, function and method parameters, return values,
+         and variables.
+
+        The value should be a string literal to allow static tools like editors
+        to use it.
+
+        This complements docstrings.
+
+        It returns a class ``DocInfo`` instance containing the documentation value in
+        the ``documentation`` attribute.
+
+        Example::
+
+            >>> from typing_extensions import doc, Annotated
+            >>> def hi(to: Annotated[str, doc("Who to say hi to")]) -> None: ...
+        """
+        return DocInfo(documentation)
 
 # Aliases for items that have always been in typing.
 # Explicitly assign these (rather than using `from typing import *` at the top),