[3.12] pythongh-124269: Simplify typing.Annotated docs (pythonGH-130770) (python#131223)

miss-islington · StanFromIreland · JelleZijlstra · mike c · commit f3902d1f9400 · 2025-03-14T15:42:58.000-04:00
pythongh-124269: Simplify `typing.Annotated` docs (pythonGH-130770) --------- (cherry picked from commit e4ac196) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -1315,47 +1315,37 @@ These can be used as types in annotations. They all support subscription using
       T1 = Annotated[int, ValueRange(-10, 5)]
       T2 = Annotated[T1, ValueRange(-20, 3)]
 
-   Details of the syntax:
+   The first argument to ``Annotated`` must be a valid type. Multiple metadata
+   elements can be supplied as ``Annotated`` supports variadic arguments. The
+   order of the metadata elements is preserved and matters for equality checks::
 
-   * The first argument to ``Annotated`` must be a valid type
-
-   * Multiple metadata elements can be supplied (``Annotated`` supports variadic
-     arguments)::
-
-        @dataclass
-        class ctype:
-            kind: str
-
-        Annotated[int, ValueRange(3, 10), ctype("char")]
-
-     It is up to the tool consuming the annotations to decide whether the
-     client is allowed to add multiple metadata elements to one annotation and how to
-     merge those annotations.
+      @dataclass
+      class ctype:
+           kind: str
 
-   * ``Annotated`` must be subscripted with at least two arguments (
-     ``Annotated[int]`` is not valid)
+      a1 = Annotated[int, ValueRange(3, 10), ctype("char")]
+      a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]
 
-   * The order of the metadata elements is preserved and matters for equality
-     checks::
+      assert a1 != a2  # Order matters
 
-        assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
-            int, ctype("char"), ValueRange(3, 10)
-        ]
+   It is up to the tool consuming the annotations to decide whether the
+   client is allowed to add multiple metadata elements to one annotation and how to
+   merge those annotations.
 
-   * Nested ``Annotated`` types are flattened. The order of the metadata elements
-     starts with the innermost annotation::
+   Nested ``Annotated`` types are flattened. The order of the metadata elements
+   starts with the innermost annotation::
 
-        assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
-            int, ValueRange(3, 10), ctype("char")
-        ]
+      assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
+          int, ValueRange(3, 10), ctype("char")
+      ]
 
-   * Duplicated metadata elements are not removed::
+   Duplicated metadata elements are not removed::
 
-        assert Annotated[int, ValueRange(3, 10)] != Annotated[
-            int, ValueRange(3, 10), ValueRange(3, 10)
-        ]
+      assert Annotated[int, ValueRange(3, 10)] != Annotated[
+          int, ValueRange(3, 10), ValueRange(3, 10)
+      ]
 
-   * ``Annotated`` can be used with nested and generic aliases:
+   ``Annotated`` can be used with nested and generic aliases:
 
      .. testcode::
 
@@ -1369,19 +1359,15 @@ These can be used as types in annotations. They all support subscription using
         # ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
         type V = Vec[int]
 
-   * ``Annotated`` cannot be used with an unpacked :class:`TypeVarTuple`::
-
-        type Variadic[*Ts] = Annotated[*Ts, Ann1]  # NOT valid
-
-     This would be equivalent to::
+   ``Annotated`` cannot be used with an unpacked :class:`TypeVarTuple`::
 
-        Annotated[T1, T2, T3, ..., Ann1]
+        type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1]  # NOT valid
 
-     where ``T1``, ``T2``, etc. are :class:`TypeVars <TypeVar>`. This would be
-     invalid: only one type should be passed to Annotated.
+   where ``T1``, ``T2``, ... are :class:`TypeVars <TypeVar>`. This is invalid as
+   only one type should be passed to Annotated.
 
-   * By default, :func:`get_type_hints` strips the metadata from annotations.
-     Pass ``include_extras=True`` to have the metadata preserved:
+   By default, :func:`get_type_hints` strips the metadata from annotations.
+   Pass ``include_extras=True`` to have the metadata preserved:
 
      .. doctest::
 
@@ -1393,8 +1379,8 @@ These can be used as types in annotations. They all support subscription using
         >>> get_type_hints(func, include_extras=True)
         {'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}
 
-   * At runtime, the metadata associated with an ``Annotated`` type can be
-     retrieved via the :attr:`!__metadata__` attribute:
+   At runtime, the metadata associated with an ``Annotated`` type can be
+   retrieved via the :attr:`!__metadata__` attribute:
 
      .. doctest::
 
@@ -1405,8 +1391,8 @@ These can be used as types in annotations. They all support subscription using
         >>> X.__metadata__
         ('very', 'important', 'metadata')
 
-   * At runtime, if you want to retrieve the original
-     type wrapped by ``Annotated``, use the :attr:`!__origin__` attribute:
+   If you want to retrieve the original type wrapped by ``Annotated``, use the
+   :attr:`!__origin__` attribute:
 
      .. doctest::
 
@@ -1415,7 +1401,7 @@ These can be used as types in annotations. They all support subscription using
         >>> Password.__origin__
         <class 'str'>
 
-     Note that using :func:`get_origin` will return ``Annotated`` itself:
+   Note that using :func:`get_origin` will return ``Annotated`` itself:
 
      .. doctest::
 
