From b3e2c908bc99c1ae9e28449faa9fb0a63e57c1e7 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 2 Mar 2025 19:46:06 +0000 Subject: [PATCH 1/7] Simplify Annotated docs --- Doc/library/typing.rst | 88 +++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 53 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 0fee782121b0af..7ab6d3ae3b2352 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1368,47 +1368,39 @@ 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: + ``Annotated`` must be subscripted with at least two arguments. + 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) + Annotated[int, ValueRange(3, 10), ctype("char")] - * The order of the metadata elements is preserved and matters for equality - checks:: + assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[ + int, ctype("char"), ValueRange(3, 10) + ] # 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:: @@ -1422,19 +1414,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 + ``Annotated`` cannot be used with an unpacked :class:`TypeVarTuple`:: - This would be equivalent to:: + type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1] # NOT valid - Annotated[T1, T2, T3, ..., Ann1] + where ``T1``, ``T2``,... are :class:`TypeVars `. This is invalid as + only one type should be passed to Annotated. - where ``T1``, ``T2``, etc. are :class:`TypeVars `. This would be - invalid: 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:: @@ -1446,29 +1434,23 @@ 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. If you want to retrieve + the original type wrapped by ``Annotated``, use the :attr:`!__origin__` attribute: .. doctest:: - >>> from typing import Annotated + >>> from typing import Annotated, get_origin >>> X = Annotated[int, "very", "important", "metadata"] >>> X typing.Annotated[int, 'very', 'important', 'metadata'] >>> X.__metadata__ ('very', 'important', 'metadata') - - * At runtime, if you want to retrieve the original - type wrapped by ``Annotated``, use the :attr:`!__origin__` attribute: - - .. doctest:: - - >>> from typing import Annotated, get_origin >>> Password = Annotated[str, "secret"] >>> Password.__origin__ - Note that using :func:`get_origin` will return ``Annotated`` itself: + Note that using :func:`get_origin` will return ``Annotated`` itself: .. doctest:: From f54a3688af3f39aad3082e26190356abec9518ca Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 3 Mar 2025 23:06:28 +0000 Subject: [PATCH 2/7] Apply suggestions from Jelle --- Doc/library/typing.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7ab6d3ae3b2352..294c92e216b0d0 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1368,7 +1368,6 @@ 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)] - ``Annotated`` must be subscripted with at least two arguments. 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:: @@ -1418,7 +1417,7 @@ These can be used as types in annotations. They all support subscription using type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1] # NOT valid - where ``T1``, ``T2``,... are :class:`TypeVars `. This is invalid as + 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. From d9ce97435d01164b7f55011510dbae66f67b2b87 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Mon, 3 Mar 2025 23:19:32 +0000 Subject: [PATCH 3/7] Apply suggestions Co-authored-by: Jelle Zijlstra --- Doc/library/typing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 294c92e216b0d0..661ed6209d9cfb 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1374,7 +1374,7 @@ These can be used as types in annotations. They all support subscription using @dataclass class ctype: - kind: str + kind: str Annotated[int, ValueRange(3, 10), ctype("char")] @@ -1390,13 +1390,13 @@ These can be used as types in annotations. They all support subscription using starts with the innermost annotation:: assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[ - int, ValueRange(3, 10), ctype("char") + int, ValueRange(3, 10), ctype("char") ] Duplicated metadata elements are not removed:: assert Annotated[int, ValueRange(3, 10)] != Annotated[ - int, ValueRange(3, 10), ValueRange(3, 10) + int, ValueRange(3, 10), ValueRange(3, 10) ] ``Annotated`` can be used with nested and generic aliases: From f13b485ed27dc928b3442d419ecfe7886f862855 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 7 Mar 2025 18:30:48 +0000 Subject: [PATCH 4/7] Benedikt's suggestions --- Doc/library/typing.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 661ed6209d9cfb..bfedb2f6808243 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1376,11 +1376,10 @@ These can be used as types in annotations. They all support subscription using class ctype: kind: str - Annotated[int, ValueRange(3, 10), ctype("char")] + a1 = Annotated[int, ValueRange(3, 10), ctype("char")] + a2 = Annotated[int, ctype("char"), ValueRange(3, 10)] - assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[ - int, ctype("char"), ValueRange(3, 10) - ] # Order matters + assert a1 != a2 # Order matters 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 @@ -1445,6 +1444,9 @@ These can be used as types in annotations. They all support subscription using typing.Annotated[int, 'very', 'important', 'metadata'] >>> X.__metadata__ ('very', 'important', 'metadata') + + .. doctest:: + >>> Password = Annotated[str, "secret"] >>> Password.__origin__ From 9abbabb787dd1d3069d763474cc89d3fe34c67f3 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 12 Mar 2025 18:57:43 +0000 Subject: [PATCH 5/7] Benedikt's suggestions --- Doc/library/typing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index bfedb2f6808243..d1b2ff5c4c57bb 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1379,7 +1379,7 @@ These can be used as types in annotations. They all support subscription using a1 = Annotated[int, ValueRange(3, 10), ctype("char")] a2 = Annotated[int, ctype("char"), ValueRange(3, 10)] - assert a1 != a2 # Order matters + assert a1 != a2 # Order matters 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 @@ -1447,6 +1447,7 @@ These can be used as types in annotations. They all support subscription using .. doctest:: + >>> from typing import Annotated, get_origin >>> Password = Annotated[str, "secret"] >>> Password.__origin__ From e79625df8db6a9083ed3ebced7aafdc343d89473 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 13 Mar 2025 15:41:04 +0000 Subject: [PATCH 6/7] Benedikt won, I moved the section ;-) --- Doc/library/typing.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index d1b2ff5c4c57bb..393bad0d72df43 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1433,18 +1433,20 @@ These can be used as types in annotations. They all support subscription using {'x': typing.Annotated[int, 'metadata'], 'return': } At runtime, the metadata associated with an ``Annotated`` type can be - retrieved via the :attr:`!__metadata__` attribute. If you want to retrieve - the original type wrapped by ``Annotated``, use the :attr:`!__origin__` attribute: + retrieved via the :attr:`!__metadata__` attribute. .. doctest:: - >>> from typing import Annotated, get_origin + >>> from typing import Annotated >>> X = Annotated[int, "very", "important", "metadata"] >>> X typing.Annotated[int, 'very', 'important', 'metadata'] >>> X.__metadata__ ('very', 'important', 'metadata') + If you want to retrieve the original type wrapped by ``Annotated``, use the + :attr:`!__origin__` attribute: + .. doctest:: >>> from typing import Annotated, get_origin From 54e3b19b8cb77262aa9eb65378e44c5316e10312 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 13 Mar 2025 16:33:04 +0000 Subject: [PATCH 7/7] Update with Benedikts suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/typing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 393bad0d72df43..125aed8d1aaf0f 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1433,7 +1433,7 @@ These can be used as types in annotations. They all support subscription using {'x': typing.Annotated[int, 'metadata'], 'return': } At runtime, the metadata associated with an ``Annotated`` type can be - retrieved via the :attr:`!__metadata__` attribute. + retrieved via the :attr:`!__metadata__` attribute: .. doctest::