https://github.com/python/cpython/commit/e4ac196aaaa9fd2f1bd0050797b58959671c549a
commit: e4ac196aaaa9fd2f1bd0050797b58959671c549a
branch: main
author: Stan Ulbrych <89152624+stanfromirel...@users.noreply.github.com>
committer: picnixz <10796600+picn...@users.noreply.github.com>
date: 2025-03-14T10:46:57+01:00
summary:
gh-124269: Simplify `typing.Annotated` docs (#130770)
---------
Co-authored-by: Jelle Zijlstra <jelle.zijls...@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picn...@users.noreply.github.com>
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 6d5ee75f11efa7..44cbc73d7ca478 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1376,47 +1376,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::
@@ -1430,19 +1420,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::
@@ -1454,8 +1440,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::
@@ -1466,8 +1452,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::
@@ -1476,7 +1462,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::
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
