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): Any, NoReturn, ClassVar, Union, Optional 8* Two classes whose instances can be type arguments in addition to types: ForwardRef and TypeVar 9* The core of internal generics API: _GenericAlias and _VariadicGenericAlias, the latter is 10 currently only used by Tuple and Callable. All subscripted types like X[int], Union[int, str], 11 etc., are instances of either of these classes. 12* The public counterpart of the generics API consists of two classes: Generic and Protocol. 13* Public helper functions: get_type_hints, overload, cast, no_type_check, 14 no_type_check_decorator. 15* Generic aliases for collections.abc ABCs and few additional protocols. 16* Special types: NewType, NamedTuple, TypedDict. 17* Wrapper submodules for re and io related types. 18""" 19 20from abc import abstractmethod, ABCMeta 21import collections 22import collections.abc 23import contextlib 24import functools 25import operator 26import re as stdlib_re # Avoid confusion with the re we export. 27import sys 28import types 29from types import WrapperDescriptorType, MethodWrapperType, MethodDescriptorType 30 31# Please keep __all__ alphabetized within each category. 32__all__ = [ 33 # Super-special typing primitives. 34 'Any', 35 'Callable', 36 'ClassVar', 37 'Final', 38 'ForwardRef', 39 'Generic', 40 'Literal', 41 'Optional', 42 'Protocol', 43 'Tuple', 44 'Type', 45 'TypeVar', 46 'Union', 47 48 # ABCs (from collections.abc). 49 'AbstractSet', # collections.abc.Set. 50 'ByteString', 51 'Container', 52 'ContextManager', 53 'Hashable', 54 'ItemsView', 55 'Iterable', 56 'Iterator', 57 'KeysView', 58 'Mapping', 59 'MappingView', 60 'MutableMapping', 61 'MutableSequence', 62 'MutableSet', 63 'Sequence', 64 'Sized', 65 'ValuesView', 66 'Awaitable', 67 'AsyncIterator', 68 'AsyncIterable', 69 'Coroutine', 70 'Collection', 71 'AsyncGenerator', 72 'AsyncContextManager', 73 74 # Structural checks, a.k.a. protocols. 75 'Reversible', 76 'SupportsAbs', 77 'SupportsBytes', 78 'SupportsComplex', 79 'SupportsFloat', 80 'SupportsIndex', 81 'SupportsInt', 82 'SupportsRound', 83 84 # Concrete collection types. 85 'ChainMap', 86 'Counter', 87 'Deque', 88 'Dict', 89 'DefaultDict', 90 'List', 91 'OrderedDict', 92 'Set', 93 'FrozenSet', 94 'NamedTuple', # Not really a type. 95 'TypedDict', # Not really a type. 96 'Generator', 97 98 # One-off things. 99 'AnyStr', 100 'cast', 101 'final', 102 'get_args', 103 'get_origin', 104 'get_type_hints', 105 'NewType', 106 'no_type_check', 107 'no_type_check_decorator', 108 'NoReturn', 109 'overload', 110 'runtime_checkable', 111 'Text', 112 'TYPE_CHECKING', 113] 114 115# The pseudo-submodules 're' and 'io' are part of the public 116# namespace, but excluded from __all__ because they might stomp on 117# legitimate imports of those modules. 118 119 120def _type_check(arg, msg, is_argument=True): 121 """Check that the argument is a type, and return it (internal helper). 122 123 As a special case, accept None and return type(None) instead. Also wrap strings 124 into ForwardRef instances. Consider several corner cases, for example plain 125 special forms like Union are not valid, while Union[int, str] is OK, etc. 126 The msg argument is a human-readable error message, e.g:: 127 128 "Union[arg, ...]: arg should be a type." 129 130 We append the repr() of the actual value (truncated to 100 chars). 131 """ 132 invalid_generic_forms = (Generic, Protocol) 133 if is_argument: 134 invalid_generic_forms = invalid_generic_forms + (ClassVar, Final) 135 136 if arg is None: 137 return type(None) 138 if isinstance(arg, str): 139 return ForwardRef(arg) 140 if (isinstance(arg, _GenericAlias) and 141 arg.__origin__ in invalid_generic_forms): 142 raise TypeError(f"{arg} is not valid as type argument") 143 if (isinstance(arg, _SpecialForm) and arg not in (Any, NoReturn) or 144 arg in (Generic, Protocol)): 145 raise TypeError(f"Plain {arg} is not valid as type argument") 146 if isinstance(arg, (type, TypeVar, ForwardRef)): 147 return arg 148 if not callable(arg): 149 raise TypeError(f"{msg} Got {arg!r:.100}.") 150 return arg 151 152 153def _type_repr(obj): 154 """Return the repr() of an object, special-casing types (internal helper). 155 156 If obj is a type, we return a shorter version than the default 157 type.__repr__, based on the module and qualified name, which is 158 typically enough to uniquely identify a type. For everything 159 else, we fall back on repr(obj). 160 """ 161 if isinstance(obj, type): 162 if obj.__module__ == 'builtins': 163 return obj.__qualname__ 164 return f'{obj.__module__}.{obj.__qualname__}' 165 if obj is ...: 166 return('...') 167 if isinstance(obj, types.FunctionType): 168 return obj.__name__ 169 return repr(obj) 170 171 172def _collect_type_vars(types): 173 """Collect all type variable contained in types in order of 174 first appearance (lexicographic order). For example:: 175 176 _collect_type_vars((T, List[S, T])) == (T, S) 177 """ 178 tvars = [] 179 for t in types: 180 if isinstance(t, TypeVar) and t not in tvars: 181 tvars.append(t) 182 if isinstance(t, _GenericAlias) and not t._special: 183 tvars.extend([t for t in t.__parameters__ if t not in tvars]) 184 return tuple(tvars) 185 186 187def _subs_tvars(tp, tvars, subs): 188 """Substitute type variables 'tvars' with substitutions 'subs'. 189 These two must have the same length. 190 """ 191 if not isinstance(tp, _GenericAlias): 192 return tp 193 new_args = list(tp.__args__) 194 for a, arg in enumerate(tp.__args__): 195 if isinstance(arg, TypeVar): 196 for i, tvar in enumerate(tvars): 197 if arg == tvar: 198 new_args[a] = subs[i] 199 else: 200 new_args[a] = _subs_tvars(arg, tvars, subs) 201 if tp.__origin__ is Union: 202 return Union[tuple(new_args)] 203 return tp.copy_with(tuple(new_args)) 204 205 206def _check_generic(cls, parameters): 207 """Check correct count for parameters of a generic cls (internal helper). 208 This gives a nice error message in case of count mismatch. 209 """ 210 if not cls.__parameters__: 211 raise TypeError(f"{cls} is not a generic class") 212 alen = len(parameters) 213 elen = len(cls.__parameters__) 214 if alen != elen: 215 raise TypeError(f"Too {'many' if alen > elen else 'few'} parameters for {cls};" 216 f" actual {alen}, expected {elen}") 217 218 219def _remove_dups_flatten(parameters): 220 """An internal helper for Union creation and substitution: flatten Unions 221 among parameters, then remove duplicates. 222 """ 223 # Flatten out Union[Union[...], ...]. 224 params = [] 225 for p in parameters: 226 if isinstance(p, _GenericAlias) and p.__origin__ is Union: 227 params.extend(p.__args__) 228 elif isinstance(p, tuple) and len(p) > 0 and p[0] is Union: 229 params.extend(p[1:]) 230 else: 231 params.append(p) 232 # Weed out strict duplicates, preserving the first of each occurrence. 233 all_params = set(params) 234 if len(all_params) < len(params): 235 new_params = [] 236 for t in params: 237 if t in all_params: 238 new_params.append(t) 239 all_params.remove(t) 240 params = new_params 241 assert not all_params, all_params 242 return tuple(params) 243 244 245_cleanups = [] 246 247 248def _tp_cache(func): 249 """Internal wrapper caching __getitem__ of generic types with a fallback to 250 original function for non-hashable arguments. 251 """ 252 cached = functools.lru_cache()(func) 253 _cleanups.append(cached.cache_clear) 254 255 @functools.wraps(func) 256 def inner(*args, **kwds): 257 try: 258 return cached(*args, **kwds) 259 except TypeError: 260 pass # All real errors (not unhashable args) are raised below. 261 return func(*args, **kwds) 262 return inner 263 264 265def _eval_type(t, globalns, localns): 266 """Evaluate all forward reverences in the given type t. 267 For use of globalns and localns see the docstring for get_type_hints(). 268 """ 269 if isinstance(t, ForwardRef): 270 return t._evaluate(globalns, localns) 271 if isinstance(t, _GenericAlias): 272 ev_args = tuple(_eval_type(a, globalns, localns) for a in t.__args__) 273 if ev_args == t.__args__: 274 return t 275 res = t.copy_with(ev_args) 276 res._special = t._special 277 return res 278 return t 279 280 281class _Final: 282 """Mixin to prohibit subclassing""" 283 284 __slots__ = ('__weakref__',) 285 286 def __init_subclass__(self, /, *args, **kwds): 287 if '_root' not in kwds: 288 raise TypeError("Cannot subclass special typing classes") 289 290class _Immutable: 291 """Mixin to indicate that object should not be copied.""" 292 293 def __copy__(self): 294 return self 295 296 def __deepcopy__(self, memo): 297 return self 298 299 300class _SpecialForm(_Final, _Immutable, _root=True): 301 """Internal indicator of special typing constructs. 302 See _doc instance attribute for specific docs. 303 """ 304 305 __slots__ = ('_name', '_doc') 306 307 def __new__(cls, *args, **kwds): 308 """Constructor. 309 310 This only exists to give a better error message in case 311 someone tries to subclass a special typing object (not a good idea). 312 """ 313 if (len(args) == 3 and 314 isinstance(args[0], str) and 315 isinstance(args[1], tuple)): 316 # Close enough. 317 raise TypeError(f"Cannot subclass {cls!r}") 318 return super().__new__(cls) 319 320 def __init__(self, name, doc): 321 self._name = name 322 self._doc = doc 323 324 def __eq__(self, other): 325 if not isinstance(other, _SpecialForm): 326 return NotImplemented 327 return self._name == other._name 328 329 def __hash__(self): 330 return hash((self._name,)) 331 332 def __repr__(self): 333 return 'typing.' + self._name 334 335 def __reduce__(self): 336 return self._name 337 338 def __call__(self, *args, **kwds): 339 raise TypeError(f"Cannot instantiate {self!r}") 340 341 def __instancecheck__(self, obj): 342 raise TypeError(f"{self} cannot be used with isinstance()") 343 344 def __subclasscheck__(self, cls): 345 raise TypeError(f"{self} cannot be used with issubclass()") 346 347 @_tp_cache 348 def __getitem__(self, parameters): 349 if self._name in ('ClassVar', 'Final'): 350 item = _type_check(parameters, f'{self._name} accepts only single type.') 351 return _GenericAlias(self, (item,)) 352 if self._name == 'Union': 353 if parameters == (): 354 raise TypeError("Cannot take a Union of no types.") 355 if not isinstance(parameters, tuple): 356 parameters = (parameters,) 357 msg = "Union[arg, ...]: each arg must be a type." 358 parameters = tuple(_type_check(p, msg) for p in parameters) 359 parameters = _remove_dups_flatten(parameters) 360 if len(parameters) == 1: 361 return parameters[0] 362 return _GenericAlias(self, parameters) 363 if self._name == 'Optional': 364 arg = _type_check(parameters, "Optional[t] requires a single type.") 365 return Union[arg, type(None)] 366 if self._name == 'Literal': 367 # There is no '_type_check' call because arguments to Literal[...] are 368 # values, not types. 369 return _GenericAlias(self, parameters) 370 raise TypeError(f"{self} is not subscriptable") 371 372 373Any = _SpecialForm('Any', doc= 374 """Special type indicating an unconstrained type. 375 376 - Any is compatible with every type. 377 - Any assumed to have all methods. 378 - All values assumed to be instances of Any. 379 380 Note that all the above statements are true from the point of view of 381 static type checkers. At runtime, Any should not be used with instance 382 or class checks. 383 """) 384 385NoReturn = _SpecialForm('NoReturn', doc= 386 """Special type indicating functions that never return. 387 Example:: 388 389 from typing import NoReturn 390 391 def stop() -> NoReturn: 392 raise Exception('no way') 393 394 This type is invalid in other positions, e.g., ``List[NoReturn]`` 395 will fail in static type checkers. 396 """) 397 398ClassVar = _SpecialForm('ClassVar', doc= 399 """Special type construct to mark class variables. 400 401 An annotation wrapped in ClassVar indicates that a given 402 attribute is intended to be used as a class variable and 403 should not be set on instances of that class. Usage:: 404 405 class Starship: 406 stats: ClassVar[Dict[str, int]] = {} # class variable 407 damage: int = 10 # instance variable 408 409 ClassVar accepts only types and cannot be further subscribed. 410 411 Note that ClassVar is not a class itself, and should not 412 be used with isinstance() or issubclass(). 413 """) 414 415Final = _SpecialForm('Final', doc= 416 """Special typing construct to indicate final names to type checkers. 417 418 A final name cannot be re-assigned or overridden in a subclass. 419 For example: 420 421 MAX_SIZE: Final = 9000 422 MAX_SIZE += 1 # Error reported by type checker 423 424 class Connection: 425 TIMEOUT: Final[int] = 10 426 427 class FastConnector(Connection): 428 TIMEOUT = 1 # Error reported by type checker 429 430 There is no runtime checking of these properties. 431 """) 432 433Union = _SpecialForm('Union', doc= 434 """Union type; Union[X, Y] means either X or Y. 435 436 To define a union, use e.g. Union[int, str]. Details: 437 - The arguments must be types and there must be at least one. 438 - None as an argument is a special case and is replaced by 439 type(None). 440 - Unions of unions are flattened, e.g.:: 441 442 Union[Union[int, str], float] == Union[int, str, float] 443 444 - Unions of a single argument vanish, e.g.:: 445 446 Union[int] == int # The constructor actually returns int 447 448 - Redundant arguments are skipped, e.g.:: 449 450 Union[int, str, int] == Union[int, str] 451 452 - When comparing unions, the argument order is ignored, e.g.:: 453 454 Union[int, str] == Union[str, int] 455 456 - You cannot subclass or instantiate a union. 457 - You can use Optional[X] as a shorthand for Union[X, None]. 458 """) 459 460Optional = _SpecialForm('Optional', doc= 461 """Optional type. 462 463 Optional[X] is equivalent to Union[X, None]. 464 """) 465 466Literal = _SpecialForm('Literal', doc= 467 """Special typing form to define literal types (a.k.a. value types). 468 469 This form can be used to indicate to type checkers that the corresponding 470 variable or function parameter has a value equivalent to the provided 471 literal (or one of several literals): 472 473 def validate_simple(data: Any) -> Literal[True]: # always returns True 474 ... 475 476 MODE = Literal['r', 'rb', 'w', 'wb'] 477 def open_helper(file: str, mode: MODE) -> str: 478 ... 479 480 open_helper('/some/path', 'r') # Passes type check 481 open_helper('/other/path', 'typo') # Error in type checker 482 483 Literal[...] cannot be subclassed. At runtime, an arbitrary value 484 is allowed as type argument to Literal[...], but type checkers may 485 impose restrictions. 486 """) 487 488 489class ForwardRef(_Final, _root=True): 490 """Internal wrapper to hold a forward reference.""" 491 492 __slots__ = ('__forward_arg__', '__forward_code__', 493 '__forward_evaluated__', '__forward_value__', 494 '__forward_is_argument__') 495 496 def __init__(self, arg, is_argument=True): 497 if not isinstance(arg, str): 498 raise TypeError(f"Forward reference must be a string -- got {arg!r}") 499 try: 500 code = compile(arg, '<string>', 'eval') 501 except SyntaxError: 502 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}") 503 self.__forward_arg__ = arg 504 self.__forward_code__ = code 505 self.__forward_evaluated__ = False 506 self.__forward_value__ = None 507 self.__forward_is_argument__ = is_argument 508 509 def _evaluate(self, globalns, localns): 510 if not self.__forward_evaluated__ or localns is not globalns: 511 if globalns is None and localns is None: 512 globalns = localns = {} 513 elif globalns is None: 514 globalns = localns 515 elif localns is None: 516 localns = globalns 517 self.__forward_value__ = _type_check( 518 eval(self.__forward_code__, globalns, localns), 519 "Forward references must evaluate to types.", 520 is_argument=self.__forward_is_argument__) 521 self.__forward_evaluated__ = True 522 return self.__forward_value__ 523 524 def __eq__(self, other): 525 if not isinstance(other, ForwardRef): 526 return NotImplemented 527 if self.__forward_evaluated__ and other.__forward_evaluated__: 528 return (self.__forward_arg__ == other.__forward_arg__ and 529 self.__forward_value__ == other.__forward_value__) 530 return self.__forward_arg__ == other.__forward_arg__ 531 532 def __hash__(self): 533 return hash(self.__forward_arg__) 534 535 def __repr__(self): 536 return f'ForwardRef({self.__forward_arg__!r})' 537 538 539class TypeVar(_Final, _Immutable, _root=True): 540 """Type variable. 541 542 Usage:: 543 544 T = TypeVar('T') # Can be anything 545 A = TypeVar('A', str, bytes) # Must be str or bytes 546 547 Type variables exist primarily for the benefit of static type 548 checkers. They serve as the parameters for generic types as well 549 as for generic function definitions. See class Generic for more 550 information on generic types. Generic functions work as follows: 551 552 def repeat(x: T, n: int) -> List[T]: 553 '''Return a list containing n references to x.''' 554 return [x]*n 555 556 def longest(x: A, y: A) -> A: 557 '''Return the longest of two strings.''' 558 return x if len(x) >= len(y) else y 559 560 The latter example's signature is essentially the overloading 561 of (str, str) -> str and (bytes, bytes) -> bytes. Also note 562 that if the arguments are instances of some subclass of str, 563 the return type is still plain str. 564 565 At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError. 566 567 Type variables defined with covariant=True or contravariant=True 568 can be used to declare covariant or contravariant generic types. 569 See PEP 484 for more details. By default generic types are invariant 570 in all type variables. 571 572 Type variables can be introspected. e.g.: 573 574 T.__name__ == 'T' 575 T.__constraints__ == () 576 T.__covariant__ == False 577 T.__contravariant__ = False 578 A.__constraints__ == (str, bytes) 579 580 Note that only type variables defined in global scope can be pickled. 581 """ 582 583 __slots__ = ('__name__', '__bound__', '__constraints__', 584 '__covariant__', '__contravariant__') 585 586 def __init__(self, name, *constraints, bound=None, 587 covariant=False, contravariant=False): 588 self.__name__ = name 589 if covariant and contravariant: 590 raise ValueError("Bivariant types are not supported.") 591 self.__covariant__ = bool(covariant) 592 self.__contravariant__ = bool(contravariant) 593 if constraints and bound is not None: 594 raise TypeError("Constraints cannot be combined with bound=...") 595 if constraints and len(constraints) == 1: 596 raise TypeError("A single constraint is not allowed") 597 msg = "TypeVar(name, constraint, ...): constraints must be types." 598 self.__constraints__ = tuple(_type_check(t, msg) for t in constraints) 599 if bound: 600 self.__bound__ = _type_check(bound, "Bound must be a type.") 601 else: 602 self.__bound__ = None 603 try: 604 def_mod = sys._getframe(1).f_globals.get('__name__', '__main__') # for pickling 605 except (AttributeError, ValueError): 606 def_mod = None 607 if def_mod != 'typing': 608 self.__module__ = def_mod 609 610 def __repr__(self): 611 if self.__covariant__: 612 prefix = '+' 613 elif self.__contravariant__: 614 prefix = '-' 615 else: 616 prefix = '~' 617 return prefix + self.__name__ 618 619 def __reduce__(self): 620 return self.__name__ 621 622 623# Special typing constructs Union, Optional, Generic, Callable and Tuple 624# use three special attributes for internal bookkeeping of generic types: 625# * __parameters__ is a tuple of unique free type parameters of a generic 626# type, for example, Dict[T, T].__parameters__ == (T,); 627# * __origin__ keeps a reference to a type that was subscripted, 628# e.g., Union[T, int].__origin__ == Union, or the non-generic version of 629# the type. 630# * __args__ is a tuple of all arguments used in subscripting, 631# e.g., Dict[T, int].__args__ == (T, int). 632 633 634# Mapping from non-generic type names that have a generic alias in typing 635# but with a different name. 636_normalize_alias = {'list': 'List', 637 'tuple': 'Tuple', 638 'dict': 'Dict', 639 'set': 'Set', 640 'frozenset': 'FrozenSet', 641 'deque': 'Deque', 642 'defaultdict': 'DefaultDict', 643 'type': 'Type', 644 'Set': 'AbstractSet'} 645 646def _is_dunder(attr): 647 return attr.startswith('__') and attr.endswith('__') 648 649 650class _GenericAlias(_Final, _root=True): 651 """The central part of internal API. 652 653 This represents a generic version of type 'origin' with type arguments 'params'. 654 There are two kind of these aliases: user defined and special. The special ones 655 are wrappers around builtin collections and ABCs in collections.abc. These must 656 have 'name' always set. If 'inst' is False, then the alias can't be instantiated, 657 this is used by e.g. typing.List and typing.Dict. 658 """ 659 def __init__(self, origin, params, *, inst=True, special=False, name=None): 660 self._inst = inst 661 self._special = special 662 if special and name is None: 663 orig_name = origin.__name__ 664 name = _normalize_alias.get(orig_name, orig_name) 665 self._name = name 666 if not isinstance(params, tuple): 667 params = (params,) 668 self.__origin__ = origin 669 self.__args__ = tuple(... if a is _TypingEllipsis else 670 () if a is _TypingEmpty else 671 a for a in params) 672 self.__parameters__ = _collect_type_vars(params) 673 self.__slots__ = None # This is not documented. 674 if not name: 675 self.__module__ = origin.__module__ 676 677 @_tp_cache 678 def __getitem__(self, params): 679 if self.__origin__ in (Generic, Protocol): 680 # Can't subscript Generic[...] or Protocol[...]. 681 raise TypeError(f"Cannot subscript already-subscripted {self}") 682 if not isinstance(params, tuple): 683 params = (params,) 684 msg = "Parameters to generic types must be types." 685 params = tuple(_type_check(p, msg) for p in params) 686 _check_generic(self, params) 687 return _subs_tvars(self, self.__parameters__, params) 688 689 def copy_with(self, params): 690 # We don't copy self._special. 691 return _GenericAlias(self.__origin__, params, name=self._name, inst=self._inst) 692 693 def __repr__(self): 694 if (self._name != 'Callable' or 695 len(self.__args__) == 2 and self.__args__[0] is Ellipsis): 696 if self._name: 697 name = 'typing.' + self._name 698 else: 699 name = _type_repr(self.__origin__) 700 if not self._special: 701 args = f'[{", ".join([_type_repr(a) for a in self.__args__])}]' 702 else: 703 args = '' 704 return (f'{name}{args}') 705 if self._special: 706 return 'typing.Callable' 707 return (f'typing.Callable' 708 f'[[{", ".join([_type_repr(a) for a in self.__args__[:-1]])}], ' 709 f'{_type_repr(self.__args__[-1])}]') 710 711 def __eq__(self, other): 712 if not isinstance(other, _GenericAlias): 713 return NotImplemented 714 if self.__origin__ != other.__origin__: 715 return False 716 if self.__origin__ is Union and other.__origin__ is Union: 717 return frozenset(self.__args__) == frozenset(other.__args__) 718 return self.__args__ == other.__args__ 719 720 def __hash__(self): 721 if self.__origin__ is Union: 722 return hash((Union, frozenset(self.__args__))) 723 return hash((self.__origin__, self.__args__)) 724 725 def __call__(self, *args, **kwargs): 726 if not self._inst: 727 raise TypeError(f"Type {self._name} cannot be instantiated; " 728 f"use {self._name.lower()}() instead") 729 result = self.__origin__(*args, **kwargs) 730 try: 731 result.__orig_class__ = self 732 except AttributeError: 733 pass 734 return result 735 736 def __mro_entries__(self, bases): 737 if self._name: # generic version of an ABC or built-in class 738 res = [] 739 if self.__origin__ not in bases: 740 res.append(self.__origin__) 741 i = bases.index(self) 742 if not any(isinstance(b, _GenericAlias) or issubclass(b, Generic) 743 for b in bases[i+1:]): 744 res.append(Generic) 745 return tuple(res) 746 if self.__origin__ is Generic: 747 if Protocol in bases: 748 return () 749 i = bases.index(self) 750 for b in bases[i+1:]: 751 if isinstance(b, _GenericAlias) and b is not self: 752 return () 753 return (self.__origin__,) 754 755 def __getattr__(self, attr): 756 # We are careful for copy and pickle. 757 # Also for simplicity we just don't relay all dunder names 758 if '__origin__' in self.__dict__ and not _is_dunder(attr): 759 return getattr(self.__origin__, attr) 760 raise AttributeError(attr) 761 762 def __setattr__(self, attr, val): 763 if _is_dunder(attr) or attr in ('_name', '_inst', '_special'): 764 super().__setattr__(attr, val) 765 else: 766 setattr(self.__origin__, attr, val) 767 768 def __instancecheck__(self, obj): 769 return self.__subclasscheck__(type(obj)) 770 771 def __subclasscheck__(self, cls): 772 if self._special: 773 if not isinstance(cls, _GenericAlias): 774 return issubclass(cls, self.__origin__) 775 if cls._special: 776 return issubclass(cls.__origin__, self.__origin__) 777 raise TypeError("Subscripted generics cannot be used with" 778 " class and instance checks") 779 780 def __reduce__(self): 781 if self._special: 782 return self._name 783 784 if self._name: 785 origin = globals()[self._name] 786 else: 787 origin = self.__origin__ 788 if (origin is Callable and 789 not (len(self.__args__) == 2 and self.__args__[0] is Ellipsis)): 790 args = list(self.__args__[:-1]), self.__args__[-1] 791 else: 792 args = tuple(self.__args__) 793 if len(args) == 1 and not isinstance(args[0], tuple): 794 args, = args 795 return operator.getitem, (origin, args) 796 797 798class _VariadicGenericAlias(_GenericAlias, _root=True): 799 """Same as _GenericAlias above but for variadic aliases. Currently, 800 this is used only by special internal aliases: Tuple and Callable. 801 """ 802 def __getitem__(self, params): 803 if self._name != 'Callable' or not self._special: 804 return self.__getitem_inner__(params) 805 if not isinstance(params, tuple) or len(params) != 2: 806 raise TypeError("Callable must be used as " 807 "Callable[[arg, ...], result].") 808 args, result = params 809 if args is Ellipsis: 810 params = (Ellipsis, result) 811 else: 812 if not isinstance(args, list): 813 raise TypeError(f"Callable[args, result]: args must be a list." 814 f" Got {args}") 815 params = (tuple(args), result) 816 return self.__getitem_inner__(params) 817 818 @_tp_cache 819 def __getitem_inner__(self, params): 820 if self.__origin__ is tuple and self._special: 821 if params == (): 822 return self.copy_with((_TypingEmpty,)) 823 if not isinstance(params, tuple): 824 params = (params,) 825 if len(params) == 2 and params[1] is ...: 826 msg = "Tuple[t, ...]: t must be a type." 827 p = _type_check(params[0], msg) 828 return self.copy_with((p, _TypingEllipsis)) 829 msg = "Tuple[t0, t1, ...]: each t must be a type." 830 params = tuple(_type_check(p, msg) for p in params) 831 return self.copy_with(params) 832 if self.__origin__ is collections.abc.Callable and self._special: 833 args, result = params 834 msg = "Callable[args, result]: result must be a type." 835 result = _type_check(result, msg) 836 if args is Ellipsis: 837 return self.copy_with((_TypingEllipsis, result)) 838 msg = "Callable[[arg, ...], result]: each arg must be a type." 839 args = tuple(_type_check(arg, msg) for arg in args) 840 params = args + (result,) 841 return self.copy_with(params) 842 return super().__getitem__(params) 843 844 845class Generic: 846 """Abstract base class for generic types. 847 848 A generic type is typically declared by inheriting from 849 this class parameterized with one or more type variables. 850 For example, a generic mapping type might be defined as:: 851 852 class Mapping(Generic[KT, VT]): 853 def __getitem__(self, key: KT) -> VT: 854 ... 855 # Etc. 856 857 This class can then be used as follows:: 858 859 def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT: 860 try: 861 return mapping[key] 862 except KeyError: 863 return default 864 """ 865 __slots__ = () 866 _is_protocol = False 867 868 def __new__(cls, *args, **kwds): 869 if cls in (Generic, Protocol): 870 raise TypeError(f"Type {cls.__name__} cannot be instantiated; " 871 "it can be used only as a base class") 872 if super().__new__ is object.__new__ and cls.__init__ is not object.__init__: 873 obj = super().__new__(cls) 874 else: 875 obj = super().__new__(cls, *args, **kwds) 876 return obj 877 878 @_tp_cache 879 def __class_getitem__(cls, params): 880 if not isinstance(params, tuple): 881 params = (params,) 882 if not params and cls is not Tuple: 883 raise TypeError( 884 f"Parameter list to {cls.__qualname__}[...] cannot be empty") 885 msg = "Parameters to generic types must be types." 886 params = tuple(_type_check(p, msg) for p in params) 887 if cls in (Generic, Protocol): 888 # Generic and Protocol can only be subscripted with unique type variables. 889 if not all(isinstance(p, TypeVar) for p in params): 890 raise TypeError( 891 f"Parameters to {cls.__name__}[...] must all be type variables") 892 if len(set(params)) != len(params): 893 raise TypeError( 894 f"Parameters to {cls.__name__}[...] must all be unique") 895 else: 896 # Subscripting a regular Generic subclass. 897 _check_generic(cls, params) 898 return _GenericAlias(cls, params) 899 900 def __init_subclass__(cls, *args, **kwargs): 901 super().__init_subclass__(*args, **kwargs) 902 tvars = [] 903 if '__orig_bases__' in cls.__dict__: 904 error = Generic in cls.__orig_bases__ 905 else: 906 error = Generic in cls.__bases__ and cls.__name__ != 'Protocol' 907 if error: 908 raise TypeError("Cannot inherit from plain Generic") 909 if '__orig_bases__' in cls.__dict__: 910 tvars = _collect_type_vars(cls.__orig_bases__) 911 # Look for Generic[T1, ..., Tn]. 912 # If found, tvars must be a subset of it. 913 # If not found, tvars is it. 914 # Also check for and reject plain Generic, 915 # and reject multiple Generic[...]. 916 gvars = None 917 for base in cls.__orig_bases__: 918 if (isinstance(base, _GenericAlias) and 919 base.__origin__ is Generic): 920 if gvars is not None: 921 raise TypeError( 922 "Cannot inherit from Generic[...] multiple types.") 923 gvars = base.__parameters__ 924 if gvars is not None: 925 tvarset = set(tvars) 926 gvarset = set(gvars) 927 if not tvarset <= gvarset: 928 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset) 929 s_args = ', '.join(str(g) for g in gvars) 930 raise TypeError(f"Some type variables ({s_vars}) are" 931 f" not listed in Generic[{s_args}]") 932 tvars = gvars 933 cls.__parameters__ = tuple(tvars) 934 935 936class _TypingEmpty: 937 """Internal placeholder for () or []. Used by TupleMeta and CallableMeta 938 to allow empty list/tuple in specific places, without allowing them 939 to sneak in where prohibited. 940 """ 941 942 943class _TypingEllipsis: 944 """Internal placeholder for ... (ellipsis).""" 945 946 947_TYPING_INTERNALS = ['__parameters__', '__orig_bases__', '__orig_class__', 948 '_is_protocol', '_is_runtime_protocol'] 949 950_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__', 951 '__init__', '__module__', '__new__', '__slots__', 952 '__subclasshook__', '__weakref__'] 953 954# These special attributes will be not collected as protocol members. 955EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker'] 956 957 958def _get_protocol_attrs(cls): 959 """Collect protocol members from a protocol class objects. 960 961 This includes names actually defined in the class dictionary, as well 962 as names that appear in annotations. Special names (above) are skipped. 963 """ 964 attrs = set() 965 for base in cls.__mro__[:-1]: # without object 966 if base.__name__ in ('Protocol', 'Generic'): 967 continue 968 annotations = getattr(base, '__annotations__', {}) 969 for attr in list(base.__dict__.keys()) + list(annotations.keys()): 970 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES: 971 attrs.add(attr) 972 return attrs 973 974 975def _is_callable_members_only(cls): 976 # PEP 544 prohibits using issubclass() with protocols that have non-method members. 977 return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls)) 978 979 980def _no_init(self, *args, **kwargs): 981 if type(self)._is_protocol: 982 raise TypeError('Protocols cannot be instantiated') 983 984 985def _allow_reckless_class_cheks(): 986 """Allow instnance and class checks for special stdlib modules. 987 988 The abc and functools modules indiscriminately call isinstance() and 989 issubclass() on the whole MRO of a user class, which may contain protocols. 990 """ 991 try: 992 return sys._getframe(3).f_globals['__name__'] in ['abc', 'functools'] 993 except (AttributeError, ValueError): # For platforms without _getframe(). 994 return True 995 996 997_PROTO_WHITELIST = { 998 'collections.abc': [ 999 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable', 1000 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible', 1001 ], 1002 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'], 1003} 1004 1005 1006class _ProtocolMeta(ABCMeta): 1007 # This metaclass is really unfortunate and exists only because of 1008 # the lack of __instancehook__. 1009 def __instancecheck__(cls, instance): 1010 # We need this method for situations where attributes are 1011 # assigned in __init__. 1012 if ((not getattr(cls, '_is_protocol', False) or 1013 _is_callable_members_only(cls)) and 1014 issubclass(instance.__class__, cls)): 1015 return True 1016 if cls._is_protocol: 1017 if all(hasattr(instance, attr) and 1018 # All *methods* can be blocked by setting them to None. 1019 (not callable(getattr(cls, attr, None)) or 1020 getattr(instance, attr) is not None) 1021 for attr in _get_protocol_attrs(cls)): 1022 return True 1023 return super().__instancecheck__(instance) 1024 1025 1026class Protocol(Generic, metaclass=_ProtocolMeta): 1027 """Base class for protocol classes. 1028 1029 Protocol classes are defined as:: 1030 1031 class Proto(Protocol): 1032 def meth(self) -> int: 1033 ... 1034 1035 Such classes are primarily used with static type checkers that recognize 1036 structural subtyping (static duck-typing), for example:: 1037 1038 class C: 1039 def meth(self) -> int: 1040 return 0 1041 1042 def func(x: Proto) -> int: 1043 return x.meth() 1044 1045 func(C()) # Passes static type check 1046 1047 See PEP 544 for details. Protocol classes decorated with 1048 @typing.runtime_checkable act as simple-minded runtime protocols that check 1049 only the presence of given attributes, ignoring their type signatures. 1050 Protocol classes can be generic, they are defined as:: 1051 1052 class GenProto(Protocol[T]): 1053 def meth(self) -> T: 1054 ... 1055 """ 1056 __slots__ = () 1057 _is_protocol = True 1058 _is_runtime_protocol = False 1059 1060 def __init_subclass__(cls, *args, **kwargs): 1061 super().__init_subclass__(*args, **kwargs) 1062 1063 # Determine if this is a protocol or a concrete subclass. 1064 if not cls.__dict__.get('_is_protocol', False): 1065 cls._is_protocol = any(b is Protocol for b in cls.__bases__) 1066 1067 # Set (or override) the protocol subclass hook. 1068 def _proto_hook(other): 1069 if not cls.__dict__.get('_is_protocol', False): 1070 return NotImplemented 1071 1072 # First, perform various sanity checks. 1073 if not getattr(cls, '_is_runtime_protocol', False): 1074 if _allow_reckless_class_cheks(): 1075 return NotImplemented 1076 raise TypeError("Instance and class checks can only be used with" 1077 " @runtime_checkable protocols") 1078 if not _is_callable_members_only(cls): 1079 if _allow_reckless_class_cheks(): 1080 return NotImplemented 1081 raise TypeError("Protocols with non-method members" 1082 " don't support issubclass()") 1083 if not isinstance(other, type): 1084 # Same error message as for issubclass(1, int). 1085 raise TypeError('issubclass() arg 1 must be a class') 1086 1087 # Second, perform the actual structural compatibility check. 1088 for attr in _get_protocol_attrs(cls): 1089 for base in other.__mro__: 1090 # Check if the members appears in the class dictionary... 1091 if attr in base.__dict__: 1092 if base.__dict__[attr] is None: 1093 return NotImplemented 1094 break 1095 1096 # ...or in annotations, if it is a sub-protocol. 1097 annotations = getattr(base, '__annotations__', {}) 1098 if (isinstance(annotations, collections.abc.Mapping) and 1099 attr in annotations and 1100 issubclass(other, Generic) and other._is_protocol): 1101 break 1102 else: 1103 return NotImplemented 1104 return True 1105 1106 if '__subclasshook__' not in cls.__dict__: 1107 cls.__subclasshook__ = _proto_hook 1108 1109 # We have nothing more to do for non-protocols... 1110 if not cls._is_protocol: 1111 return 1112 1113 # ... otherwise check consistency of bases, and prohibit instantiation. 1114 for base in cls.__bases__: 1115 if not (base in (object, Generic) or 1116 base.__module__ in _PROTO_WHITELIST and 1117 base.__name__ in _PROTO_WHITELIST[base.__module__] or 1118 issubclass(base, Generic) and base._is_protocol): 1119 raise TypeError('Protocols can only inherit from other' 1120 ' protocols, got %r' % base) 1121 cls.__init__ = _no_init 1122 1123 1124def runtime_checkable(cls): 1125 """Mark a protocol class as a runtime protocol. 1126 1127 Such protocol can be used with isinstance() and issubclass(). 1128 Raise TypeError if applied to a non-protocol class. 1129 This allows a simple-minded structural check very similar to 1130 one trick ponies in collections.abc such as Iterable. 1131 For example:: 1132 1133 @runtime_checkable 1134 class Closable(Protocol): 1135 def close(self): ... 1136 1137 assert isinstance(open('/some/file'), Closable) 1138 1139 Warning: this will check only the presence of the required methods, 1140 not their type signatures! 1141 """ 1142 if not issubclass(cls, Generic) or not cls._is_protocol: 1143 raise TypeError('@runtime_checkable can be only applied to protocol classes,' 1144 ' got %r' % cls) 1145 cls._is_runtime_protocol = True 1146 return cls 1147 1148 1149def cast(typ, val): 1150 """Cast a value to a type. 1151 1152 This returns the value unchanged. To the type checker this 1153 signals that the return value has the designated type, but at 1154 runtime we intentionally don't check anything (we want this 1155 to be as fast as possible). 1156 """ 1157 return val 1158 1159 1160def _get_defaults(func): 1161 """Internal helper to extract the default arguments, by name.""" 1162 try: 1163 code = func.__code__ 1164 except AttributeError: 1165 # Some built-in functions don't have __code__, __defaults__, etc. 1166 return {} 1167 pos_count = code.co_argcount 1168 arg_names = code.co_varnames 1169 arg_names = arg_names[:pos_count] 1170 defaults = func.__defaults__ or () 1171 kwdefaults = func.__kwdefaults__ 1172 res = dict(kwdefaults) if kwdefaults else {} 1173 pos_offset = pos_count - len(defaults) 1174 for name, value in zip(arg_names[pos_offset:], defaults): 1175 assert name not in res 1176 res[name] = value 1177 return res 1178 1179 1180_allowed_types = (types.FunctionType, types.BuiltinFunctionType, 1181 types.MethodType, types.ModuleType, 1182 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType) 1183 1184 1185def get_type_hints(obj, globalns=None, localns=None): 1186 """Return type hints for an object. 1187 1188 This is often the same as obj.__annotations__, but it handles 1189 forward references encoded as string literals, and if necessary 1190 adds Optional[t] if a default value equal to None is set. 1191 1192 The argument may be a module, class, method, or function. The annotations 1193 are returned as a dictionary. For classes, annotations include also 1194 inherited members. 1195 1196 TypeError is raised if the argument is not of a type that can contain 1197 annotations, and an empty dictionary is returned if no annotations are 1198 present. 1199 1200 BEWARE -- the behavior of globalns and localns is counterintuitive 1201 (unless you are familiar with how eval() and exec() work). The 1202 search order is locals first, then globals. 1203 1204 - If no dict arguments are passed, an attempt is made to use the 1205 globals from obj (or the respective module's globals for classes), 1206 and these are also used as the locals. If the object does not appear 1207 to have globals, an empty dictionary is used. 1208 1209 - If one dict argument is passed, it is used for both globals and 1210 locals. 1211 1212 - If two dict arguments are passed, they specify globals and 1213 locals, respectively. 1214 """ 1215 1216 if getattr(obj, '__no_type_check__', None): 1217 return {} 1218 # Classes require a special treatment. 1219 if isinstance(obj, type): 1220 hints = {} 1221 for base in reversed(obj.__mro__): 1222 if globalns is None: 1223 base_globals = sys.modules[base.__module__].__dict__ 1224 else: 1225 base_globals = globalns 1226 ann = base.__dict__.get('__annotations__', {}) 1227 for name, value in ann.items(): 1228 if value is None: 1229 value = type(None) 1230 if isinstance(value, str): 1231 value = ForwardRef(value, is_argument=False) 1232 value = _eval_type(value, base_globals, localns) 1233 hints[name] = value 1234 return hints 1235 1236 if globalns is None: 1237 if isinstance(obj, types.ModuleType): 1238 globalns = obj.__dict__ 1239 else: 1240 nsobj = obj 1241 # Find globalns for the unwrapped object. 1242 while hasattr(nsobj, '__wrapped__'): 1243 nsobj = nsobj.__wrapped__ 1244 globalns = getattr(nsobj, '__globals__', {}) 1245 if localns is None: 1246 localns = globalns 1247 elif localns is None: 1248 localns = globalns 1249 hints = getattr(obj, '__annotations__', None) 1250 if hints is None: 1251 # Return empty annotations for something that _could_ have them. 1252 if isinstance(obj, _allowed_types): 1253 return {} 1254 else: 1255 raise TypeError('{!r} is not a module, class, method, ' 1256 'or function.'.format(obj)) 1257 defaults = _get_defaults(obj) 1258 hints = dict(hints) 1259 for name, value in hints.items(): 1260 if value is None: 1261 value = type(None) 1262 if isinstance(value, str): 1263 value = ForwardRef(value) 1264 value = _eval_type(value, globalns, localns) 1265 if name in defaults and defaults[name] is None: 1266 value = Optional[value] 1267 hints[name] = value 1268 return hints 1269 1270 1271def get_origin(tp): 1272 """Get the unsubscripted version of a type. 1273 1274 This supports generic types, Callable, Tuple, Union, Literal, Final and ClassVar. 1275 Return None for unsupported types. Examples:: 1276 1277 get_origin(Literal[42]) is Literal 1278 get_origin(int) is None 1279 get_origin(ClassVar[int]) is ClassVar 1280 get_origin(Generic) is Generic 1281 get_origin(Generic[T]) is Generic 1282 get_origin(Union[T, int]) is Union 1283 get_origin(List[Tuple[T, T]][int]) == list 1284 """ 1285 if isinstance(tp, _GenericAlias): 1286 return tp.__origin__ 1287 if tp is Generic: 1288 return Generic 1289 return None 1290 1291 1292def get_args(tp): 1293 """Get type arguments with all substitutions performed. 1294 1295 For unions, basic simplifications used by Union constructor are performed. 1296 Examples:: 1297 get_args(Dict[str, int]) == (str, int) 1298 get_args(int) == () 1299 get_args(Union[int, Union[T, int], str][int]) == (int, str) 1300 get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) 1301 get_args(Callable[[], T][int]) == ([], int) 1302 """ 1303 if isinstance(tp, _GenericAlias) and not tp._special: 1304 res = tp.__args__ 1305 if get_origin(tp) is collections.abc.Callable and res[0] is not Ellipsis: 1306 res = (list(res[:-1]), res[-1]) 1307 return res 1308 return () 1309 1310 1311def no_type_check(arg): 1312 """Decorator to indicate that annotations are not type hints. 1313 1314 The argument must be a class or function; if it is a class, it 1315 applies recursively to all methods and classes defined in that class 1316 (but not to methods defined in its superclasses or subclasses). 1317 1318 This mutates the function(s) or class(es) in place. 1319 """ 1320 if isinstance(arg, type): 1321 arg_attrs = arg.__dict__.copy() 1322 for attr, val in arg.__dict__.items(): 1323 if val in arg.__bases__ + (arg,): 1324 arg_attrs.pop(attr) 1325 for obj in arg_attrs.values(): 1326 if isinstance(obj, types.FunctionType): 1327 obj.__no_type_check__ = True 1328 if isinstance(obj, type): 1329 no_type_check(obj) 1330 try: 1331 arg.__no_type_check__ = True 1332 except TypeError: # built-in classes 1333 pass 1334 return arg 1335 1336 1337def no_type_check_decorator(decorator): 1338 """Decorator to give another decorator the @no_type_check effect. 1339 1340 This wraps the decorator with something that wraps the decorated 1341 function in @no_type_check. 1342 """ 1343 1344 @functools.wraps(decorator) 1345 def wrapped_decorator(*args, **kwds): 1346 func = decorator(*args, **kwds) 1347 func = no_type_check(func) 1348 return func 1349 1350 return wrapped_decorator 1351 1352 1353def _overload_dummy(*args, **kwds): 1354 """Helper for @overload to raise when called.""" 1355 raise NotImplementedError( 1356 "You should not call an overloaded function. " 1357 "A series of @overload-decorated functions " 1358 "outside a stub module should always be followed " 1359 "by an implementation that is not @overload-ed.") 1360 1361 1362def overload(func): 1363 """Decorator for overloaded functions/methods. 1364 1365 In a stub file, place two or more stub definitions for the same 1366 function in a row, each decorated with @overload. For example: 1367 1368 @overload 1369 def utf8(value: None) -> None: ... 1370 @overload 1371 def utf8(value: bytes) -> bytes: ... 1372 @overload 1373 def utf8(value: str) -> bytes: ... 1374 1375 In a non-stub file (i.e. a regular .py file), do the same but 1376 follow it with an implementation. The implementation should *not* 1377 be decorated with @overload. For example: 1378 1379 @overload 1380 def utf8(value: None) -> None: ... 1381 @overload 1382 def utf8(value: bytes) -> bytes: ... 1383 @overload 1384 def utf8(value: str) -> bytes: ... 1385 def utf8(value): 1386 # implementation goes here 1387 """ 1388 return _overload_dummy 1389 1390 1391def final(f): 1392 """A decorator to indicate final methods and final classes. 1393 1394 Use this decorator to indicate to type checkers that the decorated 1395 method cannot be overridden, and decorated class cannot be subclassed. 1396 For example: 1397 1398 class Base: 1399 @final 1400 def done(self) -> None: 1401 ... 1402 class Sub(Base): 1403 def done(self) -> None: # Error reported by type checker 1404 ... 1405 1406 @final 1407 class Leaf: 1408 ... 1409 class Other(Leaf): # Error reported by type checker 1410 ... 1411 1412 There is no runtime checking of these properties. 1413 """ 1414 return f 1415 1416 1417# Some unconstrained type variables. These are used by the container types. 1418# (These are not for export.) 1419T = TypeVar('T') # Any type. 1420KT = TypeVar('KT') # Key type. 1421VT = TypeVar('VT') # Value type. 1422T_co = TypeVar('T_co', covariant=True) # Any type covariant containers. 1423V_co = TypeVar('V_co', covariant=True) # Any type covariant containers. 1424VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers. 1425T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant. 1426# Internal type variable used for Type[]. 1427CT_co = TypeVar('CT_co', covariant=True, bound=type) 1428 1429# A useful type variable with constraints. This represents string types. 1430# (This one *is* for export!) 1431AnyStr = TypeVar('AnyStr', bytes, str) 1432 1433 1434# Various ABCs mimicking those in collections.abc. 1435def _alias(origin, params, inst=True): 1436 return _GenericAlias(origin, params, special=True, inst=inst) 1437 1438Hashable = _alias(collections.abc.Hashable, ()) # Not generic. 1439Awaitable = _alias(collections.abc.Awaitable, T_co) 1440Coroutine = _alias(collections.abc.Coroutine, (T_co, T_contra, V_co)) 1441AsyncIterable = _alias(collections.abc.AsyncIterable, T_co) 1442AsyncIterator = _alias(collections.abc.AsyncIterator, T_co) 1443Iterable = _alias(collections.abc.Iterable, T_co) 1444Iterator = _alias(collections.abc.Iterator, T_co) 1445Reversible = _alias(collections.abc.Reversible, T_co) 1446Sized = _alias(collections.abc.Sized, ()) # Not generic. 1447Container = _alias(collections.abc.Container, T_co) 1448Collection = _alias(collections.abc.Collection, T_co) 1449Callable = _VariadicGenericAlias(collections.abc.Callable, (), special=True) 1450Callable.__doc__ = \ 1451 """Callable type; Callable[[int], str] is a function of (int) -> str. 1452 1453 The subscription syntax must always be used with exactly two 1454 values: the argument list and the return type. The argument list 1455 must be a list of types or ellipsis; the return type must be a single type. 1456 1457 There is no syntax to indicate optional or keyword arguments, 1458 such function types are rarely used as callback types. 1459 """ 1460AbstractSet = _alias(collections.abc.Set, T_co) 1461MutableSet = _alias(collections.abc.MutableSet, T) 1462# NOTE: Mapping is only covariant in the value type. 1463Mapping = _alias(collections.abc.Mapping, (KT, VT_co)) 1464MutableMapping = _alias(collections.abc.MutableMapping, (KT, VT)) 1465Sequence = _alias(collections.abc.Sequence, T_co) 1466MutableSequence = _alias(collections.abc.MutableSequence, T) 1467ByteString = _alias(collections.abc.ByteString, ()) # Not generic 1468Tuple = _VariadicGenericAlias(tuple, (), inst=False, special=True) 1469Tuple.__doc__ = \ 1470 """Tuple type; Tuple[X, Y] is the cross-product type of X and Y. 1471 1472 Example: Tuple[T1, T2] is a tuple of two elements corresponding 1473 to type variables T1 and T2. Tuple[int, float, str] is a tuple 1474 of an int, a float and a string. 1475 1476 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...]. 1477 """ 1478List = _alias(list, T, inst=False) 1479Deque = _alias(collections.deque, T) 1480Set = _alias(set, T, inst=False) 1481FrozenSet = _alias(frozenset, T_co, inst=False) 1482MappingView = _alias(collections.abc.MappingView, T_co) 1483KeysView = _alias(collections.abc.KeysView, KT) 1484ItemsView = _alias(collections.abc.ItemsView, (KT, VT_co)) 1485ValuesView = _alias(collections.abc.ValuesView, VT_co) 1486ContextManager = _alias(contextlib.AbstractContextManager, T_co) 1487AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, T_co) 1488Dict = _alias(dict, (KT, VT), inst=False) 1489DefaultDict = _alias(collections.defaultdict, (KT, VT)) 1490OrderedDict = _alias(collections.OrderedDict, (KT, VT)) 1491Counter = _alias(collections.Counter, T) 1492ChainMap = _alias(collections.ChainMap, (KT, VT)) 1493Generator = _alias(collections.abc.Generator, (T_co, T_contra, V_co)) 1494AsyncGenerator = _alias(collections.abc.AsyncGenerator, (T_co, T_contra)) 1495Type = _alias(type, CT_co, inst=False) 1496Type.__doc__ = \ 1497 """A special construct usable to annotate class objects. 1498 1499 For example, suppose we have the following classes:: 1500 1501 class User: ... # Abstract base for User classes 1502 class BasicUser(User): ... 1503 class ProUser(User): ... 1504 class TeamUser(User): ... 1505 1506 And a function that takes a class argument that's a subclass of 1507 User and returns an instance of the corresponding class:: 1508 1509 U = TypeVar('U', bound=User) 1510 def new_user(user_class: Type[U]) -> U: 1511 user = user_class() 1512 # (Here we could write the user object to a database) 1513 return user 1514 1515 joe = new_user(BasicUser) 1516 1517 At this point the type checker knows that joe has type BasicUser. 1518 """ 1519 1520 1521@runtime_checkable 1522class SupportsInt(Protocol): 1523 """An ABC with one abstract method __int__.""" 1524 __slots__ = () 1525 1526 @abstractmethod 1527 def __int__(self) -> int: 1528 pass 1529 1530 1531@runtime_checkable 1532class SupportsFloat(Protocol): 1533 """An ABC with one abstract method __float__.""" 1534 __slots__ = () 1535 1536 @abstractmethod 1537 def __float__(self) -> float: 1538 pass 1539 1540 1541@runtime_checkable 1542class SupportsComplex(Protocol): 1543 """An ABC with one abstract method __complex__.""" 1544 __slots__ = () 1545 1546 @abstractmethod 1547 def __complex__(self) -> complex: 1548 pass 1549 1550 1551@runtime_checkable 1552class SupportsBytes(Protocol): 1553 """An ABC with one abstract method __bytes__.""" 1554 __slots__ = () 1555 1556 @abstractmethod 1557 def __bytes__(self) -> bytes: 1558 pass 1559 1560 1561@runtime_checkable 1562class SupportsIndex(Protocol): 1563 """An ABC with one abstract method __index__.""" 1564 __slots__ = () 1565 1566 @abstractmethod 1567 def __index__(self) -> int: 1568 pass 1569 1570 1571@runtime_checkable 1572class SupportsAbs(Protocol[T_co]): 1573 """An ABC with one abstract method __abs__ that is covariant in its return type.""" 1574 __slots__ = () 1575 1576 @abstractmethod 1577 def __abs__(self) -> T_co: 1578 pass 1579 1580 1581@runtime_checkable 1582class SupportsRound(Protocol[T_co]): 1583 """An ABC with one abstract method __round__ that is covariant in its return type.""" 1584 __slots__ = () 1585 1586 @abstractmethod 1587 def __round__(self, ndigits: int = 0) -> T_co: 1588 pass 1589 1590 1591def _make_nmtuple(name, types): 1592 msg = "NamedTuple('Name', [(f0, t0), (f1, t1), ...]); each t must be a type" 1593 types = [(n, _type_check(t, msg)) for n, t in types] 1594 nm_tpl = collections.namedtuple(name, [n for n, t in types]) 1595 # Prior to PEP 526, only _field_types attribute was assigned. 1596 # Now __annotations__ are used and _field_types is deprecated (remove in 3.9) 1597 nm_tpl.__annotations__ = nm_tpl._field_types = dict(types) 1598 try: 1599 nm_tpl.__module__ = sys._getframe(2).f_globals.get('__name__', '__main__') 1600 except (AttributeError, ValueError): 1601 pass 1602 return nm_tpl 1603 1604 1605# attributes prohibited to set in NamedTuple class syntax 1606_prohibited = ('__new__', '__init__', '__slots__', '__getnewargs__', 1607 '_fields', '_field_defaults', '_field_types', 1608 '_make', '_replace', '_asdict', '_source') 1609 1610_special = ('__module__', '__name__', '__annotations__') 1611 1612 1613class NamedTupleMeta(type): 1614 1615 def __new__(cls, typename, bases, ns): 1616 if ns.get('_root', False): 1617 return super().__new__(cls, typename, bases, ns) 1618 types = ns.get('__annotations__', {}) 1619 nm_tpl = _make_nmtuple(typename, types.items()) 1620 defaults = [] 1621 defaults_dict = {} 1622 for field_name in types: 1623 if field_name in ns: 1624 default_value = ns[field_name] 1625 defaults.append(default_value) 1626 defaults_dict[field_name] = default_value 1627 elif defaults: 1628 raise TypeError("Non-default namedtuple field {field_name} cannot " 1629 "follow default field(s) {default_names}" 1630 .format(field_name=field_name, 1631 default_names=', '.join(defaults_dict.keys()))) 1632 nm_tpl.__new__.__annotations__ = dict(types) 1633 nm_tpl.__new__.__defaults__ = tuple(defaults) 1634 nm_tpl._field_defaults = defaults_dict 1635 # update from user namespace without overriding special namedtuple attributes 1636 for key in ns: 1637 if key in _prohibited: 1638 raise AttributeError("Cannot overwrite NamedTuple attribute " + key) 1639 elif key not in _special and key not in nm_tpl._fields: 1640 setattr(nm_tpl, key, ns[key]) 1641 return nm_tpl 1642 1643 1644class NamedTuple(metaclass=NamedTupleMeta): 1645 """Typed version of namedtuple. 1646 1647 Usage in Python versions >= 3.6:: 1648 1649 class Employee(NamedTuple): 1650 name: str 1651 id: int 1652 1653 This is equivalent to:: 1654 1655 Employee = collections.namedtuple('Employee', ['name', 'id']) 1656 1657 The resulting class has an extra __annotations__ attribute, giving a 1658 dict that maps field names to types. (The field names are also in 1659 the _fields attribute, which is part of the namedtuple API.) 1660 Alternative equivalent keyword syntax is also accepted:: 1661 1662 Employee = NamedTuple('Employee', name=str, id=int) 1663 1664 In Python versions <= 3.5 use:: 1665 1666 Employee = NamedTuple('Employee', [('name', str), ('id', int)]) 1667 """ 1668 _root = True 1669 1670 def __new__(*args, **kwargs): 1671 if not args: 1672 raise TypeError('NamedTuple.__new__(): not enough arguments') 1673 cls, *args = args # allow the "cls" keyword be passed 1674 if args: 1675 typename, *args = args # allow the "typename" keyword be passed 1676 elif 'typename' in kwargs: 1677 typename = kwargs.pop('typename') 1678 import warnings 1679 warnings.warn("Passing 'typename' as keyword argument is deprecated", 1680 DeprecationWarning, stacklevel=2) 1681 else: 1682 raise TypeError("NamedTuple.__new__() missing 1 required positional " 1683 "argument: 'typename'") 1684 if args: 1685 try: 1686 fields, = args # allow the "fields" keyword be passed 1687 except ValueError: 1688 raise TypeError(f'NamedTuple.__new__() takes from 2 to 3 ' 1689 f'positional arguments but {len(args) + 2} ' 1690 f'were given') from None 1691 elif 'fields' in kwargs and len(kwargs) == 1: 1692 fields = kwargs.pop('fields') 1693 import warnings 1694 warnings.warn("Passing 'fields' as keyword argument is deprecated", 1695 DeprecationWarning, stacklevel=2) 1696 else: 1697 fields = None 1698 1699 if fields is None: 1700 fields = kwargs.items() 1701 elif kwargs: 1702 raise TypeError("Either list of fields or keywords" 1703 " can be provided to NamedTuple, not both") 1704 return _make_nmtuple(typename, fields) 1705 __new__.__text_signature__ = '($cls, typename, fields=None, /, **kwargs)' 1706 1707 1708def _dict_new(cls, /, *args, **kwargs): 1709 return dict(*args, **kwargs) 1710 1711 1712def _typeddict_new(cls, typename, fields=None, /, *, total=True, **kwargs): 1713 if fields is None: 1714 fields = kwargs 1715 elif kwargs: 1716 raise TypeError("TypedDict takes either a dict or keyword arguments," 1717 " but not both") 1718 1719 ns = {'__annotations__': dict(fields), '__total__': total} 1720 try: 1721 # Setting correct module is necessary to make typed dict classes pickleable. 1722 ns['__module__'] = sys._getframe(1).f_globals.get('__name__', '__main__') 1723 except (AttributeError, ValueError): 1724 pass 1725 1726 return _TypedDictMeta(typename, (), ns) 1727 1728 1729def _check_fails(cls, other): 1730 # Typed dicts are only for static structural subtyping. 1731 raise TypeError('TypedDict does not support instance and class checks') 1732 1733 1734class _TypedDictMeta(type): 1735 def __new__(cls, name, bases, ns, total=True): 1736 """Create new typed dict class object. 1737 1738 This method is called directly when TypedDict is subclassed, 1739 or via _typeddict_new when TypedDict is instantiated. This way 1740 TypedDict supports all three syntax forms described in its docstring. 1741 Subclasses and instances of TypedDict return actual dictionaries 1742 via _dict_new. 1743 """ 1744 ns['__new__'] = _typeddict_new if name == 'TypedDict' else _dict_new 1745 tp_dict = super(_TypedDictMeta, cls).__new__(cls, name, (dict,), ns) 1746 1747 anns = ns.get('__annotations__', {}) 1748 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type" 1749 anns = {n: _type_check(tp, msg) for n, tp in anns.items()} 1750 for base in bases: 1751 anns.update(base.__dict__.get('__annotations__', {})) 1752 tp_dict.__annotations__ = anns 1753 if not hasattr(tp_dict, '__total__'): 1754 tp_dict.__total__ = total 1755 return tp_dict 1756 1757 __instancecheck__ = __subclasscheck__ = _check_fails 1758 1759 1760class TypedDict(dict, metaclass=_TypedDictMeta): 1761 """A simple typed namespace. At runtime it is equivalent to a plain dict. 1762 1763 TypedDict creates a dictionary type that expects all of its 1764 instances to have a certain set of keys, where each key is 1765 associated with a value of a consistent type. This expectation 1766 is not checked at runtime but is only enforced by type checkers. 1767 Usage:: 1768 1769 class Point2D(TypedDict): 1770 x: int 1771 y: int 1772 label: str 1773 1774 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK 1775 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check 1776 1777 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') 1778 1779 The type info can be accessed via Point2D.__annotations__. TypedDict 1780 supports two additional equivalent forms:: 1781 1782 Point2D = TypedDict('Point2D', x=int, y=int, label=str) 1783 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) 1784 1785 By default, all keys must be present in a TypedDict. It is possible 1786 to override this by specifying totality. 1787 Usage:: 1788 1789 class point2D(TypedDict, total=False): 1790 x: int 1791 y: int 1792 1793 This means that a point2D TypedDict can have any of the keys omitted.A type 1794 checker is only expected to support a literal False or True as the value of 1795 the total argument. True is the default, and makes all items defined in the 1796 class body be required. 1797 1798 The class syntax is only supported in Python 3.6+, while two other 1799 syntax forms work for Python 2.7 and 3.2+ 1800 """ 1801 1802 1803def NewType(name, tp): 1804 """NewType creates simple unique types with almost zero 1805 runtime overhead. NewType(name, tp) is considered a subtype of tp 1806 by static type checkers. At runtime, NewType(name, tp) returns 1807 a dummy function that simply returns its argument. Usage:: 1808 1809 UserId = NewType('UserId', int) 1810 1811 def name_by_id(user_id: UserId) -> str: 1812 ... 1813 1814 UserId('user') # Fails type check 1815 1816 name_by_id(42) # Fails type check 1817 name_by_id(UserId(42)) # OK 1818 1819 num = UserId(5) + 1 # type: int 1820 """ 1821 1822 def new_type(x): 1823 return x 1824 1825 new_type.__name__ = name 1826 new_type.__supertype__ = tp 1827 return new_type 1828 1829 1830# Python-version-specific alias (Python 2: unicode; Python 3: str) 1831Text = str 1832 1833 1834# Constant that's True when type checking, but False here. 1835TYPE_CHECKING = False 1836 1837 1838class IO(Generic[AnyStr]): 1839 """Generic base class for TextIO and BinaryIO. 1840 1841 This is an abstract, generic version of the return of open(). 1842 1843 NOTE: This does not distinguish between the different possible 1844 classes (text vs. binary, read vs. write vs. read/write, 1845 append-only, unbuffered). The TextIO and BinaryIO subclasses 1846 below capture the distinctions between text vs. binary, which is 1847 pervasive in the interface; however we currently do not offer a 1848 way to track the other distinctions in the type system. 1849 """ 1850 1851 __slots__ = () 1852 1853 @property 1854 @abstractmethod 1855 def mode(self) -> str: 1856 pass 1857 1858 @property 1859 @abstractmethod 1860 def name(self) -> str: 1861 pass 1862 1863 @abstractmethod 1864 def close(self) -> None: 1865 pass 1866 1867 @property 1868 @abstractmethod 1869 def closed(self) -> bool: 1870 pass 1871 1872 @abstractmethod 1873 def fileno(self) -> int: 1874 pass 1875 1876 @abstractmethod 1877 def flush(self) -> None: 1878 pass 1879 1880 @abstractmethod 1881 def isatty(self) -> bool: 1882 pass 1883 1884 @abstractmethod 1885 def read(self, n: int = -1) -> AnyStr: 1886 pass 1887 1888 @abstractmethod 1889 def readable(self) -> bool: 1890 pass 1891 1892 @abstractmethod 1893 def readline(self, limit: int = -1) -> AnyStr: 1894 pass 1895 1896 @abstractmethod 1897 def readlines(self, hint: int = -1) -> List[AnyStr]: 1898 pass 1899 1900 @abstractmethod 1901 def seek(self, offset: int, whence: int = 0) -> int: 1902 pass 1903 1904 @abstractmethod 1905 def seekable(self) -> bool: 1906 pass 1907 1908 @abstractmethod 1909 def tell(self) -> int: 1910 pass 1911 1912 @abstractmethod 1913 def truncate(self, size: int = None) -> int: 1914 pass 1915 1916 @abstractmethod 1917 def writable(self) -> bool: 1918 pass 1919 1920 @abstractmethod 1921 def write(self, s: AnyStr) -> int: 1922 pass 1923 1924 @abstractmethod 1925 def writelines(self, lines: List[AnyStr]) -> None: 1926 pass 1927 1928 @abstractmethod 1929 def __enter__(self) -> 'IO[AnyStr]': 1930 pass 1931 1932 @abstractmethod 1933 def __exit__(self, type, value, traceback) -> None: 1934 pass 1935 1936 1937class BinaryIO(IO[bytes]): 1938 """Typed version of the return of open() in binary mode.""" 1939 1940 __slots__ = () 1941 1942 @abstractmethod 1943 def write(self, s: Union[bytes, bytearray]) -> int: 1944 pass 1945 1946 @abstractmethod 1947 def __enter__(self) -> 'BinaryIO': 1948 pass 1949 1950 1951class TextIO(IO[str]): 1952 """Typed version of the return of open() in text mode.""" 1953 1954 __slots__ = () 1955 1956 @property 1957 @abstractmethod 1958 def buffer(self) -> BinaryIO: 1959 pass 1960 1961 @property 1962 @abstractmethod 1963 def encoding(self) -> str: 1964 pass 1965 1966 @property 1967 @abstractmethod 1968 def errors(self) -> Optional[str]: 1969 pass 1970 1971 @property 1972 @abstractmethod 1973 def line_buffering(self) -> bool: 1974 pass 1975 1976 @property 1977 @abstractmethod 1978 def newlines(self) -> Any: 1979 pass 1980 1981 @abstractmethod 1982 def __enter__(self) -> 'TextIO': 1983 pass 1984 1985 1986class io: 1987 """Wrapper namespace for IO generic classes.""" 1988 1989 __all__ = ['IO', 'TextIO', 'BinaryIO'] 1990 IO = IO 1991 TextIO = TextIO 1992 BinaryIO = BinaryIO 1993 1994 1995io.__name__ = __name__ + '.io' 1996sys.modules[io.__name__] = io 1997 1998Pattern = _alias(stdlib_re.Pattern, AnyStr) 1999Match = _alias(stdlib_re.Match, AnyStr) 2000 2001class re: 2002 """Wrapper namespace for re type aliases.""" 2003 2004 __all__ = ['Pattern', 'Match'] 2005 Pattern = Pattern 2006 Match = Match 2007 2008 2009re.__name__ = __name__ + '.re' 2010sys.modules[re.__name__] = re 2011