@@ -1376,47 +1376,37 @@ These can be used as types in annotations. They all support subscription using
1376
1376
T1 = Annotated[int, ValueRange(-10, 5)]
1377
1377
T2 = Annotated[T1, ValueRange(-20, 3)]
1378
1378
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::
1380
1382
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
1395
1386
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)]
1398
1389
1399
- * The order of the metadata elements is preserved and matters for equality
1400
- checks::
1390
+ assert a1 != a2 # Order matters
1401
1391
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.
1405
1395
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::
1408
1398
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
+ ]
1412
1402
1413
- * Duplicated metadata elements are not removed::
1403
+ Duplicated metadata elements are not removed::
1414
1404
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
+ ]
1418
1408
1419
- * ``Annotated `` can be used with nested and generic aliases:
1409
+ ``Annotated `` can be used with nested and generic aliases:
1420
1410
1421
1411
.. testcode ::
1422
1412
@@ -1430,19 +1420,15 @@ These can be used as types in annotations. They all support subscription using
1430
1420
# ``Annotated[list[tuple[int, int]], MaxLen(10)] ``:
1431
1421
type V = Vec[int]
1432
1422
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 `::
1438
1424
1439
- Annotated[T1, T2, T3, ..., Ann1]
1425
+ type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[ T1, T2, T3, ..., Ann1] # NOT valid
1440
1426
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.
1443
1429
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:
1446
1432
1447
1433
.. doctest ::
1448
1434
@@ -1454,8 +1440,8 @@ These can be used as types in annotations. They all support subscription using
1454
1440
>>> get_type_hints(func, include_extras = True )
1455
1441
{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}
1456
1442
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:
1459
1445
1460
1446
.. doctest ::
1461
1447
@@ -1466,8 +1452,8 @@ These can be used as types in annotations. They all support subscription using
1466
1452
>>> X.__metadata__
1467
1453
('very', 'important', 'metadata')
1468
1454
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:
1471
1457
1472
1458
.. doctest ::
1473
1459
@@ -1476,7 +1462,7 @@ These can be used as types in annotations. They all support subscription using
1476
1462
>>> Password.__origin__
1477
1463
<class 'str'>
1478
1464
1479
- Note that using :func: `get_origin ` will return ``Annotated `` itself:
1465
+ Note that using :func: `get_origin ` will return ``Annotated `` itself:
1480
1466
1481
1467
.. doctest ::
1482
1468
0 commit comments