typing
The typing module: Support for gradual typing as defined by PEP 484 and subsequent PEPs.
Among other things, the module includes the following:
- Generic, Protocol, and internal machinery to support generic aliases. All subscripted types like X[int], Union[int, str] are generic aliases.
- Various "special forms" that have unique meanings in type annotations: NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others.
- Classes whose instances can be type arguments to generic classes and functions: TypeVar, ParamSpec, TypeVarTuple.
- Public helper functions: get_type_hints, overload, cast, final, and others.
- Several protocols to support duck-typing: SupportsFloat, SupportsIndex, SupportsAbs, and others.
- Special types: NewType, NamedTuple, TypedDict.
- Deprecated wrapper submodules for re and io related types.
- Deprecated aliases for builtin types and collections.abc ABCs.
Any name not present in __all__ is an implementation detail that may be changed without notice. Use at your own risk!
1""" 2The typing module: Support for gradual typing as defined by PEP 484 and subsequent PEPs. 3 4Among other things, the module includes the following: 5* Generic, Protocol, and internal machinery to support generic aliases. 6 All subscripted types like X[int], Union[int, str] are generic aliases. 7* Various "special forms" that have unique meanings in type annotations: 8 NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others. 9* Classes whose instances can be type arguments to generic classes and functions: 10 TypeVar, ParamSpec, TypeVarTuple. 11* Public helper functions: get_type_hints, overload, cast, final, and others. 12* Several protocols to support duck-typing: 13 SupportsFloat, SupportsIndex, SupportsAbs, and others. 14* Special types: NewType, NamedTuple, TypedDict. 15* Deprecated wrapper submodules for re and io related types. 16* Deprecated aliases for builtin types and collections.abc ABCs. 17 18Any name not present in __all__ is an implementation detail 19that may be changed without notice. Use at your own risk! 20""" 21 22from abc import abstractmethod, ABCMeta 23import collections 24from collections import defaultdict 25import collections.abc 26import copyreg 27import contextlib 28import functools 29import operator 30import re as stdlib_re # Avoid confusion with the re we export. 31import sys 32import types 33import warnings 34from types import WrapperDescriptorType, MethodWrapperType, MethodDescriptorType, GenericAlias 35 36from _typing import ( 37 _idfunc, 38 TypeVar, 39 ParamSpec, 40 TypeVarTuple, 41 ParamSpecArgs, 42 ParamSpecKwargs, 43 TypeAliasType, 44 Generic, 45) 46 47# Please keep __all__ alphabetized within each category. 48__all__ = [ 49 # Super-special typing primitives. 50 'Annotated', 51 'Any', 52 'Callable', 53 'ClassVar', 54 'Concatenate', 55 'Final', 56 'ForwardRef', 57 'Generic', 58 'Literal', 59 'Optional', 60 'ParamSpec', 61 'Protocol', 62 'Tuple', 63 'Type', 64 'TypeVar', 65 'TypeVarTuple', 66 'Union', 67 68 # ABCs (from collections.abc). 69 'AbstractSet', # collections.abc.Set. 70 'ByteString', 71 'Container', 72 'ContextManager', 73 'Hashable', 74 'ItemsView', 75 'Iterable', 76 'Iterator', 77 'KeysView', 78 'Mapping', 79 'MappingView', 80 'MutableMapping', 81 'MutableSequence', 82 'MutableSet', 83 'Sequence', 84 'Sized', 85 'ValuesView', 86 'Awaitable', 87 'AsyncIterator', 88 'AsyncIterable', 89 'Coroutine', 90 'Collection', 91 'AsyncGenerator', 92 'AsyncContextManager', 93 94 # Structural checks, a.k.a. protocols. 95 'Reversible', 96 'SupportsAbs', 97 'SupportsBytes', 98 'SupportsComplex', 99 'SupportsFloat', 100 'SupportsIndex', 101 'SupportsInt', 102 'SupportsRound', 103 104 # Concrete collection types. 105 'ChainMap', 106 'Counter', 107 'Deque', 108 'Dict', 109 'DefaultDict', 110 'List', 111 'OrderedDict', 112 'Set', 113 'FrozenSet', 114 'NamedTuple', # Not really a type. 115 'TypedDict', # Not really a type. 116 'Generator', 117 118 # Other concrete types. 119 'BinaryIO', 120 'IO', 121 'Match', 122 'Pattern', 123 'TextIO', 124 125 # One-off things. 126 'AnyStr', 127 'assert_type', 128 'assert_never', 129 'cast', 130 'clear_overloads', 131 'dataclass_transform', 132 'final', 133 'get_args', 134 'get_origin', 135 'get_overloads', 136 'get_type_hints', 137 'is_typeddict', 138 'LiteralString', 139 'Never', 140 'NewType', 141 'no_type_check', 142 'no_type_check_decorator', 143 'NoReturn', 144 'NotRequired', 145 'overload', 146 'override', 147 'ParamSpecArgs', 148 'ParamSpecKwargs', 149 'Required', 150 'reveal_type', 151 'runtime_checkable', 152 'Self', 153 'Text', 154 'TYPE_CHECKING', 155 'TypeAlias', 156 'TypeGuard', 157 'TypeAliasType', 158 'Unpack', 159] 160 161# The pseudo-submodules 're' and 'io' are part of the public 162# namespace, but excluded from __all__ because they might stomp on 163# legitimate imports of those modules. 164 165 166def _type_convert(arg, module=None, *, allow_special_forms=False): 167 """For converting None to type(None), and strings to ForwardRef.""" 168 if arg is None: 169 return type(None) 170 if isinstance(arg, str): 171 return ForwardRef(arg, module=module, is_class=allow_special_forms) 172 return arg 173 174 175def _type_check(arg, msg, is_argument=True, module=None, *, allow_special_forms=False): 176 """Check that the argument is a type, and return it (internal helper). 177 178 As a special case, accept None and return type(None) instead. Also wrap strings 179 into ForwardRef instances. Consider several corner cases, for example plain 180 special forms like Union are not valid, while Union[int, str] is OK, etc. 181 The msg argument is a human-readable error message, e.g.:: 182 183 "Union[arg, ...]: arg should be a type." 184 185 We append the repr() of the actual value (truncated to 100 chars). 186 """ 187 invalid_generic_forms = (Generic, Protocol) 188 if not allow_special_forms: 189 invalid_generic_forms += (ClassVar,) 190 if is_argument: 191 invalid_generic_forms += (Final,) 192 193 arg = _type_convert(arg, module=module, allow_special_forms=allow_special_forms) 194 if (isinstance(arg, _GenericAlias) and 195 arg.__origin__ in invalid_generic_forms): 196 raise TypeError(f"{arg} is not valid as type argument") 197 if arg in (Any, LiteralString, NoReturn, Never, Self, TypeAlias): 198 return arg 199 if allow_special_forms and arg in (ClassVar, Final): 200 return arg 201 if isinstance(arg, _SpecialForm) or arg in (Generic, Protocol): 202 raise TypeError(f"Plain {arg} is not valid as type argument") 203 if type(arg) is tuple: 204 raise TypeError(f"{msg} Got {arg!r:.100}.") 205 return arg 206 207 208def _is_param_expr(arg): 209 return arg is ... or isinstance(arg, 210 (tuple, list, ParamSpec, _ConcatenateGenericAlias)) 211 212 213def _should_unflatten_callable_args(typ, args): 214 """Internal helper for munging collections.abc.Callable's __args__. 215 216 The canonical representation for a Callable's __args__ flattens the 217 argument types, see https://github.com/python/cpython/issues/86361. 218 219 For example:: 220 221 >>> import collections.abc 222 >>> P = ParamSpec('P') 223 >>> collections.abc.Callable[[int, int], str].__args__ == (int, int, str) 224 True 225 >>> collections.abc.Callable[P, str].__args__ == (P, str) 226 True 227 228 As a result, if we need to reconstruct the Callable from its __args__, 229 we need to unflatten it. 230 """ 231 return ( 232 typ.__origin__ is collections.abc.Callable 233 and not (len(args) == 2 and _is_param_expr(args[0])) 234 ) 235 236 237def _type_repr(obj): 238 """Return the repr() of an object, special-casing types (internal helper). 239 240 If obj is a type, we return a shorter version than the default 241 type.__repr__, based on the module and qualified name, which is 242 typically enough to uniquely identify a type. For everything 243 else, we fall back on repr(obj). 244 """ 245 # When changing this function, don't forget about 246 # `_collections_abc._type_repr`, which does the same thing 247 # and must be consistent with this one. 248 if isinstance(obj, type): 249 if obj.__module__ == 'builtins': 250 return obj.__qualname__ 251 return f'{obj.__module__}.{obj.__qualname__}' 252 if obj is ...: 253 return '...' 254 if isinstance(obj, types.FunctionType): 255 return obj.__name__ 256 if isinstance(obj, tuple): 257 # Special case for `repr` of types with `ParamSpec`: 258 return '[' + ', '.join(_type_repr(t) for t in obj) + ']' 259 return repr(obj) 260 261 262def _collect_parameters(args): 263 """Collect all type variables and parameter specifications in args 264 in order of first appearance (lexicographic order). 265 266 For example:: 267 268 >>> P = ParamSpec('P') 269 >>> T = TypeVar('T') 270 >>> _collect_parameters((T, Callable[P, T])) 271 (~T, ~P) 272 """ 273 parameters = [] 274 for t in args: 275 if isinstance(t, type): 276 # We don't want __parameters__ descriptor of a bare Python class. 277 pass 278 elif isinstance(t, tuple): 279 # `t` might be a tuple, when `ParamSpec` is substituted with 280 # `[T, int]`, or `[int, *Ts]`, etc. 281 for x in t: 282 for collected in _collect_parameters([x]): 283 if collected not in parameters: 284 parameters.append(collected) 285 elif hasattr(t, '__typing_subst__'): 286 if t not in parameters: 287 parameters.append(t) 288 else: 289 for x in getattr(t, '__parameters__', ()): 290 if x not in parameters: 291 parameters.append(x) 292 return tuple(parameters) 293 294 295def _check_generic(cls, parameters, elen): 296 """Check correct count for parameters of a generic cls (internal helper). 297 298 This gives a nice error message in case of count mismatch. 299 """ 300 if not elen: 301 raise TypeError(f"{cls} is not a generic class") 302 alen = len(parameters) 303 if alen != elen: 304 raise TypeError(f"Too {'many' if alen > elen else 'few'} arguments for {cls};" 305 f" actual {alen}, expected {elen}") 306 307def _unpack_args(args): 308 newargs = [] 309 for arg in args: 310 subargs = getattr(arg, '__typing_unpacked_tuple_args__', None) 311 if subargs is not None and not (subargs and subargs[-1] is ...): 312 newargs.extend(subargs) 313 else: 314 newargs.append(arg) 315 return newargs 316 317def _deduplicate(params, *, unhashable_fallback=False): 318 # Weed out strict duplicates, preserving the first of each occurrence. 319 try: 320 return dict.fromkeys(params) 321 except TypeError: 322 if not unhashable_fallback: 323 raise 324 # Happens for cases like `Annotated[dict, {'x': IntValidator()}]` 325 return _deduplicate_unhashable(params) 326 327def _deduplicate_unhashable(unhashable_params): 328 new_unhashable = [] 329 for t in unhashable_params: 330 if t not in new_unhashable: 331 new_unhashable.append(t) 332 return new_unhashable 333 334def _compare_args_orderless(first_args, second_args): 335 first_unhashable = _deduplicate_unhashable(first_args) 336 second_unhashable = _deduplicate_unhashable(second_args) 337 t = list(second_unhashable) 338 try: 339 for elem in first_unhashable: 340 t.remove(elem) 341 except ValueError: 342 return False 343 return not t 344 345def _remove_dups_flatten(parameters): 346 """Internal helper for Union creation and substitution. 347 348 Flatten Unions among parameters, then remove duplicates. 349 """ 350 # Flatten out Union[Union[...], ...]. 351 params = [] 352 for p in parameters: 353 if isinstance(p, (_UnionGenericAlias, types.UnionType)): 354 params.extend(p.__args__) 355 else: 356 params.append(p) 357 358 return tuple(_deduplicate(params, unhashable_fallback=True)) 359 360 361def _flatten_literal_params(parameters): 362 """Internal helper for Literal creation: flatten Literals among parameters.""" 363 params = [] 364 for p in parameters: 365 if isinstance(p, _LiteralGenericAlias): 366 params.extend(p.__args__) 367 else: 368 params.append(p) 369 return tuple(params) 370 371 372_cleanups = [] 373_caches = {} 374 375 376def _tp_cache(func=None, /, *, typed=False): 377 """Internal wrapper caching __getitem__ of generic types. 378 379 For non-hashable arguments, the original function is used as a fallback. 380 """ 381 def decorator(func): 382 # The callback 'inner' references the newly created lru_cache 383 # indirectly by performing a lookup in the global '_caches' dictionary. 384 # This breaks a reference that can be problematic when combined with 385 # C API extensions that leak references to types. See GH-98253. 386 387 cache = functools.lru_cache(typed=typed)(func) 388 _caches[func] = cache 389 _cleanups.append(cache.cache_clear) 390 del cache 391 392 @functools.wraps(func) 393 def inner(*args, **kwds): 394 try: 395 return _caches[func](*args, **kwds) 396 except TypeError: 397 pass # All real errors (not unhashable args) are raised below. 398 return func(*args, **kwds) 399 return inner 400 401 if func is not None: 402 return decorator(func) 403 404 return decorator 405 406 407def _eval_type(t, globalns, localns, type_params=None, *, recursive_guard=frozenset()): 408 """Evaluate all forward references in the given type t. 409 410 For use of globalns and localns see the docstring for get_type_hints(). 411 recursive_guard is used to prevent infinite recursion with a recursive 412 ForwardRef. 413 """ 414 if isinstance(t, ForwardRef): 415 return t._evaluate(globalns, localns, type_params, recursive_guard=recursive_guard) 416 if isinstance(t, (_GenericAlias, GenericAlias, types.UnionType)): 417 if isinstance(t, GenericAlias): 418 args = tuple( 419 ForwardRef(arg) if isinstance(arg, str) else arg 420 for arg in t.__args__ 421 ) 422 is_unpacked = t.__unpacked__ 423 if _should_unflatten_callable_args(t, args): 424 t = t.__origin__[(args[:-1], args[-1])] 425 else: 426 t = t.__origin__[args] 427 if is_unpacked: 428 t = Unpack[t] 429 430 ev_args = tuple( 431 _eval_type( 432 a, globalns, localns, type_params, recursive_guard=recursive_guard 433 ) 434 for a in t.__args__ 435 ) 436 if ev_args == t.__args__: 437 return t 438 if isinstance(t, GenericAlias): 439 return GenericAlias(t.__origin__, ev_args) 440 if isinstance(t, types.UnionType): 441 return functools.reduce(operator.or_, ev_args) 442 else: 443 return t.copy_with(ev_args) 444 return t 445 446 447class _Final: 448 """Mixin to prohibit subclassing.""" 449 450 __slots__ = ('__weakref__',) 451 452 def __init_subclass__(cls, /, *args, **kwds): 453 if '_root' not in kwds: 454 raise TypeError("Cannot subclass special typing classes") 455 456 457class _NotIterable: 458 """Mixin to prevent iteration, without being compatible with Iterable. 459 460 That is, we could do:: 461 462 def __iter__(self): raise TypeError() 463 464 But this would make users of this mixin duck type-compatible with 465 collections.abc.Iterable - isinstance(foo, Iterable) would be True. 466 467 Luckily, we can instead prevent iteration by setting __iter__ to None, which 468 is treated specially. 469 """ 470 471 __slots__ = () 472 __iter__ = None 473 474 475# Internal indicator of special typing constructs. 476# See __doc__ instance attribute for specific docs. 477class _SpecialForm(_Final, _NotIterable, _root=True): 478 __slots__ = ('_name', '__doc__', '_getitem') 479 480 def __init__(self, getitem): 481 self._getitem = getitem 482 self._name = getitem.__name__ 483 self.__doc__ = getitem.__doc__ 484 485 def __getattr__(self, item): 486 if item in {'__name__', '__qualname__'}: 487 return self._name 488 489 raise AttributeError(item) 490 491 def __mro_entries__(self, bases): 492 raise TypeError(f"Cannot subclass {self!r}") 493 494 def __repr__(self): 495 return 'typing.' + self._name 496 497 def __reduce__(self): 498 return self._name 499 500 def __call__(self, *args, **kwds): 501 raise TypeError(f"Cannot instantiate {self!r}") 502 503 def __or__(self, other): 504 return Union[self, other] 505 506 def __ror__(self, other): 507 return Union[other, self] 508 509 def __instancecheck__(self, obj): 510 raise TypeError(f"{self} cannot be used with isinstance()") 511 512 def __subclasscheck__(self, cls): 513 raise TypeError(f"{self} cannot be used with issubclass()") 514 515 @_tp_cache 516 def __getitem__(self, parameters): 517 return self._getitem(self, parameters) 518 519 520class _LiteralSpecialForm(_SpecialForm, _root=True): 521 def __getitem__(self, parameters): 522 if not isinstance(parameters, tuple): 523 parameters = (parameters,) 524 return self._getitem(self, *parameters) 525 526 527class _AnyMeta(type): 528 def __instancecheck__(self, obj): 529 if self is Any: 530 raise TypeError("typing.Any cannot be used with isinstance()") 531 return super().__instancecheck__(obj) 532 533 def __repr__(self): 534 if self is Any: 535 return "typing.Any" 536 return super().__repr__() # respect to subclasses 537 538 539class Any(metaclass=_AnyMeta): 540 """Special type indicating an unconstrained type. 541 542 - Any is compatible with every type. 543 - Any assumed to have all methods. 544 - All values assumed to be instances of Any. 545 546 Note that all the above statements are true from the point of view of 547 static type checkers. At runtime, Any should not be used with instance 548 checks. 549 """ 550 551 def __new__(cls, *args, **kwargs): 552 if cls is Any: 553 raise TypeError("Any cannot be instantiated") 554 return super().__new__(cls) 555 556 557@_SpecialForm 558def NoReturn(self, parameters): 559 """Special type indicating functions that never return. 560 561 Example:: 562 563 from typing import NoReturn 564 565 def stop() -> NoReturn: 566 raise Exception('no way') 567 568 NoReturn can also be used as a bottom type, a type that 569 has no values. Starting in Python 3.11, the Never type should 570 be used for this concept instead. Type checkers should treat the two 571 equivalently. 572 """ 573 raise TypeError(f"{self} is not subscriptable") 574 575# This is semantically identical to NoReturn, but it is implemented 576# separately so that type checkers can distinguish between the two 577# if they want. 578@_SpecialForm 579def Never(self, parameters): 580 """The bottom type, a type that has no members. 581 582 This can be used to define a function that should never be 583 called, or a function that never returns:: 584 585 from typing import Never 586 587 def never_call_me(arg: Never) -> None: 588 pass 589 590 def int_or_str(arg: int | str) -> None: 591 never_call_me(arg) # type checker error 592 match arg: 593 case int(): 594 print("It's an int") 595 case str(): 596 print("It's a str") 597 case _: 598 never_call_me(arg) # OK, arg is of type Never 599 """ 600 raise TypeError(f"{self} is not subscriptable") 601 602 603@_SpecialForm 604def Self(self, parameters): 605 """Used to spell the type of "self" in classes. 606 607 Example:: 608 609 from typing import Self 610 611 class Foo: 612 def return_self(self) -> Self: 613 ... 614 return self 615 616 This is especially useful for: 617 - classmethods that are used as alternative constructors 618 - annotating an `__enter__` method which returns self 619 """ 620 raise TypeError(f"{self} is not subscriptable") 621 622 623@_SpecialForm 624def LiteralString(self, parameters): 625 """Represents an arbitrary literal string. 626 627 Example:: 628 629 from typing import LiteralString 630 631 def run_query(sql: LiteralString) -> None: 632 ... 633 634 def caller(arbitrary_string: str, literal_string: LiteralString) -> None: 635 run_query("SELECT * FROM students") # OK 636 run_query(literal_string) # OK 637 run_query("SELECT * FROM " + literal_string) # OK 638 run_query(arbitrary_string) # type checker error 639 run_query( # type checker error 640 f"SELECT * FROM students WHERE name = {arbitrary_string}" 641 ) 642 643 Only string literals and other LiteralStrings are compatible 644 with LiteralString. This provides a tool to help prevent 645 security issues such as SQL injection. 646 """ 647 raise TypeError(f"{self} is not subscriptable") 648 649 650@_SpecialForm 651def ClassVar(self, parameters): 652 """Special type construct to mark class variables. 653 654 An annotation wrapped in ClassVar indicates that a given 655 attribute is intended to be used as a class variable and 656 should not be set on instances of that class. 657 658 Usage:: 659 660 class Starship: 661 stats: ClassVar[dict[str, int]] = {} # class variable 662 damage: int = 10 # instance variable 663 664 ClassVar accepts only types and cannot be further subscribed. 665 666 Note that ClassVar is not a class itself, and should not 667 be used with isinstance() or issubclass(). 668 """ 669 item = _type_check(parameters, f'{self} accepts only single type.') 670 return _GenericAlias(self, (item,)) 671 672@_SpecialForm 673def Final(self, parameters): 674 """Special typing construct to indicate final names to type checkers. 675 676 A final name cannot be re-assigned or overridden in a subclass. 677 678 For example:: 679 680 MAX_SIZE: Final = 9000 681 MAX_SIZE += 1 # Error reported by type checker 682 683 class Connection: 684 TIMEOUT: Final[int] = 10 685 686 class FastConnector(Connection): 687 TIMEOUT = 1 # Error reported by type checker 688 689 There is no runtime checking of these properties. 690 """ 691 item = _type_check(parameters, f'{self} accepts only single type.') 692 return _GenericAlias(self, (item,)) 693 694@_SpecialForm 695def Union(self, parameters): 696 """Union type; Union[X, Y] means either X or Y. 697 698 On Python 3.10 and higher, the | operator 699 can also be used to denote unions; 700 X | Y means the same thing to the type checker as Union[X, Y]. 701 702 To define a union, use e.g. Union[int, str]. Details: 703 - The arguments must be types and there must be at least one. 704 - None as an argument is a special case and is replaced by 705 type(None). 706 - Unions of unions are flattened, e.g.:: 707 708 assert Union[Union[int, str], float] == Union[int, str, float] 709 710 - Unions of a single argument vanish, e.g.:: 711 712 assert Union[int] == int # The constructor actually returns int 713 714 - Redundant arguments are skipped, e.g.:: 715 716 assert Union[int, str, int] == Union[int, str] 717 718 - When comparing unions, the argument order is ignored, e.g.:: 719 720 assert Union[int, str] == Union[str, int] 721 722 - You cannot subclass or instantiate a union. 723 - You can use Optional[X] as a shorthand for Union[X, None]. 724 """ 725 if parameters == (): 726 raise TypeError("Cannot take a Union of no types.") 727 if not isinstance(parameters, tuple): 728 parameters = (parameters,) 729 msg = "Union[arg, ...]: each arg must be a type." 730 parameters = tuple(_type_check(p, msg) for p in parameters) 731 parameters = _remove_dups_flatten(parameters) 732 if len(parameters) == 1: 733 return parameters[0] 734 if len(parameters) == 2 and type(None) in parameters: 735 return _UnionGenericAlias(self, parameters, name="Optional") 736 return _UnionGenericAlias(self, parameters) 737 738def _make_union(left, right): 739 """Used from the C implementation of TypeVar. 740 741 TypeVar.__or__ calls this instead of returning types.UnionType 742 because we want to allow unions between TypeVars and strings 743 (forward references). 744 """ 745 return Union[left, right] 746 747@_SpecialForm 748def Optional(self, parameters): 749 """Optional[X] is equivalent to Union[X, None].""" 750 arg = _type_check(parameters, f"{self} requires a single type.") 751 return Union[arg, type(None)] 752 753@_LiteralSpecialForm 754@_tp_cache(typed=True) 755def Literal(self, *parameters): 756 """Special typing form to define literal types (a.k.a. value types). 757 758 This form can be used to indicate to type checkers that the corresponding 759 variable or function parameter has a value equivalent to the provided 760 literal (or one of several literals):: 761 762 def validate_simple(data: Any) -> Literal[True]: # always returns True 763 ... 764 765 MODE = Literal['r', 'rb', 'w', 'wb'] 766 def open_helper(file: str, mode: MODE) -> str: 767 ... 768 769 open_helper('/some/path', 'r') # Passes type check 770 open_helper('/other/path', 'typo') # Error in type checker 771 772 Literal[...] cannot be subclassed. At runtime, an arbitrary value 773 is allowed as type argument to Literal[...], but type checkers may 774 impose restrictions. 775 """ 776 # There is no '_type_check' call because arguments to Literal[...] are 777 # values, not types. 778 parameters = _flatten_literal_params(parameters) 779 780 try: 781 parameters = tuple(p for p, _ in _deduplicate(list(_value_and_type_iter(parameters)))) 782 except TypeError: # unhashable parameters 783 pass 784 785 return _LiteralGenericAlias(self, parameters) 786 787 788@_SpecialForm 789def TypeAlias(self, parameters): 790 """Special form for marking type aliases. 791 792 Use TypeAlias to indicate that an assignment should 793 be recognized as a proper type alias definition by type 794 checkers. 795 796 For example:: 797 798 Predicate: TypeAlias = Callable[..., bool] 799 800 It's invalid when used anywhere except as in the example above. 801 """ 802 raise TypeError(f"{self} is not subscriptable") 803 804 805@_SpecialForm 806def Concatenate(self, parameters): 807 """Special form for annotating higher-order functions. 808 809 ``Concatenate`` can be used in conjunction with ``ParamSpec`` and 810 ``Callable`` to represent a higher-order function which adds, removes or 811 transforms the parameters of a callable. 812 813 For example:: 814 815 Callable[Concatenate[int, P], int] 816 817 See PEP 612 for detailed information. 818 """ 819 if parameters == (): 820 raise TypeError("Cannot take a Concatenate of no types.") 821 if not isinstance(parameters, tuple): 822 parameters = (parameters,) 823 if not (parameters[-1] is ... or isinstance(parameters[-1], ParamSpec)): 824 raise TypeError("The last parameter to Concatenate should be a " 825 "ParamSpec variable or ellipsis.") 826 msg = "Concatenate[arg, ...]: each arg must be a type." 827 parameters = (*(_type_check(p, msg) for p in parameters[:-1]), parameters[-1]) 828 return _ConcatenateGenericAlias(self, parameters) 829 830 831@_SpecialForm 832def TypeGuard(self, parameters): 833 """Special typing construct for marking user-defined type guard functions. 834 835 ``TypeGuard`` can be used to annotate the return type of a user-defined 836 type guard function. ``TypeGuard`` only accepts a single type argument. 837 At runtime, functions marked this way should return a boolean. 838 839 ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static 840 type checkers to determine a more precise type of an expression within a 841 program's code flow. Usually type narrowing is done by analyzing 842 conditional code flow and applying the narrowing to a block of code. The 843 conditional expression here is sometimes referred to as a "type guard". 844 845 Sometimes it would be convenient to use a user-defined boolean function 846 as a type guard. Such a function should use ``TypeGuard[...]`` as its 847 return type to alert static type checkers to this intention. 848 849 Using ``-> TypeGuard`` tells the static type checker that for a given 850 function: 851 852 1. The return value is a boolean. 853 2. If the return value is ``True``, the type of its argument 854 is the type inside ``TypeGuard``. 855 856 For example:: 857 858 def is_str_list(val: list[object]) -> TypeGuard[list[str]]: 859 '''Determines whether all objects in the list are strings''' 860 return all(isinstance(x, str) for x in val) 861 862 def func1(val: list[object]): 863 if is_str_list(val): 864 # Type of ``val`` is narrowed to ``list[str]``. 865 print(" ".join(val)) 866 else: 867 # Type of ``val`` remains as ``list[object]``. 868 print("Not a list of strings!") 869 870 Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower 871 form of ``TypeA`` (it can even be a wider form) and this may lead to 872 type-unsafe results. The main reason is to allow for things like 873 narrowing ``list[object]`` to ``list[str]`` even though the latter is not 874 a subtype of the former, since ``list`` is invariant. The responsibility of 875 writing type-safe type guards is left to the user. 876 877 ``TypeGuard`` also works with type variables. For more information, see 878 PEP 647 (User-Defined Type Guards). 879 """ 880 item = _type_check(parameters, f'{self} accepts only single type.') 881 return _GenericAlias(self, (item,)) 882 883 884class ForwardRef(_Final, _root=True): 885 """Internal wrapper to hold a forward reference.""" 886 887 __slots__ = ('__forward_arg__', '__forward_code__', 888 '__forward_evaluated__', '__forward_value__', 889 '__forward_is_argument__', '__forward_is_class__', 890 '__forward_module__') 891 892 def __init__(self, arg, is_argument=True, module=None, *, is_class=False): 893 if not isinstance(arg, str): 894 raise TypeError(f"Forward reference must be a string -- got {arg!r}") 895 896 # If we do `def f(*args: *Ts)`, then we'll have `arg = '*Ts'`. 897 # Unfortunately, this isn't a valid expression on its own, so we 898 # do the unpacking manually. 899 if arg.startswith('*'): 900 arg_to_compile = f'({arg},)[0]' # E.g. (*Ts,)[0] or (*tuple[int, int],)[0] 901 else: 902 arg_to_compile = arg 903 try: 904 code = compile(arg_to_compile, '<string>', 'eval') 905 except SyntaxError: 906 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}") 907 908 self.__forward_arg__ = arg 909 self.__forward_code__ = code 910 self.__forward_evaluated__ = False 911 self.__forward_value__ = None 912 self.__forward_is_argument__ = is_argument 913 self.__forward_is_class__ = is_class 914 self.__forward_module__ = module 915 916 def _evaluate(self, globalns, localns, type_params=None, *, recursive_guard): 917 if self.__forward_arg__ in recursive_guard: 918 return self 919 if not self.__forward_evaluated__ or localns is not globalns: 920 if globalns is None and localns is None: 921 globalns = localns = {} 922 elif globalns is None: 923 globalns = localns 924 elif localns is None: 925 localns = globalns 926 if self.__forward_module__ is not None: 927 globalns = getattr( 928 sys.modules.get(self.__forward_module__, None), '__dict__', globalns 929 ) 930 931 # type parameters require some special handling, 932 # as they exist in their own scope 933 # but `eval()` does not have a dedicated parameter for that scope. 934 # For classes, names in type parameter scopes should override 935 # names in the global scope (which here are called `localns`!), 936 # but should in turn be overridden by names in the class scope 937 # (which here are called `globalns`!) 938 if type_params: 939 globalns, localns = dict(globalns), dict(localns) 940 for param in type_params: 941 param_name = param.__name__ 942 if not self.__forward_is_class__ or param_name not in globalns: 943 globalns[param_name] = param 944 localns.pop(param_name, None) 945 946 type_ = _type_check( 947 eval(self.__forward_code__, globalns, localns), 948 "Forward references must evaluate to types.", 949 is_argument=self.__forward_is_argument__, 950 allow_special_forms=self.__forward_is_class__, 951 ) 952 self.__forward_value__ = _eval_type( 953 type_, 954 globalns, 955 localns, 956 type_params, 957 recursive_guard=(recursive_guard | {self.__forward_arg__}), 958 ) 959 self.__forward_evaluated__ = True 960 return self.__forward_value__ 961 962 def __eq__(self, other): 963 if not isinstance(other, ForwardRef): 964 return NotImplemented 965 if self.__forward_evaluated__ and other.__forward_evaluated__: 966 return (self.__forward_arg__ == other.__forward_arg__ and 967 self.__forward_value__ == other.__forward_value__) 968 return (self.__forward_arg__ == other.__forward_arg__ and 969 self.__forward_module__ == other.__forward_module__) 970 971 def __hash__(self): 972 return hash((self.__forward_arg__, self.__forward_module__)) 973 974 def __or__(self, other): 975 return Union[self, other] 976 977 def __ror__(self, other): 978 return Union[other, self] 979 980 def __repr__(self): 981 if self.__forward_module__ is None: 982 module_repr = '' 983 else: 984 module_repr = f', module={self.__forward_module__!r}' 985 return f'ForwardRef({self.__forward_arg__!r}{module_repr})' 986 987 988def _is_unpacked_typevartuple(x: Any) -> bool: 989 return ((not isinstance(x, type)) and 990 getattr(x, '__typing_is_unpacked_typevartuple__', False)) 991 992 993def _is_typevar_like(x: Any) -> bool: 994 return isinstance(x, (TypeVar, ParamSpec)) or _is_unpacked_typevartuple(x) 995 996 997class _PickleUsingNameMixin: 998 """Mixin enabling pickling based on self.__name__.""" 999 1000 def __reduce__(self): 1001 return self.__name__ 1002 1003 1004def _typevar_subst(self, arg): 1005 msg = "Parameters to generic types must be types." 1006 arg = _type_check(arg, msg, is_argument=True) 1007 if ((isinstance(arg, _GenericAlias) and arg.__origin__ is Unpack) or 1008 (isinstance(arg, GenericAlias) and getattr(arg, '__unpacked__', False))): 1009 raise TypeError(f"{arg} is not valid as type argument") 1010 return arg 1011 1012 1013def _typevartuple_prepare_subst(self, alias, args): 1014 params = alias.__parameters__ 1015 typevartuple_index = params.index(self) 1016 for param in params[typevartuple_index + 1:]: 1017 if isinstance(param, TypeVarTuple): 1018 raise TypeError(f"More than one TypeVarTuple parameter in {alias}") 1019 1020 alen = len(args) 1021 plen = len(params) 1022 left = typevartuple_index 1023 right = plen - typevartuple_index - 1 1024 var_tuple_index = None 1025 fillarg = None 1026 for k, arg in enumerate(args): 1027 if not isinstance(arg, type): 1028 subargs = getattr(arg, '__typing_unpacked_tuple_args__', None) 1029 if subargs and len(subargs) == 2 and subargs[-1] is ...: 1030 if var_tuple_index is not None: 1031 raise TypeError("More than one unpacked arbitrary-length tuple argument") 1032 var_tuple_index = k 1033 fillarg = subargs[0] 1034 if var_tuple_index is not None: 1035 left = min(left, var_tuple_index) 1036 right = min(right, alen - var_tuple_index - 1) 1037 elif left + right > alen: 1038 raise TypeError(f"Too few arguments for {alias};" 1039 f" actual {alen}, expected at least {plen-1}") 1040 1041 return ( 1042 *args[:left], 1043 *([fillarg]*(typevartuple_index - left)), 1044 tuple(args[left: alen - right]), 1045 *([fillarg]*(plen - right - left - typevartuple_index - 1)), 1046 *args[alen - right:], 1047 ) 1048 1049 1050def _paramspec_subst(self, arg): 1051 if isinstance(arg, (list, tuple)): 1052 arg = tuple(_type_check(a, "Expected a type.") for a in arg) 1053 elif not _is_param_expr(arg): 1054 raise TypeError(f"Expected a list of types, an ellipsis, " 1055 f"ParamSpec, or Concatenate. Got {arg}") 1056 return arg 1057 1058 1059def _paramspec_prepare_subst(self, alias, args): 1060 params = alias.__parameters__ 1061 i = params.index(self) 1062 if i >= len(args): 1063 raise TypeError(f"Too few arguments for {alias}") 1064 # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612. 1065 if len(params) == 1 and not _is_param_expr(args[0]): 1066 assert i == 0 1067 args = (args,) 1068 # Convert lists to tuples to help other libraries cache the results. 1069 elif isinstance(args[i], list): 1070 args = (*args[:i], tuple(args[i]), *args[i+1:]) 1071 return args 1072 1073 1074@_tp_cache 1075def _generic_class_getitem(cls, params): 1076 """Parameterizes a generic class. 1077 1078 At least, parameterizing a generic class is the *main* thing this method 1079 does. For example, for some generic class `Foo`, this is called when we 1080 do `Foo[int]` - there, with `cls=Foo` and `params=int`. 1081 1082 However, note that this method is also called when defining generic 1083 classes in the first place with `class Foo(Generic[T]): ...`. 1084 """ 1085 if not isinstance(params, tuple): 1086 params = (params,) 1087 1088 params = tuple(_type_convert(p) for p in params) 1089 is_generic_or_protocol = cls in (Generic, Protocol) 1090 1091 if is_generic_or_protocol: 1092 # Generic and Protocol can only be subscripted with unique type variables. 1093 if not params: 1094 raise TypeError( 1095 f"Parameter list to {cls.__qualname__}[...] cannot be empty" 1096 ) 1097 if not all(_is_typevar_like(p) for p in params): 1098 raise TypeError( 1099 f"Parameters to {cls.__name__}[...] must all be type variables " 1100 f"or parameter specification variables.") 1101 if len(set(params)) != len(params): 1102 raise TypeError( 1103 f"Parameters to {cls.__name__}[...] must all be unique") 1104 else: 1105 # Subscripting a regular Generic subclass. 1106 for param in cls.__parameters__: 1107 prepare = getattr(param, '__typing_prepare_subst__', None) 1108 if prepare is not None: 1109 params = prepare(cls, params) 1110 _check_generic(cls, params, len(cls.__parameters__)) 1111 1112 new_args = [] 1113 for param, new_arg in zip(cls.__parameters__, params): 1114 if isinstance(param, TypeVarTuple): 1115 new_args.extend(new_arg) 1116 else: 1117 new_args.append(new_arg) 1118 params = tuple(new_args) 1119 1120 return _GenericAlias(cls, params) 1121 1122 1123def _generic_init_subclass(cls, *args, **kwargs): 1124 super(Generic, cls).__init_subclass__(*args, **kwargs) 1125 tvars = [] 1126 if '__orig_bases__' in cls.__dict__: 1127 error = Generic in cls.__orig_bases__ 1128 else: 1129 error = (Generic in cls.__bases__ and 1130 cls.__name__ != 'Protocol' and 1131 type(cls) != _TypedDictMeta) 1132 if error: 1133 raise TypeError("Cannot inherit from plain Generic") 1134 if '__orig_bases__' in cls.__dict__: 1135 tvars = _collect_parameters(cls.__orig_bases__) 1136 # Look for Generic[T1, ..., Tn]. 1137 # If found, tvars must be a subset of it. 1138 # If not found, tvars is it. 1139 # Also check for and reject plain Generic, 1140 # and reject multiple Generic[...]. 1141 gvars = None 1142 for base in cls.__orig_bases__: 1143 if (isinstance(base, _GenericAlias) and 1144 base.__origin__ is Generic): 1145 if gvars is not None: 1146 raise TypeError( 1147 "Cannot inherit from Generic[...] multiple times.") 1148 gvars = base.__parameters__ 1149 if gvars is not None: 1150 tvarset = set(tvars) 1151 gvarset = set(gvars) 1152 if not tvarset <= gvarset: 1153 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset) 1154 s_args = ', '.join(str(g) for g in gvars) 1155 raise TypeError(f"Some type variables ({s_vars}) are" 1156 f" not listed in Generic[{s_args}]") 1157 tvars = gvars 1158 cls.__parameters__ = tuple(tvars) 1159 1160 1161def _is_dunder(attr): 1162 return attr.startswith('__') and attr.endswith('__') 1163 1164class _BaseGenericAlias(_Final, _root=True): 1165 """The central part of the internal API. 1166 1167 This represents a generic version of type 'origin' with type arguments 'params'. 1168 There are two kind of these aliases: user defined and special. The special ones 1169 are wrappers around builtin collections and ABCs in collections.abc. These must 1170 have 'name' always set. If 'inst' is False, then the alias can't be instantiated; 1171 this is used by e.g. typing.List and typing.Dict. 1172 """ 1173 1174 def __init__(self, origin, *, inst=True, name=None): 1175 self._inst = inst 1176 self._name = name 1177 self.__origin__ = origin 1178 self.__slots__ = None # This is not documented. 1179 1180 def __call__(self, *args, **kwargs): 1181 if not self._inst: 1182 raise TypeError(f"Type {self._name} cannot be instantiated; " 1183 f"use {self.__origin__.__name__}() instead") 1184 result = self.__origin__(*args, **kwargs) 1185 try: 1186 result.__orig_class__ = self 1187 # Some objects raise TypeError (or something even more exotic) 1188 # if you try to set attributes on them; we guard against that here 1189 except Exception: 1190 pass 1191 return result 1192 1193 def __mro_entries__(self, bases): 1194 res = [] 1195 if self.__origin__ not in bases: 1196 res.append(self.__origin__) 1197 i = bases.index(self) 1198 for b in bases[i+1:]: 1199 if isinstance(b, _BaseGenericAlias) or issubclass(b, Generic): 1200 break 1201 else: 1202 res.append(Generic) 1203 return tuple(res) 1204 1205 def __getattr__(self, attr): 1206 if attr in {'__name__', '__qualname__'}: 1207 return self._name or self.__origin__.__name__ 1208 1209 # We are careful for copy and pickle. 1210 # Also for simplicity we don't relay any dunder names 1211 if '__origin__' in self.__dict__ and not _is_dunder(attr): 1212 return getattr(self.__origin__, attr) 1213 raise AttributeError(attr) 1214 1215 def __setattr__(self, attr, val): 1216 if _is_dunder(attr) or attr in {'_name', '_inst', '_nparams'}: 1217 super().__setattr__(attr, val) 1218 else: 1219 setattr(self.__origin__, attr, val) 1220 1221 def __instancecheck__(self, obj): 1222 return self.__subclasscheck__(type(obj)) 1223 1224 def __subclasscheck__(self, cls): 1225 raise TypeError("Subscripted generics cannot be used with" 1226 " class and instance checks") 1227 1228 def __dir__(self): 1229 return list(set(super().__dir__() 1230 + [attr for attr in dir(self.__origin__) if not _is_dunder(attr)])) 1231 1232 1233# Special typing constructs Union, Optional, Generic, Callable and Tuple 1234# use three special attributes for internal bookkeeping of generic types: 1235# * __parameters__ is a tuple of unique free type parameters of a generic 1236# type, for example, Dict[T, T].__parameters__ == (T,); 1237# * __origin__ keeps a reference to a type that was subscripted, 1238# e.g., Union[T, int].__origin__ == Union, or the non-generic version of 1239# the type. 1240# * __args__ is a tuple of all arguments used in subscripting, 1241# e.g., Dict[T, int].__args__ == (T, int). 1242 1243 1244class _GenericAlias(_BaseGenericAlias, _root=True): 1245 # The type of parameterized generics. 1246 # 1247 # That is, for example, `type(List[int])` is `_GenericAlias`. 1248 # 1249 # Objects which are instances of this class include: 1250 # * Parameterized container types, e.g. `Tuple[int]`, `List[int]`. 1251 # * Note that native container types, e.g. `tuple`, `list`, use 1252 # `types.GenericAlias` instead. 1253 # * Parameterized classes: 1254 # class C[T]: pass 1255 # # C[int] is a _GenericAlias 1256 # * `Callable` aliases, generic `Callable` aliases, and 1257 # parameterized `Callable` aliases: 1258 # T = TypeVar('T') 1259 # # _CallableGenericAlias inherits from _GenericAlias. 1260 # A = Callable[[], None] # _CallableGenericAlias 1261 # B = Callable[[T], None] # _CallableGenericAlias 1262 # C = B[int] # _CallableGenericAlias 1263 # * Parameterized `Final`, `ClassVar` and `TypeGuard`: 1264 # # All _GenericAlias 1265 # Final[int] 1266 # ClassVar[float] 1267 # TypeVar[bool] 1268 1269 def __init__(self, origin, args, *, inst=True, name=None): 1270 super().__init__(origin, inst=inst, name=name) 1271 if not isinstance(args, tuple): 1272 args = (args,) 1273 self.__args__ = tuple(... if a is _TypingEllipsis else 1274 a for a in args) 1275 self.__parameters__ = _collect_parameters(args) 1276 if not name: 1277 self.__module__ = origin.__module__ 1278 1279 def __eq__(self, other): 1280 if not isinstance(other, _GenericAlias): 1281 return NotImplemented 1282 return (self.__origin__ == other.__origin__ 1283 and self.__args__ == other.__args__) 1284 1285 def __hash__(self): 1286 return hash((self.__origin__, self.__args__)) 1287 1288 def __or__(self, right): 1289 return Union[self, right] 1290 1291 def __ror__(self, left): 1292 return Union[left, self] 1293 1294 @_tp_cache 1295 def __getitem__(self, args): 1296 # Parameterizes an already-parameterized object. 1297 # 1298 # For example, we arrive here doing something like: 1299 # T1 = TypeVar('T1') 1300 # T2 = TypeVar('T2') 1301 # T3 = TypeVar('T3') 1302 # class A(Generic[T1]): pass 1303 # B = A[T2] # B is a _GenericAlias 1304 # C = B[T3] # Invokes _GenericAlias.__getitem__ 1305 # 1306 # We also arrive here when parameterizing a generic `Callable` alias: 1307 # T = TypeVar('T') 1308 # C = Callable[[T], None] 1309 # C[int] # Invokes _GenericAlias.__getitem__ 1310 1311 if self.__origin__ in (Generic, Protocol): 1312 # Can't subscript Generic[...] or Protocol[...]. 1313 raise TypeError(f"Cannot subscript already-subscripted {self}") 1314 if not self.__parameters__: 1315 raise TypeError(f"{self} is not a generic class") 1316 1317 # Preprocess `args`. 1318 if not isinstance(args, tuple): 1319 args = (args,) 1320 args = tuple(_type_convert(p) for p in args) 1321 args = _unpack_args(args) 1322 new_args = self._determine_new_args(args) 1323 r = self.copy_with(new_args) 1324 return r 1325 1326 def _determine_new_args(self, args): 1327 # Determines new __args__ for __getitem__. 1328 # 1329 # For example, suppose we had: 1330 # T1 = TypeVar('T1') 1331 # T2 = TypeVar('T2') 1332 # class A(Generic[T1, T2]): pass 1333 # T3 = TypeVar('T3') 1334 # B = A[int, T3] 1335 # C = B[str] 1336 # `B.__args__` is `(int, T3)`, so `C.__args__` should be `(int, str)`. 1337 # Unfortunately, this is harder than it looks, because if `T3` is 1338 # anything more exotic than a plain `TypeVar`, we need to consider 1339 # edge cases. 1340 1341 params = self.__parameters__ 1342 # In the example above, this would be {T3: str} 1343 for param in params: 1344 prepare = getattr(param, '__typing_prepare_subst__', None) 1345 if prepare is not None: 1346 args = prepare(self, args) 1347 alen = len(args) 1348 plen = len(params) 1349 if alen != plen: 1350 raise TypeError(f"Too {'many' if alen > plen else 'few'} arguments for {self};" 1351 f" actual {alen}, expected {plen}") 1352 new_arg_by_param = dict(zip(params, args)) 1353 return tuple(self._make_substitution(self.__args__, new_arg_by_param)) 1354 1355 def _make_substitution(self, args, new_arg_by_param): 1356 """Create a list of new type arguments.""" 1357 new_args = [] 1358 for old_arg in args: 1359 if isinstance(old_arg, type): 1360 new_args.append(old_arg) 1361 continue 1362 1363 substfunc = getattr(old_arg, '__typing_subst__', None) 1364 if substfunc: 1365 new_arg = substfunc(new_arg_by_param[old_arg]) 1366 else: 1367 subparams = getattr(old_arg, '__parameters__', ()) 1368 if not subparams: 1369 new_arg = old_arg 1370 else: 1371 subargs = [] 1372 for x in subparams: 1373 if isinstance(x, TypeVarTuple): 1374 subargs.extend(new_arg_by_param[x]) 1375 else: 1376 subargs.append(new_arg_by_param[x]) 1377 new_arg = old_arg[tuple(subargs)] 1378 1379 if self.__origin__ == collections.abc.Callable and isinstance(new_arg, tuple): 1380 # Consider the following `Callable`. 1381 # C = Callable[[int], str] 1382 # Here, `C.__args__` should be (int, str) - NOT ([int], str). 1383 # That means that if we had something like... 1384 # P = ParamSpec('P') 1385 # T = TypeVar('T') 1386 # C = Callable[P, T] 1387 # D = C[[int, str], float] 1388 # ...we need to be careful; `new_args` should end up as 1389 # `(int, str, float)` rather than `([int, str], float)`. 1390 new_args.extend(new_arg) 1391 elif _is_unpacked_typevartuple(old_arg): 1392 # Consider the following `_GenericAlias`, `B`: 1393 # class A(Generic[*Ts]): ... 1394 # B = A[T, *Ts] 1395 # If we then do: 1396 # B[float, int, str] 1397 # The `new_arg` corresponding to `T` will be `float`, and the 1398 # `new_arg` corresponding to `*Ts` will be `(int, str)`. We 1399 # should join all these types together in a flat list 1400 # `(float, int, str)` - so again, we should `extend`. 1401 new_args.extend(new_arg) 1402 elif isinstance(old_arg, tuple): 1403 # Corner case: 1404 # P = ParamSpec('P') 1405 # T = TypeVar('T') 1406 # class Base(Generic[P]): ... 1407 # Can be substituted like this: 1408 # X = Base[[int, T]] 1409 # In this case, `old_arg` will be a tuple: 1410 new_args.append( 1411 tuple(self._make_substitution(old_arg, new_arg_by_param)), 1412 ) 1413 else: 1414 new_args.append(new_arg) 1415 return new_args 1416 1417 def copy_with(self, args): 1418 return self.__class__(self.__origin__, args, name=self._name, inst=self._inst) 1419 1420 def __repr__(self): 1421 if self._name: 1422 name = 'typing.' + self._name 1423 else: 1424 name = _type_repr(self.__origin__) 1425 if self.__args__: 1426 args = ", ".join([_type_repr(a) for a in self.__args__]) 1427 else: 1428 # To ensure the repr is eval-able. 1429 args = "()" 1430 return f'{name}[{args}]' 1431 1432 def __reduce__(self): 1433 if self._name: 1434 origin = globals()[self._name] 1435 else: 1436 origin = self.__origin__ 1437 args = tuple(self.__args__) 1438 if len(args) == 1 and not isinstance(args[0], tuple): 1439 args, = args 1440 return operator.getitem, (origin, args) 1441 1442 def __mro_entries__(self, bases): 1443 if isinstance(self.__origin__, _SpecialForm): 1444 raise TypeError(f"Cannot subclass {self!r}") 1445 1446 if self._name: # generic version of an ABC or built-in class 1447 return super().__mro_entries__(bases) 1448 if self.__origin__ is Generic: 1449 if Protocol in bases: 1450 return () 1451 i = bases.index(self) 1452 for b in bases[i+1:]: 1453 if isinstance(b, _BaseGenericAlias) and b is not self: 1454 return () 1455 return (self.__origin__,) 1456 1457 def __iter__(self): 1458 yield Unpack[self] 1459 1460 1461# _nparams is the number of accepted parameters, e.g. 0 for Hashable, 1462# 1 for List and 2 for Dict. It may be -1 if variable number of 1463# parameters are accepted (needs custom __getitem__). 1464 1465class _SpecialGenericAlias(_NotIterable, _BaseGenericAlias, _root=True): 1466 def __init__(self, origin, nparams, *, inst=True, name=None): 1467 if name is None: 1468 name = origin.__name__ 1469 super().__init__(origin, inst=inst, name=name) 1470 self._nparams = nparams 1471 if origin.__module__ == 'builtins': 1472 self.__doc__ = f'A generic version of {origin.__qualname__}.' 1473 else: 1474 self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}.' 1475 1476 @_tp_cache 1477 def __getitem__(self, params): 1478 if not isinstance(params, tuple): 1479 params = (params,) 1480 msg = "Parameters to generic types must be types." 1481 params = tuple(_type_check(p, msg) for p in params) 1482 _check_generic(self, params, self._nparams) 1483 return self.copy_with(params) 1484 1485 def copy_with(self, params): 1486 return _GenericAlias(self.__origin__, params, 1487 name=self._name, inst=self._inst) 1488 1489 def __repr__(self): 1490 return 'typing.' + self._name 1491 1492 def __subclasscheck__(self, cls): 1493 if isinstance(cls, _SpecialGenericAlias): 1494 return issubclass(cls.__origin__, self.__origin__) 1495 if not isinstance(cls, _GenericAlias): 1496 return issubclass(cls, self.__origin__) 1497 return super().__subclasscheck__(cls) 1498 1499 def __reduce__(self): 1500 return self._name 1501 1502 def __or__(self, right): 1503 return Union[self, right] 1504 1505 def __ror__(self, left): 1506 return Union[left, self] 1507 1508 1509class _DeprecatedGenericAlias(_SpecialGenericAlias, _root=True): 1510 def __init__( 1511 self, origin, nparams, *, removal_version, inst=True, name=None 1512 ): 1513 super().__init__(origin, nparams, inst=inst, name=name) 1514 self._removal_version = removal_version 1515 1516 def __instancecheck__(self, inst): 1517 import warnings 1518 warnings._deprecated( 1519 f"{self.__module__}.{self._name}", remove=self._removal_version 1520 ) 1521 return super().__instancecheck__(inst) 1522 1523 1524class _CallableGenericAlias(_NotIterable, _GenericAlias, _root=True): 1525 def __repr__(self): 1526 assert self._name == 'Callable' 1527 args = self.__args__ 1528 if len(args) == 2 and _is_param_expr(args[0]): 1529 return super().__repr__() 1530 return (f'typing.Callable' 1531 f'[[{", ".join([_type_repr(a) for a in args[:-1]])}], ' 1532 f'{_type_repr(args[-1])}]') 1533 1534 def __reduce__(self): 1535 args = self.__args__ 1536 if not (len(args) == 2 and _is_param_expr(args[0])): 1537 args = list(args[:-1]), args[-1] 1538 return operator.getitem, (Callable, args) 1539 1540 1541class _CallableType(_SpecialGenericAlias, _root=True): 1542 def copy_with(self, params): 1543 return _CallableGenericAlias(self.__origin__, params, 1544 name=self._name, inst=self._inst) 1545 1546 def __getitem__(self, params): 1547 if not isinstance(params, tuple) or len(params) != 2: 1548 raise TypeError("Callable must be used as " 1549 "Callable[[arg, ...], result].") 1550 args, result = params 1551 # This relaxes what args can be on purpose to allow things like 1552 # PEP 612 ParamSpec. Responsibility for whether a user is using 1553 # Callable[...] properly is deferred to static type checkers. 1554 if isinstance(args, list): 1555 params = (tuple(args), result) 1556 else: 1557 params = (args, result) 1558 return self.__getitem_inner__(params) 1559 1560 @_tp_cache 1561 def __getitem_inner__(self, params): 1562 args, result = params 1563 msg = "Callable[args, result]: result must be a type." 1564 result = _type_check(result, msg) 1565 if args is Ellipsis: 1566 return self.copy_with((_TypingEllipsis, result)) 1567 if not isinstance(args, tuple): 1568 args = (args,) 1569 args = tuple(_type_convert(arg) for arg in args) 1570 params = args + (result,) 1571 return self.copy_with(params) 1572 1573 1574class _TupleType(_SpecialGenericAlias, _root=True): 1575 @_tp_cache 1576 def __getitem__(self, params): 1577 if not isinstance(params, tuple): 1578 params = (params,) 1579 if len(params) >= 2 and params[-1] is ...: 1580 msg = "Tuple[t, ...]: t must be a type." 1581 params = tuple(_type_check(p, msg) for p in params[:-1]) 1582 return self.copy_with((*params, _TypingEllipsis)) 1583 msg = "Tuple[t0, t1, ...]: each t must be a type." 1584 params = tuple(_type_check(p, msg) for p in params) 1585 return self.copy_with(params) 1586 1587 1588class _UnionGenericAlias(_NotIterable, _GenericAlias, _root=True): 1589 def copy_with(self, params): 1590 return Union[params] 1591 1592 def __eq__(self, other): 1593 if not isinstance(other, (_UnionGenericAlias, types.UnionType)): 1594 return NotImplemented 1595 try: # fast path 1596 return set(self.__args__) == set(other.__args__) 1597 except TypeError: # not hashable, slow path 1598 return _compare_args_orderless(self.__args__, other.__args__) 1599 1600 def __hash__(self): 1601 return hash(frozenset(self.__args__)) 1602 1603 def __repr__(self): 1604 args = self.__args__ 1605 if len(args) == 2: 1606 if args[0] is type(None): 1607 return f'typing.Optional[{_type_repr(args[1])}]' 1608 elif args[1] is type(None): 1609 return f'typing.Optional[{_type_repr(args[0])}]' 1610 return super().__repr__() 1611 1612 def __instancecheck__(self, obj): 1613 for arg in self.__args__: 1614 if isinstance(obj, arg): 1615 return True 1616 return False 1617 1618 def __subclasscheck__(self, cls): 1619 for arg in self.__args__: 1620 if issubclass(cls, arg): 1621 return True 1622 return False 1623 1624 def __reduce__(self): 1625 func, (origin, args) = super().__reduce__() 1626 return func, (Union, args) 1627 1628 1629def _value_and_type_iter(parameters): 1630 return ((p, type(p)) for p in parameters) 1631 1632 1633class _LiteralGenericAlias(_GenericAlias, _root=True): 1634 def __eq__(self, other): 1635 if not isinstance(other, _LiteralGenericAlias): 1636 return NotImplemented 1637 1638 return set(_value_and_type_iter(self.__args__)) == set(_value_and_type_iter(other.__args__)) 1639 1640 def __hash__(self): 1641 return hash(frozenset(_value_and_type_iter(self.__args__))) 1642 1643 1644class _ConcatenateGenericAlias(_GenericAlias, _root=True): 1645 def copy_with(self, params): 1646 if isinstance(params[-1], (list, tuple)): 1647 return (*params[:-1], *params[-1]) 1648 if isinstance(params[-1], _ConcatenateGenericAlias): 1649 params = (*params[:-1], *params[-1].__args__) 1650 return super().copy_with(params) 1651 1652 1653@_SpecialForm 1654def Unpack(self, parameters): 1655 """Type unpack operator. 1656 1657 The type unpack operator takes the child types from some container type, 1658 such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'. 1659 1660 For example:: 1661 1662 # For some generic class `Foo`: 1663 Foo[Unpack[tuple[int, str]]] # Equivalent to Foo[int, str] 1664 1665 Ts = TypeVarTuple('Ts') 1666 # Specifies that `Bar` is generic in an arbitrary number of types. 1667 # (Think of `Ts` as a tuple of an arbitrary number of individual 1668 # `TypeVar`s, which the `Unpack` is 'pulling out' directly into the 1669 # `Generic[]`.) 1670 class Bar(Generic[Unpack[Ts]]): ... 1671 Bar[int] # Valid 1672 Bar[int, str] # Also valid 1673 1674 From Python 3.11, this can also be done using the `*` operator:: 1675 1676 Foo[*tuple[int, str]] 1677 class Bar(Generic[*Ts]): ... 1678 1679 And from Python 3.12, it can be done using built-in syntax for generics:: 1680 1681 Foo[*tuple[int, str]] 1682 class Bar[*Ts]: ... 1683 1684 The operator can also be used along with a `TypedDict` to annotate 1685 `**kwargs` in a function signature:: 1686 1687 class Movie(TypedDict): 1688 name: str 1689 year: int 1690 1691 # This function expects two keyword arguments - *name* of type `str` and 1692 # *year* of type `int`. 1693 def foo(**kwargs: Unpack[Movie]): ... 1694 1695 Note that there is only some runtime checking of this operator. Not 1696 everything the runtime allows may be accepted by static type checkers. 1697 1698 For more information, see PEPs 646 and 692. 1699 """ 1700 item = _type_check(parameters, f'{self} accepts only single type.') 1701 return _UnpackGenericAlias(origin=self, args=(item,)) 1702 1703 1704class _UnpackGenericAlias(_GenericAlias, _root=True): 1705 def __repr__(self): 1706 # `Unpack` only takes one argument, so __args__ should contain only 1707 # a single item. 1708 return f'typing.Unpack[{_type_repr(self.__args__[0])}]' 1709 1710 def __getitem__(self, args): 1711 if self.__typing_is_unpacked_typevartuple__: 1712 return args 1713 return super().__getitem__(args) 1714 1715 @property 1716 def __typing_unpacked_tuple_args__(self): 1717 assert self.__origin__ is Unpack 1718 assert len(self.__args__) == 1 1719 arg, = self.__args__ 1720 if isinstance(arg, (_GenericAlias, types.GenericAlias)): 1721 if arg.__origin__ is not tuple: 1722 raise TypeError("Unpack[...] must be used with a tuple type") 1723 return arg.__args__ 1724 return None 1725 1726 @property 1727 def __typing_is_unpacked_typevartuple__(self): 1728 assert self.__origin__ is Unpack 1729 assert len(self.__args__) == 1 1730 return isinstance(self.__args__[0], TypeVarTuple) 1731 1732 1733class _TypingEllipsis: 1734 """Internal placeholder for ... (ellipsis).""" 1735 1736 1737_TYPING_INTERNALS = frozenset({ 1738 '__parameters__', '__orig_bases__', '__orig_class__', 1739 '_is_protocol', '_is_runtime_protocol', '__protocol_attrs__', 1740 '__non_callable_proto_members__', '__type_params__', 1741}) 1742 1743_SPECIAL_NAMES = frozenset({ 1744 '__abstractmethods__', '__annotations__', '__dict__', '__doc__', 1745 '__init__', '__module__', '__new__', '__slots__', 1746 '__subclasshook__', '__weakref__', '__class_getitem__' 1747}) 1748 1749# These special attributes will be not collected as protocol members. 1750EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS | _SPECIAL_NAMES | {'_MutableMapping__marker'} 1751 1752 1753def _get_protocol_attrs(cls): 1754 """Collect protocol members from a protocol class objects. 1755 1756 This includes names actually defined in the class dictionary, as well 1757 as names that appear in annotations. Special names (above) are skipped. 1758 """ 1759 attrs = set() 1760 for base in cls.__mro__[:-1]: # without object 1761 if base.__name__ in {'Protocol', 'Generic'}: 1762 continue 1763 annotations = getattr(base, '__annotations__', {}) 1764 for attr in (*base.__dict__, *annotations): 1765 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES: 1766 attrs.add(attr) 1767 return attrs 1768 1769 1770def _no_init_or_replace_init(self, *args, **kwargs): 1771 cls = type(self) 1772 1773 if cls._is_protocol: 1774 raise TypeError('Protocols cannot be instantiated') 1775 1776 # Already using a custom `__init__`. No need to calculate correct 1777 # `__init__` to call. This can lead to RecursionError. See bpo-45121. 1778 if cls.__init__ is not _no_init_or_replace_init: 1779 return 1780 1781 # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`. 1782 # The first instantiation of the subclass will call `_no_init_or_replace_init` which 1783 # searches for a proper new `__init__` in the MRO. The new `__init__` 1784 # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent 1785 # instantiation of the protocol subclass will thus use the new 1786 # `__init__` and no longer call `_no_init_or_replace_init`. 1787 for base in cls.__mro__: 1788 init = base.__dict__.get('__init__', _no_init_or_replace_init) 1789 if init is not _no_init_or_replace_init: 1790 cls.__init__ = init 1791 break 1792 else: 1793 # should not happen 1794 cls.__init__ = object.__init__ 1795 1796 cls.__init__(self, *args, **kwargs) 1797 1798 1799def _caller(depth=1, default='__main__'): 1800 try: 1801 return sys._getframemodulename(depth + 1) or default 1802 except AttributeError: # For platforms without _getframemodulename() 1803 pass 1804 try: 1805 return sys._getframe(depth + 1).f_globals.get('__name__', default) 1806 except (AttributeError, ValueError): # For platforms without _getframe() 1807 pass 1808 return None 1809 1810def _allow_reckless_class_checks(depth=2): 1811 """Allow instance and class checks for special stdlib modules. 1812 1813 The abc and functools modules indiscriminately call isinstance() and 1814 issubclass() on the whole MRO of a user class, which may contain protocols. 1815 """ 1816 return _caller(depth) in {'abc', 'functools', None} 1817 1818 1819_PROTO_ALLOWLIST = { 1820 'collections.abc': [ 1821 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable', 1822 'AsyncIterator', 'Hashable', 'Sized', 'Container', 'Collection', 1823 'Reversible', 'Buffer', 1824 ], 1825 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'], 1826} 1827 1828 1829@functools.cache 1830def _lazy_load_getattr_static(): 1831 # Import getattr_static lazily so as not to slow down the import of typing.py 1832 # Cache the result so we don't slow down _ProtocolMeta.__instancecheck__ unnecessarily 1833 from inspect import getattr_static 1834 return getattr_static 1835 1836 1837_cleanups.append(_lazy_load_getattr_static.cache_clear) 1838 1839def _pickle_psargs(psargs): 1840 return ParamSpecArgs, (psargs.__origin__,) 1841 1842copyreg.pickle(ParamSpecArgs, _pickle_psargs) 1843 1844def _pickle_pskwargs(pskwargs): 1845 return ParamSpecKwargs, (pskwargs.__origin__,) 1846 1847copyreg.pickle(ParamSpecKwargs, _pickle_pskwargs) 1848 1849del _pickle_psargs, _pickle_pskwargs 1850 1851 1852class _ProtocolMeta(ABCMeta): 1853 # This metaclass is somewhat unfortunate, 1854 # but is necessary for several reasons... 1855 def __new__(mcls, name, bases, namespace, /, **kwargs): 1856 if name == "Protocol" and bases == (Generic,): 1857 pass 1858 elif Protocol in bases: 1859 for base in bases: 1860 if not ( 1861 base in {object, Generic} 1862 or base.__name__ in _PROTO_ALLOWLIST.get(base.__module__, []) 1863 or ( 1864 issubclass(base, Generic) 1865 and getattr(base, "_is_protocol", False) 1866 ) 1867 ): 1868 raise TypeError( 1869 f"Protocols can only inherit from other protocols, " 1870 f"got {base!r}" 1871 ) 1872 return super().__new__(mcls, name, bases, namespace, **kwargs) 1873 1874 def __init__(cls, *args, **kwargs): 1875 super().__init__(*args, **kwargs) 1876 if getattr(cls, "_is_protocol", False): 1877 cls.__protocol_attrs__ = _get_protocol_attrs(cls) 1878 1879 def __subclasscheck__(cls, other): 1880 if cls is Protocol: 1881 return type.__subclasscheck__(cls, other) 1882 if ( 1883 getattr(cls, '_is_protocol', False) 1884 and not _allow_reckless_class_checks() 1885 ): 1886 if not isinstance(other, type): 1887 # Same error message as for issubclass(1, int). 1888 raise TypeError('issubclass() arg 1 must be a class') 1889 if not getattr(cls, '_is_runtime_protocol', False): 1890 raise TypeError( 1891 "Instance and class checks can only be used with " 1892 "@runtime_checkable protocols" 1893 ) 1894 if ( 1895 # this attribute is set by @runtime_checkable: 1896 cls.__non_callable_proto_members__ 1897 and cls.__dict__.get("__subclasshook__") is _proto_hook 1898 ): 1899 raise TypeError( 1900 "Protocols with non-method members don't support issubclass()" 1901 ) 1902 return super().__subclasscheck__(other) 1903 1904 def __instancecheck__(cls, instance): 1905 # We need this method for situations where attributes are 1906 # assigned in __init__. 1907 if cls is Protocol: 1908 return type.__instancecheck__(cls, instance) 1909 if not getattr(cls, "_is_protocol", False): 1910 # i.e., it's a concrete subclass of a protocol 1911 return super().__instancecheck__(instance) 1912 1913 if ( 1914 not getattr(cls, '_is_runtime_protocol', False) and 1915 not _allow_reckless_class_checks() 1916 ): 1917 raise TypeError("Instance and class checks can only be used with" 1918 " @runtime_checkable protocols") 1919 1920 if super().__instancecheck__(instance): 1921 return True 1922 1923 getattr_static = _lazy_load_getattr_static() 1924 for attr in cls.__protocol_attrs__: 1925 try: 1926 val = getattr_static(instance, attr) 1927 except AttributeError: 1928 break 1929 # this attribute is set by @runtime_checkable: 1930 if val is None and attr not in cls.__non_callable_proto_members__: 1931 break 1932 else: 1933 return True 1934 1935 return False 1936 1937 1938@classmethod 1939def _proto_hook(cls, other): 1940 if not cls.__dict__.get('_is_protocol', False): 1941 return NotImplemented 1942 1943 for attr in cls.__protocol_attrs__: 1944 for base in other.__mro__: 1945 # Check if the members appears in the class dictionary... 1946 if attr in base.__dict__: 1947 if base.__dict__[attr] is None: 1948 return NotImplemented 1949 break 1950 1951 # ...or in annotations, if it is a sub-protocol. 1952 annotations = getattr(base, '__annotations__', {}) 1953 if (isinstance(annotations, collections.abc.Mapping) and 1954 attr in annotations and 1955 issubclass(other, Generic) and getattr(other, '_is_protocol', False)): 1956 break 1957 else: 1958 return NotImplemented 1959 return True 1960 1961 1962class Protocol(Generic, metaclass=_ProtocolMeta): 1963 """Base class for protocol classes. 1964 1965 Protocol classes are defined as:: 1966 1967 class Proto(Protocol): 1968 def meth(self) -> int: 1969 ... 1970 1971 Such classes are primarily used with static type checkers that recognize 1972 structural subtyping (static duck-typing). 1973 1974 For example:: 1975 1976 class C: 1977 def meth(self) -> int: 1978 return 0 1979 1980 def func(x: Proto) -> int: 1981 return x.meth() 1982 1983 func(C()) # Passes static type check 1984 1985 See PEP 544 for details. Protocol classes decorated with 1986 @typing.runtime_checkable act as simple-minded runtime protocols that check 1987 only the presence of given attributes, ignoring their type signatures. 1988 Protocol classes can be generic, they are defined as:: 1989 1990 class GenProto[T](Protocol): 1991 def meth(self) -> T: 1992 ... 1993 """ 1994 1995 __slots__ = () 1996 _is_protocol = True 1997 _is_runtime_protocol = False 1998 1999 def __init_subclass__(cls, *args, **kwargs): 2000 super().__init_subclass__(*args, **kwargs) 2001 2002 # Determine if this is a protocol or a concrete subclass. 2003 if not cls.__dict__.get('_is_protocol', False): 2004 cls._is_protocol = any(b is Protocol for b in cls.__bases__) 2005 2006 # Set (or override) the protocol subclass hook. 2007 if '__subclasshook__' not in cls.__dict__: 2008 cls.__subclasshook__ = _proto_hook 2009 2010 # Prohibit instantiation for protocol classes 2011 if cls._is_protocol and cls.__init__ is Protocol.__init__: 2012 cls.__init__ = _no_init_or_replace_init 2013 2014 2015class _AnnotatedAlias(_NotIterable, _GenericAlias, _root=True): 2016 """Runtime representation of an annotated type. 2017 2018 At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't' 2019 with extra annotations. The alias behaves like a normal typing alias. 2020 Instantiating is the same as instantiating the underlying type; binding 2021 it to types is also the same. 2022 2023 The metadata itself is stored in a '__metadata__' attribute as a tuple. 2024 """ 2025 2026 def __init__(self, origin, metadata): 2027 if isinstance(origin, _AnnotatedAlias): 2028 metadata = origin.__metadata__ + metadata 2029 origin = origin.__origin__ 2030 super().__init__(origin, origin, name='Annotated') 2031 self.__metadata__ = metadata 2032 2033 def copy_with(self, params): 2034 assert len(params) == 1 2035 new_type = params[0] 2036 return _AnnotatedAlias(new_type, self.__metadata__) 2037 2038 def __repr__(self): 2039 return "typing.Annotated[{}, {}]".format( 2040 _type_repr(self.__origin__), 2041 ", ".join(repr(a) for a in self.__metadata__) 2042 ) 2043 2044 def __reduce__(self): 2045 return operator.getitem, ( 2046 Annotated, (self.__origin__,) + self.__metadata__ 2047 ) 2048 2049 def __eq__(self, other): 2050 if not isinstance(other, _AnnotatedAlias): 2051 return NotImplemented 2052 return (self.__origin__ == other.__origin__ 2053 and self.__metadata__ == other.__metadata__) 2054 2055 def __hash__(self): 2056 return hash((self.__origin__, self.__metadata__)) 2057 2058 def __getattr__(self, attr): 2059 if attr in {'__name__', '__qualname__'}: 2060 return 'Annotated' 2061 return super().__getattr__(attr) 2062 2063 def __mro_entries__(self, bases): 2064 return (self.__origin__,) 2065 2066 2067class Annotated: 2068 """Add context-specific metadata to a type. 2069 2070 Example: Annotated[int, runtime_check.Unsigned] indicates to the 2071 hypothetical runtime_check module that this type is an unsigned int. 2072 Every other consumer of this type can ignore this metadata and treat 2073 this type as int. 2074 2075 The first argument to Annotated must be a valid type. 2076 2077 Details: 2078 2079 - It's an error to call `Annotated` with less than two arguments. 2080 - Access the metadata via the ``__metadata__`` attribute:: 2081 2082 assert Annotated[int, '$'].__metadata__ == ('$',) 2083 2084 - Nested Annotated types are flattened:: 2085 2086 assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3] 2087 2088 - Instantiating an annotated type is equivalent to instantiating the 2089 underlying type:: 2090 2091 assert Annotated[C, Ann1](5) == C(5) 2092 2093 - Annotated can be used as a generic type alias:: 2094 2095 type Optimized[T] = Annotated[T, runtime.Optimize()] 2096 # type checker will treat Optimized[int] 2097 # as equivalent to Annotated[int, runtime.Optimize()] 2098 2099 type OptimizedList[T] = Annotated[list[T], runtime.Optimize()] 2100 # type checker will treat OptimizedList[int] 2101 # as equivalent to Annotated[list[int], runtime.Optimize()] 2102 2103 - Annotated cannot be used with an unpacked TypeVarTuple:: 2104 2105 type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid 2106 2107 This would be equivalent to:: 2108 2109 Annotated[T1, T2, T3, ..., Ann1] 2110 2111 where T1, T2 etc. are TypeVars, which would be invalid, because 2112 only one type should be passed to Annotated. 2113 """ 2114 2115 __slots__ = () 2116 2117 def __new__(cls, *args, **kwargs): 2118 raise TypeError("Type Annotated cannot be instantiated.") 2119 2120 def __class_getitem__(cls, params): 2121 if not isinstance(params, tuple): 2122 params = (params,) 2123 return cls._class_getitem_inner(cls, *params) 2124 2125 @_tp_cache(typed=True) 2126 def _class_getitem_inner(cls, *params): 2127 if len(params) < 2: 2128 raise TypeError("Annotated[...] should be used " 2129 "with at least two arguments (a type and an " 2130 "annotation).") 2131 if _is_unpacked_typevartuple(params[0]): 2132 raise TypeError("Annotated[...] should not be used with an " 2133 "unpacked TypeVarTuple") 2134 msg = "Annotated[t, ...]: t must be a type." 2135 origin = _type_check(params[0], msg, allow_special_forms=True) 2136 metadata = tuple(params[1:]) 2137 return _AnnotatedAlias(origin, metadata) 2138 2139 def __init_subclass__(cls, *args, **kwargs): 2140 raise TypeError( 2141 "Cannot subclass {}.Annotated".format(cls.__module__) 2142 ) 2143 2144 2145def runtime_checkable(cls): 2146 """Mark a protocol class as a runtime protocol. 2147 2148 Such protocol can be used with isinstance() and issubclass(). 2149 Raise TypeError if applied to a non-protocol class. 2150 This allows a simple-minded structural check very similar to 2151 one trick ponies in collections.abc such as Iterable. 2152 2153 For example:: 2154 2155 @runtime_checkable 2156 class Closable(Protocol): 2157 def close(self): ... 2158 2159 assert isinstance(open('/some/file'), Closable) 2160 2161 Warning: this will check only the presence of the required methods, 2162 not their type signatures! 2163 """ 2164 if not issubclass(cls, Generic) or not getattr(cls, '_is_protocol', False): 2165 raise TypeError('@runtime_checkable can be only applied to protocol classes,' 2166 ' got %r' % cls) 2167 cls._is_runtime_protocol = True 2168 # PEP 544 prohibits using issubclass() 2169 # with protocols that have non-method members. 2170 # See gh-113320 for why we compute this attribute here, 2171 # rather than in `_ProtocolMeta.__init__` 2172 cls.__non_callable_proto_members__ = set() 2173 for attr in cls.__protocol_attrs__: 2174 try: 2175 is_callable = callable(getattr(cls, attr, None)) 2176 except Exception as e: 2177 raise TypeError( 2178 f"Failed to determine whether protocol member {attr!r} " 2179 "is a method member" 2180 ) from e 2181 else: 2182 if not is_callable: 2183 cls.__non_callable_proto_members__.add(attr) 2184 return cls 2185 2186 2187def cast(typ, val): 2188 """Cast a value to a type. 2189 2190 This returns the value unchanged. To the type checker this 2191 signals that the return value has the designated type, but at 2192 runtime we intentionally don't check anything (we want this 2193 to be as fast as possible). 2194 """ 2195 return val 2196 2197 2198def assert_type(val, typ, /): 2199 """Ask a static type checker to confirm that the value is of the given type. 2200 2201 At runtime this does nothing: it returns the first argument unchanged with no 2202 checks or side effects, no matter the actual type of the argument. 2203 2204 When a static type checker encounters a call to assert_type(), it 2205 emits an error if the value is not of the specified type:: 2206 2207 def greet(name: str) -> None: 2208 assert_type(name, str) # OK 2209 assert_type(name, int) # type checker error 2210 """ 2211 return val 2212 2213 2214_allowed_types = (types.FunctionType, types.BuiltinFunctionType, 2215 types.MethodType, types.ModuleType, 2216 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType) 2217 2218 2219def get_type_hints(obj, globalns=None, localns=None, include_extras=False): 2220 """Return type hints for an object. 2221 2222 This is often the same as obj.__annotations__, but it handles 2223 forward references encoded as string literals and recursively replaces all 2224 'Annotated[T, ...]' with 'T' (unless 'include_extras=True'). 2225 2226 The argument may be a module, class, method, or function. The annotations 2227 are returned as a dictionary. For classes, annotations include also 2228 inherited members. 2229 2230 TypeError is raised if the argument is not of a type that can contain 2231 annotations, and an empty dictionary is returned if no annotations are 2232 present. 2233 2234 BEWARE -- the behavior of globalns and localns is counterintuitive 2235 (unless you are familiar with how eval() and exec() work). The 2236 search order is locals first, then globals. 2237 2238 - If no dict arguments are passed, an attempt is made to use the 2239 globals from obj (or the respective module's globals for classes), 2240 and these are also used as the locals. If the object does not appear 2241 to have globals, an empty dictionary is used. For classes, the search 2242 order is globals first then locals. 2243 2244 - If one dict argument is passed, it is used for both globals and 2245 locals. 2246 2247 - If two dict arguments are passed, they specify globals and 2248 locals, respectively. 2249 """ 2250 if getattr(obj, '__no_type_check__', None): 2251 return {} 2252 # Classes require a special treatment. 2253 if isinstance(obj, type): 2254 hints = {} 2255 for base in reversed(obj.__mro__): 2256 if globalns is None: 2257 base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {}) 2258 else: 2259 base_globals = globalns 2260 ann = base.__dict__.get('__annotations__', {}) 2261 if isinstance(ann, types.GetSetDescriptorType): 2262 ann = {} 2263 base_locals = dict(vars(base)) if localns is None else localns 2264 if localns is None and globalns is None: 2265 # This is surprising, but required. Before Python 3.10, 2266 # get_type_hints only evaluated the globalns of 2267 # a class. To maintain backwards compatibility, we reverse 2268 # the globalns and localns order so that eval() looks into 2269 # *base_globals* first rather than *base_locals*. 2270 # This only affects ForwardRefs. 2271 base_globals, base_locals = base_locals, base_globals 2272 for name, value in ann.items(): 2273 if value is None: 2274 value = type(None) 2275 if isinstance(value, str): 2276 value = ForwardRef(value, is_argument=False, is_class=True) 2277 value = _eval_type(value, base_globals, base_locals, base.__type_params__) 2278 hints[name] = value 2279 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()} 2280 2281 if globalns is None: 2282 if isinstance(obj, types.ModuleType): 2283 globalns = obj.__dict__ 2284 else: 2285 nsobj = obj 2286 # Find globalns for the unwrapped object. 2287 while hasattr(nsobj, '__wrapped__'): 2288 nsobj = nsobj.__wrapped__ 2289 globalns = getattr(nsobj, '__globals__', {}) 2290 if localns is None: 2291 localns = globalns 2292 elif localns is None: 2293 localns = globalns 2294 hints = getattr(obj, '__annotations__', None) 2295 if hints is None: 2296 # Return empty annotations for something that _could_ have them. 2297 if isinstance(obj, _allowed_types): 2298 return {} 2299 else: 2300 raise TypeError('{!r} is not a module, class, method, ' 2301 'or function.'.format(obj)) 2302 hints = dict(hints) 2303 type_params = getattr(obj, "__type_params__", ()) 2304 for name, value in hints.items(): 2305 if value is None: 2306 value = type(None) 2307 if isinstance(value, str): 2308 # class-level forward refs were handled above, this must be either 2309 # a module-level annotation or a function argument annotation 2310 value = ForwardRef( 2311 value, 2312 is_argument=not isinstance(obj, types.ModuleType), 2313 is_class=False, 2314 ) 2315 hints[name] = _eval_type(value, globalns, localns, type_params) 2316 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()} 2317 2318 2319def _strip_annotations(t): 2320 """Strip the annotations from a given type.""" 2321 if isinstance(t, _AnnotatedAlias): 2322 return _strip_annotations(t.__origin__) 2323 if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired): 2324 return _strip_annotations(t.__args__[0]) 2325 if isinstance(t, _GenericAlias): 2326 stripped_args = tuple(_strip_annotations(a) for a in t.__args__) 2327 if stripped_args == t.__args__: 2328 return t 2329 return t.copy_with(stripped_args) 2330 if isinstance(t, GenericAlias): 2331 stripped_args = tuple(_strip_annotations(a) for a in t.__args__) 2332 if stripped_args == t.__args__: 2333 return t 2334 return GenericAlias(t.__origin__, stripped_args) 2335 if isinstance(t, types.UnionType): 2336 stripped_args = tuple(_strip_annotations(a) for a in t.__args__) 2337 if stripped_args == t.__args__: 2338 return t 2339 return functools.reduce(operator.or_, stripped_args) 2340 2341 return t 2342 2343 2344def get_origin(tp): 2345 """Get the unsubscripted version of a type. 2346 2347 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar, 2348 Annotated, and others. Return None for unsupported types. 2349 2350 Examples:: 2351 2352 >>> P = ParamSpec('P') 2353 >>> assert get_origin(Literal[42]) is Literal 2354 >>> assert get_origin(int) is None 2355 >>> assert get_origin(ClassVar[int]) is ClassVar 2356 >>> assert get_origin(Generic) is Generic 2357 >>> assert get_origin(Generic[T]) is Generic 2358 >>> assert get_origin(Union[T, int]) is Union 2359 >>> assert get_origin(List[Tuple[T, T]][int]) is list 2360 >>> assert get_origin(P.args) is P 2361 """ 2362 if isinstance(tp, _AnnotatedAlias): 2363 return Annotated 2364 if isinstance(tp, (_BaseGenericAlias, GenericAlias, 2365 ParamSpecArgs, ParamSpecKwargs)): 2366 return tp.__origin__ 2367 if tp is Generic: 2368 return Generic 2369 if isinstance(tp, types.UnionType): 2370 return types.UnionType 2371 return None 2372 2373 2374def get_args(tp): 2375 """Get type arguments with all substitutions performed. 2376 2377 For unions, basic simplifications used by Union constructor are performed. 2378 2379 Examples:: 2380 2381 >>> T = TypeVar('T') 2382 >>> assert get_args(Dict[str, int]) == (str, int) 2383 >>> assert get_args(int) == () 2384 >>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str) 2385 >>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) 2386 >>> assert get_args(Callable[[], T][int]) == ([], int) 2387 """ 2388 if isinstance(tp, _AnnotatedAlias): 2389 return (tp.__origin__,) + tp.__metadata__ 2390 if isinstance(tp, (_GenericAlias, GenericAlias)): 2391 res = tp.__args__ 2392 if _should_unflatten_callable_args(tp, res): 2393 res = (list(res[:-1]), res[-1]) 2394 return res 2395 if isinstance(tp, types.UnionType): 2396 return tp.__args__ 2397 return () 2398 2399 2400def is_typeddict(tp): 2401 """Check if an annotation is a TypedDict class. 2402 2403 For example:: 2404 2405 >>> from typing import TypedDict 2406 >>> class Film(TypedDict): 2407 ... title: str 2408 ... year: int 2409 ... 2410 >>> is_typeddict(Film) 2411 True 2412 >>> is_typeddict(dict) 2413 False 2414 """ 2415 return isinstance(tp, _TypedDictMeta) 2416 2417 2418_ASSERT_NEVER_REPR_MAX_LENGTH = 100 2419 2420 2421def assert_never(arg: Never, /) -> Never: 2422 """Statically assert that a line of code is unreachable. 2423 2424 Example:: 2425 2426 def int_or_str(arg: int | str) -> None: 2427 match arg: 2428 case int(): 2429 print("It's an int") 2430 case str(): 2431 print("It's a str") 2432 case _: 2433 assert_never(arg) 2434 2435 If a type checker finds that a call to assert_never() is 2436 reachable, it will emit an error. 2437 2438 At runtime, this throws an exception when called. 2439 """ 2440 value = repr(arg) 2441 if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH: 2442 value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...' 2443 raise AssertionError(f"Expected code to be unreachable, but got: {value}") 2444 2445 2446def no_type_check(arg): 2447 """Decorator to indicate that annotations are not type hints. 2448 2449 The argument must be a class or function; if it is a class, it 2450 applies recursively to all methods and classes defined in that class 2451 (but not to methods defined in its superclasses or subclasses). 2452 2453 This mutates the function(s) or class(es) in place. 2454 """ 2455 if isinstance(arg, type): 2456 for key in dir(arg): 2457 obj = getattr(arg, key) 2458 if ( 2459 not hasattr(obj, '__qualname__') 2460 or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}' 2461 or getattr(obj, '__module__', None) != arg.__module__ 2462 ): 2463 # We only modify objects that are defined in this type directly. 2464 # If classes / methods are nested in multiple layers, 2465 # we will modify them when processing their direct holders. 2466 continue 2467 # Instance, class, and static methods: 2468 if isinstance(obj, types.FunctionType): 2469 obj.__no_type_check__ = True 2470 if isinstance(obj, types.MethodType): 2471 obj.__func__.__no_type_check__ = True 2472 # Nested types: 2473 if isinstance(obj, type): 2474 no_type_check(obj) 2475 try: 2476 arg.__no_type_check__ = True 2477 except TypeError: # built-in classes 2478 pass 2479 return arg 2480 2481 2482def no_type_check_decorator(decorator): 2483 """Decorator to give another decorator the @no_type_check effect. 2484 2485 This wraps the decorator with something that wraps the decorated 2486 function in @no_type_check. 2487 """ 2488 @functools.wraps(decorator) 2489 def wrapped_decorator(*args, **kwds): 2490 func = decorator(*args, **kwds) 2491 func = no_type_check(func) 2492 return func 2493 2494 return wrapped_decorator 2495 2496 2497def _overload_dummy(*args, **kwds): 2498 """Helper for @overload to raise when called.""" 2499 raise NotImplementedError( 2500 "You should not call an overloaded function. " 2501 "A series of @overload-decorated functions " 2502 "outside a stub module should always be followed " 2503 "by an implementation that is not @overload-ed.") 2504 2505 2506# {module: {qualname: {firstlineno: func}}} 2507_overload_registry = defaultdict(functools.partial(defaultdict, dict)) 2508 2509 2510def overload(func): 2511 """Decorator for overloaded functions/methods. 2512 2513 In a stub file, place two or more stub definitions for the same 2514 function in a row, each decorated with @overload. 2515 2516 For example:: 2517 2518 @overload 2519 def utf8(value: None) -> None: ... 2520 @overload 2521 def utf8(value: bytes) -> bytes: ... 2522 @overload 2523 def utf8(value: str) -> bytes: ... 2524 2525 In a non-stub file (i.e. a regular .py file), do the same but 2526 follow it with an implementation. The implementation should *not* 2527 be decorated with @overload:: 2528 2529 @overload 2530 def utf8(value: None) -> None: ... 2531 @overload 2532 def utf8(value: bytes) -> bytes: ... 2533 @overload 2534 def utf8(value: str) -> bytes: ... 2535 def utf8(value): 2536 ... # implementation goes here 2537 2538 The overloads for a function can be retrieved at runtime using the 2539 get_overloads() function. 2540 """ 2541 # classmethod and staticmethod 2542 f = getattr(func, "__func__", func) 2543 try: 2544 _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func 2545 except AttributeError: 2546 # Not a normal function; ignore. 2547 pass 2548 return _overload_dummy 2549 2550 2551def get_overloads(func): 2552 """Return all defined overloads for *func* as a sequence.""" 2553 # classmethod and staticmethod 2554 f = getattr(func, "__func__", func) 2555 if f.__module__ not in _overload_registry: 2556 return [] 2557 mod_dict = _overload_registry[f.__module__] 2558 if f.__qualname__ not in mod_dict: 2559 return [] 2560 return list(mod_dict[f.__qualname__].values()) 2561 2562 2563def clear_overloads(): 2564 """Clear all overloads in the registry.""" 2565 _overload_registry.clear() 2566 2567 2568def final(f): 2569 """Decorator to indicate final methods and final classes. 2570 2571 Use this decorator to indicate to type checkers that the decorated 2572 method cannot be overridden, and decorated class cannot be subclassed. 2573 2574 For example:: 2575 2576 class Base: 2577 @final 2578 def done(self) -> None: 2579 ... 2580 class Sub(Base): 2581 def done(self) -> None: # Error reported by type checker 2582 ... 2583 2584 @final 2585 class Leaf: 2586 ... 2587 class Other(Leaf): # Error reported by type checker 2588 ... 2589 2590 There is no runtime checking of these properties. The decorator 2591 attempts to set the ``__final__`` attribute to ``True`` on the decorated 2592 object to allow runtime introspection. 2593 """ 2594 try: 2595 f.__final__ = True 2596 except (AttributeError, TypeError): 2597 # Skip the attribute silently if it is not writable. 2598 # AttributeError happens if the object has __slots__ or a 2599 # read-only property, TypeError if it's a builtin class. 2600 pass 2601 return f 2602 2603 2604# Some unconstrained type variables. These were initially used by the container types. 2605# They were never meant for export and are now unused, but we keep them around to 2606# avoid breaking compatibility with users who import them. 2607T = TypeVar('T') # Any type. 2608KT = TypeVar('KT') # Key type. 2609VT = TypeVar('VT') # Value type. 2610T_co = TypeVar('T_co', covariant=True) # Any type covariant containers. 2611V_co = TypeVar('V_co', covariant=True) # Any type covariant containers. 2612VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers. 2613T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant. 2614# Internal type variable used for Type[]. 2615CT_co = TypeVar('CT_co', covariant=True, bound=type) 2616 2617 2618# A useful type variable with constraints. This represents string types. 2619# (This one *is* for export!) 2620AnyStr = TypeVar('AnyStr', bytes, str) 2621 2622 2623# Various ABCs mimicking those in collections.abc. 2624_alias = _SpecialGenericAlias 2625 2626Hashable = _alias(collections.abc.Hashable, 0) # Not generic. 2627Awaitable = _alias(collections.abc.Awaitable, 1) 2628Coroutine = _alias(collections.abc.Coroutine, 3) 2629AsyncIterable = _alias(collections.abc.AsyncIterable, 1) 2630AsyncIterator = _alias(collections.abc.AsyncIterator, 1) 2631Iterable = _alias(collections.abc.Iterable, 1) 2632Iterator = _alias(collections.abc.Iterator, 1) 2633Reversible = _alias(collections.abc.Reversible, 1) 2634Sized = _alias(collections.abc.Sized, 0) # Not generic. 2635Container = _alias(collections.abc.Container, 1) 2636Collection = _alias(collections.abc.Collection, 1) 2637Callable = _CallableType(collections.abc.Callable, 2) 2638Callable.__doc__ = \ 2639 """Deprecated alias to collections.abc.Callable. 2640 2641 Callable[[int], str] signifies a function that takes a single 2642 parameter of type int and returns a str. 2643 2644 The subscription syntax must always be used with exactly two 2645 values: the argument list and the return type. 2646 The argument list must be a list of types, a ParamSpec, 2647 Concatenate or ellipsis. The return type must be a single type. 2648 2649 There is no syntax to indicate optional or keyword arguments; 2650 such function types are rarely used as callback types. 2651 """ 2652AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet') 2653MutableSet = _alias(collections.abc.MutableSet, 1) 2654# NOTE: Mapping is only covariant in the value type. 2655Mapping = _alias(collections.abc.Mapping, 2) 2656MutableMapping = _alias(collections.abc.MutableMapping, 2) 2657Sequence = _alias(collections.abc.Sequence, 1) 2658MutableSequence = _alias(collections.abc.MutableSequence, 1) 2659ByteString = _DeprecatedGenericAlias( 2660 collections.abc.ByteString, 0, removal_version=(3, 14) # Not generic. 2661) 2662# Tuple accepts variable number of parameters. 2663Tuple = _TupleType(tuple, -1, inst=False, name='Tuple') 2664Tuple.__doc__ = \ 2665 """Deprecated alias to builtins.tuple. 2666 2667 Tuple[X, Y] is the cross-product type of X and Y. 2668 2669 Example: Tuple[T1, T2] is a tuple of two elements corresponding 2670 to type variables T1 and T2. Tuple[int, float, str] is a tuple 2671 of an int, a float and a string. 2672 2673 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...]. 2674 """ 2675List = _alias(list, 1, inst=False, name='List') 2676Deque = _alias(collections.deque, 1, name='Deque') 2677Set = _alias(set, 1, inst=False, name='Set') 2678FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet') 2679MappingView = _alias(collections.abc.MappingView, 1) 2680KeysView = _alias(collections.abc.KeysView, 1) 2681ItemsView = _alias(collections.abc.ItemsView, 2) 2682ValuesView = _alias(collections.abc.ValuesView, 1) 2683ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager') 2684AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager') 2685Dict = _alias(dict, 2, inst=False, name='Dict') 2686DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict') 2687OrderedDict = _alias(collections.OrderedDict, 2) 2688Counter = _alias(collections.Counter, 1) 2689ChainMap = _alias(collections.ChainMap, 2) 2690Generator = _alias(collections.abc.Generator, 3) 2691AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2) 2692Type = _alias(type, 1, inst=False, name='Type') 2693Type.__doc__ = \ 2694 """Deprecated alias to builtins.type. 2695 2696 builtins.type or typing.Type can be used to annotate class objects. 2697 For example, suppose we have the following classes:: 2698 2699 class User: ... # Abstract base for User classes 2700 class BasicUser(User): ... 2701 class ProUser(User): ... 2702 class TeamUser(User): ... 2703 2704 And a function that takes a class argument that's a subclass of 2705 User and returns an instance of the corresponding class:: 2706 2707 def new_user[U](user_class: Type[U]) -> U: 2708 user = user_class() 2709 # (Here we could write the user object to a database) 2710 return user 2711 2712 joe = new_user(BasicUser) 2713 2714 At this point the type checker knows that joe has type BasicUser. 2715 """ 2716 2717 2718@runtime_checkable 2719class SupportsInt(Protocol): 2720 """An ABC with one abstract method __int__.""" 2721 2722 __slots__ = () 2723 2724 @abstractmethod 2725 def __int__(self) -> int: 2726 pass 2727 2728 2729@runtime_checkable 2730class SupportsFloat(Protocol): 2731 """An ABC with one abstract method __float__.""" 2732 2733 __slots__ = () 2734 2735 @abstractmethod 2736 def __float__(self) -> float: 2737 pass 2738 2739 2740@runtime_checkable 2741class SupportsComplex(Protocol): 2742 """An ABC with one abstract method __complex__.""" 2743 2744 __slots__ = () 2745 2746 @abstractmethod 2747 def __complex__(self) -> complex: 2748 pass 2749 2750 2751@runtime_checkable 2752class SupportsBytes(Protocol): 2753 """An ABC with one abstract method __bytes__.""" 2754 2755 __slots__ = () 2756 2757 @abstractmethod 2758 def __bytes__(self) -> bytes: 2759 pass 2760 2761 2762@runtime_checkable 2763class SupportsIndex(Protocol): 2764 """An ABC with one abstract method __index__.""" 2765 2766 __slots__ = () 2767 2768 @abstractmethod 2769 def __index__(self) -> int: 2770 pass 2771 2772 2773@runtime_checkable 2774class SupportsAbs[T](Protocol): 2775 """An ABC with one abstract method __abs__ that is covariant in its return type.""" 2776 2777 __slots__ = () 2778 2779 @abstractmethod 2780 def __abs__(self) -> T: 2781 pass 2782 2783 2784@runtime_checkable 2785class SupportsRound[T](Protocol): 2786 """An ABC with one abstract method __round__ that is covariant in its return type.""" 2787 2788 __slots__ = () 2789 2790 @abstractmethod 2791 def __round__(self, ndigits: int = 0) -> T: 2792 pass 2793 2794 2795def _make_nmtuple(name, types, module, defaults = ()): 2796 fields = [n for n, t in types] 2797 types = {n: _type_check(t, f"field {n} annotation must be a type") 2798 for n, t in types} 2799 nm_tpl = collections.namedtuple(name, fields, 2800 defaults=defaults, module=module) 2801 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types 2802 return nm_tpl 2803 2804 2805# attributes prohibited to set in NamedTuple class syntax 2806_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__', 2807 '_fields', '_field_defaults', 2808 '_make', '_replace', '_asdict', '_source'}) 2809 2810_special = frozenset({'__module__', '__name__', '__annotations__'}) 2811 2812 2813class NamedTupleMeta(type): 2814 def __new__(cls, typename, bases, ns): 2815 assert _NamedTuple in bases 2816 for base in bases: 2817 if base is not _NamedTuple and base is not Generic: 2818 raise TypeError( 2819 'can only inherit from a NamedTuple type and Generic') 2820 bases = tuple(tuple if base is _NamedTuple else base for base in bases) 2821 types = ns.get('__annotations__', {}) 2822 default_names = [] 2823 for field_name in types: 2824 if field_name in ns: 2825 default_names.append(field_name) 2826 elif default_names: 2827 raise TypeError(f"Non-default namedtuple field {field_name} " 2828 f"cannot follow default field" 2829 f"{'s' if len(default_names) > 1 else ''} " 2830 f"{', '.join(default_names)}") 2831 nm_tpl = _make_nmtuple(typename, types.items(), 2832 defaults=[ns[n] for n in default_names], 2833 module=ns['__module__']) 2834 nm_tpl.__bases__ = bases 2835 if Generic in bases: 2836 class_getitem = _generic_class_getitem 2837 nm_tpl.__class_getitem__ = classmethod(class_getitem) 2838 # update from user namespace without overriding special namedtuple attributes 2839 for key in ns: 2840 if key in _prohibited: 2841 raise AttributeError("Cannot overwrite NamedTuple attribute " + key) 2842 elif key not in _special and key not in nm_tpl._fields: 2843 setattr(nm_tpl, key, ns[key]) 2844 if Generic in bases: 2845 nm_tpl.__init_subclass__() 2846 return nm_tpl 2847 2848 2849def NamedTuple(typename, fields=None, /, **kwargs): 2850 """Typed version of namedtuple. 2851 2852 Usage:: 2853 2854 class Employee(NamedTuple): 2855 name: str 2856 id: int 2857 2858 This is equivalent to:: 2859 2860 Employee = collections.namedtuple('Employee', ['name', 'id']) 2861 2862 The resulting class has an extra __annotations__ attribute, giving a 2863 dict that maps field names to types. (The field names are also in 2864 the _fields attribute, which is part of the namedtuple API.) 2865 An alternative equivalent functional syntax is also accepted:: 2866 2867 Employee = NamedTuple('Employee', [('name', str), ('id', int)]) 2868 """ 2869 if fields is None: 2870 fields = kwargs.items() 2871 elif kwargs: 2872 raise TypeError("Either list of fields or keywords" 2873 " can be provided to NamedTuple, not both") 2874 nt = _make_nmtuple(typename, fields, module=_caller()) 2875 nt.__orig_bases__ = (NamedTuple,) 2876 return nt 2877 2878_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {}) 2879 2880def _namedtuple_mro_entries(bases): 2881 assert NamedTuple in bases 2882 return (_NamedTuple,) 2883 2884NamedTuple.__mro_entries__ = _namedtuple_mro_entries 2885 2886 2887class _TypedDictMeta(type): 2888 def __new__(cls, name, bases, ns, total=True): 2889 """Create a new typed dict class object. 2890 2891 This method is called when TypedDict is subclassed, 2892 or when TypedDict is instantiated. This way 2893 TypedDict supports all three syntax forms described in its docstring. 2894 Subclasses and instances of TypedDict return actual dictionaries. 2895 """ 2896 for base in bases: 2897 if type(base) is not _TypedDictMeta and base is not Generic: 2898 raise TypeError('cannot inherit from both a TypedDict type ' 2899 'and a non-TypedDict base class') 2900 2901 if any(issubclass(b, Generic) for b in bases): 2902 generic_base = (Generic,) 2903 else: 2904 generic_base = () 2905 2906 tp_dict = type.__new__(_TypedDictMeta, name, (*generic_base, dict), ns) 2907 2908 if not hasattr(tp_dict, '__orig_bases__'): 2909 tp_dict.__orig_bases__ = bases 2910 2911 annotations = {} 2912 own_annotations = ns.get('__annotations__', {}) 2913 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type" 2914 own_annotations = { 2915 n: _type_check(tp, msg, module=tp_dict.__module__) 2916 for n, tp in own_annotations.items() 2917 } 2918 required_keys = set() 2919 optional_keys = set() 2920 2921 for base in bases: 2922 annotations.update(base.__dict__.get('__annotations__', {})) 2923 2924 base_required = base.__dict__.get('__required_keys__', set()) 2925 required_keys |= base_required 2926 optional_keys -= base_required 2927 2928 base_optional = base.__dict__.get('__optional_keys__', set()) 2929 required_keys -= base_optional 2930 optional_keys |= base_optional 2931 2932 annotations.update(own_annotations) 2933 for annotation_key, annotation_type in own_annotations.items(): 2934 annotation_origin = get_origin(annotation_type) 2935 if annotation_origin is Annotated: 2936 annotation_args = get_args(annotation_type) 2937 if annotation_args: 2938 annotation_type = annotation_args[0] 2939 annotation_origin = get_origin(annotation_type) 2940 2941 if annotation_origin is Required: 2942 is_required = True 2943 elif annotation_origin is NotRequired: 2944 is_required = False 2945 else: 2946 is_required = total 2947 2948 if is_required: 2949 required_keys.add(annotation_key) 2950 optional_keys.discard(annotation_key) 2951 else: 2952 optional_keys.add(annotation_key) 2953 required_keys.discard(annotation_key) 2954 2955 assert required_keys.isdisjoint(optional_keys), ( 2956 f"Required keys overlap with optional keys in {name}:" 2957 f" {required_keys=}, {optional_keys=}" 2958 ) 2959 tp_dict.__annotations__ = annotations 2960 tp_dict.__required_keys__ = frozenset(required_keys) 2961 tp_dict.__optional_keys__ = frozenset(optional_keys) 2962 if not hasattr(tp_dict, '__total__'): 2963 tp_dict.__total__ = total 2964 return tp_dict 2965 2966 __call__ = dict # static method 2967 2968 def __subclasscheck__(cls, other): 2969 # Typed dicts are only for static structural subtyping. 2970 raise TypeError('TypedDict does not support instance and class checks') 2971 2972 __instancecheck__ = __subclasscheck__ 2973 2974 2975def TypedDict(typename, fields=None, /, *, total=True, **kwargs): 2976 """A simple typed namespace. At runtime it is equivalent to a plain dict. 2977 2978 TypedDict creates a dictionary type such that a type checker will expect all 2979 instances to have a certain set of keys, where each key is 2980 associated with a value of a consistent type. This expectation 2981 is not checked at runtime. 2982 2983 Usage:: 2984 2985 >>> class Point2D(TypedDict): 2986 ... x: int 2987 ... y: int 2988 ... label: str 2989 ... 2990 >>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK 2991 >>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check 2992 >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') 2993 True 2994 2995 The type info can be accessed via the Point2D.__annotations__ dict, and 2996 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets. 2997 TypedDict supports an additional equivalent form:: 2998 2999 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) 3000 3001 By default, all keys must be present in a TypedDict. It is possible 3002 to override this by specifying totality:: 3003 3004 class Point2D(TypedDict, total=False): 3005 x: int 3006 y: int 3007 3008 This means that a Point2D TypedDict can have any of the keys omitted. A type 3009 checker is only expected to support a literal False or True as the value of 3010 the total argument. True is the default, and makes all items defined in the 3011 class body be required. 3012 3013 The Required and NotRequired special forms can also be used to mark 3014 individual keys as being required or not required:: 3015 3016 class Point2D(TypedDict): 3017 x: int # the "x" key must always be present (Required is the default) 3018 y: NotRequired[int] # the "y" key can be omitted 3019 3020 See PEP 655 for more details on Required and NotRequired. 3021 """ 3022 if fields is None: 3023 fields = kwargs 3024 elif kwargs: 3025 raise TypeError("TypedDict takes either a dict or keyword arguments," 3026 " but not both") 3027 if kwargs: 3028 warnings.warn( 3029 "The kwargs-based syntax for TypedDict definitions is deprecated " 3030 "in Python 3.11, will be removed in Python 3.13, and may not be " 3031 "understood by third-party type checkers.", 3032 DeprecationWarning, 3033 stacklevel=2, 3034 ) 3035 3036 ns = {'__annotations__': dict(fields)} 3037 module = _caller() 3038 if module is not None: 3039 # Setting correct module is necessary to make typed dict classes pickleable. 3040 ns['__module__'] = module 3041 3042 td = _TypedDictMeta(typename, (), ns, total=total) 3043 td.__orig_bases__ = (TypedDict,) 3044 return td 3045 3046_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {}) 3047TypedDict.__mro_entries__ = lambda bases: (_TypedDict,) 3048 3049 3050@_SpecialForm 3051def Required(self, parameters): 3052 """Special typing construct to mark a TypedDict key as required. 3053 3054 This is mainly useful for total=False TypedDicts. 3055 3056 For example:: 3057 3058 class Movie(TypedDict, total=False): 3059 title: Required[str] 3060 year: int 3061 3062 m = Movie( 3063 title='The Matrix', # typechecker error if key is omitted 3064 year=1999, 3065 ) 3066 3067 There is no runtime checking that a required key is actually provided 3068 when instantiating a related TypedDict. 3069 """ 3070 item = _type_check(parameters, f'{self._name} accepts only a single type.') 3071 return _GenericAlias(self, (item,)) 3072 3073 3074@_SpecialForm 3075def NotRequired(self, parameters): 3076 """Special typing construct to mark a TypedDict key as potentially missing. 3077 3078 For example:: 3079 3080 class Movie(TypedDict): 3081 title: str 3082 year: NotRequired[int] 3083 3084 m = Movie( 3085 title='The Matrix', # typechecker error if key is omitted 3086 year=1999, 3087 ) 3088 """ 3089 item = _type_check(parameters, f'{self._name} accepts only a single type.') 3090 return _GenericAlias(self, (item,)) 3091 3092 3093class NewType: 3094 """NewType creates simple unique types with almost zero runtime overhead. 3095 3096 NewType(name, tp) is considered a subtype of tp 3097 by static type checkers. At runtime, NewType(name, tp) returns 3098 a dummy callable that simply returns its argument. 3099 3100 Usage:: 3101 3102 UserId = NewType('UserId', int) 3103 3104 def name_by_id(user_id: UserId) -> str: 3105 ... 3106 3107 UserId('user') # Fails type check 3108 3109 name_by_id(42) # Fails type check 3110 name_by_id(UserId(42)) # OK 3111 3112 num = UserId(5) + 1 # type: int 3113 """ 3114 3115 __call__ = _idfunc 3116 3117 def __init__(self, name, tp): 3118 self.__qualname__ = name 3119 if '.' in name: 3120 name = name.rpartition('.')[-1] 3121 self.__name__ = name 3122 self.__supertype__ = tp 3123 def_mod = _caller() 3124 if def_mod != 'typing': 3125 self.__module__ = def_mod 3126 3127 def __mro_entries__(self, bases): 3128 # We defined __mro_entries__ to get a better error message 3129 # if a user attempts to subclass a NewType instance. bpo-46170 3130 superclass_name = self.__name__ 3131 3132 class Dummy: 3133 def __init_subclass__(cls): 3134 subclass_name = cls.__name__ 3135 raise TypeError( 3136 f"Cannot subclass an instance of NewType. Perhaps you were looking for: " 3137 f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`" 3138 ) 3139 3140 return (Dummy,) 3141 3142 def __repr__(self): 3143 return f'{self.__module__}.{self.__qualname__}' 3144 3145 def __reduce__(self): 3146 return self.__qualname__ 3147 3148 def __or__(self, other): 3149 return Union[self, other] 3150 3151 def __ror__(self, other): 3152 return Union[other, self] 3153 3154 3155# Python-version-specific alias (Python 2: unicode; Python 3: str) 3156Text = str 3157 3158 3159# Constant that's True when type checking, but False here. 3160TYPE_CHECKING = False 3161 3162 3163class IO(Generic[AnyStr]): 3164 """Generic base class for TextIO and BinaryIO. 3165 3166 This is an abstract, generic version of the return of open(). 3167 3168 NOTE: This does not distinguish between the different possible 3169 classes (text vs. binary, read vs. write vs. read/write, 3170 append-only, unbuffered). The TextIO and BinaryIO subclasses 3171 below capture the distinctions between text vs. binary, which is 3172 pervasive in the interface; however we currently do not offer a 3173 way to track the other distinctions in the type system. 3174 """ 3175 3176 __slots__ = () 3177 3178 @property 3179 @abstractmethod 3180 def mode(self) -> str: 3181 pass 3182 3183 @property 3184 @abstractmethod 3185 def name(self) -> str: 3186 pass 3187 3188 @abstractmethod 3189 def close(self) -> None: 3190 pass 3191 3192 @property 3193 @abstractmethod 3194 def closed(self) -> bool: 3195 pass 3196 3197 @abstractmethod 3198 def fileno(self) -> int: 3199 pass 3200 3201 @abstractmethod 3202 def flush(self) -> None: 3203 pass 3204 3205 @abstractmethod 3206 def isatty(self) -> bool: 3207 pass 3208 3209 @abstractmethod 3210 def read(self, n: int = -1) -> AnyStr: 3211 pass 3212 3213 @abstractmethod 3214 def readable(self) -> bool: 3215 pass 3216 3217 @abstractmethod 3218 def readline(self, limit: int = -1) -> AnyStr: 3219 pass 3220 3221 @abstractmethod 3222 def readlines(self, hint: int = -1) -> List[AnyStr]: 3223 pass 3224 3225 @abstractmethod 3226 def seek(self, offset: int, whence: int = 0) -> int: 3227 pass 3228 3229 @abstractmethod 3230 def seekable(self) -> bool: 3231 pass 3232 3233 @abstractmethod 3234 def tell(self) -> int: 3235 pass 3236 3237 @abstractmethod 3238 def truncate(self, size: int = None) -> int: 3239 pass 3240 3241 @abstractmethod 3242 def writable(self) -> bool: 3243 pass 3244 3245 @abstractmethod 3246 def write(self, s: AnyStr) -> int: 3247 pass 3248 3249 @abstractmethod 3250 def writelines(self, lines: List[AnyStr]) -> None: 3251 pass 3252 3253 @abstractmethod 3254 def __enter__(self) -> 'IO[AnyStr]': 3255 pass 3256 3257 @abstractmethod 3258 def __exit__(self, type, value, traceback) -> None: 3259 pass 3260 3261 3262class BinaryIO(IO[bytes]): 3263 """Typed version of the return of open() in binary mode.""" 3264 3265 __slots__ = () 3266 3267 @abstractmethod 3268 def write(self, s: Union[bytes, bytearray]) -> int: 3269 pass 3270 3271 @abstractmethod 3272 def __enter__(self) -> 'BinaryIO': 3273 pass 3274 3275 3276class TextIO(IO[str]): 3277 """Typed version of the return of open() in text mode.""" 3278 3279 __slots__ = () 3280 3281 @property 3282 @abstractmethod 3283 def buffer(self) -> BinaryIO: 3284 pass 3285 3286 @property 3287 @abstractmethod 3288 def encoding(self) -> str: 3289 pass 3290 3291 @property 3292 @abstractmethod 3293 def errors(self) -> Optional[str]: 3294 pass 3295 3296 @property 3297 @abstractmethod 3298 def line_buffering(self) -> bool: 3299 pass 3300 3301 @property 3302 @abstractmethod 3303 def newlines(self) -> Any: 3304 pass 3305 3306 @abstractmethod 3307 def __enter__(self) -> 'TextIO': 3308 pass 3309 3310 3311class _DeprecatedType(type): 3312 def __getattribute__(cls, name): 3313 if name not in {"__dict__", "__module__", "__doc__"} and name in cls.__dict__: 3314 warnings.warn( 3315 f"{cls.__name__} is deprecated, import directly " 3316 f"from typing instead. {cls.__name__} will be removed " 3317 "in Python 3.13.", 3318 DeprecationWarning, 3319 stacklevel=2, 3320 ) 3321 return super().__getattribute__(name) 3322 3323 3324class io(metaclass=_DeprecatedType): 3325 """Wrapper namespace for IO generic classes.""" 3326 3327 __all__ = ['IO', 'TextIO', 'BinaryIO'] 3328 IO = IO 3329 TextIO = TextIO 3330 BinaryIO = BinaryIO 3331 3332 3333io.__name__ = __name__ + '.io' 3334sys.modules[io.__name__] = io 3335 3336Pattern = _alias(stdlib_re.Pattern, 1) 3337Match = _alias(stdlib_re.Match, 1) 3338 3339class re(metaclass=_DeprecatedType): 3340 """Wrapper namespace for re type aliases.""" 3341 3342 __all__ = ['Pattern', 'Match'] 3343 Pattern = Pattern 3344 Match = Match 3345 3346 3347re.__name__ = __name__ + '.re' 3348sys.modules[re.__name__] = re 3349 3350 3351def reveal_type[T](obj: T, /) -> T: 3352 """Ask a static type checker to reveal the inferred type of an expression. 3353 3354 When a static type checker encounters a call to ``reveal_type()``, 3355 it will emit the inferred type of the argument:: 3356 3357 x: int = 1 3358 reveal_type(x) 3359 3360 Running a static type checker (e.g., mypy) on this example 3361 will produce output similar to 'Revealed type is "builtins.int"'. 3362 3363 At runtime, the function prints the runtime type of the 3364 argument and returns the argument unchanged. 3365 """ 3366 print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr) 3367 return obj 3368 3369 3370class _IdentityCallable(Protocol): 3371 def __call__[T](self, arg: T, /) -> T: 3372 ... 3373 3374 3375def dataclass_transform( 3376 *, 3377 eq_default: bool = True, 3378 order_default: bool = False, 3379 kw_only_default: bool = False, 3380 frozen_default: bool = False, 3381 field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (), 3382 **kwargs: Any, 3383) -> _IdentityCallable: 3384 """Decorator to mark an object as providing dataclass-like behaviour. 3385 3386 The decorator can be applied to a function, class, or metaclass. 3387 3388 Example usage with a decorator function:: 3389 3390 @dataclass_transform() 3391 def create_model[T](cls: type[T]) -> type[T]: 3392 ... 3393 return cls 3394 3395 @create_model 3396 class CustomerModel: 3397 id: int 3398 name: str 3399 3400 On a base class:: 3401 3402 @dataclass_transform() 3403 class ModelBase: ... 3404 3405 class CustomerModel(ModelBase): 3406 id: int 3407 name: str 3408 3409 On a metaclass:: 3410 3411 @dataclass_transform() 3412 class ModelMeta(type): ... 3413 3414 class ModelBase(metaclass=ModelMeta): ... 3415 3416 class CustomerModel(ModelBase): 3417 id: int 3418 name: str 3419 3420 The ``CustomerModel`` classes defined above will 3421 be treated by type checkers similarly to classes created with 3422 ``@dataclasses.dataclass``. 3423 For example, type checkers will assume these classes have 3424 ``__init__`` methods that accept ``id`` and ``name``. 3425 3426 The arguments to this decorator can be used to customize this behavior: 3427 - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be 3428 ``True`` or ``False`` if it is omitted by the caller. 3429 - ``order_default`` indicates whether the ``order`` parameter is 3430 assumed to be True or False if it is omitted by the caller. 3431 - ``kw_only_default`` indicates whether the ``kw_only`` parameter is 3432 assumed to be True or False if it is omitted by the caller. 3433 - ``frozen_default`` indicates whether the ``frozen`` parameter is 3434 assumed to be True or False if it is omitted by the caller. 3435 - ``field_specifiers`` specifies a static list of supported classes 3436 or functions that describe fields, similar to ``dataclasses.field()``. 3437 - Arbitrary other keyword arguments are accepted in order to allow for 3438 possible future extensions. 3439 3440 At runtime, this decorator records its arguments in the 3441 ``__dataclass_transform__`` attribute on the decorated object. 3442 It has no other runtime effect. 3443 3444 See PEP 681 for more details. 3445 """ 3446 def decorator(cls_or_fn): 3447 cls_or_fn.__dataclass_transform__ = { 3448 "eq_default": eq_default, 3449 "order_default": order_default, 3450 "kw_only_default": kw_only_default, 3451 "frozen_default": frozen_default, 3452 "field_specifiers": field_specifiers, 3453 "kwargs": kwargs, 3454 } 3455 return cls_or_fn 3456 return decorator 3457 3458 3459type _Func = Callable[..., Any] 3460 3461 3462def override[F: _Func](method: F, /) -> F: 3463 """Indicate that a method is intended to override a method in a base class. 3464 3465 Usage:: 3466 3467 class Base: 3468 def method(self) -> None: 3469 pass 3470 3471 class Child(Base): 3472 @override 3473 def method(self) -> None: 3474 super().method() 3475 3476 When this decorator is applied to a method, the type checker will 3477 validate that it overrides a method or attribute with the same name on a 3478 base class. This helps prevent bugs that may occur when a base class is 3479 changed without an equivalent change to a child class. 3480 3481 There is no runtime checking of this property. The decorator attempts to 3482 set the ``__override__`` attribute to ``True`` on the decorated object to 3483 allow runtime introspection. 3484 3485 See PEP 698 for details. 3486 """ 3487 try: 3488 method.__override__ = True 3489 except (AttributeError, TypeError): 3490 # Skip the attribute silently if it is not writable. 3491 # AttributeError happens if the object has __slots__ or a 3492 # read-only property, TypeError if it's a builtin class. 3493 pass 3494 return method
class
Annotated:
2068class Annotated: 2069 """Add context-specific metadata to a type. 2070 2071 Example: Annotated[int, runtime_check.Unsigned] indicates to the 2072 hypothetical runtime_check module that this type is an unsigned int. 2073 Every other consumer of this type can ignore this metadata and treat 2074 this type as int. 2075 2076 The first argument to Annotated must be a valid type. 2077 2078 Details: 2079 2080 - It's an error to call `Annotated` with less than two arguments. 2081 - Access the metadata via the ``__metadata__`` attribute:: 2082 2083 assert Annotated[int, '$'].__metadata__ == ('$',) 2084 2085 - Nested Annotated types are flattened:: 2086 2087 assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3] 2088 2089 - Instantiating an annotated type is equivalent to instantiating the 2090 underlying type:: 2091 2092 assert Annotated[C, Ann1](5) == C(5) 2093 2094 - Annotated can be used as a generic type alias:: 2095 2096 type Optimized[T] = Annotated[T, runtime.Optimize()] 2097 # type checker will treat Optimized[int] 2098 # as equivalent to Annotated[int, runtime.Optimize()] 2099 2100 type OptimizedList[T] = Annotated[list[T], runtime.Optimize()] 2101 # type checker will treat OptimizedList[int] 2102 # as equivalent to Annotated[list[int], runtime.Optimize()] 2103 2104 - Annotated cannot be used with an unpacked TypeVarTuple:: 2105 2106 type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid 2107 2108 This would be equivalent to:: 2109 2110 Annotated[T1, T2, T3, ..., Ann1] 2111 2112 where T1, T2 etc. are TypeVars, which would be invalid, because 2113 only one type should be passed to Annotated. 2114 """ 2115 2116 __slots__ = () 2117 2118 def __new__(cls, *args, **kwargs): 2119 raise TypeError("Type Annotated cannot be instantiated.") 2120 2121 def __class_getitem__(cls, params): 2122 if not isinstance(params, tuple): 2123 params = (params,) 2124 return cls._class_getitem_inner(cls, *params) 2125 2126 @_tp_cache(typed=True) 2127 def _class_getitem_inner(cls, *params): 2128 if len(params) < 2: 2129 raise TypeError("Annotated[...] should be used " 2130 "with at least two arguments (a type and an " 2131 "annotation).") 2132 if _is_unpacked_typevartuple(params[0]): 2133 raise TypeError("Annotated[...] should not be used with an " 2134 "unpacked TypeVarTuple") 2135 msg = "Annotated[t, ...]: t must be a type." 2136 origin = _type_check(params[0], msg, allow_special_forms=True) 2137 metadata = tuple(params[1:]) 2138 return _AnnotatedAlias(origin, metadata) 2139 2140 def __init_subclass__(cls, *args, **kwargs): 2141 raise TypeError( 2142 "Cannot subclass {}.Annotated".format(cls.__module__) 2143 )
Add context-specific metadata to a type.
Example: Annotated[int, runtime_check.Unsigned] indicates to the hypothetical runtime_check module that this type is an unsigned int. Every other consumer of this type can ignore this metadata and treat this type as int.
The first argument to Annotated must be a valid type.
Details:
- It's an error to call
Annotatedwith less than two arguments. Access the metadata via the
__metadata__attribute::assert Annotated[int, '$'].__metadata__ == ('$',)
Nested Annotated types are flattened::
assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
Instantiating an annotated type is equivalent to instantiating the underlying type::
assert AnnotatedC, Ann1 == C(5)
Annotated can be used as a generic type alias::
type Optimized[T] = Annotated[T, runtime.Optimize()]
type checker will treat Optimized[int]
as equivalent to Annotated[int, runtime.Optimize()]
type OptimizedList[T] = Annotated[list[T], runtime.Optimize()]
type checker will treat OptimizedList[int]
as equivalent to Annotated[list[int], runtime.Optimize()]
Annotated cannot be used with an unpacked TypeVarTuple::
type Variadic[Ts] = Annotated[Ts, Ann1] # NOT valid
This would be equivalent to::
Annotated[T1, T2, T3, ..., Ann1]
where T1, T2 etc. are TypeVars, which would be invalid, because only one type should be passed to Annotated.
class
Any:
540class Any(metaclass=_AnyMeta): 541 """Special type indicating an unconstrained type. 542 543 - Any is compatible with every type. 544 - Any assumed to have all methods. 545 - All values assumed to be instances of Any. 546 547 Note that all the above statements are true from the point of view of 548 static type checkers. At runtime, Any should not be used with instance 549 checks. 550 """ 551 552 def __new__(cls, *args, **kwargs): 553 if cls is Any: 554 raise TypeError("Any cannot be instantiated") 555 return super().__new__(cls)
Special type indicating an unconstrained type.
- Any is compatible with every type.
- Any assumed to have all methods.
- All values assumed to be instances of Any.
Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.
Callable =
Callable
ClassVar =
ClassVar
Special type construct to mark class variables.
An annotation wrapped in ClassVar indicates that a given attribute is intended to be used as a class variable and should not be set on instances of that class.
Usage::
class Starship:
stats: ClassVar[dict[str, int]] = {} # class variable
damage: int = 10 # instance variable
ClassVar accepts only types and cannot be further subscribed.
Note that ClassVar is not a class itself, and should not be used with isinstance() or issubclass().
Concatenate =
Concatenate
Special form for annotating higher-order functions.
Concatenate can be used in conjunction with ParamSpec and
Callable to represent a higher-order function which adds, removes or
transforms the parameters of a callable.
For example::
Callable[Concatenate[int, P], int]
See PEP 612 for detailed information.
Final =
Final
Special typing construct to indicate final names to type checkers.
A final name cannot be re-assigned or overridden in a subclass.
For example::
MAX_SIZE: Final = 9000
MAX_SIZE += 1 # Error reported by type checker
class Connection:
TIMEOUT: Final[int] = 10
class FastConnector(Connection):
TIMEOUT = 1 # Error reported by type checker
There is no runtime checking of these properties.
885class ForwardRef(_Final, _root=True): 886 """Internal wrapper to hold a forward reference.""" 887 888 __slots__ = ('__forward_arg__', '__forward_code__', 889 '__forward_evaluated__', '__forward_value__', 890 '__forward_is_argument__', '__forward_is_class__', 891 '__forward_module__') 892 893 def __init__(self, arg, is_argument=True, module=None, *, is_class=False): 894 if not isinstance(arg, str): 895 raise TypeError(f"Forward reference must be a string -- got {arg!r}") 896 897 # If we do `def f(*args: *Ts)`, then we'll have `arg = '*Ts'`. 898 # Unfortunately, this isn't a valid expression on its own, so we 899 # do the unpacking manually. 900 if arg.startswith('*'): 901 arg_to_compile = f'({arg},)[0]' # E.g. (*Ts,)[0] or (*tuple[int, int],)[0] 902 else: 903 arg_to_compile = arg 904 try: 905 code = compile(arg_to_compile, '<string>', 'eval') 906 except SyntaxError: 907 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}") 908 909 self.__forward_arg__ = arg 910 self.__forward_code__ = code 911 self.__forward_evaluated__ = False 912 self.__forward_value__ = None 913 self.__forward_is_argument__ = is_argument 914 self.__forward_is_class__ = is_class 915 self.__forward_module__ = module 916 917 def _evaluate(self, globalns, localns, type_params=None, *, recursive_guard): 918 if self.__forward_arg__ in recursive_guard: 919 return self 920 if not self.__forward_evaluated__ or localns is not globalns: 921 if globalns is None and localns is None: 922 globalns = localns = {} 923 elif globalns is None: 924 globalns = localns 925 elif localns is None: 926 localns = globalns 927 if self.__forward_module__ is not None: 928 globalns = getattr( 929 sys.modules.get(self.__forward_module__, None), '__dict__', globalns 930 ) 931 932 # type parameters require some special handling, 933 # as they exist in their own scope 934 # but `eval()` does not have a dedicated parameter for that scope. 935 # For classes, names in type parameter scopes should override 936 # names in the global scope (which here are called `localns`!), 937 # but should in turn be overridden by names in the class scope 938 # (which here are called `globalns`!) 939 if type_params: 940 globalns, localns = dict(globalns), dict(localns) 941 for param in type_params: 942 param_name = param.__name__ 943 if not self.__forward_is_class__ or param_name not in globalns: 944 globalns[param_name] = param 945 localns.pop(param_name, None) 946 947 type_ = _type_check( 948 eval(self.__forward_code__, globalns, localns), 949 "Forward references must evaluate to types.", 950 is_argument=self.__forward_is_argument__, 951 allow_special_forms=self.__forward_is_class__, 952 ) 953 self.__forward_value__ = _eval_type( 954 type_, 955 globalns, 956 localns, 957 type_params, 958 recursive_guard=(recursive_guard | {self.__forward_arg__}), 959 ) 960 self.__forward_evaluated__ = True 961 return self.__forward_value__ 962 963 def __eq__(self, other): 964 if not isinstance(other, ForwardRef): 965 return NotImplemented 966 if self.__forward_evaluated__ and other.__forward_evaluated__: 967 return (self.__forward_arg__ == other.__forward_arg__ and 968 self.__forward_value__ == other.__forward_value__) 969 return (self.__forward_arg__ == other.__forward_arg__ and 970 self.__forward_module__ == other.__forward_module__) 971 972 def __hash__(self): 973 return hash((self.__forward_arg__, self.__forward_module__)) 974 975 def __or__(self, other): 976 return Union[self, other] 977 978 def __ror__(self, other): 979 return Union[other, self] 980 981 def __repr__(self): 982 if self.__forward_module__ is None: 983 module_repr = '' 984 else: 985 module_repr = f', module={self.__forward_module__!r}' 986 return f'ForwardRef({self.__forward_arg__!r}{module_repr})'
Internal wrapper to hold a forward reference.
ForwardRef(arg, is_argument=True, module=None, *, is_class=False)
893 def __init__(self, arg, is_argument=True, module=None, *, is_class=False): 894 if not isinstance(arg, str): 895 raise TypeError(f"Forward reference must be a string -- got {arg!r}") 896 897 # If we do `def f(*args: *Ts)`, then we'll have `arg = '*Ts'`. 898 # Unfortunately, this isn't a valid expression on its own, so we 899 # do the unpacking manually. 900 if arg.startswith('*'): 901 arg_to_compile = f'({arg},)[0]' # E.g. (*Ts,)[0] or (*tuple[int, int],)[0] 902 else: 903 arg_to_compile = arg 904 try: 905 code = compile(arg_to_compile, '<string>', 'eval') 906 except SyntaxError: 907 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}") 908 909 self.__forward_arg__ = arg 910 self.__forward_code__ = code 911 self.__forward_evaluated__ = False 912 self.__forward_value__ = None 913 self.__forward_is_argument__ = is_argument 914 self.__forward_is_class__ = is_class 915 self.__forward_module__ = module
class
Generic:
Abstract base class for generic types.
On Python 3.12 and newer, generic classes implicitly inherit from Generic when they declare a parameter list after the class's name::
class Mapping[KT, VT]:
def __getitem__(self, key: KT) -> VT:
...
# Etc.
On older versions of Python, however, generic classes have to explicitly inherit from Generic.
After a class has been declared to be generic, it can then be used as follows::
def lookup_name[KT, VT](mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
try:
return mapping[key]
except KeyError:
return default
Literal =
Literal
Special typing form to define literal types (a.k.a. value types).
This form can be used to indicate to type checkers that the corresponding variable or function parameter has a value equivalent to the provided literal (or one of several literals)::
def validate_simple(data: Any) -> Literal[True]: # always returns True
...
MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
...
open_helper('/some/path', 'r') # Passes type check
open_helper('/other/path', 'typo') # Error in type checker
Literal[...] cannot be subclassed. At runtime, an arbitrary value is allowed as type argument to Literal[...], but type checkers may impose restrictions.
Optional =
Optional
Optional[X] is equivalent to Union[X, None].
class
ParamSpec:
Parameter specification variable.
The preferred way to construct a parameter specification is via the dedicated syntax for generic functions, classes, and type aliases, where the use of '**' creates a parameter specification::
type IntFunc[**P] = Callable[P, int]
For compatibility with Python 3.11 and earlier, ParamSpec objects can also be created as follows::
P = ParamSpec('P')
Parameter specification variables exist primarily for the benefit of
static type checkers. They are used to forward the parameter types of
one callable to another callable, a pattern commonly found in
higher-order functions and decorators. They are only valid when used
in Concatenate, or as the first argument to Callable, or as
parameters for user-defined Generics. See class Generic for more
information on generic types.
An example for annotating a decorator::
def add_logging[**P, T](f: Callable[P, T]) -> Callable[P, T]:
'''A type-safe decorator to add logging to a function.'''
def inner(*args: P.args, **kwargs: P.kwargs) -> T:
logging.info(f'{f.__name__} was called')
return f(*args, **kwargs)
return inner
@add_logging
def add_two(x: float, y: float) -> float:
'''Add two numbers together.'''
return x + y
Parameter specification variables can be introspected. e.g.::
>>> P = ParamSpec("P")
>>> P.__name__
'P'
Note that only parameter specification variables defined in the global scope can be pickled.
1963class Protocol(Generic, metaclass=_ProtocolMeta): 1964 """Base class for protocol classes. 1965 1966 Protocol classes are defined as:: 1967 1968 class Proto(Protocol): 1969 def meth(self) -> int: 1970 ... 1971 1972 Such classes are primarily used with static type checkers that recognize 1973 structural subtyping (static duck-typing). 1974 1975 For example:: 1976 1977 class C: 1978 def meth(self) -> int: 1979 return 0 1980 1981 def func(x: Proto) -> int: 1982 return x.meth() 1983 1984 func(C()) # Passes static type check 1985 1986 See PEP 544 for details. Protocol classes decorated with 1987 @typing.runtime_checkable act as simple-minded runtime protocols that check 1988 only the presence of given attributes, ignoring their type signatures. 1989 Protocol classes can be generic, they are defined as:: 1990 1991 class GenProto[T](Protocol): 1992 def meth(self) -> T: 1993 ... 1994 """ 1995 1996 __slots__ = () 1997 _is_protocol = True 1998 _is_runtime_protocol = False 1999 2000 def __init_subclass__(cls, *args, **kwargs): 2001 super().__init_subclass__(*args, **kwargs) 2002 2003 # Determine if this is a protocol or a concrete subclass. 2004 if not cls.__dict__.get('_is_protocol', False): 2005 cls._is_protocol = any(b is Protocol for b in cls.__bases__) 2006 2007 # Set (or override) the protocol subclass hook. 2008 if '__subclasshook__' not in cls.__dict__: 2009 cls.__subclasshook__ = _proto_hook 2010 2011 # Prohibit instantiation for protocol classes 2012 if cls._is_protocol and cls.__init__ is Protocol.__init__: 2013 cls.__init__ = _no_init_or_replace_init
Base class for protocol classes.
Protocol classes are defined as::
class Proto(Protocol):
def meth(self) -> int:
...
Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).
For example::
class C:
def meth(self) -> int:
return 0
def func(x: Proto) -> int:
return x.meth()
func(C()) # Passes static type check
See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as::
class GenProto[T](Protocol):
def meth(self) -> T:
...
Tuple =
Tuple
Type =
Type
class
TypeVar:
Type variable.
The preferred way to construct a type variable is via the dedicated syntax for generic functions, classes, and type aliases::
class Sequence[T]: # T is a TypeVar
...
This syntax can also be used to create bound and constrained type variables::
# S is a TypeVar bound to str
class StrSequence[S: str]:
...
# A is a TypeVar constrained to str or bytes
class StrOrBytesSequence[A: (str, bytes)]:
...
However, if desired, reusable type variables can also be constructed manually, like so::
T = TypeVar('T') # Can be anything S = TypeVar('S', bound=str) # Can be any subtype of str A = TypeVar('A', str, bytes) # Must be exactly str or bytes
Type variables exist primarily for the benefit of static type checkers. They serve as the parameters for generic types as well as for generic function and type alias definitions.
The variance of type variables is inferred by type checkers when they
are created through the type parameter syntax and when
infer_variance=True is passed. Manually created type variables may
be explicitly marked covariant or contravariant by passing
covariant=True or contravariant=True. By default, manually
created type variables are invariant. See PEP 484 and PEP 695 for more
details.
class
TypeVarTuple:
Type variable tuple. A specialized form of type variable that enables variadic generics.
The preferred way to construct a type variable tuple is via the dedicated syntax for generic functions, classes, and type aliases, where a single '*' indicates a type variable tuple::
def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
return (*tup[1:], tup[0])
For compatibility with Python 3.11 and earlier, TypeVarTuple objects can also be created as follows::
Ts = TypeVarTuple('Ts') # Can be given any name
Just as a TypeVar (type variable) is a placeholder for a single type, a TypeVarTuple is a placeholder for an arbitrary number of types. For example, if we define a generic class using a TypeVarTuple::
class C[*Ts]: ...
Then we can parameterize that class with an arbitrary number of type arguments::
C[int] # Fine
C[int, str] # Also fine
C[()] # Even this is fine
For more details, see PEP 646.
Note that only TypeVarTuples defined in the global scope can be pickled.
Union =
Union
Union type; Union[X, Y] means either X or Y.
On Python 3.10 and higher, the | operator can also be used to denote unions; X | Y means the same thing to the type checker as Union[X, Y].
To define a union, use e.g. Union[int, str]. Details:
- The arguments must be types and there must be at least one.
- None as an argument is a special case and is replaced by type(None).
- Unions of unions are flattened, e.g.::
assert Union[Union[int, str], float] == Union[int, str, float]
Unions of a single argument vanish, e.g.::
assert Union[int] == int # The constructor actually returns int
Redundant arguments are skipped, e.g.::
assert Union[int, str, int] == Union[int, str]
When comparing unions, the argument order is ignored, e.g.::
assert Union[int, str] == Union[str, int]
You cannot subclass or instantiate a union.
- You can use Optional as a shorthand for Union[X, None].
AbstractSet =
AbstractSet
ByteString =
ByteString
Container =
Container
ContextManager =
ContextManager
Hashable =
Hashable
ItemsView =
ItemsView
Iterable =
Iterable
Iterator =
Iterator
KeysView =
KeysView
Mapping =
Mapping
MappingView =
MappingView
MutableMapping =
MutableMapping
MutableSequence =
MutableSequence
MutableSet =
MutableSet
Sequence =
Sequence
Sized =
Sized
ValuesView =
ValuesView
Awaitable =
Awaitable
AsyncIterator =
AsyncIterator
AsyncIterable =
AsyncIterable
Coroutine =
Coroutine
Collection =
Collection
AsyncGenerator =
AsyncGenerator
AsyncContextManager =
AsyncContextManager
Reversible =
Reversible
2774@runtime_checkable 2775class SupportsAbs[T](Protocol): 2776 """An ABC with one abstract method __abs__ that is covariant in its return type.""" 2777 2778 __slots__ = () 2779 2780 @abstractmethod 2781 def __abs__(self) -> T: 2782 pass
An ABC with one abstract method __abs__ that is covariant in its return type.
2752@runtime_checkable 2753class SupportsBytes(Protocol): 2754 """An ABC with one abstract method __bytes__.""" 2755 2756 __slots__ = () 2757 2758 @abstractmethod 2759 def __bytes__(self) -> bytes: 2760 pass
An ABC with one abstract method __bytes__.
2741@runtime_checkable 2742class SupportsComplex(Protocol): 2743 """An ABC with one abstract method __complex__.""" 2744 2745 __slots__ = () 2746 2747 @abstractmethod 2748 def __complex__(self) -> complex: 2749 pass
An ABC with one abstract method __complex__.
2730@runtime_checkable 2731class SupportsFloat(Protocol): 2732 """An ABC with one abstract method __float__.""" 2733 2734 __slots__ = () 2735 2736 @abstractmethod 2737 def __float__(self) -> float: 2738 pass
An ABC with one abstract method __float__.
2763@runtime_checkable 2764class SupportsIndex(Protocol): 2765 """An ABC with one abstract method __index__.""" 2766 2767 __slots__ = () 2768 2769 @abstractmethod 2770 def __index__(self) -> int: 2771 pass
An ABC with one abstract method __index__.
2719@runtime_checkable 2720class SupportsInt(Protocol): 2721 """An ABC with one abstract method __int__.""" 2722 2723 __slots__ = () 2724 2725 @abstractmethod 2726 def __int__(self) -> int: 2727 pass
An ABC with one abstract method __int__.
2785@runtime_checkable 2786class SupportsRound[T](Protocol): 2787 """An ABC with one abstract method __round__ that is covariant in its return type.""" 2788 2789 __slots__ = () 2790 2791 @abstractmethod 2792 def __round__(self, ndigits: int = 0) -> T: 2793 pass
An ABC with one abstract method __round__ that is covariant in its return type.
ChainMap =
ChainMap
Counter =
Counter
Deque =
Deque
Dict =
Dict
DefaultDict =
DefaultDict
List =
List
OrderedDict =
OrderedDict
Set =
Set
FrozenSet =
FrozenSet
def
NamedTuple(typename, fields=None, /, **kwargs):
2850def NamedTuple(typename, fields=None, /, **kwargs): 2851 """Typed version of namedtuple. 2852 2853 Usage:: 2854 2855 class Employee(NamedTuple): 2856 name: str 2857 id: int 2858 2859 This is equivalent to:: 2860 2861 Employee = collections.namedtuple('Employee', ['name', 'id']) 2862 2863 The resulting class has an extra __annotations__ attribute, giving a 2864 dict that maps field names to types. (The field names are also in 2865 the _fields attribute, which is part of the namedtuple API.) 2866 An alternative equivalent functional syntax is also accepted:: 2867 2868 Employee = NamedTuple('Employee', [('name', str), ('id', int)]) 2869 """ 2870 if fields is None: 2871 fields = kwargs.items() 2872 elif kwargs: 2873 raise TypeError("Either list of fields or keywords" 2874 " can be provided to NamedTuple, not both") 2875 nt = _make_nmtuple(typename, fields, module=_caller()) 2876 nt.__orig_bases__ = (NamedTuple,) 2877 return nt
Typed version of namedtuple.
Usage::
class Employee(NamedTuple):
name: str
id: int
This is equivalent to::
Employee = collections.namedtuple('Employee', ['name', 'id'])
The resulting class has an extra __annotations__ attribute, giving a dict that maps field names to types. (The field names are also in the _fields attribute, which is part of the namedtuple API.) An alternative equivalent functional syntax is also accepted::
Employee = NamedTuple('Employee', [('name', str), ('id', int)])
def
TypedDict(typename, fields=None, /, *, total=True, **kwargs):
2976def TypedDict(typename, fields=None, /, *, total=True, **kwargs): 2977 """A simple typed namespace. At runtime it is equivalent to a plain dict. 2978 2979 TypedDict creates a dictionary type such that a type checker will expect all 2980 instances to have a certain set of keys, where each key is 2981 associated with a value of a consistent type. This expectation 2982 is not checked at runtime. 2983 2984 Usage:: 2985 2986 >>> class Point2D(TypedDict): 2987 ... x: int 2988 ... y: int 2989 ... label: str 2990 ... 2991 >>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK 2992 >>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check 2993 >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') 2994 True 2995 2996 The type info can be accessed via the Point2D.__annotations__ dict, and 2997 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets. 2998 TypedDict supports an additional equivalent form:: 2999 3000 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) 3001 3002 By default, all keys must be present in a TypedDict. It is possible 3003 to override this by specifying totality:: 3004 3005 class Point2D(TypedDict, total=False): 3006 x: int 3007 y: int 3008 3009 This means that a Point2D TypedDict can have any of the keys omitted. A type 3010 checker is only expected to support a literal False or True as the value of 3011 the total argument. True is the default, and makes all items defined in the 3012 class body be required. 3013 3014 The Required and NotRequired special forms can also be used to mark 3015 individual keys as being required or not required:: 3016 3017 class Point2D(TypedDict): 3018 x: int # the "x" key must always be present (Required is the default) 3019 y: NotRequired[int] # the "y" key can be omitted 3020 3021 See PEP 655 for more details on Required and NotRequired. 3022 """ 3023 if fields is None: 3024 fields = kwargs 3025 elif kwargs: 3026 raise TypeError("TypedDict takes either a dict or keyword arguments," 3027 " but not both") 3028 if kwargs: 3029 warnings.warn( 3030 "The kwargs-based syntax for TypedDict definitions is deprecated " 3031 "in Python 3.11, will be removed in Python 3.13, and may not be " 3032 "understood by third-party type checkers.", 3033 DeprecationWarning, 3034 stacklevel=2, 3035 ) 3036 3037 ns = {'__annotations__': dict(fields)} 3038 module = _caller() 3039 if module is not None: 3040 # Setting correct module is necessary to make typed dict classes pickleable. 3041 ns['__module__'] = module 3042 3043 td = _TypedDictMeta(typename, (), ns, total=total) 3044 td.__orig_bases__ = (TypedDict,) 3045 return td
A simple typed namespace. At runtime it is equivalent to a plain dict.
TypedDict creates a dictionary type such that a type checker will expect all instances to have a certain set of keys, where each key is associated with a value of a consistent type. This expectation is not checked at runtime.
Usage::
>>> class Point2D(TypedDict):
... x: int
... y: int
... label: str
...
>>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
>>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
>>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
True
The type info can be accessed via the Point2D.__annotations__ dict, and the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets. TypedDict supports an additional equivalent form::
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality::
class Point2D(TypedDict, total=False):
x: int
y: int
This means that a Point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body be required.
The Required and NotRequired special forms can also be used to mark individual keys as being required or not required::
class Point2D(TypedDict):
x: int # the "x" key must always be present (Required is the default)
y: NotRequired[int] # the "y" key can be omitted
See PEP 655 for more details on Required and NotRequired.
Generator =
Generator
3263class BinaryIO(IO[bytes]): 3264 """Typed version of the return of open() in binary mode.""" 3265 3266 __slots__ = () 3267 3268 @abstractmethod 3269 def write(self, s: Union[bytes, bytearray]) -> int: 3270 pass 3271 3272 @abstractmethod 3273 def __enter__(self) -> 'BinaryIO': 3274 pass
Typed version of the return of open() in binary mode.
3164class IO(Generic[AnyStr]): 3165 """Generic base class for TextIO and BinaryIO. 3166 3167 This is an abstract, generic version of the return of open(). 3168 3169 NOTE: This does not distinguish between the different possible 3170 classes (text vs. binary, read vs. write vs. read/write, 3171 append-only, unbuffered). The TextIO and BinaryIO subclasses 3172 below capture the distinctions between text vs. binary, which is 3173 pervasive in the interface; however we currently do not offer a 3174 way to track the other distinctions in the type system. 3175 """ 3176 3177 __slots__ = () 3178 3179 @property 3180 @abstractmethod 3181 def mode(self) -> str: 3182 pass 3183 3184 @property 3185 @abstractmethod 3186 def name(self) -> str: 3187 pass 3188 3189 @abstractmethod 3190 def close(self) -> None: 3191 pass 3192 3193 @property 3194 @abstractmethod 3195 def closed(self) -> bool: 3196 pass 3197 3198 @abstractmethod 3199 def fileno(self) -> int: 3200 pass 3201 3202 @abstractmethod 3203 def flush(self) -> None: 3204 pass 3205 3206 @abstractmethod 3207 def isatty(self) -> bool: 3208 pass 3209 3210 @abstractmethod 3211 def read(self, n: int = -1) -> AnyStr: 3212 pass 3213 3214 @abstractmethod 3215 def readable(self) -> bool: 3216 pass 3217 3218 @abstractmethod 3219 def readline(self, limit: int = -1) -> AnyStr: 3220 pass 3221 3222 @abstractmethod 3223 def readlines(self, hint: int = -1) -> List[AnyStr]: 3224 pass 3225 3226 @abstractmethod 3227 def seek(self, offset: int, whence: int = 0) -> int: 3228 pass 3229 3230 @abstractmethod 3231 def seekable(self) -> bool: 3232 pass 3233 3234 @abstractmethod 3235 def tell(self) -> int: 3236 pass 3237 3238 @abstractmethod 3239 def truncate(self, size: int = None) -> int: 3240 pass 3241 3242 @abstractmethod 3243 def writable(self) -> bool: 3244 pass 3245 3246 @abstractmethod 3247 def write(self, s: AnyStr) -> int: 3248 pass 3249 3250 @abstractmethod 3251 def writelines(self, lines: List[AnyStr]) -> None: 3252 pass 3253 3254 @abstractmethod 3255 def __enter__(self) -> 'IO[AnyStr]': 3256 pass 3257 3258 @abstractmethod 3259 def __exit__(self, type, value, traceback) -> None: 3260 pass
Generic base class for TextIO and BinaryIO.
This is an abstract, generic version of the return of open().
NOTE: This does not distinguish between the different possible classes (text vs. binary, read vs. write vs. read/write, append-only, unbuffered). The TextIO and BinaryIO subclasses below capture the distinctions between text vs. binary, which is pervasive in the interface; however we currently do not offer a way to track the other distinctions in the type system.
Match =
Match
Pattern =
Pattern
3277class TextIO(IO[str]): 3278 """Typed version of the return of open() in text mode.""" 3279 3280 __slots__ = () 3281 3282 @property 3283 @abstractmethod 3284 def buffer(self) -> BinaryIO: 3285 pass 3286 3287 @property 3288 @abstractmethod 3289 def encoding(self) -> str: 3290 pass 3291 3292 @property 3293 @abstractmethod 3294 def errors(self) -> Optional[str]: 3295 pass 3296 3297 @property 3298 @abstractmethod 3299 def line_buffering(self) -> bool: 3300 pass 3301 3302 @property 3303 @abstractmethod 3304 def newlines(self) -> Any: 3305 pass 3306 3307 @abstractmethod 3308 def __enter__(self) -> 'TextIO': 3309 pass
Typed version of the return of open() in text mode.
def
assert_type(val, typ, /):
2199def assert_type(val, typ, /): 2200 """Ask a static type checker to confirm that the value is of the given type. 2201 2202 At runtime this does nothing: it returns the first argument unchanged with no 2203 checks or side effects, no matter the actual type of the argument. 2204 2205 When a static type checker encounters a call to assert_type(), it 2206 emits an error if the value is not of the specified type:: 2207 2208 def greet(name: str) -> None: 2209 assert_type(name, str) # OK 2210 assert_type(name, int) # type checker error 2211 """ 2212 return val
Ask a static type checker to confirm that the value is of the given type.
At runtime this does nothing: it returns the first argument unchanged with no checks or side effects, no matter the actual type of the argument.
When a static type checker encounters a call to assert_type(), it emits an error if the value is not of the specified type::
def greet(name: str) -> None:
assert_type(name, str) # OK
assert_type(name, int) # type checker error
def
assert_never(arg: Never, /) -> Never:
2422def assert_never(arg: Never, /) -> Never: 2423 """Statically assert that a line of code is unreachable. 2424 2425 Example:: 2426 2427 def int_or_str(arg: int | str) -> None: 2428 match arg: 2429 case int(): 2430 print("It's an int") 2431 case str(): 2432 print("It's a str") 2433 case _: 2434 assert_never(arg) 2435 2436 If a type checker finds that a call to assert_never() is 2437 reachable, it will emit an error. 2438 2439 At runtime, this throws an exception when called. 2440 """ 2441 value = repr(arg) 2442 if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH: 2443 value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...' 2444 raise AssertionError(f"Expected code to be unreachable, but got: {value}")
Statically assert that a line of code is unreachable.
Example::
def int_or_str(arg: int | str) -> None:
match arg:
case int():
print("It's an int")
case str():
print("It's a str")
case _:
assert_never(arg)
If a type checker finds that a call to assert_never() is reachable, it will emit an error.
At runtime, this throws an exception when called.
def
cast(typ, val):
2188def cast(typ, val): 2189 """Cast a value to a type. 2190 2191 This returns the value unchanged. To the type checker this 2192 signals that the return value has the designated type, but at 2193 runtime we intentionally don't check anything (we want this 2194 to be as fast as possible). 2195 """ 2196 return val
Cast a value to a type.
This returns the value unchanged. To the type checker this signals that the return value has the designated type, but at runtime we intentionally don't check anything (we want this to be as fast as possible).
def
clear_overloads():
2564def clear_overloads(): 2565 """Clear all overloads in the registry.""" 2566 _overload_registry.clear()
Clear all overloads in the registry.
def
dataclass_transform( *, eq_default: bool = True, order_default: bool = False, kw_only_default: bool = False, frozen_default: bool = False, field_specifiers: tuple[Union[type[Any], Callable[..., Any]], ...] = (), **kwargs: Any) -> <class '_IdentityCallable'>:
3376def dataclass_transform( 3377 *, 3378 eq_default: bool = True, 3379 order_default: bool = False, 3380 kw_only_default: bool = False, 3381 frozen_default: bool = False, 3382 field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (), 3383 **kwargs: Any, 3384) -> _IdentityCallable: 3385 """Decorator to mark an object as providing dataclass-like behaviour. 3386 3387 The decorator can be applied to a function, class, or metaclass. 3388 3389 Example usage with a decorator function:: 3390 3391 @dataclass_transform() 3392 def create_model[T](cls: type[T]) -> type[T]: 3393 ... 3394 return cls 3395 3396 @create_model 3397 class CustomerModel: 3398 id: int 3399 name: str 3400 3401 On a base class:: 3402 3403 @dataclass_transform() 3404 class ModelBase: ... 3405 3406 class CustomerModel(ModelBase): 3407 id: int 3408 name: str 3409 3410 On a metaclass:: 3411 3412 @dataclass_transform() 3413 class ModelMeta(type): ... 3414 3415 class ModelBase(metaclass=ModelMeta): ... 3416 3417 class CustomerModel(ModelBase): 3418 id: int 3419 name: str 3420 3421 The ``CustomerModel`` classes defined above will 3422 be treated by type checkers similarly to classes created with 3423 ``@dataclasses.dataclass``. 3424 For example, type checkers will assume these classes have 3425 ``__init__`` methods that accept ``id`` and ``name``. 3426 3427 The arguments to this decorator can be used to customize this behavior: 3428 - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be 3429 ``True`` or ``False`` if it is omitted by the caller. 3430 - ``order_default`` indicates whether the ``order`` parameter is 3431 assumed to be True or False if it is omitted by the caller. 3432 - ``kw_only_default`` indicates whether the ``kw_only`` parameter is 3433 assumed to be True or False if it is omitted by the caller. 3434 - ``frozen_default`` indicates whether the ``frozen`` parameter is 3435 assumed to be True or False if it is omitted by the caller. 3436 - ``field_specifiers`` specifies a static list of supported classes 3437 or functions that describe fields, similar to ``dataclasses.field()``. 3438 - Arbitrary other keyword arguments are accepted in order to allow for 3439 possible future extensions. 3440 3441 At runtime, this decorator records its arguments in the 3442 ``__dataclass_transform__`` attribute on the decorated object. 3443 It has no other runtime effect. 3444 3445 See PEP 681 for more details. 3446 """ 3447 def decorator(cls_or_fn): 3448 cls_or_fn.__dataclass_transform__ = { 3449 "eq_default": eq_default, 3450 "order_default": order_default, 3451 "kw_only_default": kw_only_default, 3452 "frozen_default": frozen_default, 3453 "field_specifiers": field_specifiers, 3454 "kwargs": kwargs, 3455 } 3456 return cls_or_fn 3457 return decorator
Decorator to mark an object as providing dataclass-like behaviour.
The decorator can be applied to a function, class, or metaclass.
Example usage with a decorator function::
@dataclass_transform()
def create_model[T](cls: type[T]) -> type[T]:
...
return cls
@create_model
class CustomerModel:
id: int
name: str
On a base class::
@dataclass_transform()
class ModelBase: ...
class CustomerModel(ModelBase):
id: int
name: str
On a metaclass::
@dataclass_transform()
class ModelMeta(type): ...
class ModelBase(metaclass=ModelMeta): ...
class CustomerModel(ModelBase):
id: int
name: str
The CustomerModel classes defined above will
be treated by type checkers similarly to classes created with
@dataclasses.dataclass.
For example, type checkers will assume these classes have
__init__ methods that accept id and name.
The arguments to this decorator can be used to customize this behavior:
eq_defaultindicates whether theeqparameter is assumed to beTrueorFalseif it is omitted by the caller.order_defaultindicates whether theorderparameter is assumed to be True or False if it is omitted by the caller.kw_only_defaultindicates whether thekw_onlyparameter is assumed to be True or False if it is omitted by the caller.frozen_defaultindicates whether thefrozenparameter is assumed to be True or False if it is omitted by the caller.field_specifiersspecifies a static list of supported classes or functions that describe fields, similar todataclasses.field().- Arbitrary other keyword arguments are accepted in order to allow for possible future extensions.
At runtime, this decorator records its arguments in the
__dataclass_transform__ attribute on the decorated object.
It has no other runtime effect.
See PEP 681 for more details.
def
final(f):
2569def final(f): 2570 """Decorator to indicate final methods and final classes. 2571 2572 Use this decorator to indicate to type checkers that the decorated 2573 method cannot be overridden, and decorated class cannot be subclassed. 2574 2575 For example:: 2576 2577 class Base: 2578 @final 2579 def done(self) -> None: 2580 ... 2581 class Sub(Base): 2582 def done(self) -> None: # Error reported by type checker 2583 ... 2584 2585 @final 2586 class Leaf: 2587 ... 2588 class Other(Leaf): # Error reported by type checker 2589 ... 2590 2591 There is no runtime checking of these properties. The decorator 2592 attempts to set the ``__final__`` attribute to ``True`` on the decorated 2593 object to allow runtime introspection. 2594 """ 2595 try: 2596 f.__final__ = True 2597 except (AttributeError, TypeError): 2598 # Skip the attribute silently if it is not writable. 2599 # AttributeError happens if the object has __slots__ or a 2600 # read-only property, TypeError if it's a builtin class. 2601 pass 2602 return f
Decorator to indicate final methods and final classes.
Use this decorator to indicate to type checkers that the decorated method cannot be overridden, and decorated class cannot be subclassed.
For example::
class Base:
@final
def done(self) -> None:
...
class Sub(Base):
def done(self) -> None: # Error reported by type checker
...
@final
class Leaf:
...
class Other(Leaf): # Error reported by type checker
...
There is no runtime checking of these properties. The decorator
attempts to set the __final__ attribute to True on the decorated
object to allow runtime introspection.
def
get_args(tp):
2375def get_args(tp): 2376 """Get type arguments with all substitutions performed. 2377 2378 For unions, basic simplifications used by Union constructor are performed. 2379 2380 Examples:: 2381 2382 >>> T = TypeVar('T') 2383 >>> assert get_args(Dict[str, int]) == (str, int) 2384 >>> assert get_args(int) == () 2385 >>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str) 2386 >>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) 2387 >>> assert get_args(Callable[[], T][int]) == ([], int) 2388 """ 2389 if isinstance(tp, _AnnotatedAlias): 2390 return (tp.__origin__,) + tp.__metadata__ 2391 if isinstance(tp, (_GenericAlias, GenericAlias)): 2392 res = tp.__args__ 2393 if _should_unflatten_callable_args(tp, res): 2394 res = (list(res[:-1]), res[-1]) 2395 return res 2396 if isinstance(tp, types.UnionType): 2397 return tp.__args__ 2398 return ()
Get type arguments with all substitutions performed.
For unions, basic simplifications used by Union constructor are performed.
Examples::
>>> T = TypeVar('T')
>>> assert get_args(Dict[str, int]) == (str, int)
>>> assert get_args(int) == ()
>>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
>>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
>>> assert get_args(Callable[[], T][int]) == ([], int)
def
get_origin(tp):
2345def get_origin(tp): 2346 """Get the unsubscripted version of a type. 2347 2348 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar, 2349 Annotated, and others. Return None for unsupported types. 2350 2351 Examples:: 2352 2353 >>> P = ParamSpec('P') 2354 >>> assert get_origin(Literal[42]) is Literal 2355 >>> assert get_origin(int) is None 2356 >>> assert get_origin(ClassVar[int]) is ClassVar 2357 >>> assert get_origin(Generic) is Generic 2358 >>> assert get_origin(Generic[T]) is Generic 2359 >>> assert get_origin(Union[T, int]) is Union 2360 >>> assert get_origin(List[Tuple[T, T]][int]) is list 2361 >>> assert get_origin(P.args) is P 2362 """ 2363 if isinstance(tp, _AnnotatedAlias): 2364 return Annotated 2365 if isinstance(tp, (_BaseGenericAlias, GenericAlias, 2366 ParamSpecArgs, ParamSpecKwargs)): 2367 return tp.__origin__ 2368 if tp is Generic: 2369 return Generic 2370 if isinstance(tp, types.UnionType): 2371 return types.UnionType 2372 return None
Get the unsubscripted version of a type.
This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar, Annotated, and others. Return None for unsupported types.
Examples::
>>> P = ParamSpec('P')
>>> assert get_origin(Literal[42]) is Literal
>>> assert get_origin(int) is None
>>> assert get_origin(ClassVar[int]) is ClassVar
>>> assert get_origin(Generic) is Generic
>>> assert get_origin(Generic[T]) is Generic
>>> assert get_origin(Union[T, int]) is Union
>>> assert get_origin(List[Tuple[T, T]][int]) is list
>>> assert get_origin(P.args) is P
def
get_overloads(func):
2552def get_overloads(func): 2553 """Return all defined overloads for *func* as a sequence.""" 2554 # classmethod and staticmethod 2555 f = getattr(func, "__func__", func) 2556 if f.__module__ not in _overload_registry: 2557 return [] 2558 mod_dict = _overload_registry[f.__module__] 2559 if f.__qualname__ not in mod_dict: 2560 return [] 2561 return list(mod_dict[f.__qualname__].values())
Return all defined overloads for func as a sequence.
def
get_type_hints(obj, globalns=None, localns=None, include_extras=False):
2220def get_type_hints(obj, globalns=None, localns=None, include_extras=False): 2221 """Return type hints for an object. 2222 2223 This is often the same as obj.__annotations__, but it handles 2224 forward references encoded as string literals and recursively replaces all 2225 'Annotated[T, ...]' with 'T' (unless 'include_extras=True'). 2226 2227 The argument may be a module, class, method, or function. The annotations 2228 are returned as a dictionary. For classes, annotations include also 2229 inherited members. 2230 2231 TypeError is raised if the argument is not of a type that can contain 2232 annotations, and an empty dictionary is returned if no annotations are 2233 present. 2234 2235 BEWARE -- the behavior of globalns and localns is counterintuitive 2236 (unless you are familiar with how eval() and exec() work). The 2237 search order is locals first, then globals. 2238 2239 - If no dict arguments are passed, an attempt is made to use the 2240 globals from obj (or the respective module's globals for classes), 2241 and these are also used as the locals. If the object does not appear 2242 to have globals, an empty dictionary is used. For classes, the search 2243 order is globals first then locals. 2244 2245 - If one dict argument is passed, it is used for both globals and 2246 locals. 2247 2248 - If two dict arguments are passed, they specify globals and 2249 locals, respectively. 2250 """ 2251 if getattr(obj, '__no_type_check__', None): 2252 return {} 2253 # Classes require a special treatment. 2254 if isinstance(obj, type): 2255 hints = {} 2256 for base in reversed(obj.__mro__): 2257 if globalns is None: 2258 base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {}) 2259 else: 2260 base_globals = globalns 2261 ann = base.__dict__.get('__annotations__', {}) 2262 if isinstance(ann, types.GetSetDescriptorType): 2263 ann = {} 2264 base_locals = dict(vars(base)) if localns is None else localns 2265 if localns is None and globalns is None: 2266 # This is surprising, but required. Before Python 3.10, 2267 # get_type_hints only evaluated the globalns of 2268 # a class. To maintain backwards compatibility, we reverse 2269 # the globalns and localns order so that eval() looks into 2270 # *base_globals* first rather than *base_locals*. 2271 # This only affects ForwardRefs. 2272 base_globals, base_locals = base_locals, base_globals 2273 for name, value in ann.items(): 2274 if value is None: 2275 value = type(None) 2276 if isinstance(value, str): 2277 value = ForwardRef(value, is_argument=False, is_class=True) 2278 value = _eval_type(value, base_globals, base_locals, base.__type_params__) 2279 hints[name] = value 2280 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()} 2281 2282 if globalns is None: 2283 if isinstance(obj, types.ModuleType): 2284 globalns = obj.__dict__ 2285 else: 2286 nsobj = obj 2287 # Find globalns for the unwrapped object. 2288 while hasattr(nsobj, '__wrapped__'): 2289 nsobj = nsobj.__wrapped__ 2290 globalns = getattr(nsobj, '__globals__', {}) 2291 if localns is None: 2292 localns = globalns 2293 elif localns is None: 2294 localns = globalns 2295 hints = getattr(obj, '__annotations__', None) 2296 if hints is None: 2297 # Return empty annotations for something that _could_ have them. 2298 if isinstance(obj, _allowed_types): 2299 return {} 2300 else: 2301 raise TypeError('{!r} is not a module, class, method, ' 2302 'or function.'.format(obj)) 2303 hints = dict(hints) 2304 type_params = getattr(obj, "__type_params__", ()) 2305 for name, value in hints.items(): 2306 if value is None: 2307 value = type(None) 2308 if isinstance(value, str): 2309 # class-level forward refs were handled above, this must be either 2310 # a module-level annotation or a function argument annotation 2311 value = ForwardRef( 2312 value, 2313 is_argument=not isinstance(obj, types.ModuleType), 2314 is_class=False, 2315 ) 2316 hints[name] = _eval_type(value, globalns, localns, type_params) 2317 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
Return type hints for an object.
This is often the same as obj.__annotations__, but it handles forward references encoded as string literals and recursively replaces all 'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
The argument may be a module, class, method, or function. The annotations are returned as a dictionary. For classes, annotations include also inherited members.
TypeError is raised if the argument is not of a type that can contain annotations, and an empty dictionary is returned if no annotations are present.
BEWARE -- the behavior of globalns and localns is counterintuitive (unless you are familiar with how eval() and exec() work). The search order is locals first, then globals.
If no dict arguments are passed, an attempt is made to use the globals from obj (or the respective module's globals for classes), and these are also used as the locals. If the object does not appear to have globals, an empty dictionary is used. For classes, the search order is globals first then locals.
If one dict argument is passed, it is used for both globals and locals.
If two dict arguments are passed, they specify globals and locals, respectively.
def
is_typeddict(tp):
2401def is_typeddict(tp): 2402 """Check if an annotation is a TypedDict class. 2403 2404 For example:: 2405 2406 >>> from typing import TypedDict 2407 >>> class Film(TypedDict): 2408 ... title: str 2409 ... year: int 2410 ... 2411 >>> is_typeddict(Film) 2412 True 2413 >>> is_typeddict(dict) 2414 False 2415 """ 2416 return isinstance(tp, _TypedDictMeta)
Check if an annotation is a TypedDict class.
For example::
>>> from typing import TypedDict
>>> class Film(TypedDict):
... title: str
... year: int
...
>>> is_typeddict(Film)
True
>>> is_typeddict(dict)
False
LiteralString =
LiteralString
Represents an arbitrary literal string.
Example::
from typing import LiteralString
def run_query(sql: LiteralString) -> None:
...
def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
run_query("SELECT * FROM students") # OK
run_query(literal_string) # OK
run_query("SELECT * FROM " + literal_string) # OK
run_query(arbitrary_string) # type checker error
run_query( # type checker error
f"SELECT * FROM students WHERE name = {arbitrary_string}"
)
Only string literals and other LiteralStrings are compatible with LiteralString. This provides a tool to help prevent security issues such as SQL injection.
Never =
Never
The bottom type, a type that has no members.
This can be used to define a function that should never be called, or a function that never returns::
from typing import Never
def never_call_me(arg: Never) -> None:
pass
def int_or_str(arg: int | str) -> None:
never_call_me(arg) # type checker error
match arg:
case int():
print("It's an int")
case str():
print("It's a str")
case _:
never_call_me(arg) # OK, arg is of type Never
class
NewType:
3094class NewType: 3095 """NewType creates simple unique types with almost zero runtime overhead. 3096 3097 NewType(name, tp) is considered a subtype of tp 3098 by static type checkers. At runtime, NewType(name, tp) returns 3099 a dummy callable that simply returns its argument. 3100 3101 Usage:: 3102 3103 UserId = NewType('UserId', int) 3104 3105 def name_by_id(user_id: UserId) -> str: 3106 ... 3107 3108 UserId('user') # Fails type check 3109 3110 name_by_id(42) # Fails type check 3111 name_by_id(UserId(42)) # OK 3112 3113 num = UserId(5) + 1 # type: int 3114 """ 3115 3116 __call__ = _idfunc 3117 3118 def __init__(self, name, tp): 3119 self.__qualname__ = name 3120 if '.' in name: 3121 name = name.rpartition('.')[-1] 3122 self.__name__ = name 3123 self.__supertype__ = tp 3124 def_mod = _caller() 3125 if def_mod != 'typing': 3126 self.__module__ = def_mod 3127 3128 def __mro_entries__(self, bases): 3129 # We defined __mro_entries__ to get a better error message 3130 # if a user attempts to subclass a NewType instance. bpo-46170 3131 superclass_name = self.__name__ 3132 3133 class Dummy: 3134 def __init_subclass__(cls): 3135 subclass_name = cls.__name__ 3136 raise TypeError( 3137 f"Cannot subclass an instance of NewType. Perhaps you were looking for: " 3138 f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`" 3139 ) 3140 3141 return (Dummy,) 3142 3143 def __repr__(self): 3144 return f'{self.__module__}.{self.__qualname__}' 3145 3146 def __reduce__(self): 3147 return self.__qualname__ 3148 3149 def __or__(self, other): 3150 return Union[self, other] 3151 3152 def __ror__(self, other): 3153 return Union[other, self]
NewType creates simple unique types with almost zero runtime overhead.
NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns a dummy callable that simply returns its argument.
Usage::
UserId = NewType('UserId', int)
def name_by_id(user_id: UserId) -> str:
...
UserId('user') # Fails type check
name_by_id(42) # Fails type check
name_by_id(UserId(42)) # OK
num = UserId(5) + 1 # type: int
def
no_type_check(arg):
2447def no_type_check(arg): 2448 """Decorator to indicate that annotations are not type hints. 2449 2450 The argument must be a class or function; if it is a class, it 2451 applies recursively to all methods and classes defined in that class 2452 (but not to methods defined in its superclasses or subclasses). 2453 2454 This mutates the function(s) or class(es) in place. 2455 """ 2456 if isinstance(arg, type): 2457 for key in dir(arg): 2458 obj = getattr(arg, key) 2459 if ( 2460 not hasattr(obj, '__qualname__') 2461 or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}' 2462 or getattr(obj, '__module__', None) != arg.__module__ 2463 ): 2464 # We only modify objects that are defined in this type directly. 2465 # If classes / methods are nested in multiple layers, 2466 # we will modify them when processing their direct holders. 2467 continue 2468 # Instance, class, and static methods: 2469 if isinstance(obj, types.FunctionType): 2470 obj.__no_type_check__ = True 2471 if isinstance(obj, types.MethodType): 2472 obj.__func__.__no_type_check__ = True 2473 # Nested types: 2474 if isinstance(obj, type): 2475 no_type_check(obj) 2476 try: 2477 arg.__no_type_check__ = True 2478 except TypeError: # built-in classes 2479 pass 2480 return arg
Decorator to indicate that annotations are not type hints.
The argument must be a class or function; if it is a class, it applies recursively to all methods and classes defined in that class (but not to methods defined in its superclasses or subclasses).
This mutates the function(s) or class(es) in place.
def
no_type_check_decorator(decorator):
2483def no_type_check_decorator(decorator): 2484 """Decorator to give another decorator the @no_type_check effect. 2485 2486 This wraps the decorator with something that wraps the decorated 2487 function in @no_type_check. 2488 """ 2489 @functools.wraps(decorator) 2490 def wrapped_decorator(*args, **kwds): 2491 func = decorator(*args, **kwds) 2492 func = no_type_check(func) 2493 return func 2494 2495 return wrapped_decorator
Decorator to give another decorator the @no_type_check effect.
This wraps the decorator with something that wraps the decorated function in @no_type_check.
NoReturn =
NoReturn
Special type indicating functions that never return.
Example::
from typing import NoReturn
def stop() -> NoReturn:
raise Exception('no way')
NoReturn can also be used as a bottom type, a type that has no values. Starting in Python 3.11, the Never type should be used for this concept instead. Type checkers should treat the two equivalently.
NotRequired =
NotRequired
Special typing construct to mark a TypedDict key as potentially missing.
For example::
class Movie(TypedDict):
title: str
year: NotRequired[int]
m = Movie(
title='The Matrix', # typechecker error if key is omitted
year=1999,
)
def
overload(func):
2511def overload(func): 2512 """Decorator for overloaded functions/methods. 2513 2514 In a stub file, place two or more stub definitions for the same 2515 function in a row, each decorated with @overload. 2516 2517 For example:: 2518 2519 @overload 2520 def utf8(value: None) -> None: ... 2521 @overload 2522 def utf8(value: bytes) -> bytes: ... 2523 @overload 2524 def utf8(value: str) -> bytes: ... 2525 2526 In a non-stub file (i.e. a regular .py file), do the same but 2527 follow it with an implementation. The implementation should *not* 2528 be decorated with @overload:: 2529 2530 @overload 2531 def utf8(value: None) -> None: ... 2532 @overload 2533 def utf8(value: bytes) -> bytes: ... 2534 @overload 2535 def utf8(value: str) -> bytes: ... 2536 def utf8(value): 2537 ... # implementation goes here 2538 2539 The overloads for a function can be retrieved at runtime using the 2540 get_overloads() function. 2541 """ 2542 # classmethod and staticmethod 2543 f = getattr(func, "__func__", func) 2544 try: 2545 _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func 2546 except AttributeError: 2547 # Not a normal function; ignore. 2548 pass 2549 return _overload_dummy
Decorator for overloaded functions/methods.
In a stub file, place two or more stub definitions for the same function in a row, each decorated with @overload.
For example::
@overload
def utf8(value: None) -> None: ...
@overload
def utf8(value: bytes) -> bytes: ...
@overload
def utf8(value: str) -> bytes: ...
In a non-stub file (i.e. a regular .py file), do the same but follow it with an implementation. The implementation should not be decorated with @overload::
@overload
def utf8(value: None) -> None: ...
@overload
def utf8(value: bytes) -> bytes: ...
@overload
def utf8(value: str) -> bytes: ...
def utf8(value):
... # implementation goes here
The overloads for a function can be retrieved at runtime using the get_overloads() function.
def
override(method: F, /) -> F:
3463def override[F: _Func](method: F, /) -> F: 3464 """Indicate that a method is intended to override a method in a base class. 3465 3466 Usage:: 3467 3468 class Base: 3469 def method(self) -> None: 3470 pass 3471 3472 class Child(Base): 3473 @override 3474 def method(self) -> None: 3475 super().method() 3476 3477 When this decorator is applied to a method, the type checker will 3478 validate that it overrides a method or attribute with the same name on a 3479 base class. This helps prevent bugs that may occur when a base class is 3480 changed without an equivalent change to a child class. 3481 3482 There is no runtime checking of this property. The decorator attempts to 3483 set the ``__override__`` attribute to ``True`` on the decorated object to 3484 allow runtime introspection. 3485 3486 See PEP 698 for details. 3487 """ 3488 try: 3489 method.__override__ = True 3490 except (AttributeError, TypeError): 3491 # Skip the attribute silently if it is not writable. 3492 # AttributeError happens if the object has __slots__ or a 3493 # read-only property, TypeError if it's a builtin class. 3494 pass 3495 return method
Indicate that a method is intended to override a method in a base class.
Usage::
class Base:
def method(self) -> None:
pass
class Child(Base):
@override
def method(self) -> None:
super().method()
When this decorator is applied to a method, the type checker will validate that it overrides a method or attribute with the same name on a base class. This helps prevent bugs that may occur when a base class is changed without an equivalent change to a child class.
There is no runtime checking of this property. The decorator attempts to
set the __override__ attribute to True on the decorated object to
allow runtime introspection.
See PEP 698 for details.
class
ParamSpecArgs:
The args for a ParamSpec object.
Given a ParamSpec object P, P.args is an instance of ParamSpecArgs.
ParamSpecArgs objects have a reference back to their ParamSpec::
>>> P = ParamSpec("P")
>>> P.args.__origin__ is P
True
This type is meant for runtime introspection and has no special meaning to static type checkers.
class
ParamSpecKwargs:
The kwargs for a ParamSpec object.
Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs.
ParamSpecKwargs objects have a reference back to their ParamSpec::
>>> P = ParamSpec("P")
>>> P.kwargs.__origin__ is P
True
This type is meant for runtime introspection and has no special meaning to static type checkers.
Required =
Required
Special typing construct to mark a TypedDict key as required.
This is mainly useful for total=False TypedDicts.
For example::
class Movie(TypedDict, total=False):
title: Required[str]
year: int
m = Movie(
title='The Matrix', # typechecker error if key is omitted
year=1999,
)
There is no runtime checking that a required key is actually provided when instantiating a related TypedDict.
def
reveal_type(obj: T, /) -> T:
3352def reveal_type[T](obj: T, /) -> T: 3353 """Ask a static type checker to reveal the inferred type of an expression. 3354 3355 When a static type checker encounters a call to ``reveal_type()``, 3356 it will emit the inferred type of the argument:: 3357 3358 x: int = 1 3359 reveal_type(x) 3360 3361 Running a static type checker (e.g., mypy) on this example 3362 will produce output similar to 'Revealed type is "builtins.int"'. 3363 3364 At runtime, the function prints the runtime type of the 3365 argument and returns the argument unchanged. 3366 """ 3367 print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr) 3368 return obj
Ask a static type checker to reveal the inferred type of an expression.
When a static type checker encounters a call to reveal_type(),
it will emit the inferred type of the argument::
x: int = 1
reveal_type(x)
Running a static type checker (e.g., mypy) on this example will produce output similar to 'Revealed type is "builtins.int"'.
At runtime, the function prints the runtime type of the argument and returns the argument unchanged.
def
runtime_checkable(cls):
2146def runtime_checkable(cls): 2147 """Mark a protocol class as a runtime protocol. 2148 2149 Such protocol can be used with isinstance() and issubclass(). 2150 Raise TypeError if applied to a non-protocol class. 2151 This allows a simple-minded structural check very similar to 2152 one trick ponies in collections.abc such as Iterable. 2153 2154 For example:: 2155 2156 @runtime_checkable 2157 class Closable(Protocol): 2158 def close(self): ... 2159 2160 assert isinstance(open('/some/file'), Closable) 2161 2162 Warning: this will check only the presence of the required methods, 2163 not their type signatures! 2164 """ 2165 if not issubclass(cls, Generic) or not getattr(cls, '_is_protocol', False): 2166 raise TypeError('@runtime_checkable can be only applied to protocol classes,' 2167 ' got %r' % cls) 2168 cls._is_runtime_protocol = True 2169 # PEP 544 prohibits using issubclass() 2170 # with protocols that have non-method members. 2171 # See gh-113320 for why we compute this attribute here, 2172 # rather than in `_ProtocolMeta.__init__` 2173 cls.__non_callable_proto_members__ = set() 2174 for attr in cls.__protocol_attrs__: 2175 try: 2176 is_callable = callable(getattr(cls, attr, None)) 2177 except Exception as e: 2178 raise TypeError( 2179 f"Failed to determine whether protocol member {attr!r} " 2180 "is a method member" 2181 ) from e 2182 else: 2183 if not is_callable: 2184 cls.__non_callable_proto_members__.add(attr) 2185 return cls
Mark a protocol class as a runtime protocol.
Such protocol can be used with isinstance() and issubclass(). Raise TypeError if applied to a non-protocol class. This allows a simple-minded structural check very similar to one trick ponies in collections.abc such as Iterable.
For example::
@runtime_checkable
class Closable(Protocol):
def close(self): ...
assert isinstance(open('/some/file'), Closable)
Warning: this will check only the presence of the required methods, not their type signatures!
Self =
Self
Used to spell the type of "self" in classes.
Example::
from typing import Self
class Foo:
def return_self(self) -> Self:
...
return self
This is especially useful for:
- classmethods that are used as alternative constructors
- annotating an
__enter__method which returns self
Text =
<class 'str'>
TYPE_CHECKING =
False
TypeAlias =
TypeAlias
Special form for marking type aliases.
Use TypeAlias to indicate that an assignment should be recognized as a proper type alias definition by type checkers.
For example::
Predicate: TypeAlias = Callable[..., bool]
It's invalid when used anywhere except as in the example above.
TypeGuard =
TypeGuard
Special typing construct for marking user-defined type guard functions.
TypeGuard can be used to annotate the return type of a user-defined
type guard function. TypeGuard only accepts a single type argument.
At runtime, functions marked this way should return a boolean.
TypeGuard aims to benefit type narrowing -- a technique used by static
type checkers to determine a more precise type of an expression within a
program's code flow. Usually type narrowing is done by analyzing
conditional code flow and applying the narrowing to a block of code. The
conditional expression here is sometimes referred to as a "type guard".
Sometimes it would be convenient to use a user-defined boolean function
as a type guard. Such a function should use TypeGuard[...] as its
return type to alert static type checkers to this intention.
Using -> TypeGuard tells the static type checker that for a given
function:
- The return value is a boolean.
- If the return value is
True, the type of its argument is the type insideTypeGuard.
For example::
def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
'''Determines whether all objects in the list are strings'''
return all(isinstance(x, str) for x in val)
def func1(val: list[object]):
if is_str_list(val):
# Type of ``val`` is narrowed to ``list[str]``.
print(" ".join(val))
else:
# Type of ``val`` remains as ``list[object]``.
print("Not a list of strings!")
Strict type narrowing is not enforced -- TypeB need not be a narrower
form of TypeA (it can even be a wider form) and this may lead to
type-unsafe results. The main reason is to allow for things like
narrowing list[object] to list[str] even though the latter is not
a subtype of the former, since list is invariant. The responsibility of
writing type-safe type guards is left to the user.
TypeGuard also works with type variables. For more information, see
PEP 647 (User-Defined Type Guards).
class
TypeAliasType:
Type alias.
Type aliases are created through the type statement::
type Alias = int
In this example, Alias and int will be treated equivalently by static type checkers.
At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.
Type aliases can also be generic::
type ListOrSet[T] = list[T] | set[T]
In this case, the type parameters of the alias are stored in the __type_params__ attribute.
See PEP 695 for more information.
Unpack =
Unpack
Type unpack operator.
The type unpack operator takes the child types from some container type,
such as tuple[int, str] or a TypeVarTuple, and 'pulls them out'.
For example::
# For some generic class `Foo`:
Foo[Unpack[tuple[int, str]]] # Equivalent to Foo[int, str]
Ts = TypeVarTuple('Ts')
# Specifies that `Bar` is generic in an arbitrary number of types.
# (Think of `Ts` as a tuple of an arbitrary number of individual
# `TypeVar`s, which the `Unpack` is 'pulling out' directly into the
# `Generic[]`.)
class Bar(Generic[Unpack[Ts]]): ...
Bar[int] # Valid
Bar[int, str] # Also valid
From Python 3.11, this can also be done using the * operator::
Foo[*tuple[int, str]]
class Bar(Generic[*Ts]): ...
And from Python 3.12, it can be done using built-in syntax for generics::
Foo[*tuple[int, str]]
class Bar[*Ts]: ...
The operator can also be used along with a TypedDict to annotate
**kwargs in a function signature::
class Movie(TypedDict):
name: str
year: int
# This function expects two keyword arguments - *name* of type `str` and
# *year* of type `int`.
def foo(**kwargs: Unpack[Movie]): ...
Note that there is only some runtime checking of this operator. Not everything the runtime allows may be accepted by static type checkers.
For more information, see PEPs 646 and 692.