8000 gh-124269: Simplify `typing.Annotated` docs (#130770) · python/cpython@e4ac196 · GitHub
[go: up one dir, main page]

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit e4ac196

Browse files
StanFromIrelandJelleZijlstrapicnixz
authored
gh-124269: Simplify typing.Annotated docs (#130770)
--------- Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
1 parent c497f83 commit e4ac196

File tree

1 file changed

+33
-47
lines changed

1 file changed

+33
-47
lines changed

Doc/library/typing.rst

Lines changed: 33 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1376,47 +1376,37 @@ These can be used as types in annotations. They all support subscription using
13761376
T1 = Annotated[int, ValueRange(-10, 5)]
13771377
T2 = Annotated[T1, ValueRange(-20, 3)]
13781378

1379-
Details of the syntax:
1379+
The first argument to ``Annotated`` must be a valid type. Multiple metadata
1380+
elements can be supplied as ``Annotated`` supports variadic arguments. The
1381+
order of the metadata elements is preserved and matters for equality checks::
13801382

1381-
* The first argument to ``Annotated`` must be a valid type
1382-
1383-
* Multiple metadata elements can be supplied (``Annotated`` supports variadic
1384-
arguments)::
1385-
1386-
@dataclass
1387-
class ctype:
1388-
kind: str
1389-
1390-
Annotated[int, ValueRange(3, 10), ctype("char")]
1391-
1392-
It is up to the tool consuming the annotations to decide whether the
1393-
client is allowed to add multiple metadata elements to one annotation and how to
1394-
merge those annotations.
1383+
@dataclass
1384+
class ctype:
1385+
kind: str
13951386

1396-
* ``Annotated`` must be subscripted with at least two arguments (
1397-
``Annotated[int]`` is not valid)
1387+
a1 = Annotated[int, ValueRange(3, 10), ctype("char")]
1388+
a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]
13981389

1399-
* The order of the metadata elements is preserved and matters for equality
1400-
checks::
1390+
assert a1 != a2 # Order matters
14011391

1402-
assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
1403-
int, ctype("char"), ValueRange(3, 10)
1404-
]
1392+
It is up to the tool consuming the annotations to decide whether the
1393+
client is allowed to add multiple metadata elements to one annotation and how to
1394+
merge those annotations.
14051395

1406-
* Nested ``Annotated`` types are flattened. The order of the metadata elements
1407-
starts with the innermost annotation::
1396+
Neste 10000 d ``Annotated`` types are flattened. The order of the metadata elements
1397+
starts with the innermost annotation::
14081398

1409-
assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
1410-
int, ValueRange(3, 10), ctype("char")
1411-
]
1399+
assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
1400+
int, ValueRange(3, 10), ctype("char")
1401+
]
14121402

1413-
* Duplicated metadata elements are not removed::
1403+
Duplicated metadata elements are not removed::
14141404

1415-
assert Annotated[int, ValueRange(3, 10)] != Annotated[
1416-
int, ValueRange(3, 10), ValueRange(3, 10)
1417-
]
1405+
assert Annotated[int, ValueRange(3, 10)] != Annotated[
1406+
int, ValueRange(3, 10), ValueRange(3, 10)
1407+
]
14181408

1419-
* ``Annotated`` can be used with nested and generic aliases:
1409+
``Annotated`` can be used with nested and generic aliases:
14201410

14211411
.. testcode::
14221412

@@ -1430,19 +1420,15 @@ These can be used as types in annotations. They all support subscription using
14301420
# ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
14311421
type V = Vec[int]
14321422

1433-
* ``Annotated`` cannot be used with an unpacked :class:`TypeVarTuple`::
1434-
1435-
type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid
1436-
1437-
This would be equivalent to::
1423+
``Annotated`` cannot be used with an unpacked :class:`TypeVarTuple`::
14381424

1439-
Annotated[T1, T2, T3, ..., Ann1]
1425+
type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1] # NOT valid
14401426

1441-
where ``T1``, ``T2``, etc. are :class:`TypeVars <TypeVar>`. This would be
1442-
invalid: only one type should be passed to Annotated.
1427+
where ``T1``, ``T2``, ... are :class:`TypeVars <TypeVar>`. This is invalid as
1428+
only one type should be passed to Annotated.
14431429

1444-
* By default, :func:`get_type_hints` strips the metadata from annotations.
1445-
Pass ``include_extras=True`` to have the metadata preserved:
1430+
By default, :func:`get_type_hints` strips the metadata from annotations.
1431+
Pass ``include_extras=True`` to have the metadata preserved:
14461432

14471433
.. doctest::
14481434

@@ -1454,8 +1440,8 @@ These can be used as types in annotations. They all support subscription using
14541440
>>> get_type_hints(func, include_extras=True)
14551441
{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}
14561442

1457-
* At runtime, the metadata associated with an ``Annotated`` type can be
1458-
retrieved via the :attr:`!__metadata__` attribute:
1443+
At runtime, the metadata associated with an ``Annotated`` type can be
1444+
retrieved via the :attr:`!__metadata__` attribute:
14591445

14601446
.. doctest::
14611447

@@ -1466,8 +1452,8 @@ These can be used as types in annotations. They all support subscription using
14661452
>>> X.__metadata__
14671453
('very', 'important', 'metadata')
14681454

1469-
* At runtime, if you want to retrieve the original
1470-
type wrapped by ``Annotated``, use the :attr:`!__origin__` attribute:
1455+
If you want to retrieve the original type wrapped by ``Annotated``, use the
1456+
:attr:`!__origin__` attribute:
14711457

14721458
.. doctest::
14731459

@@ -1476,7 +1462,7 @@ These can be used as types in annotations. They all support subscription using
14761462
>>> Password.__origin__
14771463
<class 'str'>
14781464

1479-
Note that using :func:`get_origin` will return ``Annotated`` itself:
1465+
Note that using :func:`get_origin` will return ``Annotated`` itself:
14801466

14811467
.. doctest::
14821468

0 commit comments

Comments
 (0)
0