1""" 2The typing module: Support for gradual typing as defined by PEP 484. 3 4At large scale, the structure of the module is following: 5* Imports and exports, all public names should be explicitly added to __all__. 6* Internal helper functions: these should never be used in code outside this module. 7* _SpecialForm and its instances (special forms): 8 Any, NoReturn, ClassVar, Union, Optional, Concatenate 9* Classes whose instances can be type arguments in addition to types: 10 ForwardRef, TypeVar and ParamSpec 11* The core of internal generics API: _GenericAlias and _VariadicGenericAlias, the latter is 12 currently only used by Tuple and Callable. All subscripted types like X[int], Union[int, str], 13 etc., are instances of either of these classes. 14* The public counterpart of the generics API consists of two classes: Generic and Protocol. 15* Public helper functions: get_type_hints, overload, cast, no_type_check, 16 no_type_check_decorator. 17* Generic aliases for collections.abc ABCs and few additional protocols. 18* Special types: NewType, NamedTuple, TypedDict. 19* Wrapper submodules for re and io related types. 20""" 21 22from abc import abstractmethod, ABCMeta 23import collections 24import collections.abc 25import contextlib 26import functools 27import operator 28import re as stdlib_re # Avoid confusion with the re we export. 29import sys 30import types 31from types import WrapperDescriptorType, MethodWrapperType, MethodDescriptorType, GenericAlias 32 33# Please keep __all__ alphabetized within each category. 34__all__ = [ 35 # Super-special typing primitives. 36 'Annotated', 37 'Any', 38 'Callable', 39 'ClassVar', 40 'Concatenate', 41 'Final', 42 'ForwardRef', 43 'Generic', 44 'Literal', 45 'Optional', 46 'ParamSpec', 47 'Protocol', 48 'Tuple', 49 'Type', 50 'TypeVar', 51 'Union', 52 53 # ABCs (from collections.abc). 54 'AbstractSet', # collections.abc.Set. 55 'ByteString', 56 'Container', 57 'ContextManager', 58 'Hashable', 59 'ItemsView', 60 'Iterable', 61 'Iterator', 62 'KeysView', 63 'Mapping', 64 'MappingView', 65 'MutableMapping', 66 'MutableSequence', 67 'MutableSet', 68 'Sequence', 69 'Sized', 70 'ValuesView', 71 'Awaitable', 72 'AsyncIterator', 73 'AsyncIterable', 74 'Coroutine', 75 'Collection', 76 'AsyncGenerator', 77 'AsyncContextManager', 78 79 # Structural checks, a.k.a. protocols. 80 'Reversible', 81 'SupportsAbs', 82 'SupportsBytes', 83 'SupportsComplex', 84 'SupportsFloat', 85 'SupportsIndex', 86 'SupportsInt', 87 'SupportsRound', 88 89 # Concrete collection types. 90 'ChainMap', 91 'Counter', 92 'Deque', 93 'Dict', 94 'DefaultDict', 95 'List', 96 'OrderedDict', 97 'Set', 98 'FrozenSet', 99 'NamedTuple', # Not really a type. 100 'TypedDict', # Not really a type. 101 'Generator', 102 103 # Other concrete types. 104 'BinaryIO', 105 'IO', 106 'Match', 107 'Pattern', 108 'TextIO', 109 110 # One-off things. 111 'AnyStr', 112 'cast', 113 'final', 114 'get_args', 115 'get_origin', 116 'get_type_hints', 117 'is_typeddict', 118 'NewType', 119 'no_type_check', 120 'no_type_check_decorator', 121 'NoReturn', 122 'overload', 123 'ParamSpecArgs', 124 'ParamSpecKwargs', 125 'runtime_checkable', 126 'Text', 127 'TYPE_CHECKING', 128 'TypeAlias', 129 'TypeGuard', 130] 131 132# The pseudo-submodules 're' and 'io' are part of the public 133# namespace, but excluded from __all__ because they might stomp on 134# legitimate imports of those modules. 135 136 137def _type_convert(arg, module=None): 138 """For converting None to type(None), and strings to ForwardRef.""" 139 if arg is None: 140 return type(None) 141 if isinstance(arg, str): 142 return ForwardRef(arg, module=module) 143 return arg 144 145 146def _type_check(arg, msg, is_argument=True, module=None, *, is_class=False): 147 """Check that the argument is a type, and return it (internal helper). 148 149 As a special case, accept None and return type(None) instead. Also wrap strings 150 into ForwardRef instances. Consider several corner cases, for example plain 151 special forms like Union are not valid, while Union[int, str] is OK, etc. 152 The msg argument is a human-readable error message, e.g:: 153 154 "Union[arg, ...]: arg should be a type." 155 156 We append the repr() of the actual value (truncated to 100 chars). 157 """ 158 invalid_generic_forms = (Generic, Protocol) 159 if not is_class: 160 invalid_generic_forms += (ClassVar,) 161 if is_argument: 162 invalid_generic_forms += (Final,) 163 164 arg = _type_convert(arg, module=module) 165 if (isinstance(arg, _GenericAlias) and 166 arg.__origin__ in invalid_generic_forms): 167 raise TypeError(f"{arg} is not valid as type argument") 168 if arg in (Any, NoReturn, Final): 169 return arg 170 if isinstance(arg, _SpecialForm) or arg in (Generic, Protocol): 171 raise TypeError(f"Plain {arg} is not valid as type argument") 172 if isinstance(arg, (type, TypeVar, ForwardRef, types.UnionType, ParamSpec)): 173 return arg 174 if not callable(arg): 175 raise TypeError(f"{msg} Got {arg!r:.100}.") 176 return arg 177 178 179def _is_param_expr(arg): 180 return arg is ... or isinstance(arg, 181 (tuple, list, ParamSpec, _ConcatenateGenericAlias)) 182 183 184def _type_repr(obj): 185 """Return the repr() of an object, special-casing types (internal helper). 186 187 If obj is a type, we return a shorter version than the default 188 type.__repr__, based on the module and qualified name, which is 189 typically enough to uniquely identify a type. For everything 190 else, we fall back on repr(obj). 191 """ 192 if isinstance(obj, types.GenericAlias): 193 return repr(obj) 194 if isinstance(obj, type): 195 if obj.__module__ == 'builtins': 196 return obj.__qualname__ 197 return f'{obj.__module__}.{obj.__qualname__}' 198 if obj is ...: 199 return('...') 200 if isinstance(obj, types.FunctionType): 201 return obj.__name__ 202 return repr(obj) 203 204 205def _collect_type_vars(types_, typevar_types=None): 206 """Collect all type variable contained 207 in types in order of first appearance (lexicographic order). For example:: 208 209 _collect_type_vars((T, List[S, T])) == (T, S) 210 """ 211 if typevar_types is None: 212 typevar_types = TypeVar 213 tvars = [] 214 for t in types_: 215 if isinstance(t, typevar_types) and t not in tvars: 216 tvars.append(t) 217 if isinstance(t, (_GenericAlias, GenericAlias, types.UnionType)): 218 tvars.extend([t for t in t.__parameters__ if t not in tvars]) 219 return tuple(tvars) 220 221 222def _check_generic(cls, parameters, elen): 223 """Check correct count for parameters of a generic cls (internal helper). 224 This gives a nice error message in case of count mismatch. 225 """ 226 if not elen: 227 raise TypeError(f"{cls} is not a generic class") 228 alen = len(parameters) 229 if alen != elen: 230 raise TypeError(f"Too {'many' if alen > elen else 'few'} arguments for {cls};" 231 f" actual {alen}, expected {elen}") 232 233def _prepare_paramspec_params(cls, params): 234 """Prepares the parameters for a Generic containing ParamSpec 235 variables (internal helper). 236 """ 237 # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612. 238 if (len(cls.__parameters__) == 1 239 and params and not _is_param_expr(params[0])): 240 assert isinstance(cls.__parameters__[0], ParamSpec) 241 return (params,) 242 else: 243 _check_generic(cls, params, len(cls.__parameters__)) 244 _params = [] 245 # Convert lists to tuples to help other libraries cache the results. 246 for p, tvar in zip(params, cls.__parameters__): 247 if isinstance(tvar, ParamSpec) and isinstance(p, list): 248 p = tuple(p) 249 _params.append(p) 250 return tuple(_params) 251 252def _deduplicate(params): 253 # Weed out strict duplicates, preserving the first of each occurrence. 254 all_params = set(params) 255 if len(all_params) < len(params): 256 new_params = [] 257 for t in params: 258 if t in all_params: 259 new_params.append(t) 260 all_params.remove(t) 261 params = new_params 262 assert not all_params, all_params 263 return params 264 265 266def _remove_dups_flatten(parameters): 267 """An internal helper for Union creation and substitution: flatten Unions 268 among parameters, then remove duplicates. 269 """ 270 # Flatten out Union[Union[...], ...]. 271 params = [] 272 for p in parameters: 273 if isinstance(p, (_UnionGenericAlias, types.UnionType)): 274 params.extend(p.__args__) 275 elif isinstance(p, tuple) and len(p) > 0 and p[0] is Union: 276 params.extend(p[1:]) 277 else: 278 params.append(p) 279 280 return tuple(_deduplicate(params)) 281 282 283def _flatten_literal_params(parameters): 284 """An internal helper for Literal creation: flatten Literals among parameters""" 285 params = [] 286 for p in parameters: 287 if isinstance(p, _LiteralGenericAlias): 288 params.extend(p.__args__) 289 else: 290 params.append(p) 291 return tuple(params) 292 293 294_cleanups = [] 295 296 297def _tp_cache(func=None, /, *, typed=False): 298 """Internal wrapper caching __getitem__ of generic types with a fallback to 299 original function for non-hashable arguments. 300 """ 301 def decorator(func): 302 cached = functools.lru_cache(typed=typed)(func) 303 _cleanups.append(cached.cache_clear) 304 305 @functools.wraps(func) 306 def inner(*args, **kwds): 307 try: 308 return cached(*args, **kwds) 309 except TypeError: 310 pass # All real errors (not unhashable args) are raised below. 311 return func(*args, **kwds) 312 return inner 313 314 if func is not None: 315 return decorator(func) 316 317 return decorator 318 319def _eval_type(t, globalns, localns, recursive_guard=frozenset()): 320 """Evaluate all forward references in the given type t. 321 For use of globalns and localns see the docstring for get_type_hints(). 322 recursive_guard is used to prevent prevent infinite recursion 323 with recursive ForwardRef. 324 """ 325 if isinstance(t, ForwardRef): 326 return t._evaluate(globalns, localns, recursive_guard) 327 if isinstance(t, (_GenericAlias, GenericAlias, types.UnionType)): 328 ev_args = tuple(_eval_type(a, globalns, localns, recursive_guard) for a in t.__args__) 329 if ev_args == t.__args__: 330 return t 331 if isinstance(t, GenericAlias): 332 return GenericAlias(t.__origin__, ev_args) 333 if isinstance(t, types.UnionType): 334 return functools.reduce(operator.or_, ev_args) 335 else: 336 return t.copy_with(ev_args) 337 return t 338 339 340class _Final: 341 """Mixin to prohibit subclassing""" 342 343 __slots__ = ('__weakref__',) 344 345 def __init_subclass__(self, /, *args, **kwds): 346 if '_root' not in kwds: 347 raise TypeError("Cannot subclass special typing classes") 348 349class _Immutable: 350 """Mixin to indicate that object should not be copied.""" 351 __slots__ = () 352 353 def __copy__(self): 354 return self 355 356 def __deepcopy__(self, memo): 357 return self 358 359 360# Internal indicator of special typing constructs. 361# See __doc__ instance attribute for specific docs. 362class _SpecialForm(_Final, _root=True): 363 __slots__ = ('_name', '__doc__', '_getitem') 364 365 def __init__(self, getitem): 366 self._getitem = getitem 367 self._name = getitem.__name__ 368 self.__doc__ = getitem.__doc__ 369 370 def __getattr__(self, item): 371 if item in {'__name__', '__qualname__'}: 372 return self._name 373 374 raise AttributeError(item) 375 376 def __mro_entries__(self, bases): 377 raise TypeError(f"Cannot subclass {self!r}") 378 379 def __repr__(self): 380 return 'typing.' + self._name 381 382 def __reduce__(self): 383 return self._name 384 385 def __call__(self, *args, **kwds): 386 raise TypeError(f"Cannot instantiate {self!r}") 387 388 def __or__(self, other): 389 return Union[self, other] 390 391 def __ror__(self, other): 392 return Union[other, self] 393 394 def __instancecheck__(self, obj): 395 raise TypeError(f"{self} cannot be used with isinstance()") 396 397 def __subclasscheck__(self, cls): 398 raise TypeError(f"{self} cannot be used with issubclass()") 399 400 @_tp_cache 401 def __getitem__(self, parameters): 402 return self._getitem(self, parameters) 403 404 405class _LiteralSpecialForm(_SpecialForm, _root=True): 406 def __getitem__(self, parameters): 407 if not isinstance(parameters, tuple): 408 parameters = (parameters,) 409 return self._getitem(self, *parameters) 410 411 412@_SpecialForm 413def Any(self, parameters): 414 """Special type indicating an unconstrained type. 415 416 - Any is compatible with every type. 417 - Any assumed to have all methods. 418 - All values assumed to be instances of Any. 419 420 Note that all the above statements are true from the point of view of 421 static type checkers. At runtime, Any should not be used with instance 422 or class checks. 423 """ 424 raise TypeError(f"{self} is not subscriptable") 425 426@_SpecialForm 427def NoReturn(self, parameters): 428 """Special type indicating functions that never return. 429 Example:: 430 431 from typing import NoReturn 432 433 def stop() -> NoReturn: 434 raise Exception('no way') 435 436 This type is invalid in other positions, e.g., ``List[NoReturn]`` 437 will fail in static type checkers. 438 """ 439 raise TypeError(f"{self} is not subscriptable") 440 441@_SpecialForm 442def ClassVar(self, parameters): 443 """Special type construct to mark class variables. 444 445 An annotation wrapped in ClassVar indicates that a given 446 attribute is intended to be used as a class variable and 447 should not be set on instances of that class. Usage:: 448 449 class Starship: 450 stats: ClassVar[Dict[str, int]] = {} # class variable 451 damage: int = 10 # instance variable 452 453 ClassVar accepts only types and cannot be further subscribed. 454 455 Note that ClassVar is not a class itself, and should not 456 be used with isinstance() or issubclass(). 457 """ 458 item = _type_check(parameters, f'{self} accepts only single type.') 459 return _GenericAlias(self, (item,)) 460 461@_SpecialForm 462def Final(self, parameters): 463 """Special typing construct to indicate final names to type checkers. 464 465 A final name cannot be re-assigned or overridden in a subclass. 466 For example: 467 468 MAX_SIZE: Final = 9000 469 MAX_SIZE += 1 # Error reported by type checker 470 471 class Connection: 472 TIMEOUT: Final[int] = 10 473 474 class FastConnector(Connection): 475 TIMEOUT = 1 # Error reported by type checker 476 477 There is no runtime checking of these properties. 478 """ 479 item = _type_check(parameters, f'{self} accepts only single type.') 480 return _GenericAlias(self, (item,)) 481 482@_SpecialForm 483def Union(self, parameters): 484 """Union type; Union[X, Y] means either X or Y. 485 486 To define a union, use e.g. Union[int, str]. Details: 487 - The arguments must be types and there must be at least one. 488 - None as an argument is a special case and is replaced by 489 type(None). 490 - Unions of unions are flattened, e.g.:: 491 492 Union[Union[int, str], float] == Union[int, str, float] 493 494 - Unions of a single argument vanish, e.g.:: 495 496 Union[int] == int # The constructor actually returns int 497 498 - Redundant arguments are skipped, e.g.:: 499 500 Union[int, str, int] == Union[int, str] 501 502 - When comparing unions, the argument order is ignored, e.g.:: 503 504 Union[int, str] == Union[str, int] 505 506 - You cannot subclass or instantiate a union. 507 - You can use Optional[X] as a shorthand for Union[X, None]. 508 """ 509 if parameters == (): 510 raise TypeError("Cannot take a Union of no types.") 511 if not isinstance(parameters, tuple): 512 parameters = (parameters,) 513 msg = "Union[arg, ...]: each arg must be a type." 514 parameters = tuple(_type_check(p, msg) for p in parameters) 515 parameters = _remove_dups_flatten(parameters) 516 if len(parameters) == 1: 517 return parameters[0] 518 if len(parameters) == 2 and type(None) in parameters: 519 return _UnionGenericAlias(self, parameters, name="Optional") 520 return _UnionGenericAlias(self, parameters) 521 522@_SpecialForm 523def Optional(self, parameters): 524 """Optional type. 525 526 Optional[X] is equivalent to Union[X, None]. 527 """ 528 arg = _type_check(parameters, f"{self} requires a single type.") 529 return Union[arg, type(None)] 530 531@_LiteralSpecialForm 532@_tp_cache(typed=True) 533def Literal(self, *parameters): 534 """Special typing form to define literal types (a.k.a. value types). 535 536 This form can be used to indicate to type checkers that the corresponding 537 variable or function parameter has a value equivalent to the provided 538 literal (or one of several literals): 539 540 def validate_simple(data: Any) -> Literal[True]: # always returns True 541 ... 542 543 MODE = Literal['r', 'rb', 'w', 'wb'] 544 def open_helper(file: str, mode: MODE) -> str: 545 ... 546 547 open_helper('/some/path', 'r') # Passes type check 548 open_helper('/other/path', 'typo') # Error in type checker 549 550 Literal[...] cannot be subclassed. At runtime, an arbitrary value 551 is allowed as type argument to Literal[...], but type checkers may 552 impose restrictions. 553 """ 554 # There is no '_type_check' call because arguments to Literal[...] are 555 # values, not types. 556 parameters = _flatten_literal_params(parameters) 557 558 try: 559 parameters = tuple(p for p, _ in _deduplicate(list(_value_and_type_iter(parameters)))) 560 except TypeError: # unhashable parameters 561 pass 562 563 return _LiteralGenericAlias(self, parameters) 564 565 566@_SpecialForm 567def TypeAlias(self, parameters): 568 """Special marker indicating that an assignment should 569 be recognized as a proper type alias definition by type 570 checkers. 571 572 For example:: 573 574 Predicate: TypeAlias = Callable[..., bool] 575 576 It's invalid when used anywhere except as in the example above. 577 """ 578 raise TypeError(f"{self} is not subscriptable") 579 580 581@_SpecialForm 582def Concatenate(self, parameters): 583 """Used in conjunction with ``ParamSpec`` and ``Callable`` to represent a 584 higher order function which adds, removes or transforms parameters of a 585 callable. 586 587 For example:: 588 589 Callable[Concatenate[int, P], int] 590 591 See PEP 612 for detailed information. 592 """ 593 if parameters == (): 594 raise TypeError("Cannot take a Concatenate of no types.") 595 if not isinstance(parameters, tuple): 596 parameters = (parameters,) 597 if not isinstance(parameters[-1], ParamSpec): 598 raise TypeError("The last parameter to Concatenate should be a " 599 "ParamSpec variable.") 600 msg = "Concatenate[arg, ...]: each arg must be a type." 601 parameters = tuple(_type_check(p, msg) for p in parameters) 602 return _ConcatenateGenericAlias(self, parameters) 603 604 605@_SpecialForm 606def TypeGuard(self, parameters): 607 """Special typing form used to annotate the return type of a user-defined 608 type guard function. ``TypeGuard`` only accepts a single type argument. 609 At runtime, functions marked this way should return a boolean. 610 611 ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static 612 type checkers to determine a more precise type of an expression within a 613 program's code flow. Usually type narrowing is done by analyzing 614 conditional code flow and applying the narrowing to a block of code. The 615 conditional expression here is sometimes referred to as a "type guard". 616 617 Sometimes it would be convenient to use a user-defined boolean function 618 as a type guard. Such a function should use ``TypeGuard[...]`` as its 619 return type to alert static type checkers to this intention. 620 621 Using ``-> TypeGuard`` tells the static type checker that for a given 622 function: 623 624 1. The return value is a boolean. 625 2. If the return value is ``True``, the type of its argument 626 is the type inside ``TypeGuard``. 627 628 For example:: 629 630 def is_str(val: Union[str, float]): 631 # "isinstance" type guard 632 if isinstance(val, str): 633 # Type of ``val`` is narrowed to ``str`` 634 ... 635 else: 636 # Else, type of ``val`` is narrowed to ``float``. 637 ... 638 639 Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower 640 form of ``TypeA`` (it can even be a wider form) and this may lead to 641 type-unsafe results. The main reason is to allow for things like 642 narrowing ``List[object]`` to ``List[str]`` even though the latter is not 643 a subtype of the former, since ``List`` is invariant. The responsibility of 644 writing type-safe type guards is left to the user. 645 646 ``TypeGuard`` also works with type variables. For more information, see 647 PEP 647 (User-Defined Type Guards). 648 """ 649 item = _type_check(parameters, f'{self} accepts only single type.') 650 return _GenericAlias(self, (item,)) 651 652 653class ForwardRef(_Final, _root=True): 654 """Internal wrapper to hold a forward reference.""" 655 656 __slots__ = ('__forward_arg__', '__forward_code__', 657 '__forward_evaluated__', '__forward_value__', 658 '__forward_is_argument__', '__forward_is_class__', 659 '__forward_module__') 660 661 def __init__(self, arg, is_argument=True, module=None, *, is_class=False): 662 if not isinstance(arg, str): 663 raise TypeError(f"Forward reference must be a string -- got {arg!r}") 664 try: 665 code = compile(arg, '<string>', 'eval') 666 except SyntaxError: 667 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}") 668 self.__forward_arg__ = arg 669 self.__forward_code__ = code 670 self.__forward_evaluated__ = False 671 self.__forward_value__ = None 672 self.__forward_is_argument__ = is_argument 673 self.__forward_is_class__ = is_class 674 self.__forward_module__ = module 675 676 def _evaluate(self, globalns, localns, recursive_guard): 677 if self.__forward_arg__ in recursive_guard: 678 return self 679 if not self.__forward_evaluated__ or localns is not globalns: 680 if globalns is None and localns is None: 681 globalns = localns = {} 682 elif globalns is None: 683 globalns = localns 684 elif localns is None: 685 localns = globalns 686 if self.__forward_module__ is not None: 687 globalns = getattr( 688 sys.modules.get(self.__forward_module__, None), '__dict__', globalns 689 ) 690 type_ = _type_check( 691 eval(self.__forward_code__, globalns, localns), 692 "Forward references must evaluate to types.", 693 is_argument=self.__forward_is_argument__, 694 is_class=self.__forward_is_class__, 695 ) 696 self.__forward_value__ = _eval_type( 697 type_, globalns, localns, recursive_guard | {self.__forward_arg__} 698 ) 699 self.__forward_evaluated__ = True 700 return self.__forward_value__ 701 702 def __eq__(self, other): 703 if not isinstance(other, ForwardRef): 704 return NotImplemented 705 if self.__forward_evaluated__ and other.__forward_evaluated__: 706 return (self.__forward_arg__ == other.__forward_arg__ and 707 self.__forward_value__ == other.__forward_value__) 708 return self.__forward_arg__ == other.__forward_arg__ 709 710 def __hash__(self): 711 return hash(self.__forward_arg__) 712 713 def __repr__(self): 714 return f'ForwardRef({self.__forward_arg__!r})' 715 716class _TypeVarLike: 717 """Mixin for TypeVar-like types (TypeVar and ParamSpec).""" 718 def __init__(self, bound, covariant, contravariant): 719 """Used to setup TypeVars and ParamSpec's bound, covariant and 720 contravariant attributes. 721 """ 722 if covariant and contravariant: 723 raise ValueError("Bivariant types are not supported.") 724 self.__covariant__ = bool(covariant) 725 self.__contravariant__ = bool(contravariant) 726 if bound: 727 self.__bound__ = _type_check(bound, "Bound must be a type.") 728 else: 729 self.__bound__ = None 730 731 def __or__(self, right): 732 return Union[self, right] 733 734 def __ror__(self, left): 735 return Union[left, self] 736 737 def __repr__(self): 738 if self.__covariant__: 739 prefix = '+' 740 elif self.__contravariant__: 741 prefix = '-' 742 else: 743 prefix = '~' 744 return prefix + self.__name__ 745 746 def __reduce__(self): 747 return self.__name__ 748 749 750class TypeVar( _Final, _Immutable, _TypeVarLike, _root=True): 751 """Type variable. 752 753 Usage:: 754 755 T = TypeVar('T') # Can be anything 756 A = TypeVar('A', str, bytes) # Must be str or bytes 757 758 Type variables exist primarily for the benefit of static type 759 checkers. They serve as the parameters for generic types as well 760 as for generic function definitions. See class Generic for more 761 information on generic types. Generic functions work as follows: 762 763 def repeat(x: T, n: int) -> List[T]: 764 '''Return a list containing n references to x.''' 765 return [x]*n 766 767 def longest(x: A, y: A) -> A: 768 '''Return the longest of two strings.''' 769 return x if len(x) >= len(y) else y 770 771 The latter example's signature is essentially the overloading 772 of (str, str) -> str and (bytes, bytes) -> bytes. Also note 773 that if the arguments are instances of some subclass of str, 774 the return type is still plain str. 775 776 At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError. 777 778 Type variables defined with covariant=True or contravariant=True 779 can be used to declare covariant or contravariant generic types. 780 See PEP 484 for more details. By default generic types are invariant 781 in all type variables. 782 783 Type variables can be introspected. e.g.: 784 785 T.__name__ == 'T' 786 T.__constraints__ == () 787 T.__covariant__ == False 788 T.__contravariant__ = False 789 A.__constraints__ == (str, bytes) 790 791 Note that only type variables defined in global scope can be pickled. 792 """ 793 794 __slots__ = ('__name__', '__bound__', '__constraints__', 795 '__covariant__', '__contravariant__', '__dict__') 796 797 def __init__(self, name, *constraints, bound=None, 798 covariant=False, contravariant=False): 799 self.__name__ = name 800 super().__init__(bound, covariant, contravariant) 801 if constraints and bound is not None: 802 raise TypeError("Constraints cannot be combined with bound=...") 803 if constraints and len(constraints) == 1: 804 raise TypeError("A single constraint is not allowed") 805 msg = "TypeVar(name, constraint, ...): constraints must be types." 806 self.__constraints__ = tuple(_type_check(t, msg) for t in constraints) 807 try: 808 def_mod = sys._getframe(1).f_globals.get('__name__', '__main__') # for pickling 809 except (AttributeError, ValueError): 810 def_mod = None 811 if def_mod != 'typing': 812 self.__module__ = def_mod 813 814 815class ParamSpecArgs(_Final, _Immutable, _root=True): 816 """The args for a ParamSpec object. 817 818 Given a ParamSpec object P, P.args is an instance of ParamSpecArgs. 819 820 ParamSpecArgs objects have a reference back to their ParamSpec: 821 822 P.args.__origin__ is P 823 824 This type is meant for runtime introspection and has no special meaning to 825 static type checkers. 826 """ 827 def __init__(self, origin): 828 self.__origin__ = origin 829 830 def __repr__(self): 831 return f"{self.__origin__.__name__}.args" 832 833 834class ParamSpecKwargs(_Final, _Immutable, _root=True): 835 """The kwargs for a ParamSpec object. 836 837 Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs. 838 839 ParamSpecKwargs objects have a reference back to their ParamSpec: 840 841 P.kwargs.__origin__ is P 842 843 This type is meant for runtime introspection and has no special meaning to 844 static type checkers. 845 """ 846 def __init__(self, origin): 847 self.__origin__ = origin 848 849 def __repr__(self): 850 return f"{self.__origin__.__name__}.kwargs" 851 852 853class ParamSpec(_Final, _Immutable, _TypeVarLike, _root=True): 854 """Parameter specification variable. 855 856 Usage:: 857 858 P = ParamSpec('P') 859 860 Parameter specification variables exist primarily for the benefit of static 861 type checkers. They are used to forward the parameter types of one 862 callable to another callable, a pattern commonly found in higher order 863 functions and decorators. They are only valid when used in ``Concatenate``, 864 or s the first argument to ``Callable``, or as parameters for user-defined 865 Generics. See class Generic for more information on generic types. An 866 example for annotating a decorator:: 867 868 T = TypeVar('T') 869 P = ParamSpec('P') 870 871 def add_logging(f: Callable[P, T]) -> Callable[P, T]: 872 '''A type-safe decorator to add logging to a function.''' 873 def inner(*args: P.args, **kwargs: P.kwargs) -> T: 874 logging.info(f'{f.__name__} was called') 875 return f(*args, **kwargs) 876 return inner 877 878 @add_logging 879 def add_two(x: float, y: float) -> float: 880 '''Add two numbers together.''' 881 return x + y 882 883 Parameter specification variables defined with covariant=True or 884 contravariant=True can be used to declare covariant or contravariant 885 generic types. These keyword arguments are valid, but their actual semantics 886 are yet to be decided. See PEP 612 for details. 887 888 Parameter specification variables can be introspected. e.g.: 889 890 P.__name__ == 'T' 891 P.__bound__ == None 892 P.__covariant__ == False 893 P.__contravariant__ == False 894 895 Note that only parameter specification variables defined in global scope can 896 be pickled. 897 """ 898 899 __slots__ = ('__name__', '__bound__', '__covariant__', '__contravariant__', 900 '__dict__') 901 902 @property 903 def args(self): 904 return ParamSpecArgs(self) 905 906 @property 907 def kwargs(self): 908 return ParamSpecKwargs(self) 909 910 def __init__(self, name, *, bound=None, covariant=False, contravariant=False): 911 self.__name__ = name 912 super().__init__(bound, covariant, contravariant) 913 try: 914 def_mod = sys._getframe(1).f_globals.get('__name__', '__main__') 915 except (AttributeError, ValueError): 916 def_mod = None 917 if def_mod != 'typing': 918 self.__module__ = def_mod 919 920 921def _is_dunder(attr): 922 return attr.startswith('__') and attr.endswith('__') 923 924class _BaseGenericAlias(_Final, _root=True): 925 """The central part of internal API. 926 927 This represents a generic version of type 'origin' with type arguments 'params'. 928 There are two kind of these aliases: user defined and special. The special ones 929 are wrappers around builtin collections and ABCs in collections.abc. These must 930 have 'name' always set. If 'inst' is False, then the alias can't be instantiated, 931 this is used by e.g. typing.List and typing.Dict. 932 """ 933 def __init__(self, origin, *, inst=True, name=None): 934 self._inst = inst 935 self._name = name 936 self.__origin__ = origin 937 self.__slots__ = None # This is not documented. 938 939 def __call__(self, *args, **kwargs): 940 if not self._inst: 941 raise TypeError(f"Type {self._name} cannot be instantiated; " 942 f"use {self.__origin__.__name__}() instead") 943 result = self.__origin__(*args, **kwargs) 944 try: 945 result.__orig_class__ = self 946 except AttributeError: 947 pass 948 return result 949 950 def __mro_entries__(self, bases): 951 res = [] 952 if self.__origin__ not in bases: 953 res.append(self.__origin__) 954 i = bases.index(self) 955 for b in bases[i+1:]: 956 if isinstance(b, _BaseGenericAlias) or issubclass(b, Generic): 957 break 958 else: 959 res.append(Generic) 960 return tuple(res) 961 962 def __getattr__(self, attr): 963 if attr in {'__name__', '__qualname__'}: 964 return self._name or self.__origin__.__name__ 965 966 # We are careful for copy and pickle. 967 # Also for simplicity we just don't relay all dunder names 968 if '__origin__' in self.__dict__ and not _is_dunder(attr): 969 return getattr(self.__origin__, attr) 970 raise AttributeError(attr) 971 972 def __setattr__(self, attr, val): 973 if _is_dunder(attr) or attr in {'_name', '_inst', '_nparams', 974 '_typevar_types', '_paramspec_tvars'}: 975 super().__setattr__(attr, val) 976 else: 977 setattr(self.__origin__, attr, val) 978 979 def __instancecheck__(self, obj): 980 return self.__subclasscheck__(type(obj)) 981 982 def __subclasscheck__(self, cls): 983 raise TypeError("Subscripted generics cannot be used with" 984 " class and instance checks") 985 986 987# Special typing constructs Union, Optional, Generic, Callable and Tuple 988# use three special attributes for internal bookkeeping of generic types: 989# * __parameters__ is a tuple of unique free type parameters of a generic 990# type, for example, Dict[T, T].__parameters__ == (T,); 991# * __origin__ keeps a reference to a type that was subscripted, 992# e.g., Union[T, int].__origin__ == Union, or the non-generic version of 993# the type. 994# * __args__ is a tuple of all arguments used in subscripting, 995# e.g., Dict[T, int].__args__ == (T, int). 996 997 998class _GenericAlias(_BaseGenericAlias, _root=True): 999 def __init__(self, origin, params, *, inst=True, name=None, 1000 _typevar_types=TypeVar, 1001 _paramspec_tvars=False): 1002 super().__init__(origin, inst=inst, name=name) 1003 if not isinstance(params, tuple): 1004 params = (params,) 1005 self.__args__ = tuple(... if a is _TypingEllipsis else 1006 () if a is _TypingEmpty else 1007 a for a in params) 1008 self.__parameters__ = _collect_type_vars(params, typevar_types=_typevar_types) 1009 self._typevar_types = _typevar_types 1010 self._paramspec_tvars = _paramspec_tvars 1011 if not name: 1012 self.__module__ = origin.__module__ 1013 1014 def __eq__(self, other): 1015 if not isinstance(other, _GenericAlias): 1016 return NotImplemented 1017 return (self.__origin__ == other.__origin__ 1018 and self.__args__ == other.__args__) 1019 1020 def __hash__(self): 1021 return hash((self.__origin__, self.__args__)) 1022 1023 def __or__(self, right): 1024 return Union[self, right] 1025 1026 def __ror__(self, left): 1027 return Union[left, self] 1028 1029 @_tp_cache 1030 def __getitem__(self, params): 1031 if self.__origin__ in (Generic, Protocol): 1032 # Can't subscript Generic[...] or Protocol[...]. 1033 raise TypeError(f"Cannot subscript already-subscripted {self}") 1034 if not isinstance(params, tuple): 1035 params = (params,) 1036 params = tuple(_type_convert(p) for p in params) 1037 if (self._paramspec_tvars 1038 and any(isinstance(t, ParamSpec) for t in self.__parameters__)): 1039 params = _prepare_paramspec_params(self, params) 1040 else: 1041 _check_generic(self, params, len(self.__parameters__)) 1042 1043 subst = dict(zip(self.__parameters__, params)) 1044 new_args = [] 1045 for arg in self.__args__: 1046 if isinstance(arg, self._typevar_types): 1047 if isinstance(arg, ParamSpec): 1048 arg = subst[arg] 1049 if not _is_param_expr(arg): 1050 raise TypeError(f"Expected a list of types, an ellipsis, " 1051 f"ParamSpec, or Concatenate. Got {arg}") 1052 else: 1053 arg = subst[arg] 1054 elif isinstance(arg, (_GenericAlias, GenericAlias, types.UnionType)): 1055 subparams = arg.__parameters__ 1056 if subparams: 1057 subargs = tuple(subst[x] for x in subparams) 1058 arg = arg[subargs] 1059 # Required to flatten out the args for CallableGenericAlias 1060 if self.__origin__ == collections.abc.Callable and isinstance(arg, tuple): 1061 new_args.extend(arg) 1062 else: 1063 new_args.append(arg) 1064 return self.copy_with(tuple(new_args)) 1065 1066 def copy_with(self, params): 1067 return self.__class__(self.__origin__, params, name=self._name, inst=self._inst) 1068 1069 def __repr__(self): 1070 if self._name: 1071 name = 'typing.' + self._name 1072 else: 1073 name = _type_repr(self.__origin__) 1074 args = ", ".join([_type_repr(a) for a in self.__args__]) 1075 return f'{name}[{args}]' 1076 1077 def __reduce__(self): 1078 if self._name: 1079 origin = globals()[self._name] 1080 else: 1081 origin = self.__origin__ 1082 args = tuple(self.__args__) 1083 if len(args) == 1 and not isinstance(args[0], tuple): 1084 args, = args 1085 return operator.getitem, (origin, args) 1086 1087 def __mro_entries__(self, bases): 1088 if isinstance(self.__origin__, _SpecialForm): 1089 raise TypeError(f"Cannot subclass {self!r}") 1090 1091 if self._name: # generic version of an ABC or built-in class 1092 return super().__mro_entries__(bases) 1093 if self.__origin__ is Generic: 1094 if Protocol in bases: 1095 return () 1096 i = bases.index(self) 1097 for b in bases[i+1:]: 1098 if isinstance(b, _BaseGenericAlias) and b is not self: 1099 return () 1100 return (self.__origin__,) 1101 1102 1103# _nparams is the number of accepted parameters, e.g. 0 for Hashable, 1104# 1 for List and 2 for Dict. It may be -1 if variable number of 1105# parameters are accepted (needs custom __getitem__). 1106 1107class _SpecialGenericAlias(_BaseGenericAlias, _root=True): 1108 def __init__(self, origin, nparams, *, inst=True, name=None): 1109 if name is None: 1110 name = origin.__name__ 1111 super().__init__(origin, inst=inst, name=name) 1112 self._nparams = nparams 1113 if origin.__module__ == 'builtins': 1114 self.__doc__ = f'A generic version of {origin.__qualname__}.' 1115 else: 1116 self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}.' 1117 1118 @_tp_cache 1119 def __getitem__(self, params): 1120 if not isinstance(params, tuple): 1121 params = (params,) 1122 msg = "Parameters to generic types must be types." 1123 params = tuple(_type_check(p, msg) for p in params) 1124 _check_generic(self, params, self._nparams) 1125 return self.copy_with(params) 1126 1127 def copy_with(self, params): 1128 return _GenericAlias(self.__origin__, params, 1129 name=self._name, inst=self._inst) 1130 1131 def __repr__(self): 1132 return 'typing.' + self._name 1133 1134 def __subclasscheck__(self, cls): 1135 if isinstance(cls, _SpecialGenericAlias): 1136 return issubclass(cls.__origin__, self.__origin__) 1137 if not isinstance(cls, _GenericAlias): 1138 return issubclass(cls, self.__origin__) 1139 return super().__subclasscheck__(cls) 1140 1141 def __reduce__(self): 1142 return self._name 1143 1144 def __or__(self, right): 1145 return Union[self, right] 1146 1147 def __ror__(self, left): 1148 return Union[left, self] 1149 1150class _CallableGenericAlias(_GenericAlias, _root=True): 1151 def __repr__(self): 1152 assert self._name == 'Callable' 1153 args = self.__args__ 1154 if len(args) == 2 and _is_param_expr(args[0]): 1155 return super().__repr__() 1156 return (f'typing.Callable' 1157 f'[[{", ".join([_type_repr(a) for a in args[:-1]])}], ' 1158 f'{_type_repr(args[-1])}]') 1159 1160 def __reduce__(self): 1161 args = self.__args__ 1162 if not (len(args) == 2 and _is_param_expr(args[0])): 1163 args = list(args[:-1]), args[-1] 1164 return operator.getitem, (Callable, args) 1165 1166 1167class _CallableType(_SpecialGenericAlias, _root=True): 1168 def copy_with(self, params): 1169 return _CallableGenericAlias(self.__origin__, params, 1170 name=self._name, inst=self._inst, 1171 _typevar_types=(TypeVar, ParamSpec), 1172 _paramspec_tvars=True) 1173 1174 def __getitem__(self, params): 1175 if not isinstance(params, tuple) or len(params) != 2: 1176 raise TypeError("Callable must be used as " 1177 "Callable[[arg, ...], result].") 1178 args, result = params 1179 # This relaxes what args can be on purpose to allow things like 1180 # PEP 612 ParamSpec. Responsibility for whether a user is using 1181 # Callable[...] properly is deferred to static type checkers. 1182 if isinstance(args, list): 1183 params = (tuple(args), result) 1184 else: 1185 params = (args, result) 1186 return self.__getitem_inner__(params) 1187 1188 @_tp_cache 1189 def __getitem_inner__(self, params): 1190 args, result = params 1191 msg = "Callable[args, result]: result must be a type." 1192 result = _type_check(result, msg) 1193 if args is Ellipsis: 1194 return self.copy_with((_TypingEllipsis, result)) 1195 if not isinstance(args, tuple): 1196 args = (args,) 1197 args = tuple(_type_convert(arg) for arg in args) 1198 params = args + (result,) 1199 return self.copy_with(params) 1200 1201 1202class _TupleType(_SpecialGenericAlias, _root=True): 1203 @_tp_cache 1204 def __getitem__(self, params): 1205 if params == (): 1206 return self.copy_with((_TypingEmpty,)) 1207 if not isinstance(params, tuple): 1208 params = (params,) 1209 if len(params) == 2 and params[1] is ...: 1210 msg = "Tuple[t, ...]: t must be a type." 1211 p = _type_check(params[0], msg) 1212 return self.copy_with((p, _TypingEllipsis)) 1213 msg = "Tuple[t0, t1, ...]: each t must be a type." 1214 params = tuple(_type_check(p, msg) for p in params) 1215 return self.copy_with(params) 1216 1217 1218class _UnionGenericAlias(_GenericAlias, _root=True): 1219 def copy_with(self, params): 1220 return Union[params] 1221 1222 def __eq__(self, other): 1223 if not isinstance(other, (_UnionGenericAlias, types.UnionType)): 1224 return NotImplemented 1225 return set(self.__args__) == set(other.__args__) 1226 1227 def __hash__(self): 1228 return hash(frozenset(self.__args__)) 1229 1230 def __repr__(self): 1231 args = self.__args__ 1232 if len(args) == 2: 1233 if args[0] is type(None): 1234 return f'typing.Optional[{_type_repr(args[1])}]' 1235 elif args[1] is type(None): 1236 return f'typing.Optional[{_type_repr(args[0])}]' 1237 return super().__repr__() 1238 1239 def __instancecheck__(self, obj): 1240 return self.__subclasscheck__(type(obj)) 1241 1242 def __subclasscheck__(self, cls): 1243 for arg in self.__args__: 1244 if issubclass(cls, arg): 1245 return True 1246 1247 def __reduce__(self): 1248 func, (origin, args) = super().__reduce__() 1249 return func, (Union, args) 1250 1251 1252def _value_and_type_iter(parameters): 1253 return ((p, type(p)) for p in parameters) 1254 1255 1256class _LiteralGenericAlias(_GenericAlias, _root=True): 1257 1258 def __eq__(self, other): 1259 if not isinstance(other, _LiteralGenericAlias): 1260 return NotImplemented 1261 1262 return set(_value_and_type_iter(self.__args__)) == set(_value_and_type_iter(other.__args__)) 1263 1264 def __hash__(self): 1265 return hash(frozenset(_value_and_type_iter(self.__args__))) 1266 1267 1268class _ConcatenateGenericAlias(_GenericAlias, _root=True): 1269 def __init__(self, *args, **kwargs): 1270 super().__init__(*args, **kwargs, 1271 _typevar_types=(TypeVar, ParamSpec), 1272 _paramspec_tvars=True) 1273 1274 1275class Generic: 1276 """Abstract base class for generic types. 1277 1278 A generic type is typically declared by inheriting from 1279 this class parameterized with one or more type variables. 1280 For example, a generic mapping type might be defined as:: 1281 1282 class Mapping(Generic[KT, VT]): 1283 def __getitem__(self, key: KT) -> VT: 1284 ... 1285 # Etc. 1286 1287 This class can then be used as follows:: 1288 1289 def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT: 1290 try: 1291 return mapping[key] 1292 except KeyError: 1293 return default 1294 """ 1295 __slots__ = () 1296 _is_protocol = False 1297 1298 @_tp_cache 1299 def __class_getitem__(cls, params): 1300 if not isinstance(params, tuple): 1301 params = (params,) 1302 if not params and cls is not Tuple: 1303 raise TypeError( 1304 f"Parameter list to {cls.__qualname__}[...] cannot be empty") 1305 params = tuple(_type_convert(p) for p in params) 1306 if cls in (Generic, Protocol): 1307 # Generic and Protocol can only be subscripted with unique type variables. 1308 if not all(isinstance(p, (TypeVar, ParamSpec)) for p in params): 1309 raise TypeError( 1310 f"Parameters to {cls.__name__}[...] must all be type variables " 1311 f"or parameter specification variables.") 1312 if len(set(params)) != len(params): 1313 raise TypeError( 1314 f"Parameters to {cls.__name__}[...] must all be unique") 1315 else: 1316 # Subscripting a regular Generic subclass. 1317 if any(isinstance(t, ParamSpec) for t in cls.__parameters__): 1318 params = _prepare_paramspec_params(cls, params) 1319 else: 1320 _check_generic(cls, params, len(cls.__parameters__)) 1321 return _GenericAlias(cls, params, 1322 _typevar_types=(TypeVar, ParamSpec), 1323 _paramspec_tvars=True) 1324 1325 def __init_subclass__(cls, *args, **kwargs): 1326 super().__init_subclass__(*args, **kwargs) 1327 tvars = [] 1328 if '__orig_bases__' in cls.__dict__: 1329 error = Generic in cls.__orig_bases__ 1330 else: 1331 error = Generic in cls.__bases__ and cls.__name__ != 'Protocol' 1332 if error: 1333 raise TypeError("Cannot inherit from plain Generic") 1334 if '__orig_bases__' in cls.__dict__: 1335 tvars = _collect_type_vars(cls.__orig_bases__, (TypeVar, ParamSpec)) 1336 # Look for Generic[T1, ..., Tn]. 1337 # If found, tvars must be a subset of it. 1338 # If not found, tvars is it. 1339 # Also check for and reject plain Generic, 1340 # and reject multiple Generic[...]. 1341 gvars = None 1342 for base in cls.__orig_bases__: 1343 if (isinstance(base, _GenericAlias) and 1344 base.__origin__ is Generic): 1345 if gvars is not None: 1346 raise TypeError( 1347 "Cannot inherit from Generic[...] multiple types.") 1348 gvars = base.__parameters__ 1349 if gvars is not None: 1350 tvarset = set(tvars) 1351 gvarset = set(gvars) 1352 if not tvarset <= gvarset: 1353 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset) 1354 s_args = ', '.join(str(g) for g in gvars) 1355 raise TypeError(f"Some type variables ({s_vars}) are" 1356 f" not listed in Generic[{s_args}]") 1357 tvars = gvars 1358 cls.__parameters__ = tuple(tvars) 1359 1360 1361class _TypingEmpty: 1362 """Internal placeholder for () or []. Used by TupleMeta and CallableMeta 1363 to allow empty list/tuple in specific places, without allowing them 1364 to sneak in where prohibited. 1365 """ 1366 1367 1368class _TypingEllipsis: 1369 """Internal placeholder for ... (ellipsis).""" 1370 1371 1372_TYPING_INTERNALS = ['__parameters__', '__orig_bases__', '__orig_class__', 1373 '_is_protocol', '_is_runtime_protocol'] 1374 1375_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__', 1376 '__init__', '__module__', '__new__', '__slots__', 1377 '__subclasshook__', '__weakref__', '__class_getitem__'] 1378 1379# These special attributes will be not collected as protocol members. 1380EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker'] 1381 1382 1383def _get_protocol_attrs(cls): 1384 """Collect protocol members from a protocol class objects. 1385 1386 This includes names actually defined in the class dictionary, as well 1387 as names that appear in annotations. Special names (above) are skipped. 1388 """ 1389 attrs = set() 1390 for base in cls.__mro__[:-1]: # without object 1391 if base.__name__ in ('Protocol', 'Generic'): 1392 continue 1393 annotations = getattr(base, '__annotations__', {}) 1394 for attr in list(base.__dict__.keys()) + list(annotations.keys()): 1395 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES: 1396 attrs.add(attr) 1397 return attrs 1398 1399 1400def _is_callable_members_only(cls): 1401 # PEP 544 prohibits using issubclass() with protocols that have non-method members. 1402 return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls)) 1403 1404 1405def _no_init_or_replace_init(self, *args, **kwargs): 1406 cls = type(self) 1407 1408 if cls._is_protocol: 1409 raise TypeError('Protocols cannot be instantiated') 1410 1411 # Already using a custom `__init__`. No need to calculate correct 1412 # `__init__` to call. This can lead to RecursionError. See bpo-45121. 1413 if cls.__init__ is not _no_init_or_replace_init: 1414 return 1415 1416 # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`. 1417 # The first instantiation of the subclass will call `_no_init_or_replace_init` which 1418 # searches for a proper new `__init__` in the MRO. The new `__init__` 1419 # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent 1420 # instantiation of the protocol subclass will thus use the new 1421 # `__init__` and no longer call `_no_init_or_replace_init`. 1422 for base in cls.__mro__: 1423 init = base.__dict__.get('__init__', _no_init_or_replace_init) 1424 if init is not _no_init_or_replace_init: 1425 cls.__init__ = init 1426 break 1427 else: 1428 # should not happen 1429 cls.__init__ = object.__init__ 1430 1431 cls.__init__(self, *args, **kwargs) 1432 1433 1434def _caller(depth=1, default='__main__'): 1435 try: 1436 return sys._getframe(depth + 1).f_globals.get('__name__', default) 1437 except (AttributeError, ValueError): # For platforms without _getframe() 1438 return None 1439 1440 1441def _allow_reckless_class_checks(depth=3): 1442 """Allow instance and class checks for special stdlib modules. 1443 1444 The abc and functools modules indiscriminately call isinstance() and 1445 issubclass() on the whole MRO of a user class, which may contain protocols. 1446 """ 1447 try: 1448 return sys._getframe(depth).f_globals['__name__'] in ['abc', 'functools'] 1449 except (AttributeError, ValueError): # For platforms without _getframe(). 1450 return True 1451 1452 1453_PROTO_ALLOWLIST = { 1454 'collections.abc': [ 1455 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable', 1456 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible', 1457 ], 1458 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'], 1459} 1460 1461 1462class _ProtocolMeta(ABCMeta): 1463 # This metaclass is really unfortunate and exists only because of 1464 # the lack of __instancehook__. 1465 def __instancecheck__(cls, instance): 1466 # We need this method for situations where attributes are 1467 # assigned in __init__. 1468 if ( 1469 getattr(cls, '_is_protocol', False) and 1470 not getattr(cls, '_is_runtime_protocol', False) and 1471 not _allow_reckless_class_checks(depth=2) 1472 ): 1473 raise TypeError("Instance and class checks can only be used with" 1474 " @runtime_checkable protocols") 1475 1476 if ((not getattr(cls, '_is_protocol', False) or 1477 _is_callable_members_only(cls)) and 1478 issubclass(instance.__class__, cls)): 1479 return True 1480 if cls._is_protocol: 1481 if all(hasattr(instance, attr) and 1482 # All *methods* can be blocked by setting them to None. 1483 (not callable(getattr(cls, attr, None)) or 1484 getattr(instance, attr) is not None) 1485 for attr in _get_protocol_attrs(cls)): 1486 return True 1487 return super().__instancecheck__(instance) 1488 1489 1490class Protocol(Generic, metaclass=_ProtocolMeta): 1491 """Base class for protocol classes. 1492 1493 Protocol classes are defined as:: 1494 1495 class Proto(Protocol): 1496 def meth(self) -> int: 1497 ... 1498 1499 Such classes are primarily used with static type checkers that recognize 1500 structural subtyping (static duck-typing), for example:: 1501 1502 class C: 1503 def meth(self) -> int: 1504 return 0 1505 1506 def func(x: Proto) -> int: 1507 return x.meth() 1508 1509 func(C()) # Passes static type check 1510 1511 See PEP 544 for details. Protocol classes decorated with 1512 @typing.runtime_checkable act as simple-minded runtime protocols that check 1513 only the presence of given attributes, ignoring their type signatures. 1514 Protocol classes can be generic, they are defined as:: 1515 1516 class GenProto(Protocol[T]): 1517 def meth(self) -> T: 1518 ... 1519 """ 1520 __slots__ = () 1521 _is_protocol = True 1522 _is_runtime_protocol = False 1523 1524 def __init_subclass__(cls, *args, **kwargs): 1525 super().__init_subclass__(*args, **kwargs) 1526 1527 # Determine if this is a protocol or a concrete subclass. 1528 if not cls.__dict__.get('_is_protocol', False): 1529 cls._is_protocol = any(b is Protocol for b in cls.__bases__) 1530 1531 # Set (or override) the protocol subclass hook. 1532 def _proto_hook(other): 1533 if not cls.__dict__.get('_is_protocol', False): 1534 return NotImplemented 1535 1536 # First, perform various sanity checks. 1537 if not getattr(cls, '_is_runtime_protocol', False): 1538 if _allow_reckless_class_checks(): 1539 return NotImplemented 1540 raise TypeError("Instance and class checks can only be used with" 1541 " @runtime_checkable protocols") 1542 if not _is_callable_members_only(cls): 1543 if _allow_reckless_class_checks(): 1544 return NotImplemented 1545 raise TypeError("Protocols with non-method members" 1546 " don't support issubclass()") 1547 if not isinstance(other, type): 1548 # Same error message as for issubclass(1, int). 1549 raise TypeError('issubclass() arg 1 must be a class') 1550 1551 # Second, perform the actual structural compatibility check. 1552 for attr in _get_protocol_attrs(cls): 1553 for base in other.__mro__: 1554 # Check if the members appears in the class dictionary... 1555 if attr in base.__dict__: 1556 if base.__dict__[attr] is None: 1557 return NotImplemented 1558 break 1559 1560 # ...or in annotations, if it is a sub-protocol. 1561 annotations = getattr(base, '__annotations__', {}) 1562 if (isinstance(annotations, collections.abc.Mapping) and 1563 attr in annotations and 1564 issubclass(other, Generic) and other._is_protocol): 1565 break 1566 else: 1567 return NotImplemented 1568 return True 1569 1570 if '__subclasshook__' not in cls.__dict__: 1571 cls.__subclasshook__ = _proto_hook 1572 1573 # We have nothing more to do for non-protocols... 1574 if not cls._is_protocol: 1575 return 1576 1577 # ... otherwise check consistency of bases, and prohibit instantiation. 1578 for base in cls.__bases__: 1579 if not (base in (object, Generic) or 1580 base.__module__ in _PROTO_ALLOWLIST and 1581 base.__name__ in _PROTO_ALLOWLIST[base.__module__] or 1582 issubclass(base, Generic) and base._is_protocol): 1583 raise TypeError('Protocols can only inherit from other' 1584 ' protocols, got %r' % base) 1585 cls.__init__ = _no_init_or_replace_init 1586 1587 1588class _AnnotatedAlias(_GenericAlias, _root=True): 1589 """Runtime representation of an annotated type. 1590 1591 At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't' 1592 with extra annotations. The alias behaves like a normal typing alias, 1593 instantiating is the same as instantiating the underlying type, binding 1594 it to types is also the same. 1595 """ 1596 def __init__(self, origin, metadata): 1597 if isinstance(origin, _AnnotatedAlias): 1598 metadata = origin.__metadata__ + metadata 1599 origin = origin.__origin__ 1600 super().__init__(origin, origin) 1601 self.__metadata__ = metadata 1602 1603 def copy_with(self, params): 1604 assert len(params) == 1 1605 new_type = params[0] 1606 return _AnnotatedAlias(new_type, self.__metadata__) 1607 1608 def __repr__(self): 1609 return "typing.Annotated[{}, {}]".format( 1610 _type_repr(self.__origin__), 1611 ", ".join(repr(a) for a in self.__metadata__) 1612 ) 1613 1614 def __reduce__(self): 1615 return operator.getitem, ( 1616 Annotated, (self.__origin__,) + self.__metadata__ 1617 ) 1618 1619 def __eq__(self, other): 1620 if not isinstance(other, _AnnotatedAlias): 1621 return NotImplemented 1622 return (self.__origin__ == other.__origin__ 1623 and self.__metadata__ == other.__metadata__) 1624 1625 def __hash__(self): 1626 return hash((self.__origin__, self.__metadata__)) 1627 1628 def __getattr__(self, attr): 1629 if attr in {'__name__', '__qualname__'}: 1630 return 'Annotated' 1631 return super().__getattr__(attr) 1632 1633 1634class Annotated: 1635 """Add context specific metadata to a type. 1636 1637 Example: Annotated[int, runtime_check.Unsigned] indicates to the 1638 hypothetical runtime_check module that this type is an unsigned int. 1639 Every other consumer of this type can ignore this metadata and treat 1640 this type as int. 1641 1642 The first argument to Annotated must be a valid type. 1643 1644 Details: 1645 1646 - It's an error to call `Annotated` with less than two arguments. 1647 - Nested Annotated are flattened:: 1648 1649 Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3] 1650 1651 - Instantiating an annotated type is equivalent to instantiating the 1652 underlying type:: 1653 1654 Annotated[C, Ann1](5) == C(5) 1655 1656 - Annotated can be used as a generic type alias:: 1657 1658 Optimized = Annotated[T, runtime.Optimize()] 1659 Optimized[int] == Annotated[int, runtime.Optimize()] 1660 1661 OptimizedList = Annotated[List[T], runtime.Optimize()] 1662 OptimizedList[int] == Annotated[List[int], runtime.Optimize()] 1663 """ 1664 1665 __slots__ = () 1666 1667 def __new__(cls, *args, **kwargs): 1668 raise TypeError("Type Annotated cannot be instantiated.") 1669 1670 @_tp_cache 1671 def __class_getitem__(cls, params): 1672 if not isinstance(params, tuple) or len(params) < 2: 1673 raise TypeError("Annotated[...] should be used " 1674 "with at least two arguments (a type and an " 1675 "annotation).") 1676 msg = "Annotated[t, ...]: t must be a type." 1677 origin = _type_check(params[0], msg) 1678 metadata = tuple(params[1:]) 1679 return _AnnotatedAlias(origin, metadata) 1680 1681 def __init_subclass__(cls, *args, **kwargs): 1682 raise TypeError( 1683 "Cannot subclass {}.Annotated".format(cls.__module__) 1684 ) 1685 1686 1687def runtime_checkable(cls): 1688 """Mark a protocol class as a runtime protocol. 1689 1690 Such protocol can be used with isinstance() and issubclass(). 1691 Raise TypeError if applied to a non-protocol class. 1692 This allows a simple-minded structural check very similar to 1693 one trick ponies in collections.abc such as Iterable. 1694 For example:: 1695 1696 @runtime_checkable 1697 class Closable(Protocol): 1698 def close(self): ... 1699 1700 assert isinstance(open('/some/file'), Closable) 1701 1702 Warning: this will check only the presence of the required methods, 1703 not their type signatures! 1704 """ 1705 if not issubclass(cls, Generic) or not cls._is_protocol: 1706 raise TypeError('@runtime_checkable can be only applied to protocol classes,' 1707 ' got %r' % cls) 1708 cls._is_runtime_protocol = True 1709 return cls 1710 1711 1712def cast(typ, val): 1713 """Cast a value to a type. 1714 1715 This returns the value unchanged. To the type checker this 1716 signals that the return value has the designated type, but at 1717 runtime we intentionally don't check anything (we want this 1718 to be as fast as possible). 1719 """ 1720 return val 1721 1722 1723def _get_defaults(func): 1724 """Internal helper to extract the default arguments, by name.""" 1725 try: 1726 code = func.__code__ 1727 except AttributeError: 1728 # Some built-in functions don't have __code__, __defaults__, etc. 1729 return {} 1730 pos_count = code.co_argcount 1731 arg_names = code.co_varnames 1732 arg_names = arg_names[:pos_count] 1733 defaults = func.__defaults__ or () 1734 kwdefaults = func.__kwdefaults__ 1735 res = dict(kwdefaults) if kwdefaults else {} 1736 pos_offset = pos_count - len(defaults) 1737 for name, value in zip(arg_names[pos_offset:], defaults): 1738 assert name not in res 1739 res[name] = value 1740 return res 1741 1742 1743_allowed_types = (types.FunctionType, types.BuiltinFunctionType, 1744 types.MethodType, types.ModuleType, 1745 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType) 1746 1747 1748def get_type_hints(obj, globalns=None, localns=None, include_extras=False): 1749 """Return type hints for an object. 1750 1751 This is often the same as obj.__annotations__, but it handles 1752 forward references encoded as string literals, adds Optional[t] if a 1753 default value equal to None is set and recursively replaces all 1754 'Annotated[T, ...]' with 'T' (unless 'include_extras=True'). 1755 1756 The argument may be a module, class, method, or function. The annotations 1757 are returned as a dictionary. For classes, annotations include also 1758 inherited members. 1759 1760 TypeError is raised if the argument is not of a type that can contain 1761 annotations, and an empty dictionary is returned if no annotations are 1762 present. 1763 1764 BEWARE -- the behavior of globalns and localns is counterintuitive 1765 (unless you are familiar with how eval() and exec() work). The 1766 search order is locals first, then globals. 1767 1768 - If no dict arguments are passed, an attempt is made to use the 1769 globals from obj (or the respective module's globals for classes), 1770 and these are also used as the locals. If the object does not appear 1771 to have globals, an empty dictionary is used. For classes, the search 1772 order is globals first then locals. 1773 1774 - If one dict argument is passed, it is used for both globals and 1775 locals. 1776 1777 - If two dict arguments are passed, they specify globals and 1778 locals, respectively. 1779 """ 1780 1781 if getattr(obj, '__no_type_check__', None): 1782 return {} 1783 # Classes require a special treatment. 1784 if isinstance(obj, type): 1785 hints = {} 1786 for base in reversed(obj.__mro__): 1787 if globalns is None: 1788 base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {}) 1789 else: 1790 base_globals = globalns 1791 ann = base.__dict__.get('__annotations__', {}) 1792 if isinstance(ann, types.GetSetDescriptorType): 1793 ann = {} 1794 base_locals = dict(vars(base)) if localns is None else localns 1795 if localns is None and globalns is None: 1796 # This is surprising, but required. Before Python 3.10, 1797 # get_type_hints only evaluated the globalns of 1798 # a class. To maintain backwards compatibility, we reverse 1799 # the globalns and localns order so that eval() looks into 1800 # *base_globals* first rather than *base_locals*. 1801 # This only affects ForwardRefs. 1802 base_globals, base_locals = base_locals, base_globals 1803 for name, value in ann.items(): 1804 if value is None: 1805 value = type(None) 1806 if isinstance(value, str): 1807 value = ForwardRef(value, is_argument=False, is_class=True) 1808 value = _eval_type(value, base_globals, base_locals) 1809 hints[name] = value 1810 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()} 1811 1812 if globalns is None: 1813 if isinstance(obj, types.ModuleType): 1814 globalns = obj.__dict__ 1815 else: 1816 nsobj = obj 1817 # Find globalns for the unwrapped object. 1818 while hasattr(nsobj, '__wrapped__'): 1819 nsobj = nsobj.__wrapped__ 1820 globalns = getattr(nsobj, '__globals__', {}) 1821 if localns is None: 1822 localns = globalns 1823 elif localns is None: 1824 localns = globalns 1825 hints = getattr(obj, '__annotations__', None) 1826 if hints is None: 1827 # Return empty annotations for something that _could_ have them. 1828 if isinstance(obj, _allowed_types): 1829 return {} 1830 else: 1831 raise TypeError('{!r} is not a module, class, method, ' 1832 'or function.'.format(obj)) 1833 defaults = _get_defaults(obj) 1834 hints = dict(hints) 1835 for name, value in hints.items(): 1836 if value is None: 1837 value = type(None) 1838 if isinstance(value, str): 1839 # class-level forward refs were handled above, this must be either 1840 # a module-level annotation or a function argument annotation 1841 value = ForwardRef( 1842 value, 1843 is_argument=not isinstance(obj, types.ModuleType), 1844 is_class=False, 1845 ) 1846 value = _eval_type(value, globalns, localns) 1847 if name in defaults and defaults[name] is None: 1848 value = Optional[value] 1849 hints[name] = value 1850 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()} 1851 1852 1853def _strip_annotations(t): 1854 """Strips the annotations from a given type. 1855 """ 1856 if isinstance(t, _AnnotatedAlias): 1857 return _strip_annotations(t.__origin__) 1858 if isinstance(t, _GenericAlias): 1859 stripped_args = tuple(_strip_annotations(a) for a in t.__args__) 1860 if stripped_args == t.__args__: 1861 return t 1862 return t.copy_with(stripped_args) 1863 if isinstance(t, GenericAlias): 1864 stripped_args = tuple(_strip_annotations(a) for a in t.__args__) 1865 if stripped_args == t.__args__: 1866 return t 1867 return GenericAlias(t.__origin__, stripped_args) 1868 if isinstance(t, types.UnionType): 1869 stripped_args = tuple(_strip_annotations(a) for a in t.__args__) 1870 if stripped_args == t.__args__: 1871 return t 1872 return functools.reduce(operator.or_, stripped_args) 1873 1874 return t 1875 1876 1877def get_origin(tp): 1878 """Get the unsubscripted version of a type. 1879 1880 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar 1881 and Annotated. Return None for unsupported types. Examples:: 1882 1883 get_origin(Literal[42]) is Literal 1884 get_origin(int) is None 1885 get_origin(ClassVar[int]) is ClassVar 1886 get_origin(Generic) is Generic 1887 get_origin(Generic[T]) is Generic 1888 get_origin(Union[T, int]) is Union 1889 get_origin(List[Tuple[T, T]][int]) == list 1890 get_origin(P.args) is P 1891 """ 1892 if isinstance(tp, _AnnotatedAlias): 1893 return Annotated 1894 if isinstance(tp, (_BaseGenericAlias, GenericAlias, 1895 ParamSpecArgs, ParamSpecKwargs)): 1896 return tp.__origin__ 1897 if tp is Generic: 1898 return Generic 1899 if isinstance(tp, types.UnionType): 1900 return types.UnionType 1901 return None 1902 1903 1904def get_args(tp): 1905 """Get type arguments with all substitutions performed. 1906 1907 For unions, basic simplifications used by Union constructor are performed. 1908 Examples:: 1909 get_args(Dict[str, int]) == (str, int) 1910 get_args(int) == () 1911 get_args(Union[int, Union[T, int], str][int]) == (int, str) 1912 get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) 1913 get_args(Callable[[], T][int]) == ([], int) 1914 """ 1915 if isinstance(tp, _AnnotatedAlias): 1916 return (tp.__origin__,) + tp.__metadata__ 1917 if isinstance(tp, (_GenericAlias, GenericAlias)): 1918 res = tp.__args__ 1919 if (tp.__origin__ is collections.abc.Callable 1920 and not (len(res) == 2 and _is_param_expr(res[0]))): 1921 res = (list(res[:-1]), res[-1]) 1922 return res 1923 if isinstance(tp, types.UnionType): 1924 return tp.__args__ 1925 return () 1926 1927 1928def is_typeddict(tp): 1929 """Check if an annotation is a TypedDict class 1930 1931 For example:: 1932 class Film(TypedDict): 1933 title: str 1934 year: int 1935 1936 is_typeddict(Film) # => True 1937 is_typeddict(Union[list, str]) # => False 1938 """ 1939 return isinstance(tp, _TypedDictMeta) 1940 1941 1942def no_type_check(arg): 1943 """Decorator to indicate that annotations are not type hints. 1944 1945 The argument must be a class or function; if it is a class, it 1946 applies recursively to all methods and classes defined in that class 1947 (but not to methods defined in its superclasses or subclasses). 1948 1949 This mutates the function(s) or class(es) in place. 1950 """ 1951 if isinstance(arg, type): 1952 arg_attrs = arg.__dict__.copy() 1953 for attr, val in arg.__dict__.items(): 1954 if val in arg.__bases__ + (arg,): 1955 arg_attrs.pop(attr) 1956 for obj in arg_attrs.values(): 1957 if isinstance(obj, types.FunctionType): 1958 obj.__no_type_check__ = True 1959 if isinstance(obj, type): 1960 no_type_check(obj) 1961 try: 1962 arg.__no_type_check__ = True 1963 except TypeError: # built-in classes 1964 pass 1965 return arg 1966 1967 1968def no_type_check_decorator(decorator): 1969 """Decorator to give another decorator the @no_type_check effect. 1970 1971 This wraps the decorator with something that wraps the decorated 1972 function in @no_type_check. 1973 """ 1974 1975 @functools.wraps(decorator) 1976 def wrapped_decorator(*args, **kwds): 1977 func = decorator(*args, **kwds) 1978 func = no_type_check(func) 1979 return func 1980 1981 return wrapped_decorator 1982 1983 1984def _overload_dummy(*args, **kwds): 1985 """Helper for @overload to raise when called.""" 1986 raise NotImplementedError( 1987 "You should not call an overloaded function. " 1988 "A series of @overload-decorated functions " 1989 "outside a stub module should always be followed " 1990 "by an implementation that is not @overload-ed.") 1991 1992 1993def overload(func): 1994 """Decorator for overloaded functions/methods. 1995 1996 In a stub file, place two or more stub definitions for the same 1997 function in a row, each decorated with @overload. For example: 1998 1999 @overload 2000 def utf8(value: None) -> None: ... 2001 @overload 2002 def utf8(value: bytes) -> bytes: ... 2003 @overload 2004 def utf8(value: str) -> bytes: ... 2005 2006 In a non-stub file (i.e. a regular .py file), do the same but 2007 follow it with an implementation. The implementation should *not* 2008 be decorated with @overload. For example: 2009 2010 @overload 2011 def utf8(value: None) -> None: ... 2012 @overload 2013 def utf8(value: bytes) -> bytes: ... 2014 @overload 2015 def utf8(value: str) -> bytes: ... 2016 def utf8(value): 2017 # implementation goes here 2018 """ 2019 return _overload_dummy 2020 2021 2022def final(f): 2023 """A decorator to indicate final methods and final classes. 2024 2025 Use this decorator to indicate to type checkers that the decorated 2026 method cannot be overridden, and decorated class cannot be subclassed. 2027 For example: 2028 2029 class Base: 2030 @final 2031 def done(self) -> None: 2032 ... 2033 class Sub(Base): 2034 def done(self) -> None: # Error reported by type checker 2035 ... 2036 2037 @final 2038 class Leaf: 2039 ... 2040 class Other(Leaf): # Error reported by type checker 2041 ... 2042 2043 There is no runtime checking of these properties. 2044 """ 2045 return f 2046 2047 2048# Some unconstrained type variables. These are used by the container types. 2049# (These are not for export.) 2050T = TypeVar('T') # Any type. 2051KT = TypeVar('KT') # Key type. 2052VT = TypeVar('VT') # Value type. 2053T_co = TypeVar('T_co', covariant=True) # Any type covariant containers. 2054V_co = TypeVar('V_co', covariant=True) # Any type covariant containers. 2055VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers. 2056T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant. 2057# Internal type variable used for Type[]. 2058CT_co = TypeVar('CT_co', covariant=True, bound=type) 2059 2060# A useful type variable with constraints. This represents string types. 2061# (This one *is* for export!) 2062AnyStr = TypeVar('AnyStr', bytes, str) 2063 2064 2065# Various ABCs mimicking those in collections.abc. 2066_alias = _SpecialGenericAlias 2067 2068Hashable = _alias(collections.abc.Hashable, 0) # Not generic. 2069Awaitable = _alias(collections.abc.Awaitable, 1) 2070Coroutine = _alias(collections.abc.Coroutine, 3) 2071AsyncIterable = _alias(collections.abc.AsyncIterable, 1) 2072AsyncIterator = _alias(collections.abc.AsyncIterator, 1) 2073Iterable = _alias(collections.abc.Iterable, 1) 2074Iterator = _alias(collections.abc.Iterator, 1) 2075Reversible = _alias(collections.abc.Reversible, 1) 2076Sized = _alias(collections.abc.Sized, 0) # Not generic. 2077Container = _alias(collections.abc.Container, 1) 2078Collection = _alias(collections.abc.Collection, 1) 2079Callable = _CallableType(collections.abc.Callable, 2) 2080Callable.__doc__ = \ 2081 """Callable type; Callable[[int], str] is a function of (int) -> str. 2082 2083 The subscription syntax must always be used with exactly two 2084 values: the argument list and the return type. The argument list 2085 must be a list of types or ellipsis; the return type must be a single type. 2086 2087 There is no syntax to indicate optional or keyword arguments, 2088 such function types are rarely used as callback types. 2089 """ 2090AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet') 2091MutableSet = _alias(collections.abc.MutableSet, 1) 2092# NOTE: Mapping is only covariant in the value type. 2093Mapping = _alias(collections.abc.Mapping, 2) 2094MutableMapping = _alias(collections.abc.MutableMapping, 2) 2095Sequence = _alias(collections.abc.Sequence, 1) 2096MutableSequence = _alias(collections.abc.MutableSequence, 1) 2097ByteString = _alias(collections.abc.ByteString, 0) # Not generic 2098# Tuple accepts variable number of parameters. 2099Tuple = _TupleType(tuple, -1, inst=False, name='Tuple') 2100Tuple.__doc__ = \ 2101 """Tuple type; Tuple[X, Y] is the cross-product type of X and Y. 2102 2103 Example: Tuple[T1, T2] is a tuple of two elements corresponding 2104 to type variables T1 and T2. Tuple[int, float, str] is a tuple 2105 of an int, a float and a string. 2106 2107 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...]. 2108 """ 2109List = _alias(list, 1, inst=False, name='List') 2110Deque = _alias(collections.deque, 1, name='Deque') 2111Set = _alias(set, 1, inst=False, name='Set') 2112FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet') 2113MappingView = _alias(collections.abc.MappingView, 1) 2114KeysView = _alias(collections.abc.KeysView, 1) 2115ItemsView = _alias(collections.abc.ItemsView, 2) 2116ValuesView = _alias(collections.abc.ValuesView, 1) 2117ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager') 2118AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager') 2119Dict = _alias(dict, 2, inst=False, name='Dict') 2120DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict') 2121OrderedDict = _alias(collections.OrderedDict, 2) 2122Counter = _alias(collections.Counter, 1) 2123ChainMap = _alias(collections.ChainMap, 2) 2124Generator = _alias(collections.abc.Generator, 3) 2125AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2) 2126Type = _alias(type, 1, inst=False, name='Type') 2127Type.__doc__ = \ 2128 """A special construct usable to annotate class objects. 2129 2130 For example, suppose we have the following classes:: 2131 2132 class User: ... # Abstract base for User classes 2133 class BasicUser(User): ... 2134 class ProUser(User): ... 2135 class TeamUser(User): ... 2136 2137 And a function that takes a class argument that's a subclass of 2138 User and returns an instance of the corresponding class:: 2139 2140 U = TypeVar('U', bound=User) 2141 def new_user(user_class: Type[U]) -> U: 2142 user = user_class() 2143 # (Here we could write the user object to a database) 2144 return user 2145 2146 joe = new_user(BasicUser) 2147 2148 At this point the type checker knows that joe has type BasicUser. 2149 """ 2150 2151 2152@runtime_checkable 2153class SupportsInt(Protocol): 2154 """An ABC with one abstract method __int__.""" 2155 __slots__ = () 2156 2157 @abstractmethod 2158 def __int__(self) -> int: 2159 pass 2160 2161 2162@runtime_checkable 2163class SupportsFloat(Protocol): 2164 """An ABC with one abstract method __float__.""" 2165 __slots__ = () 2166 2167 @abstractmethod 2168 def __float__(self) -> float: 2169 pass 2170 2171 2172@runtime_checkable 2173class SupportsComplex(Protocol): 2174 """An ABC with one abstract method __complex__.""" 2175 __slots__ = () 2176 2177 @abstractmethod 2178 def __complex__(self) -> complex: 2179 pass 2180 2181 2182@runtime_checkable 2183class SupportsBytes(Protocol): 2184 """An ABC with one abstract method __bytes__.""" 2185 __slots__ = () 2186 2187 @abstractmethod 2188 def __bytes__(self) -> bytes: 2189 pass 2190 2191 2192@runtime_checkable 2193class SupportsIndex(Protocol): 2194 """An ABC with one abstract method __index__.""" 2195 __slots__ = () 2196 2197 @abstractmethod 2198 def __index__(self) -> int: 2199 pass 2200 2201 2202@runtime_checkable 2203class SupportsAbs(Protocol[T_co]): 2204 """An ABC with one abstract method __abs__ that is covariant in its return type.""" 2205 __slots__ = () 2206 2207 @abstractmethod 2208 def __abs__(self) -> T_co: 2209 pass 2210 2211 2212@runtime_checkable 2213class SupportsRound(Protocol[T_co]): 2214 """An ABC with one abstract method __round__ that is covariant in its return type.""" 2215 __slots__ = () 2216 2217 @abstractmethod 2218 def __round__(self, ndigits: int = 0) -> T_co: 2219 pass 2220 2221 2222def _make_nmtuple(name, types, module, defaults = ()): 2223 fields = [n for n, t in types] 2224 types = {n: _type_check(t, f"field {n} annotation must be a type") 2225 for n, t in types} 2226 nm_tpl = collections.namedtuple(name, fields, 2227 defaults=defaults, module=module) 2228 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types 2229 return nm_tpl 2230 2231 2232# attributes prohibited to set in NamedTuple class syntax 2233_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__', 2234 '_fields', '_field_defaults', 2235 '_make', '_replace', '_asdict', '_source'}) 2236 2237_special = frozenset({'__module__', '__name__', '__annotations__'}) 2238 2239 2240class NamedTupleMeta(type): 2241 2242 def __new__(cls, typename, bases, ns): 2243 assert bases[0] is _NamedTuple 2244 types = ns.get('__annotations__', {}) 2245 default_names = [] 2246 for field_name in types: 2247 if field_name in ns: 2248 default_names.append(field_name) 2249 elif default_names: 2250 raise TypeError(f"Non-default namedtuple field {field_name} " 2251 f"cannot follow default field" 2252 f"{'s' if len(default_names) > 1 else ''} " 2253 f"{', '.join(default_names)}") 2254 nm_tpl = _make_nmtuple(typename, types.items(), 2255 defaults=[ns[n] for n in default_names], 2256 module=ns['__module__']) 2257 # update from user namespace without overriding special namedtuple attributes 2258 for key in ns: 2259 if key in _prohibited: 2260 raise AttributeError("Cannot overwrite NamedTuple attribute " + key) 2261 elif key not in _special and key not in nm_tpl._fields: 2262 setattr(nm_tpl, key, ns[key]) 2263 return nm_tpl 2264 2265 2266def NamedTuple(typename, fields=None, /, **kwargs): 2267 """Typed version of namedtuple. 2268 2269 Usage in Python versions >= 3.6:: 2270 2271 class Employee(NamedTuple): 2272 name: str 2273 id: int 2274 2275 This is equivalent to:: 2276 2277 Employee = collections.namedtuple('Employee', ['name', 'id']) 2278 2279 The resulting class has an extra __annotations__ attribute, giving a 2280 dict that maps field names to types. (The field names are also in 2281 the _fields attribute, which is part of the namedtuple API.) 2282 Alternative equivalent keyword syntax is also accepted:: 2283 2284 Employee = NamedTuple('Employee', name=str, id=int) 2285 2286 In Python versions <= 3.5 use:: 2287 2288 Employee = NamedTuple('Employee', [('name', str), ('id', int)]) 2289 """ 2290 if fields is None: 2291 fields = kwargs.items() 2292 elif kwargs: 2293 raise TypeError("Either list of fields or keywords" 2294 " can be provided to NamedTuple, not both") 2295 try: 2296 module = sys._getframe(1).f_globals.get('__name__', '__main__') 2297 except (AttributeError, ValueError): 2298 module = None 2299 return _make_nmtuple(typename, fields, module=module) 2300 2301_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {}) 2302 2303def _namedtuple_mro_entries(bases): 2304 if len(bases) > 1: 2305 raise TypeError("Multiple inheritance with NamedTuple is not supported") 2306 assert bases[0] is NamedTuple 2307 return (_NamedTuple,) 2308 2309NamedTuple.__mro_entries__ = _namedtuple_mro_entries 2310 2311 2312class _TypedDictMeta(type): 2313 def __new__(cls, name, bases, ns, total=True): 2314 """Create new typed dict class object. 2315 2316 This method is called when TypedDict is subclassed, 2317 or when TypedDict is instantiated. This way 2318 TypedDict supports all three syntax forms described in its docstring. 2319 Subclasses and instances of TypedDict return actual dictionaries. 2320 """ 2321 for base in bases: 2322 if type(base) is not _TypedDictMeta: 2323 raise TypeError('cannot inherit from both a TypedDict type ' 2324 'and a non-TypedDict base class') 2325 tp_dict = type.__new__(_TypedDictMeta, name, (dict,), ns) 2326 2327 annotations = {} 2328 own_annotations = ns.get('__annotations__', {}) 2329 own_annotation_keys = set(own_annotations.keys()) 2330 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type" 2331 own_annotations = { 2332 n: _type_check(tp, msg, module=tp_dict.__module__) 2333 for n, tp in own_annotations.items() 2334 } 2335 required_keys = set() 2336 optional_keys = set() 2337 2338 for base in bases: 2339 annotations.update(base.__dict__.get('__annotations__', {})) 2340 required_keys.update(base.__dict__.get('__required_keys__', ())) 2341 optional_keys.update(base.__dict__.get('__optional_keys__', ())) 2342 2343 annotations.update(own_annotations) 2344 if total: 2345 required_keys.update(own_annotation_keys) 2346 else: 2347 optional_keys.update(own_annotation_keys) 2348 2349 tp_dict.__annotations__ = annotations 2350 tp_dict.__required_keys__ = frozenset(required_keys) 2351 tp_dict.__optional_keys__ = frozenset(optional_keys) 2352 if not hasattr(tp_dict, '__total__'): 2353 tp_dict.__total__ = total 2354 return tp_dict 2355 2356 __call__ = dict # static method 2357 2358 def __subclasscheck__(cls, other): 2359 # Typed dicts are only for static structural subtyping. 2360 raise TypeError('TypedDict does not support instance and class checks') 2361 2362 __instancecheck__ = __subclasscheck__ 2363 2364 2365def TypedDict(typename, fields=None, /, *, total=True, **kwargs): 2366 """A simple typed namespace. At runtime it is equivalent to a plain dict. 2367 2368 TypedDict creates a dictionary type that expects all of its 2369 instances to have a certain set of keys, where each key is 2370 associated with a value of a consistent type. This expectation 2371 is not checked at runtime but is only enforced by type checkers. 2372 Usage:: 2373 2374 class Point2D(TypedDict): 2375 x: int 2376 y: int 2377 label: str 2378 2379 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK 2380 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check 2381 2382 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') 2383 2384 The type info can be accessed via the Point2D.__annotations__ dict, and 2385 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets. 2386 TypedDict supports two additional equivalent forms:: 2387 2388 Point2D = TypedDict('Point2D', x=int, y=int, label=str) 2389 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) 2390 2391 By default, all keys must be present in a TypedDict. It is possible 2392 to override this by specifying totality. 2393 Usage:: 2394 2395 class point2D(TypedDict, total=False): 2396 x: int 2397 y: int 2398 2399 This means that a point2D TypedDict can have any of the keys omitted.A type 2400 checker is only expected to support a literal False or True as the value of 2401 the total argument. True is the default, and makes all items defined in the 2402 class body be required. 2403 2404 The class syntax is only supported in Python 3.6+, while two other 2405 syntax forms work for Python 2.7 and 3.2+ 2406 """ 2407 if fields is None: 2408 fields = kwargs 2409 elif kwargs: 2410 raise TypeError("TypedDict takes either a dict or keyword arguments," 2411 " but not both") 2412 2413 ns = {'__annotations__': dict(fields)} 2414 try: 2415 # Setting correct module is necessary to make typed dict classes pickleable. 2416 ns['__module__'] = sys._getframe(1).f_globals.get('__name__', '__main__') 2417 except (AttributeError, ValueError): 2418 pass 2419 2420 return _TypedDictMeta(typename, (), ns, total=total) 2421 2422_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {}) 2423TypedDict.__mro_entries__ = lambda bases: (_TypedDict,) 2424 2425 2426class NewType: 2427 """NewType creates simple unique types with almost zero 2428 runtime overhead. NewType(name, tp) is considered a subtype of tp 2429 by static type checkers. At runtime, NewType(name, tp) returns 2430 a dummy callable that simply returns its argument. Usage:: 2431 2432 UserId = NewType('UserId', int) 2433 2434 def name_by_id(user_id: UserId) -> str: 2435 ... 2436 2437 UserId('user') # Fails type check 2438 2439 name_by_id(42) # Fails type check 2440 name_by_id(UserId(42)) # OK 2441 2442 num = UserId(5) + 1 # type: int 2443 """ 2444 2445 def __init__(self, name, tp): 2446 self.__qualname__ = name 2447 if '.' in name: 2448 name = name.rpartition('.')[-1] 2449 self.__name__ = name 2450 self.__supertype__ = tp 2451 def_mod = _caller() 2452 if def_mod != 'typing': 2453 self.__module__ = def_mod 2454 2455 def __repr__(self): 2456 return f'{self.__module__}.{self.__qualname__}' 2457 2458 def __call__(self, x): 2459 return x 2460 2461 def __reduce__(self): 2462 return self.__qualname__ 2463 2464 def __or__(self, other): 2465 return Union[self, other] 2466 2467 def __ror__(self, other): 2468 return Union[other, self] 2469 2470 2471# Python-version-specific alias (Python 2: unicode; Python 3: str) 2472Text = str 2473 2474 2475# Constant that's True when type checking, but False here. 2476TYPE_CHECKING = False 2477 2478 2479class IO(Generic[AnyStr]): 2480 """Generic base class for TextIO and BinaryIO. 2481 2482 This is an abstract, generic version of the return of open(). 2483 2484 NOTE: This does not distinguish between the different possible 2485 classes (text vs. binary, read vs. write vs. read/write, 2486 append-only, unbuffered). The TextIO and BinaryIO subclasses 2487 below capture the distinctions between text vs. binary, which is 2488 pervasive in the interface; however we currently do not offer a 2489 way to track the other distinctions in the type system. 2490 """ 2491 2492 __slots__ = () 2493 2494 @property 2495 @abstractmethod 2496 def mode(self) -> str: 2497 pass 2498 2499 @property 2500 @abstractmethod 2501 def name(self) -> str: 2502 pass 2503 2504 @abstractmethod 2505 def close(self) -> None: 2506 pass 2507 2508 @property 2509 @abstractmethod 2510 def closed(self) -> bool: 2511 pass 2512 2513 @abstractmethod 2514 def fileno(self) -> int: 2515 pass 2516 2517 @abstractmethod 2518 def flush(self) -> None: 2519 pass 2520 2521 @abstractmethod 2522 def isatty(self) -> bool: 2523 pass 2524 2525 @abstractmethod 2526 def read(self, n: int = -1) -> AnyStr: 2527 pass 2528 2529 @abstractmethod 2530 def readable(self) -> bool: 2531 pass 2532 2533 @abstractmethod 2534 def readline(self, limit: int = -1) -> AnyStr: 2535 pass 2536 2537 @abstractmethod 2538 def readlines(self, hint: int = -1) -> List[AnyStr]: 2539 pass 2540 2541 @abstractmethod 2542 def seek(self, offset: int, whence: int = 0) -> int: 2543 pass 2544 2545 @abstractmethod 2546 def seekable(self) -> bool: 2547 pass 2548 2549 @abstractmethod 2550 def tell(self) -> int: 2551 pass 2552 2553 @abstractmethod 2554 def truncate(self, size: int = None) -> int: 2555 pass 2556 2557 @abstractmethod 2558 def writable(self) -> bool: 2559 pass 2560 2561 @abstractmethod 2562 def write(self, s: AnyStr) -> int: 2563 pass 2564 2565 @abstractmethod 2566 def writelines(self, lines: List[AnyStr]) -> None: 2567 pass 2568 2569 @abstractmethod 2570 def __enter__(self) -> 'IO[AnyStr]': 2571 pass 2572 2573 @abstractmethod 2574 def __exit__(self, type, value, traceback) -> None: 2575 pass 2576 2577 2578class BinaryIO(IO[bytes]): 2579 """Typed version of the return of open() in binary mode.""" 2580 2581 __slots__ = () 2582 2583 @abstractmethod 2584 def write(self, s: Union[bytes, bytearray]) -> int: 2585 pass 2586 2587 @abstractmethod 2588 def __enter__(self) -> 'BinaryIO': 2589 pass 2590 2591 2592class TextIO(IO[str]): 2593 """Typed version of the return of open() in text mode.""" 2594 2595 __slots__ = () 2596 2597 @property 2598 @abstractmethod 2599 def buffer(self) -> BinaryIO: 2600 pass 2601 2602 @property 2603 @abstractmethod 2604 def encoding(self) -> str: 2605 pass 2606 2607 @property 2608 @abstractmethod 2609 def errors(self) -> Optional[str]: 2610 pass 2611 2612 @property 2613 @abstractmethod 2614 def line_buffering(self) -> bool: 2615 pass 2616 2617 @property 2618 @abstractmethod 2619 def newlines(self) -> Any: 2620 pass 2621 2622 @abstractmethod 2623 def __enter__(self) -> 'TextIO': 2624 pass 2625 2626 2627class io: 2628 """Wrapper namespace for IO generic classes.""" 2629 2630 __all__ = ['IO', 'TextIO', 'BinaryIO'] 2631 IO = IO 2632 TextIO = TextIO 2633 BinaryIO = BinaryIO 2634 2635 2636io.__name__ = __name__ + '.io' 2637sys.modules[io.__name__] = io 2638 2639Pattern = _alias(stdlib_re.Pattern, 1) 2640Match = _alias(stdlib_re.Match, 1) 2641 2642class re: 2643 """Wrapper namespace for re type aliases.""" 2644 2645 __all__ = ['Pattern', 'Match'] 2646 Pattern = Pattern 2647 Match = Match 2648 2649 2650re.__name__ = __name__ + '.re' 2651sys.modules[re.__name__] = re 2652