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