mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 17:08:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

[3.12] gh-124269: Simplify typing.Annotated docs (GH-130770) (#131223)

Browse source 
gh-124269: Simplify `typing.Annotated` docs (GH-130770)

---------
(cherry picked from commit e4ac196aaa)

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>
This commit is contained in:
Miss Islington (bot) 2025-03-14 10:54:08 +01:00 • committed by GitHub
parent a3f4889413
commit 39b4f8b6ed
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 33 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

80
Doc/library/typing.rst
View file

@ -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
@dataclass
class ctype:
kind: str
* Multiple metadata elements can be supplied (``Annotated`` supports variadic
arguments)::
a1 = Annotated[int, ValueRange(3, 10), ctype("char")]
a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]
@dataclass
class ctype:
kind: str
assert a1 != a2 # Order matters
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.
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::
* ``Annotated`` must be subscripted with at least two arguments (
``Annotated[int]`` is not valid)
assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
int, ValueRange(3, 10), ctype("char")
]
* The order of the metadata elements is preserved and matters for equality
checks::
Duplicated metadata elements are not removed::
assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
int, ctype("char"), ValueRange(3, 10)
]
assert Annotated[int, ValueRange(3, 10)] != Annotated[
int, ValueRange(3, 10), ValueRange(3, 10)
]
* 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")
]
* Duplicated metadata elements are not removed::
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`::
``Annotated`` cannot be used with an unpacked :class:`TypeVarTuple`::
type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid
type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1] # NOT valid
This would be equivalent to::
where ``T1``, ``T2``, ... are :class:`TypeVars <TypeVar>`. This is invalid as
only one type should be passed to Annotated.
Annotated[T1, T2, T3, ..., Ann1]
where ``T1``, ``T2``, etc. are :class:`TypeVars <TypeVar>`. 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::
@ -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::