vendor/typing.py

OILS / vendor / typing.py View on Github | oils.pub

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