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 (may be added soon). 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 def_mod = sys._getframe(1).f_globals['__name__'] # for pickling 604 if def_mod != 'typing': 605 self.__module__ = def_mod 606 607 def __repr__(self): 608 if self.__covariant__: 609 prefix = '+' 610 elif self.__contravariant__: 611 prefix = '-' 612 else: 613 prefix = '~' 614 return prefix + self.__name__ 615 616 def __reduce__(self): 617 return self.__name__ 618 619 620# Special typing constructs Union, Optional, Generic, Callable and Tuple 621# use three special attributes for internal bookkeeping of generic types: 622# * __parameters__ is a tuple of unique free type parameters of a generic 623# type, for example, Dict[T, T].__parameters__ == (T,); 624# * __origin__ keeps a reference to a type that was subscripted, 625# e.g., Union[T, int].__origin__ == Union, or the non-generic version of 626# the type. 627# * __args__ is a tuple of all arguments used in subscripting, 628# e.g., Dict[T, int].__args__ == (T, int). 629 630 631# Mapping from non-generic type names that have a generic alias in typing 632# but with a different name. 633_normalize_alias = {'list': 'List', 634 'tuple': 'Tuple', 635 'dict': 'Dict', 636 'set': 'Set', 637 'frozenset': 'FrozenSet', 638 'deque': 'Deque', 639 'defaultdict': 'DefaultDict', 640 'type': 'Type', 641 'Set': 'AbstractSet'} 642 643def _is_dunder(attr): 644 return attr.startswith('__') and attr.endswith('__') 645 646 647class _GenericAlias(_Final, _root=True): 648 """The central part of internal API. 649 650 This represents a generic version of type 'origin' with type arguments 'params'. 651 There are two kind of these aliases: user defined and special. The special ones 652 are wrappers around builtin collections and ABCs in collections.abc. These must 653 have 'name' always set. If 'inst' is False, then the alias can't be instantiated, 654 this is used by e.g. typing.List and typing.Dict. 655 """ 656 def __init__(self, origin, params, *, inst=True, special=False, name=None): 657 self._inst = inst 658 self._special = special 659 if special and name is None: 660 orig_name = origin.__name__ 661 name = _normalize_alias.get(orig_name, orig_name) 662 self._name = name 663 if not isinstance(params, tuple): 664 params = (params,) 665 self.__origin__ = origin 666 self.__args__ = tuple(... if a is _TypingEllipsis else 667 () if a is _TypingEmpty else 668 a for a in params) 669 self.__parameters__ = _collect_type_vars(params) 670 self.__slots__ = None # This is not documented. 671 if not name: 672 self.__module__ = origin.__module__ 673 674 @_tp_cache 675 def __getitem__(self, params): 676 if self.__origin__ in (Generic, Protocol): 677 # Can't subscript Generic[...] or Protocol[...]. 678 raise TypeError(f"Cannot subscript already-subscripted {self}") 679 if not isinstance(params, tuple): 680 params = (params,) 681 msg = "Parameters to generic types must be types." 682 params = tuple(_type_check(p, msg) for p in params) 683 _check_generic(self, params) 684 return _subs_tvars(self, self.__parameters__, params) 685 686 def copy_with(self, params): 687 # We don't copy self._special. 688 return _GenericAlias(self.__origin__, params, name=self._name, inst=self._inst) 689 690 def __repr__(self): 691 if (self._name != 'Callable' or 692 len(self.__args__) == 2 and self.__args__[0] is Ellipsis): 693 if self._name: 694 name = 'typing.' + self._name 695 else: 696 name = _type_repr(self.__origin__) 697 if not self._special: 698 args = f'[{", ".join([_type_repr(a) for a in self.__args__])}]' 699 else: 700 args = '' 701 return (f'{name}{args}') 702 if self._special: 703 return 'typing.Callable' 704 return (f'typing.Callable' 705 f'[[{", ".join([_type_repr(a) for a in self.__args__[:-1]])}], ' 706 f'{_type_repr(self.__args__[-1])}]') 707 708 def __eq__(self, other): 709 if not isinstance(other, _GenericAlias): 710 return NotImplemented 711 if self.__origin__ != other.__origin__: 712 return False 713 if self.__origin__ is Union and other.__origin__ is Union: 714 return frozenset(self.__args__) == frozenset(other.__args__) 715 return self.__args__ == other.__args__ 716 717 def __hash__(self): 718 if self.__origin__ is Union: 719 return hash((Union, frozenset(self.__args__))) 720 return hash((self.__origin__, self.__args__)) 721 722 def __call__(self, *args, **kwargs): 723 if not self._inst: 724 raise TypeError(f"Type {self._name} cannot be instantiated; " 725 f"use {self._name.lower()}() instead") 726 result = self.__origin__(*args, **kwargs) 727 try: 728 result.__orig_class__ = self 729 except AttributeError: 730 pass 731 return result 732 733 def __mro_entries__(self, bases): 734 if self._name: # generic version of an ABC or built-in class 735 res = [] 736 if self.__origin__ not in bases: 737 res.append(self.__origin__) 738 i = bases.index(self) 739 if not any(isinstance(b, _GenericAlias) or issubclass(b, Generic) 740 for b in bases[i+1:]): 741 res.append(Generic) 742 return tuple(res) 743 if self.__origin__ is Generic: 744 if Protocol in bases: 745 return () 746 i = bases.index(self) 747 for b in bases[i+1:]: 748 if isinstance(b, _GenericAlias) and b is not self: 749 return () 750 return (self.__origin__,) 751 752 def __getattr__(self, attr): 753 # We are careful for copy and pickle. 754 # Also for simplicity we just don't relay all dunder names 755 if '__origin__' in self.__dict__ and not _is_dunder(attr): 756 return getattr(self.__origin__, attr) 757 raise AttributeError(attr) 758 759 def __setattr__(self, attr, val): 760 if _is_dunder(attr) or attr in ('_name', '_inst', '_special'): 761 super().__setattr__(attr, val) 762 else: 763 setattr(self.__origin__, attr, val) 764 765 def __instancecheck__(self, obj): 766 return self.__subclasscheck__(type(obj)) 767 768 def __subclasscheck__(self, cls): 769 if self._special: 770 if not isinstance(cls, _GenericAlias): 771 return issubclass(cls, self.__origin__) 772 if cls._special: 773 return issubclass(cls.__origin__, self.__origin__) 774 raise TypeError("Subscripted generics cannot be used with" 775 " class and instance checks") 776 777 def __reduce__(self): 778 if self._special: 779 return self._name 780 781 if self._name: 782 origin = globals()[self._name] 783 else: 784 origin = self.__origin__ 785 if (origin is Callable and 786 not (len(self.__args__) == 2 and self.__args__[0] is Ellipsis)): 787 args = list(self.__args__[:-1]), self.__args__[-1] 788 else: 789 args = tuple(self.__args__) 790 if len(args) == 1 and not isinstance(args[0], tuple): 791 args, = args 792 return operator.getitem, (origin, args) 793 794 795class _VariadicGenericAlias(_GenericAlias, _root=True): 796 """Same as _GenericAlias above but for variadic aliases. Currently, 797 this is used only by special internal aliases: Tuple and Callable. 798 """ 799 def __getitem__(self, params): 800 if self._name != 'Callable' or not self._special: 801 return self.__getitem_inner__(params) 802 if not isinstance(params, tuple) or len(params) != 2: 803 raise TypeError("Callable must be used as " 804 "Callable[[arg, ...], result].") 805 args, result = params 806 if args is Ellipsis: 807 params = (Ellipsis, result) 808 else: 809 if not isinstance(args, list): 810 raise TypeError(f"Callable[args, result]: args must be a list." 811 f" Got {args}") 812 params = (tuple(args), result) 813 return self.__getitem_inner__(params) 814 815 @_tp_cache 816 def __getitem_inner__(self, params): 817 if self.__origin__ is tuple and self._special: 818 if params == (): 819 return self.copy_with((_TypingEmpty,)) 820 if not isinstance(params, tuple): 821 params = (params,) 822 if len(params) == 2 and params[1] is ...: 823 msg = "Tuple[t, ...]: t must be a type." 824 p = _type_check(params[0], msg) 825 return self.copy_with((p, _TypingEllipsis)) 826 msg = "Tuple[t0, t1, ...]: each t must be a type." 827 params = tuple(_type_check(p, msg) for p in params) 828 return self.copy_with(params) 829 if self.__origin__ is collections.abc.Callable and self._special: 830 args, result = params 831 msg = "Callable[args, result]: result must be a type." 832 result = _type_check(result, msg) 833 if args is Ellipsis: 834 return self.copy_with((_TypingEllipsis, result)) 835 msg = "Callable[[arg, ...], result]: each arg must be a type." 836 args = tuple(_type_check(arg, msg) for arg in args) 837 params = args + (result,) 838 return self.copy_with(params) 839 return super().__getitem__(params) 840 841 842class Generic: 843 """Abstract base class for generic types. 844 845 A generic type is typically declared by inheriting from 846 this class parameterized with one or more type variables. 847 For example, a generic mapping type might be defined as:: 848 849 class Mapping(Generic[KT, VT]): 850 def __getitem__(self, key: KT) -> VT: 851 ... 852 # Etc. 853 854 This class can then be used as follows:: 855 856 def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT: 857 try: 858 return mapping[key] 859 except KeyError: 860 return default 861 """ 862 __slots__ = () 863 _is_protocol = False 864 865 def __new__(cls, *args, **kwds): 866 if cls in (Generic, Protocol): 867 raise TypeError(f"Type {cls.__name__} cannot be instantiated; " 868 "it can be used only as a base class") 869 if super().__new__ is object.__new__ and cls.__init__ is not object.__init__: 870 obj = super().__new__(cls) 871 else: 872 obj = super().__new__(cls, *args, **kwds) 873 return obj 874 875 @_tp_cache 876 def __class_getitem__(cls, params): 877 if not isinstance(params, tuple): 878 params = (params,) 879 if not params and cls is not Tuple: 880 raise TypeError( 881 f"Parameter list to {cls.__qualname__}[...] cannot be empty") 882 msg = "Parameters to generic types must be types." 883 params = tuple(_type_check(p, msg) for p in params) 884 if cls in (Generic, Protocol): 885 # Generic and Protocol can only be subscripted with unique type variables. 886 if not all(isinstance(p, TypeVar) for p in params): 887 raise TypeError( 888 f"Parameters to {cls.__name__}[...] must all be type variables") 889 if len(set(params)) != len(params): 890 raise TypeError( 891 f"Parameters to {cls.__name__}[...] must all be unique") 892 else: 893 # Subscripting a regular Generic subclass. 894 _check_generic(cls, params) 895 return _GenericAlias(cls, params) 896 897 def __init_subclass__(cls, *args, **kwargs): 898 super().__init_subclass__(*args, **kwargs) 899 tvars = [] 900 if '__orig_bases__' in cls.__dict__: 901 error = Generic in cls.__orig_bases__ 902 else: 903 error = Generic in cls.__bases__ and cls.__name__ != 'Protocol' 904 if error: 905 raise TypeError("Cannot inherit from plain Generic") 906 if '__orig_bases__' in cls.__dict__: 907 tvars = _collect_type_vars(cls.__orig_bases__) 908 # Look for Generic[T1, ..., Tn]. 909 # If found, tvars must be a subset of it. 910 # If not found, tvars is it. 911 # Also check for and reject plain Generic, 912 # and reject multiple Generic[...]. 913 gvars = None 914 for base in cls.__orig_bases__: 915 if (isinstance(base, _GenericAlias) and 916 base.__origin__ is Generic): 917 if gvars is not None: 918 raise TypeError( 919 "Cannot inherit from Generic[...] multiple types.") 920 gvars = base.__parameters__ 921 if gvars is not None: 922 tvarset = set(tvars) 923 gvarset = set(gvars) 924 if not tvarset <= gvarset: 925 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset) 926 s_args = ', '.join(str(g) for g in gvars) 927 raise TypeError(f"Some type variables ({s_vars}) are" 928 f" not listed in Generic[{s_args}]") 929 tvars = gvars 930 cls.__parameters__ = tuple(tvars) 931 932 933class _TypingEmpty: 934 """Internal placeholder for () or []. Used by TupleMeta and CallableMeta 935 to allow empty list/tuple in specific places, without allowing them 936 to sneak in where prohibited. 937 """ 938 939 940class _TypingEllipsis: 941 """Internal placeholder for ... (ellipsis).""" 942 943 944_TYPING_INTERNALS = ['__parameters__', '__orig_bases__', '__orig_class__', 945 '_is_protocol', '_is_runtime_protocol'] 946 947_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__', 948 '__init__', '__module__', '__new__', '__slots__', 949 '__subclasshook__', '__weakref__'] 950 951# These special attributes will be not collected as protocol members. 952EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker'] 953 954 955def _get_protocol_attrs(cls): 956 """Collect protocol members from a protocol class objects. 957 958 This includes names actually defined in the class dictionary, as well 959 as names that appear in annotations. Special names (above) are skipped. 960 """ 961 attrs = set() 962 for base in cls.__mro__[:-1]: # without object 963 if base.__name__ in ('Protocol', 'Generic'): 964 continue 965 annotations = getattr(base, '__annotations__', {}) 966 for attr in list(base.__dict__.keys()) + list(annotations.keys()): 967 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES: 968 attrs.add(attr) 969 return attrs 970 971 972def _is_callable_members_only(cls): 973 # PEP 544 prohibits using issubclass() with protocols that have non-method members. 974 return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls)) 975 976 977def _no_init(self, *args, **kwargs): 978 if type(self)._is_protocol: 979 raise TypeError('Protocols cannot be instantiated') 980 981 982def _allow_reckless_class_cheks(): 983 """Allow instnance and class checks for special stdlib modules. 984 985 The abc and functools modules indiscriminately call isinstance() and 986 issubclass() on the whole MRO of a user class, which may contain protocols. 987 """ 988 try: 989 return sys._getframe(3).f_globals['__name__'] in ['abc', 'functools'] 990 except (AttributeError, ValueError): # For platforms without _getframe(). 991 return True 992 993 994_PROTO_WHITELIST = { 995 'collections.abc': [ 996 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable', 997 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible', 998 ], 999 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'], 1000} 1001 1002 1003class _ProtocolMeta(ABCMeta): 1004 # This metaclass is really unfortunate and exists only because of 1005 # the lack of __instancehook__. 1006 def __instancecheck__(cls, instance): 1007 # We need this method for situations where attributes are 1008 # assigned in __init__. 1009 if ((not getattr(cls, '_is_protocol', False) or 1010 _is_callable_members_only(cls)) and 1011 issubclass(instance.__class__, cls)): 1012 return True 1013 if cls._is_protocol: 1014 if all(hasattr(instance, attr) and 1015 # All *methods* can be blocked by setting them to None. 1016 (not callable(getattr(cls, attr, None)) or 1017 getattr(instance, attr) is not None) 1018 for attr in _get_protocol_attrs(cls)): 1019 return True 1020 return super().__instancecheck__(instance) 1021 1022 1023class Protocol(Generic, metaclass=_ProtocolMeta): 1024 """Base class for protocol classes. 1025 1026 Protocol classes are defined as:: 1027 1028 class Proto(Protocol): 1029 def meth(self) -> int: 1030 ... 1031 1032 Such classes are primarily used with static type checkers that recognize 1033 structural subtyping (static duck-typing), for example:: 1034 1035 class C: 1036 def meth(self) -> int: 1037 return 0 1038 1039 def func(x: Proto) -> int: 1040 return x.meth() 1041 1042 func(C()) # Passes static type check 1043 1044 See PEP 544 for details. Protocol classes decorated with 1045 @typing.runtime_checkable act as simple-minded runtime protocols that check 1046 only the presence of given attributes, ignoring their type signatures. 1047 Protocol classes can be generic, they are defined as:: 1048 1049 class GenProto(Protocol[T]): 1050 def meth(self) -> T: 1051 ... 1052 """ 1053 __slots__ = () 1054 _is_protocol = True 1055 _is_runtime_protocol = False 1056 1057 def __init_subclass__(cls, *args, **kwargs): 1058 super().__init_subclass__(*args, **kwargs) 1059 1060 # Determine if this is a protocol or a concrete subclass. 1061 if not cls.__dict__.get('_is_protocol', False): 1062 cls._is_protocol = any(b is Protocol for b in cls.__bases__) 1063 1064 # Set (or override) the protocol subclass hook. 1065 def _proto_hook(other): 1066 if not cls.__dict__.get('_is_protocol', False): 1067 return NotImplemented 1068 1069 # First, perform various sanity checks. 1070 if not getattr(cls, '_is_runtime_protocol', False): 1071 if _allow_reckless_class_cheks(): 1072 return NotImplemented 1073 raise TypeError("Instance and class checks can only be used with" 1074 " @runtime_checkable protocols") 1075 if not _is_callable_members_only(cls): 1076 if _allow_reckless_class_cheks(): 1077 return NotImplemented 1078 raise TypeError("Protocols with non-method members" 1079 " don't support issubclass()") 1080 if not isinstance(other, type): 1081 # Same error message as for issubclass(1, int). 1082 raise TypeError('issubclass() arg 1 must be a class') 1083 1084 # Second, perform the actual structural compatibility check. 1085 for attr in _get_protocol_attrs(cls): 1086 for base in other.__mro__: 1087 # Check if the members appears in the class dictionary... 1088 if attr in base.__dict__: 1089 if base.__dict__[attr] is None: 1090 return NotImplemented 1091 break 1092 1093 # ...or in annotations, if it is a sub-protocol. 1094 annotations = getattr(base, '__annotations__', {}) 1095 if (isinstance(annotations, collections.abc.Mapping) and 1096 attr in annotations and 1097 issubclass(other, Generic) and other._is_protocol): 1098 break 1099 else: 1100 return NotImplemented 1101 return True 1102 1103 if '__subclasshook__' not in cls.__dict__: 1104 cls.__subclasshook__ = _proto_hook 1105 1106 # We have nothing more to do for non-protocols... 1107 if not cls._is_protocol: 1108 return 1109 1110 # ... otherwise check consistency of bases, and prohibit instantiation. 1111 for base in cls.__bases__: 1112 if not (base in (object, Generic) or 1113 base.__module__ in _PROTO_WHITELIST and 1114 base.__name__ in _PROTO_WHITELIST[base.__module__] or 1115 issubclass(base, Generic) and base._is_protocol): 1116 raise TypeError('Protocols can only inherit from other' 1117 ' protocols, got %r' % base) 1118 cls.__init__ = _no_init 1119 1120 1121def runtime_checkable(cls): 1122 """Mark a protocol class as a runtime protocol. 1123 1124 Such protocol can be used with isinstance() and issubclass(). 1125 Raise TypeError if applied to a non-protocol class. 1126 This allows a simple-minded structural check very similar to 1127 one trick ponies in collections.abc such as Iterable. 1128 For example:: 1129 1130 @runtime_checkable 1131 class Closable(Protocol): 1132 def close(self): ... 1133 1134 assert isinstance(open('/some/file'), Closable) 1135 1136 Warning: this will check only the presence of the required methods, 1137 not their type signatures! 1138 """ 1139 if not issubclass(cls, Generic) or not cls._is_protocol: 1140 raise TypeError('@runtime_checkable can be only applied to protocol classes,' 1141 ' got %r' % cls) 1142 cls._is_runtime_protocol = True 1143 return cls 1144 1145 1146def cast(typ, val): 1147 """Cast a value to a type. 1148 1149 This returns the value unchanged. To the type checker this 1150 signals that the return value has the designated type, but at 1151 runtime we intentionally don't check anything (we want this 1152 to be as fast as possible). 1153 """ 1154 return val 1155 1156 1157def _get_defaults(func): 1158 """Internal helper to extract the default arguments, by name.""" 1159 try: 1160 code = func.__code__ 1161 except AttributeError: 1162 # Some built-in functions don't have __code__, __defaults__, etc. 1163 return {} 1164 pos_count = code.co_argcount 1165 arg_names = code.co_varnames 1166 arg_names = arg_names[:pos_count] 1167 defaults = func.__defaults__ or () 1168 kwdefaults = func.__kwdefaults__ 1169 res = dict(kwdefaults) if kwdefaults else {} 1170 pos_offset = pos_count - len(defaults) 1171 for name, value in zip(arg_names[pos_offset:], defaults): 1172 assert name not in res 1173 res[name] = value 1174 return res 1175 1176 1177_allowed_types = (types.FunctionType, types.BuiltinFunctionType, 1178 types.MethodType, types.ModuleType, 1179 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType) 1180 1181 1182def get_type_hints(obj, globalns=None, localns=None): 1183 """Return type hints for an object. 1184 1185 This is often the same as obj.__annotations__, but it handles 1186 forward references encoded as string literals, and if necessary 1187 adds Optional[t] if a default value equal to None is set. 1188 1189 The argument may be a module, class, method, or function. The annotations 1190 are returned as a dictionary. For classes, annotations include also 1191 inherited members. 1192 1193 TypeError is raised if the argument is not of a type that can contain 1194 annotations, and an empty dictionary is returned if no annotations are 1195 present. 1196 1197 BEWARE -- the behavior of globalns and localns is counterintuitive 1198 (unless you are familiar with how eval() and exec() work). The 1199 search order is locals first, then globals. 1200 1201 - If no dict arguments are passed, an attempt is made to use the 1202 globals from obj (or the respective module's globals for classes), 1203 and these are also used as the locals. If the object does not appear 1204 to have globals, an empty dictionary is used. 1205 1206 - If one dict argument is passed, it is used for both globals and 1207 locals. 1208 1209 - If two dict arguments are passed, they specify globals and 1210 locals, respectively. 1211 """ 1212 1213 if getattr(obj, '__no_type_check__', None): 1214 return {} 1215 # Classes require a special treatment. 1216 if isinstance(obj, type): 1217 hints = {} 1218 for base in reversed(obj.__mro__): 1219 if globalns is None: 1220 base_globals = sys.modules[base.__module__].__dict__ 1221 else: 1222 base_globals = globalns 1223 ann = base.__dict__.get('__annotations__', {}) 1224 for name, value in ann.items(): 1225 if value is None: 1226 value = type(None) 1227 if isinstance(value, str): 1228 value = ForwardRef(value, is_argument=False) 1229 value = _eval_type(value, base_globals, localns) 1230 hints[name] = value 1231 return hints 1232 1233 if globalns is None: 1234 if isinstance(obj, types.ModuleType): 1235 globalns = obj.__dict__ 1236 else: 1237 nsobj = obj 1238 # Find globalns for the unwrapped object. 1239 while hasattr(nsobj, '__wrapped__'): 1240 nsobj = nsobj.__wrapped__ 1241 globalns = getattr(nsobj, '__globals__', {}) 1242 if localns is None: 1243 localns = globalns 1244 elif localns is None: 1245 localns = globalns 1246 hints = getattr(obj, '__annotations__', None) 1247 if hints is None: 1248 # Return empty annotations for something that _could_ have them. 1249 if isinstance(obj, _allowed_types): 1250 return {} 1251 else: 1252 raise TypeError('{!r} is not a module, class, method, ' 1253 'or function.'.format(obj)) 1254 defaults = _get_defaults(obj) 1255 hints = dict(hints) 1256 for name, value in hints.items(): 1257 if value is None: 1258 value = type(None) 1259 if isinstance(value, str): 1260 value = ForwardRef(value) 1261 value = _eval_type(value, globalns, localns) 1262 if name in defaults and defaults[name] is None: 1263 value = Optional[value] 1264 hints[name] = value 1265 return hints 1266 1267 1268def get_origin(tp): 1269 """Get the unsubscripted version of a type. 1270 1271 This supports generic types, Callable, Tuple, Union, Literal, Final and ClassVar. 1272 Return None for unsupported types. Examples:: 1273 1274 get_origin(Literal[42]) is Literal 1275 get_origin(int) is None 1276 get_origin(ClassVar[int]) is ClassVar 1277 get_origin(Generic) is Generic 1278 get_origin(Generic[T]) is Generic 1279 get_origin(Union[T, int]) is Union 1280 get_origin(List[Tuple[T, T]][int]) == list 1281 """ 1282 if isinstance(tp, _GenericAlias): 1283 return tp.__origin__ 1284 if tp is Generic: 1285 return Generic 1286 return None 1287 1288 1289def get_args(tp): 1290 """Get type arguments with all substitutions performed. 1291 1292 For unions, basic simplifications used by Union constructor are performed. 1293 Examples:: 1294 get_args(Dict[str, int]) == (str, int) 1295 get_args(int) == () 1296 get_args(Union[int, Union[T, int], str][int]) == (int, str) 1297 get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) 1298 get_args(Callable[[], T][int]) == ([], int) 1299 """ 1300 if isinstance(tp, _GenericAlias): 1301 res = tp.__args__ 1302 if get_origin(tp) is collections.abc.Callable and res[0] is not Ellipsis: 1303 res = (list(res[:-1]), res[-1]) 1304 return res 1305 return () 1306 1307 1308def no_type_check(arg): 1309 """Decorator to indicate that annotations are not type hints. 1310 1311 The argument must be a class or function; if it is a class, it 1312 applies recursively to all methods and classes defined in that class 1313 (but not to methods defined in its superclasses or subclasses). 1314 1315 This mutates the function(s) or class(es) in place. 1316 """ 1317 if isinstance(arg, type): 1318 arg_attrs = arg.__dict__.copy() 1319 for attr, val in arg.__dict__.items(): 1320 if val in arg.__bases__ + (arg,): 1321 arg_attrs.pop(attr) 1322 for obj in arg_attrs.values(): 1323 if isinstance(obj, types.FunctionType): 1324 obj.__no_type_check__ = True 1325 if isinstance(obj, type): 1326 no_type_check(obj) 1327 try: 1328 arg.__no_type_check__ = True 1329 except TypeError: # built-in classes 1330 pass 1331 return arg 1332 1333 1334def no_type_check_decorator(decorator): 1335 """Decorator to give another decorator the @no_type_check effect. 1336 1337 This wraps the decorator with something that wraps the decorated 1338 function in @no_type_check. 1339 """ 1340 1341 @functools.wraps(decorator) 1342 def wrapped_decorator(*args, **kwds): 1343 func = decorator(*args, **kwds) 1344 func = no_type_check(func) 1345 return func 1346 1347 return wrapped_decorator 1348 1349 1350def _overload_dummy(*args, **kwds): 1351 """Helper for @overload to raise when called.""" 1352 raise NotImplementedError( 1353 "You should not call an overloaded function. " 1354 "A series of @overload-decorated functions " 1355 "outside a stub module should always be followed " 1356 "by an implementation that is not @overload-ed.") 1357 1358 1359def overload(func): 1360 """Decorator for overloaded functions/methods. 1361 1362 In a stub file, place two or more stub definitions for the same 1363 function in a row, each decorated with @overload. For example: 1364 1365 @overload 1366 def utf8(value: None) -> None: ... 1367 @overload 1368 def utf8(value: bytes) -> bytes: ... 1369 @overload 1370 def utf8(value: str) -> bytes: ... 1371 1372 In a non-stub file (i.e. a regular .py file), do the same but 1373 follow it with an implementation. The implementation should *not* 1374 be decorated with @overload. For example: 1375 1376 @overload 1377 def utf8(value: None) -> None: ... 1378 @overload 1379 def utf8(value: bytes) -> bytes: ... 1380 @overload 1381 def utf8(value: str) -> bytes: ... 1382 def utf8(value): 1383 # implementation goes here 1384 """ 1385 return _overload_dummy 1386 1387 1388def final(f): 1389 """A decorator to indicate final methods and final classes. 1390 1391 Use this decorator to indicate to type checkers that the decorated 1392 method cannot be overridden, and decorated class cannot be subclassed. 1393 For example: 1394 1395 class Base: 1396 @final 1397 def done(self) -> None: 1398 ... 1399 class Sub(Base): 1400 def done(self) -> None: # Error reported by type checker 1401 ... 1402 1403 @final 1404 class Leaf: 1405 ... 1406 class Other(Leaf): # Error reported by type checker 1407 ... 1408 1409 There is no runtime checking of these properties. 1410 """ 1411 return f 1412 1413 1414# Some unconstrained type variables. These are used by the container types. 1415# (These are not for export.) 1416T = TypeVar('T') # Any type. 1417KT = TypeVar('KT') # Key type. 1418VT = TypeVar('VT') # Value type. 1419T_co = TypeVar('T_co', covariant=True) # Any type covariant containers. 1420V_co = TypeVar('V_co', covariant=True) # Any type covariant containers. 1421VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers. 1422T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant. 1423# Internal type variable used for Type[]. 1424CT_co = TypeVar('CT_co', covariant=True, bound=type) 1425 1426# A useful type variable with constraints. This represents string types. 1427# (This one *is* for export!) 1428AnyStr = TypeVar('AnyStr', bytes, str) 1429 1430 1431# Various ABCs mimicking those in collections.abc. 1432def _alias(origin, params, inst=True): 1433 return _GenericAlias(origin, params, special=True, inst=inst) 1434 1435Hashable = _alias(collections.abc.Hashable, ()) # Not generic. 1436Awaitable = _alias(collections.abc.Awaitable, T_co) 1437Coroutine = _alias(collections.abc.Coroutine, (T_co, T_contra, V_co)) 1438AsyncIterable = _alias(collections.abc.AsyncIterable, T_co) 1439AsyncIterator = _alias(collections.abc.AsyncIterator, T_co) 1440Iterable = _alias(collections.abc.Iterable, T_co) 1441Iterator = _alias(collections.abc.Iterator, T_co) 1442Reversible = _alias(collections.abc.Reversible, T_co) 1443Sized = _alias(collections.abc.Sized, ()) # Not generic. 1444Container = _alias(collections.abc.Container, T_co) 1445Collection = _alias(collections.abc.Collection, T_co) 1446Callable = _VariadicGenericAlias(collections.abc.Callable, (), special=True) 1447Callable.__doc__ = \ 1448 """Callable type; Callable[[int], str] is a function of (int) -> str. 1449 1450 The subscription syntax must always be used with exactly two 1451 values: the argument list and the return type. The argument list 1452 must be a list of types or ellipsis; the return type must be a single type. 1453 1454 There is no syntax to indicate optional or keyword arguments, 1455 such function types are rarely used as callback types. 1456 """ 1457AbstractSet = _alias(collections.abc.Set, T_co) 1458MutableSet = _alias(collections.abc.MutableSet, T) 1459# NOTE: Mapping is only covariant in the value type. 1460Mapping = _alias(collections.abc.Mapping, (KT, VT_co)) 1461MutableMapping = _alias(collections.abc.MutableMapping, (KT, VT)) 1462Sequence = _alias(collections.abc.Sequence, T_co) 1463MutableSequence = _alias(collections.abc.MutableSequence, T) 1464ByteString = _alias(collections.abc.ByteString, ()) # Not generic 1465Tuple = _VariadicGenericAlias(tuple, (), inst=False, special=True) 1466Tuple.__doc__ = \ 1467 """Tuple type; Tuple[X, Y] is the cross-product type of X and Y. 1468 1469 Example: Tuple[T1, T2] is a tuple of two elements corresponding 1470 to type variables T1 and T2. Tuple[int, float, str] is a tuple 1471 of an int, a float and a string. 1472 1473 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...]. 1474 """ 1475List = _alias(list, T, inst=False) 1476Deque = _alias(collections.deque, T) 1477Set = _alias(set, T, inst=False) 1478FrozenSet = _alias(frozenset, T_co, inst=False) 1479MappingView = _alias(collections.abc.MappingView, T_co) 1480KeysView = _alias(collections.abc.KeysView, KT) 1481ItemsView = _alias(collections.abc.ItemsView, (KT, VT_co)) 1482ValuesView = _alias(collections.abc.ValuesView, VT_co) 1483ContextManager = _alias(contextlib.AbstractContextManager, T_co) 1484AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, T_co) 1485Dict = _alias(dict, (KT, VT), inst=False) 1486DefaultDict = _alias(collections.defaultdict, (KT, VT)) 1487OrderedDict = _alias(collections.OrderedDict, (KT, VT)) 1488Counter = _alias(collections.Counter, T) 1489ChainMap = _alias(collections.ChainMap, (KT, VT)) 1490Generator = _alias(collections.abc.Generator, (T_co, T_contra, V_co)) 1491AsyncGenerator = _alias(collections.abc.AsyncGenerator, (T_co, T_contra)) 1492Type = _alias(type, CT_co, inst=False) 1493Type.__doc__ = \ 1494 """A special construct usable to annotate class objects. 1495 1496 For example, suppose we have the following classes:: 1497 1498 class User: ... # Abstract base for User classes 1499 class BasicUser(User): ... 1500 class ProUser(User): ... 1501 class TeamUser(User): ... 1502 1503 And a function that takes a class argument that's a subclass of 1504 User and returns an instance of the corresponding class:: 1505 1506 U = TypeVar('U', bound=User) 1507 def new_user(user_class: Type[U]) -> U: 1508 user = user_class() 1509 # (Here we could write the user object to a database) 1510 return user 1511 1512 joe = new_user(BasicUser) 1513 1514 At this point the type checker knows that joe has type BasicUser. 1515 """ 1516 1517 1518@runtime_checkable 1519class SupportsInt(Protocol): 1520 """An ABC with one abstract method __int__.""" 1521 __slots__ = () 1522 1523 @abstractmethod 1524 def __int__(self) -> int: 1525 pass 1526 1527 1528@runtime_checkable 1529class SupportsFloat(Protocol): 1530 """An ABC with one abstract method __float__.""" 1531 __slots__ = () 1532 1533 @abstractmethod 1534 def __float__(self) -> float: 1535 pass 1536 1537 1538@runtime_checkable 1539class SupportsComplex(Protocol): 1540 """An ABC with one abstract method __complex__.""" 1541 __slots__ = () 1542 1543 @abstractmethod 1544 def __complex__(self) -> complex: 1545 pass 1546 1547 1548@runtime_checkable 1549class SupportsBytes(Protocol): 1550 """An ABC with one abstract method __bytes__.""" 1551 __slots__ = () 1552 1553 @abstractmethod 1554 def __bytes__(self) -> bytes: 1555 pass 1556 1557 1558@runtime_checkable 1559class SupportsIndex(Protocol): 1560 """An ABC with one abstract method __index__.""" 1561 __slots__ = () 1562 1563 @abstractmethod 1564 def __index__(self) -> int: 1565 pass 1566 1567 1568@runtime_checkable 1569class SupportsAbs(Protocol[T_co]): 1570 """An ABC with one abstract method __abs__ that is covariant in its return type.""" 1571 __slots__ = () 1572 1573 @abstractmethod 1574 def __abs__(self) -> T_co: 1575 pass 1576 1577 1578@runtime_checkable 1579class SupportsRound(Protocol[T_co]): 1580 """An ABC with one abstract method __round__ that is covariant in its return type.""" 1581 __slots__ = () 1582 1583 @abstractmethod 1584 def __round__(self, ndigits: int = 0) -> T_co: 1585 pass 1586 1587 1588def _make_nmtuple(name, types): 1589 msg = "NamedTuple('Name', [(f0, t0), (f1, t1), ...]); each t must be a type" 1590 types = [(n, _type_check(t, msg)) for n, t in types] 1591 nm_tpl = collections.namedtuple(name, [n for n, t in types]) 1592 # Prior to PEP 526, only _field_types attribute was assigned. 1593 # Now __annotations__ are used and _field_types is deprecated (remove in 3.9) 1594 nm_tpl.__annotations__ = nm_tpl._field_types = dict(types) 1595 try: 1596 nm_tpl.__module__ = sys._getframe(2).f_globals.get('__name__', '__main__') 1597 except (AttributeError, ValueError): 1598 pass 1599 return nm_tpl 1600 1601 1602# attributes prohibited to set in NamedTuple class syntax 1603_prohibited = ('__new__', '__init__', '__slots__', '__getnewargs__', 1604 '_fields', '_field_defaults', '_field_types', 1605 '_make', '_replace', '_asdict', '_source') 1606 1607_special = ('__module__', '__name__', '__annotations__') 1608 1609 1610class NamedTupleMeta(type): 1611 1612 def __new__(cls, typename, bases, ns): 1613 if ns.get('_root', False): 1614 return super().__new__(cls, typename, bases, ns) 1615 types = ns.get('__annotations__', {}) 1616 nm_tpl = _make_nmtuple(typename, types.items()) 1617 defaults = [] 1618 defaults_dict = {} 1619 for field_name in types: 1620 if field_name in ns: 1621 default_value = ns[field_name] 1622 defaults.append(default_value) 1623 defaults_dict[field_name] = default_value 1624 elif defaults: 1625 raise TypeError("Non-default namedtuple field {field_name} cannot " 1626 "follow default field(s) {default_names}" 1627 .format(field_name=field_name, 1628 default_names=', '.join(defaults_dict.keys()))) 1629 nm_tpl.__new__.__annotations__ = dict(types) 1630 nm_tpl.__new__.__defaults__ = tuple(defaults) 1631 nm_tpl._field_defaults = defaults_dict 1632 # update from user namespace without overriding special namedtuple attributes 1633 for key in ns: 1634 if key in _prohibited: 1635 raise AttributeError("Cannot overwrite NamedTuple attribute " + key) 1636 elif key not in _special and key not in nm_tpl._fields: 1637 setattr(nm_tpl, key, ns[key]) 1638 return nm_tpl 1639 1640 1641class NamedTuple(metaclass=NamedTupleMeta): 1642 """Typed version of namedtuple. 1643 1644 Usage in Python versions >= 3.6:: 1645 1646 class Employee(NamedTuple): 1647 name: str 1648 id: int 1649 1650 This is equivalent to:: 1651 1652 Employee = collections.namedtuple('Employee', ['name', 'id']) 1653 1654 The resulting class has an extra __annotations__ attribute, giving a 1655 dict that maps field names to types. (The field names are also in 1656 the _fields attribute, which is part of the namedtuple API.) 1657 Alternative equivalent keyword syntax is also accepted:: 1658 1659 Employee = NamedTuple('Employee', name=str, id=int) 1660 1661 In Python versions <= 3.5 use:: 1662 1663 Employee = NamedTuple('Employee', [('name', str), ('id', int)]) 1664 """ 1665 _root = True 1666 1667 def __new__(*args, **kwargs): 1668 if not args: 1669 raise TypeError('NamedTuple.__new__(): not enough arguments') 1670 cls, *args = args # allow the "cls" keyword be passed 1671 if args: 1672 typename, *args = args # allow the "typename" keyword be passed 1673 elif 'typename' in kwargs: 1674 typename = kwargs.pop('typename') 1675 import warnings 1676 warnings.warn("Passing 'typename' as keyword argument is deprecated", 1677 DeprecationWarning, stacklevel=2) 1678 else: 1679 raise TypeError("NamedTuple.__new__() missing 1 required positional " 1680 "argument: 'typename'") 1681 if args: 1682 try: 1683 fields, = args # allow the "fields" keyword be passed 1684 except ValueError: 1685 raise TypeError(f'NamedTuple.__new__() takes from 2 to 3 ' 1686 f'positional arguments but {len(args) + 2} ' 1687 f'were given') from None 1688 elif 'fields' in kwargs and len(kwargs) == 1: 1689 fields = kwargs.pop('fields') 1690 import warnings 1691 warnings.warn("Passing 'fields' as keyword argument is deprecated", 1692 DeprecationWarning, stacklevel=2) 1693 else: 1694 fields = None 1695 1696 if fields is None: 1697 fields = kwargs.items() 1698 elif kwargs: 1699 raise TypeError("Either list of fields or keywords" 1700 " can be provided to NamedTuple, not both") 1701 return _make_nmtuple(typename, fields) 1702 __new__.__text_signature__ = '($cls, typename, fields=None, /, **kwargs)' 1703 1704 1705def _dict_new(cls, /, *args, **kwargs): 1706 return dict(*args, **kwargs) 1707 1708 1709def _typeddict_new(cls, typename, fields=None, /, *, total=True, **kwargs): 1710 if fields is None: 1711 fields = kwargs 1712 elif kwargs: 1713 raise TypeError("TypedDict takes either a dict or keyword arguments," 1714 " but not both") 1715 1716 ns = {'__annotations__': dict(fields), '__total__': total} 1717 try: 1718 # Setting correct module is necessary to make typed dict classes pickleable. 1719 ns['__module__'] = sys._getframe(1).f_globals.get('__name__', '__main__') 1720 except (AttributeError, ValueError): 1721 pass 1722 1723 return _TypedDictMeta(typename, (), ns) 1724 1725 1726def _check_fails(cls, other): 1727 # Typed dicts are only for static structural subtyping. 1728 raise TypeError('TypedDict does not support instance and class checks') 1729 1730 1731class _TypedDictMeta(type): 1732 def __new__(cls, name, bases, ns, total=True): 1733 """Create new typed dict class object. 1734 1735 This method is called directly when TypedDict is subclassed, 1736 or via _typeddict_new when TypedDict is instantiated. This way 1737 TypedDict supports all three syntax forms described in its docstring. 1738 Subclasses and instances of TypedDict return actual dictionaries 1739 via _dict_new. 1740 """ 1741 ns['__new__'] = _typeddict_new if name == 'TypedDict' else _dict_new 1742 tp_dict = super(_TypedDictMeta, cls).__new__(cls, name, (dict,), ns) 1743 1744 anns = ns.get('__annotations__', {}) 1745 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type" 1746 anns = {n: _type_check(tp, msg) for n, tp in anns.items()} 1747 for base in bases: 1748 anns.update(base.__dict__.get('__annotations__', {})) 1749 tp_dict.__annotations__ = anns 1750 if not hasattr(tp_dict, '__total__'): 1751 tp_dict.__total__ = total 1752 return tp_dict 1753 1754 __instancecheck__ = __subclasscheck__ = _check_fails 1755 1756 1757class TypedDict(dict, metaclass=_TypedDictMeta): 1758 """A simple typed namespace. At runtime it is equivalent to a plain dict. 1759 1760 TypedDict creates a dictionary type that expects all of its 1761 instances to have a certain set of keys, where each key is 1762 associated with a value of a consistent type. This expectation 1763 is not checked at runtime but is only enforced by type checkers. 1764 Usage:: 1765 1766 class Point2D(TypedDict): 1767 x: int 1768 y: int 1769 label: str 1770 1771 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK 1772 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check 1773 1774 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') 1775 1776 The type info can be accessed via Point2D.__annotations__. TypedDict 1777 supports two additional equivalent forms:: 1778 1779 Point2D = TypedDict('Point2D', x=int, y=int, label=str) 1780 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) 1781 1782 The class syntax is only supported in Python 3.6+, while two other 1783 syntax forms work for Python 2.7 and 3.2+ 1784 """ 1785 1786 1787def NewType(name, tp): 1788 """NewType creates simple unique types with almost zero 1789 runtime overhead. NewType(name, tp) is considered a subtype of tp 1790 by static type checkers. At runtime, NewType(name, tp) returns 1791 a dummy function that simply returns its argument. Usage:: 1792 1793 UserId = NewType('UserId', int) 1794 1795 def name_by_id(user_id: UserId) -> str: 1796 ... 1797 1798 UserId('user') # Fails type check 1799 1800 name_by_id(42) # Fails type check 1801 name_by_id(UserId(42)) # OK 1802 1803 num = UserId(5) + 1 # type: int 1804 """ 1805 1806 def new_type(x): 1807 return x 1808 1809 new_type.__name__ = name 1810 new_type.__supertype__ = tp 1811 return new_type 1812 1813 1814# Python-version-specific alias (Python 2: unicode; Python 3: str) 1815Text = str 1816 1817 1818# Constant that's True when type checking, but False here. 1819TYPE_CHECKING = False 1820 1821 1822class IO(Generic[AnyStr]): 1823 """Generic base class for TextIO and BinaryIO. 1824 1825 This is an abstract, generic version of the return of open(). 1826 1827 NOTE: This does not distinguish between the different possible 1828 classes (text vs. binary, read vs. write vs. read/write, 1829 append-only, unbuffered). The TextIO and BinaryIO subclasses 1830 below capture the distinctions between text vs. binary, which is 1831 pervasive in the interface; however we currently do not offer a 1832 way to track the other distinctions in the type system. 1833 """ 1834 1835 __slots__ = () 1836 1837 @property 1838 @abstractmethod 1839 def mode(self) -> str: 1840 pass 1841 1842 @property 1843 @abstractmethod 1844 def name(self) -> str: 1845 pass 1846 1847 @abstractmethod 1848 def close(self) -> None: 1849 pass 1850 1851 @abstractmethod 1852 def closed(self) -> bool: 1853 pass 1854 1855 @abstractmethod 1856 def fileno(self) -> int: 1857 pass 1858 1859 @abstractmethod 1860 def flush(self) -> None: 1861 pass 1862 1863 @abstractmethod 1864 def isatty(self) -> bool: 1865 pass 1866 1867 @abstractmethod 1868 def read(self, n: int = -1) -> AnyStr: 1869 pass 1870 1871 @abstractmethod 1872 def readable(self) -> bool: 1873 pass 1874 1875 @abstractmethod 1876 def readline(self, limit: int = -1) -> AnyStr: 1877 pass 1878 1879 @abstractmethod 1880 def readlines(self, hint: int = -1) -> List[AnyStr]: 1881 pass 1882 1883 @abstractmethod 1884 def seek(self, offset: int, whence: int = 0) -> int: 1885 pass 1886 1887 @abstractmethod 1888 def seekable(self) -> bool: 1889 pass 1890 1891 @abstractmethod 1892 def tell(self) -> int: 1893 pass 1894 1895 @abstractmethod 1896 def truncate(self, size: int = None) -> int: 1897 pass 1898 1899 @abstractmethod 1900 def writable(self) -> bool: 1901 pass 1902 1903 @abstractmethod 1904 def write(self, s: AnyStr) -> int: 1905 pass 1906 1907 @abstractmethod 1908 def writelines(self, lines: List[AnyStr]) -> None: 1909 pass 1910 1911 @abstractmethod 1912 def __enter__(self) -> 'IO[AnyStr]': 1913 pass 1914 1915 @abstractmethod 1916 def __exit__(self, type, value, traceback) -> None: 1917 pass 1918 1919 1920class BinaryIO(IO[bytes]): 1921 """Typed version of the return of open() in binary mode.""" 1922 1923 __slots__ = () 1924 1925 @abstractmethod 1926 def write(self, s: Union[bytes, bytearray]) -> int: 1927 pass 1928 1929 @abstractmethod 1930 def __enter__(self) -> 'BinaryIO': 1931 pass 1932 1933 1934class TextIO(IO[str]): 1935 """Typed version of the return of open() in text mode.""" 1936 1937 __slots__ = () 1938 1939 @property 1940 @abstractmethod 1941 def buffer(self) -> BinaryIO: 1942 pass 1943 1944 @property 1945 @abstractmethod 1946 def encoding(self) -> str: 1947 pass 1948 1949 @property 1950 @abstractmethod 1951 def errors(self) -> Optional[str]: 1952 pass 1953 1954 @property 1955 @abstractmethod 1956 def line_buffering(self) -> bool: 1957 pass 1958 1959 @property 1960 @abstractmethod 1961 def newlines(self) -> Any: 1962 pass 1963 1964 @abstractmethod 1965 def __enter__(self) -> 'TextIO': 1966 pass 1967 1968 1969class io: 1970 """Wrapper namespace for IO generic classes.""" 1971 1972 __all__ = ['IO', 'TextIO', 'BinaryIO'] 1973 IO = IO 1974 TextIO = TextIO 1975 BinaryIO = BinaryIO 1976 1977 1978io.__name__ = __name__ + '.io' 1979sys.modules[io.__name__] = io 1980 1981Pattern = _alias(stdlib_re.Pattern, AnyStr) 1982Match = _alias(stdlib_re.Match, AnyStr) 1983 1984class re: 1985 """Wrapper namespace for re type aliases.""" 1986 1987 __all__ = ['Pattern', 'Match'] 1988 Pattern = Pattern 1989 Match = Match 1990 1991 1992re.__name__ = __name__ + '.re' 1993sys.modules[re.__name__] = re 1994