From 812fccf3f37da33090e9bdbeaa3199a7f317deed Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 14 Mar 2025 09:46:57 +0000 Subject: [PATCH] gh-124269: Simplify `typing.Annotated` docs (GH-130770) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --------- (cherry picked from commit e4ac196aaaa9fd2f1bd0050797b58959671c549a) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Jelle Zijlstra Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/typing.rst | 80 +++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 47 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index facfeb4f8d3455..ab1c8e937b75dc 100644 --- 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 `. This would be - invalid: only one type should be passed to Annotated. + where ``T1``, ``T2``, ... are :class:`TypeVars `. 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': } - * 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__ - Note that using :func:`get_origin` will return ``Annotated`` itself: + Note that using :func:`get_origin` will return ``Annotated`` itself: .. doctest::