vendor/typing.py

OILS / vendor / typing.py View on Github | oilshell.org

2550 lines, 1466 significant

1	from __future__ import absolute_import, unicode_literals
2
3	import abc
4	from abc import abstractmethod, abstractproperty
5	import collections
6	import functools
7	import re as stdlib_re # Avoid confusion with the re we export.
8	import sys
9	import types
10	import copy
11	try:
12	import collections.abc as collections_abc
13	except 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
94	def _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
102	def _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
109	class 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
150	class _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
187	class _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
206	class _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
259	class _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
326	def _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
332	def _type_vars(types):
333	tvars = []
334	_get_type_vars(types, tvars)
335	return tuple(tvars)
336
337
338	def _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
344	def _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
375	def _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
394	class 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
403	class _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
456	ClassVar = _ClassVar(_root=True)
457
458
459	class _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
468	class _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
522	Final = _Final(_root=True)
523
524
525	def 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
548	class _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
557	class _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
607	Literal = _Literal(_root=True)
608
609
610	class 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
619	class _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
640	Any = _Any(_root=True)
641
642
643	class 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
652	class _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
674	NoReturn = _NoReturn(_root=True)
675
676
677	class 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
683	class 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.)
772	T = TypeVar('T') # Any type.
773	KT = TypeVar('KT') # Key type.
774	VT = TypeVar('VT') # Value type.
775	T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
776	V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
777	VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
778	T_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!)
782	AnyStr = TypeVar('AnyStr', bytes, unicode)
783
784
785	def _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
812	def _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
845	def _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
886	def _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
900	def _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
924	class 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
932	class _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
1079	Union = _Union(_root=True)
1080
1081
1082	class 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
1090	class _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
1105	Optional = _Optional(_root=True)
1106
1107
1108	def _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
1122	def _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
1152	class 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
1433	def _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
1440	copy._copy_dispatch[GenericMeta] = _copy_generic
1441
1442
1443	# Prevent checks for Generic to crash when defining Generic.
1444	Generic = None
1445
1446
1447	def _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
1471	class 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
1502	class _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
1509	class _TypingEllipsis(object):
1510	"""Internal placeholder for ... (ellipsis)."""
1511
1512
1513	class 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
1547	copy._copy_dispatch[TupleMeta] = _copy_generic
1548
1549
1550	class 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
1571	class 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
1628	copy._copy_dispatch[CallableMeta] = _copy_generic
1629
1630
1631	class 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
1653	def 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
1664	def _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
1680	def 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
1685	def 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
1711	def 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
1727	def _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
1736	def 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
1770	class _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
1875	class 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
1920	def 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
1938	Hashable = collections_abc.Hashable # Not generic.
1939
1940
1941	class Iterable(Generic[T_co]):
1942	__slots__ = ()
1943	__extra__ = collections_abc.Iterable
1944
1945
1946	class Iterator(Iterable[T_co]):
1947	__slots__ = ()
1948	__extra__ = collections_abc.Iterator
1949
1950
1951	@runtime_checkable
1952	class SupportsInt(Protocol):
1953	__slots__ = ()
1954
1955	@abstractmethod
1956	def __int__(self):
1957	pass
1958
1959
1960	@runtime_checkable
1961	class SupportsFloat(Protocol):
1962	__slots__ = ()
1963
1964	@abstractmethod
1965	def __float__(self):
1966	pass
1967
1968
1969	@runtime_checkable
1970	class SupportsComplex(Protocol):
1971	__slots__ = ()
1972
1973	@abstractmethod
1974	def __complex__(self):
1975	pass
1976
1977
1978	@runtime_checkable
1979	class SupportsIndex(Protocol):
1980	__slots__ = ()
1981
1982	@abstractmethod
1983	def __index__(self):
1984	pass
1985
1986
1987	@runtime_checkable
1988	class SupportsAbs(Protocol[T_co]):
1989	__slots__ = ()
1990
1991	@abstractmethod
1992	def __abs__(self):
1993	pass
1994
1995
1996	if hasattr(collections_abc, 'Reversible'):
1997	class Reversible(Iterable[T_co]):
1998	__slots__ = ()
1999	__extra__ = collections_abc.Reversible
2000	else:
2001	@runtime_checkable
2002	class Reversible(Protocol[T_co]):
2003	__slots__ = ()
2004
2005	@abstractmethod
2006	def __reversed__(self):
2007	pass
2008
2009
2010	Sized = collections_abc.Sized # Not generic.
2011
2012
2013	class Container(Generic[T_co]):
2014	__slots__ = ()
2015	__extra__ = collections_abc.Container
2016
2017
2018	# Callable was defined earlier.
2019
2020
2021	class AbstractSet(Sized, Iterable[T_co], Container[T_co]):
2022	__slots__ = ()
2023	__extra__ = collections_abc.Set
2024
2025
2026	class MutableSet(AbstractSet[T]):
2027	__slots__ = ()
2028	__extra__ = collections_abc.MutableSet
2029
2030
2031	# NOTE: It is only covariant in the value type.
2032	class Mapping(Sized, Iterable[KT], Container[KT], Generic[KT, VT_co]):
2033	__slots__ = ()
2034	__extra__ = collections_abc.Mapping
2035
2036
2037	class MutableMapping(Mapping[KT, VT]):
2038	__slots__ = ()
2039	__extra__ = collections_abc.MutableMapping
2040
2041
2042	if hasattr(collections_abc, 'Reversible'):
2043	class Sequence(Sized, Reversible[T_co], Container[T_co]):
2044	__slots__ = ()
2045	__extra__ = collections_abc.Sequence
2046	else:
2047	class Sequence(Sized, Iterable[T_co], Container[T_co]):
2048	__slots__ = ()
2049	__extra__ = collections_abc.Sequence
2050
2051
2052	class MutableSequence(Sequence[T]):
2053	__slots__ = ()
2054	__extra__ = collections_abc.MutableSequence
2055
2056
2057	class ByteString(Sequence[int]):
2058	pass
2059
2060
2061	ByteString.register(str)
2062	ByteString.register(bytearray)
2063
2064
2065	class 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
2076	class 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
2086	class 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
2097	class 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
2108	class MappingView(Sized, Iterable[T_co]):
2109	__slots__ = ()
2110	__extra__ = collections_abc.MappingView
2111
2112
2113	class KeysView(MappingView[KT], AbstractSet[KT]):
2114	__slots__ = ()
2115	__extra__ = collections_abc.KeysView
2116
2117
2118	class 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
2125	class ValuesView(MappingView[VT_co]):
2126	__slots__ = ()
2127	__extra__ = collections_abc.ValuesView
2128
2129
2130	class 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
2154	class 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
2165	class 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
2175	class 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.
2186	if hasattr(collections_abc, 'Generator'):
2187	# Sufficiently recent versions of 3.5 have a Generator ABC.
2188	_G_base = collections_abc.Generator
2189	else:
2190	# Fall back on the exact type.
2191	_G_base = types.GeneratorType
2192
2193
2194	class 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[].
2206	CT_co = TypeVar('CT_co', covariant=True, bound=type)
2207
2208
2209	# This is not a real generic class. Don't use outside annotations.
2210	class 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
2237	def 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
2264	def _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
2274	def _dict_new(cls, args, *kwargs):
2275	return dict(args, *kwargs)
2276
2277
2278	def _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
2296	class _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
2320	TypedDict = _TypedDictMeta(b'TypedDict', (dict,), {})
2321	TypedDict.__module__ = __name__
2322	TypedDict.__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
2345	def 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)
2375	Text = unicode
2376
2377
2378	# Constant that's True when type checking, but False here.
2379	TYPE_CHECKING = False
2380
2381
2382	class 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
2478	class 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
2492	class 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
2522	class 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
2531	io.__name__ = __name__ + b'.io'
2532	sys.modules[io.__name__] = io
2533
2534
2535	Pattern = _TypeAlias('Pattern', AnyStr, type(stdlib_re.compile('')),
2536	lambda p: p.pattern)
2537	Match = _TypeAlias('Match', AnyStr, type(stdlib_re.match('', '')),
2538	lambda m: m.re.pattern)
2539
2540
2541	class re(object):
2542	"""Wrapper namespace for re type aliases."""
2543
2544	__all__ = ['Pattern', 'Match']
2545	Pattern = Pattern
2546	Match = Match
2547
2548
2549	re.__name__ = __name__ + b'.re'
2550	sys.modules[re.__name__] = re