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