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