Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/typing.py: 13%
932 statements
« prev ^ index » next coverage.py v7.0.5, created at 2023-01-17 06:13 +0000
1"""
2The typing module: Support for gradual typing as defined by PEP 484.
4At large scale, the structure of the module is following:
5* Imports and exports, all public names should be explicitly added to __all__.
6* Internal helper functions: these should never be used in code outside this module.
7* _SpecialForm and its instances (special forms): Any, NoReturn, ClassVar, Union, Optional
8* Two classes whose instances can be type arguments in addition to types: ForwardRef and TypeVar
9* The core of internal generics API: _GenericAlias and _VariadicGenericAlias, the latter is
10 currently only used by Tuple and Callable. All subscripted types like X[int], Union[int, str],
11 etc., are instances of either of these classes.
12* The public counterpart of the generics API consists of two classes: Generic and Protocol.
13* Public helper functions: get_type_hints, overload, cast, no_type_check,
14 no_type_check_decorator.
15* Generic aliases for collections.abc ABCs and few additional protocols.
16* Special types: NewType, NamedTuple, TypedDict.
17* Wrapper submodules for re and io related types.
18"""
20from abc import abstractmethod, ABCMeta
21import collections
22import collections.abc
23import contextlib
24import functools
25import operator
26import re as stdlib_re # Avoid confusion with the re we export.
27import sys
28import types
29from types import WrapperDescriptorType, MethodWrapperType, MethodDescriptorType
31# Please keep __all__ alphabetized within each category.
32__all__ = [
33 # Super-special typing primitives.
34 'Any',
35 'Callable',
36 'ClassVar',
37 'Final',
38 'ForwardRef',
39 'Generic',
40 'Literal',
41 'Optional',
42 'Protocol',
43 'Tuple',
44 'Type',
45 'TypeVar',
46 'Union',
48 # ABCs (from collections.abc).
49 'AbstractSet', # collections.abc.Set.
50 'ByteString',
51 'Container',
52 'ContextManager',
53 'Hashable',
54 'ItemsView',
55 'Iterable',
56 'Iterator',
57 'KeysView',
58 'Mapping',
59 'MappingView',
60 'MutableMapping',
61 'MutableSequence',
62 'MutableSet',
63 'Sequence',
64 'Sized',
65 'ValuesView',
66 'Awaitable',
67 'AsyncIterator',
68 'AsyncIterable',
69 'Coroutine',
70 'Collection',
71 'AsyncGenerator',
72 'AsyncContextManager',
74 # Structural checks, a.k.a. protocols.
75 'Reversible',
76 'SupportsAbs',
77 'SupportsBytes',
78 'SupportsComplex',
79 'SupportsFloat',
80 'SupportsIndex',
81 'SupportsInt',
82 'SupportsRound',
84 # Concrete collection types.
85 'ChainMap',
86 'Counter',
87 'Deque',
88 'Dict',
89 'DefaultDict',
90 'List',
91 'OrderedDict',
92 'Set',
93 'FrozenSet',
94 'NamedTuple', # Not really a type.
95 'TypedDict', # Not really a type.
96 'Generator',
98 # One-off things.
99 'AnyStr',
100 'cast',
101 'final',
102 'get_args',
103 'get_origin',
104 'get_type_hints',
105 'NewType',
106 'no_type_check',
107 'no_type_check_decorator',
108 'NoReturn',
109 'overload',
110 'runtime_checkable',
111 'Text',
112 'TYPE_CHECKING',
113]
115# The pseudo-submodules 're' and 'io' are part of the public
116# namespace, but excluded from __all__ because they might stomp on
117# legitimate imports of those modules.
120def _type_check(arg, msg, is_argument=True):
121 """Check that the argument is a type, and return it (internal helper).
123 As a special case, accept None and return type(None) instead. Also wrap strings
124 into ForwardRef instances. Consider several corner cases, for example plain
125 special forms like Union are not valid, while Union[int, str] is OK, etc.
126 The msg argument is a human-readable error message, e.g::
128 "Union[arg, ...]: arg should be a type."
130 We append the repr() of the actual value (truncated to 100 chars).
131 """
132 invalid_generic_forms = (Generic, Protocol)
133 if is_argument:
134 invalid_generic_forms = invalid_generic_forms + (ClassVar, Final)
136 if arg is None:
137 return type(None)
138 if isinstance(arg, str):
139 return ForwardRef(arg)
140 if (isinstance(arg, _GenericAlias) and
141 arg.__origin__ in invalid_generic_forms):
142 raise TypeError(f"{arg} is not valid as type argument")
143 if (isinstance(arg, _SpecialForm) and arg not in (Any, NoReturn) or
144 arg in (Generic, Protocol)):
145 raise TypeError(f"Plain {arg} is not valid as type argument")
146 if isinstance(arg, (type, TypeVar, ForwardRef)):
147 return arg
148 if not callable(arg):
149 raise TypeError(f"{msg} Got {arg!r:.100}.")
150 return arg
153def _type_repr(obj):
154 """Return the repr() of an object, special-casing types (internal helper).
156 If obj is a type, we return a shorter version than the default
157 type.__repr__, based on the module and qualified name, which is
158 typically enough to uniquely identify a type. For everything
159 else, we fall back on repr(obj).
160 """
161 if isinstance(obj, type):
162 if obj.__module__ == 'builtins':
163 return obj.__qualname__
164 return f'{obj.__module__}.{obj.__qualname__}'
165 if obj is ...:
166 return('...')
167 if isinstance(obj, types.FunctionType):
168 return obj.__name__
169 return repr(obj)
172def _collect_type_vars(types):
173 """Collect all type variable contained in types in order of
174 first appearance (lexicographic order). For example::
176 _collect_type_vars((T, List[S, T])) == (T, S)
177 """
178 tvars = []
179 for t in types:
180 if isinstance(t, TypeVar) and t not in tvars:
181 tvars.append(t)
182 if isinstance(t, _GenericAlias) and not t._special:
183 tvars.extend([t for t in t.__parameters__ if t not in tvars])
184 return tuple(tvars)
187def _subs_tvars(tp, tvars, subs):
188 """Substitute type variables 'tvars' with substitutions 'subs'.
189 These two must have the same length.
190 """
191 if not isinstance(tp, _GenericAlias):
192 return tp
193 new_args = list(tp.__args__)
194 for a, arg in enumerate(tp.__args__):
195 if isinstance(arg, TypeVar):
196 for i, tvar in enumerate(tvars):
197 if arg == tvar:
198 new_args[a] = subs[i]
199 else:
200 new_args[a] = _subs_tvars(arg, tvars, subs)
201 if tp.__origin__ is Union:
202 return Union[tuple(new_args)]
203 return tp.copy_with(tuple(new_args))
206def _check_generic(cls, parameters):
207 """Check correct count for parameters of a generic cls (internal helper).
208 This gives a nice error message in case of count mismatch.
209 """
210 if not cls.__parameters__:
211 raise TypeError(f"{cls} is not a generic class")
212 alen = len(parameters)
213 elen = len(cls.__parameters__)
214 if alen != elen:
215 raise TypeError(f"Too {'many' if alen > elen else 'few'} parameters for {cls};"
216 f" actual {alen}, expected {elen}")
219def _remove_dups_flatten(parameters):
220 """An internal helper for Union creation and substitution: flatten Unions
221 among parameters, then remove duplicates.
222 """
223 # Flatten out Union[Union[...], ...].
224 params = []
225 for p in parameters:
226 if isinstance(p, _GenericAlias) and p.__origin__ is Union:
227 params.extend(p.__args__)
228 elif isinstance(p, tuple) and len(p) > 0 and p[0] is Union:
229 params.extend(p[1:])
230 else:
231 params.append(p)
232 # Weed out strict duplicates, preserving the first of each occurrence.
233 all_params = set(params)
234 if len(all_params) < len(params):
235 new_params = []
236 for t in params:
237 if t in all_params:
238 new_params.append(t)
239 all_params.remove(t)
240 params = new_params
241 assert not all_params, all_params
242 return tuple(params)
245_cleanups = []
248def _tp_cache(func):
249 """Internal wrapper caching __getitem__ of generic types with a fallback to
250 original function for non-hashable arguments.
251 """
252 cached = functools.lru_cache()(func)
253 _cleanups.append(cached.cache_clear)
255 @functools.wraps(func)
256 def inner(*args, **kwds):
257 try:
258 return cached(*args, **kwds)
259 except TypeError:
260 pass # All real errors (not unhashable args) are raised below.
261 return func(*args, **kwds)
262 return inner
265def _eval_type(t, globalns, localns):
266 """Evaluate all forward reverences in the given type t.
267 For use of globalns and localns see the docstring for get_type_hints().
268 """
269 if isinstance(t, ForwardRef):
270 return t._evaluate(globalns, localns)
271 if isinstance(t, _GenericAlias):
272 ev_args = tuple(_eval_type(a, globalns, localns) for a in t.__args__)
273 if ev_args == t.__args__:
274 return t
275 res = t.copy_with(ev_args)
276 res._special = t._special
277 return res
278 return t
281class _Final:
282 """Mixin to prohibit subclassing"""
284 __slots__ = ('__weakref__',)
286 def __init_subclass__(self, /, *args, **kwds):
287 if '_root' not in kwds:
288 raise TypeError("Cannot subclass special typing classes")
290class _Immutable:
291 """Mixin to indicate that object should not be copied."""
293 def __copy__(self):
294 return self
296 def __deepcopy__(self, memo):
297 return self
300class _SpecialForm(_Final, _Immutable, _root=True):
301 """Internal indicator of special typing constructs.
302 See _doc instance attribute for specific docs.
303 """
305 __slots__ = ('_name', '_doc')
307 def __new__(cls, *args, **kwds):
308 """Constructor.
310 This only exists to give a better error message in case
311 someone tries to subclass a special typing object (not a good idea).
312 """
313 if (len(args) == 3 and
314 isinstance(args[0], str) and
315 isinstance(args[1], tuple)):
316 # Close enough.
317 raise TypeError(f"Cannot subclass {cls!r}")
318 return super().__new__(cls)
320 def __init__(self, name, doc):
321 self._name = name
322 self._doc = doc
324 def __eq__(self, other):
325 if not isinstance(other, _SpecialForm):
326 return NotImplemented
327 return self._name == other._name
329 def __hash__(self):
330 return hash((self._name,))
332 def __repr__(self):
333 return 'typing.' + self._name
335 def __reduce__(self):
336 return self._name
338 def __call__(self, *args, **kwds):
339 raise TypeError(f"Cannot instantiate {self!r}")
341 def __instancecheck__(self, obj):
342 raise TypeError(f"{self} cannot be used with isinstance()")
344 def __subclasscheck__(self, cls):
345 raise TypeError(f"{self} cannot be used with issubclass()")
347 @_tp_cache
348 def __getitem__(self, parameters):
349 if self._name in ('ClassVar', 'Final'):
350 item = _type_check(parameters, f'{self._name} accepts only single type.')
351 return _GenericAlias(self, (item,))
352 if self._name == 'Union':
353 if parameters == ():
354 raise TypeError("Cannot take a Union of no types.")
355 if not isinstance(parameters, tuple):
356 parameters = (parameters,)
357 msg = "Union[arg, ...]: each arg must be a type."
358 parameters = tuple(_type_check(p, msg) for p in parameters)
359 parameters = _remove_dups_flatten(parameters)
360 if len(parameters) == 1:
361 return parameters[0]
362 return _GenericAlias(self, parameters)
363 if self._name == 'Optional':
364 arg = _type_check(parameters, "Optional[t] requires a single type.")
365 return Union[arg, type(None)]
366 if self._name == 'Literal':
367 # There is no '_type_check' call because arguments to Literal[...] are
368 # values, not types.
369 return _GenericAlias(self, parameters)
370 raise TypeError(f"{self} is not subscriptable")
373Any = _SpecialForm('Any', doc=
374 """Special type indicating an unconstrained type.
376 - Any is compatible with every type.
377 - Any assumed to have all methods.
378 - All values assumed to be instances of Any.
380 Note that all the above statements are true from the point of view of
381 static type checkers. At runtime, Any should not be used with instance
382 or class checks.
383 """)
385NoReturn = _SpecialForm('NoReturn', doc=
386 """Special type indicating functions that never return.
387 Example::
389 from typing import NoReturn
391 def stop() -> NoReturn:
392 raise Exception('no way')
394 This type is invalid in other positions, e.g., ``List[NoReturn]``
395 will fail in static type checkers.
396 """)
398ClassVar = _SpecialForm('ClassVar', doc=
399 """Special type construct to mark class variables.
401 An annotation wrapped in ClassVar indicates that a given
402 attribute is intended to be used as a class variable and
403 should not be set on instances of that class. Usage::
405 class Starship:
406 stats: ClassVar[Dict[str, int]] = {} # class variable
407 damage: int = 10 # instance variable
409 ClassVar accepts only types and cannot be further subscribed.
411 Note that ClassVar is not a class itself, and should not
412 be used with isinstance() or issubclass().
413 """)
415Final = _SpecialForm('Final', doc=
416 """Special typing construct to indicate final names to type checkers.
418 A final name cannot be re-assigned or overridden in a subclass.
419 For example:
421 MAX_SIZE: Final = 9000
422 MAX_SIZE += 1 # Error reported by type checker
424 class Connection:
425 TIMEOUT: Final[int] = 10
427 class FastConnector(Connection):
428 TIMEOUT = 1 # Error reported by type checker
430 There is no runtime checking of these properties.
431 """)
433Union = _SpecialForm('Union', doc=
434 """Union type; Union[X, Y] means either X or Y.
436 To define a union, use e.g. Union[int, str]. Details:
437 - The arguments must be types and there must be at least one.
438 - None as an argument is a special case and is replaced by
439 type(None).
440 - Unions of unions are flattened, e.g.::
442 Union[Union[int, str], float] == Union[int, str, float]
444 - Unions of a single argument vanish, e.g.::
446 Union[int] == int # The constructor actually returns int
448 - Redundant arguments are skipped, e.g.::
450 Union[int, str, int] == Union[int, str]
452 - When comparing unions, the argument order is ignored, e.g.::
454 Union[int, str] == Union[str, int]
456 - You cannot subclass or instantiate a union.
457 - You can use Optional[X] as a shorthand for Union[X, None].
458 """)
460Optional = _SpecialForm('Optional', doc=
461 """Optional type.
463 Optional[X] is equivalent to Union[X, None].
464 """)
466Literal = _SpecialForm('Literal', doc=
467 """Special typing form to define literal types (a.k.a. value types).
469 This form can be used to indicate to type checkers that the corresponding
470 variable or function parameter has a value equivalent to the provided
471 literal (or one of several literals):
473 def validate_simple(data: Any) -> Literal[True]: # always returns True
474 ...
476 MODE = Literal['r', 'rb', 'w', 'wb']
477 def open_helper(file: str, mode: MODE) -> str:
478 ...
480 open_helper('/some/path', 'r') # Passes type check
481 open_helper('/other/path', 'typo') # Error in type checker
483 Literal[...] cannot be subclassed. At runtime, an arbitrary value
484 is allowed as type argument to Literal[...], but type checkers may
485 impose restrictions.
486 """)
489class ForwardRef(_Final, _root=True):
490 """Internal wrapper to hold a forward reference."""
492 __slots__ = ('__forward_arg__', '__forward_code__',
493 '__forward_evaluated__', '__forward_value__',
494 '__forward_is_argument__')
496 def __init__(self, arg, is_argument=True):
497 if not isinstance(arg, str):
498 raise TypeError(f"Forward reference must be a string -- got {arg!r}")
499 try:
500 code = compile(arg, '<string>', 'eval')
501 except SyntaxError:
502 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}")
503 self.__forward_arg__ = arg
504 self.__forward_code__ = code
505 self.__forward_evaluated__ = False
506 self.__forward_value__ = None
507 self.__forward_is_argument__ = is_argument
509 def _evaluate(self, globalns, localns):
510 if not self.__forward_evaluated__ or localns is not globalns:
511 if globalns is None and localns is None:
512 globalns = localns = {}
513 elif globalns is None:
514 globalns = localns
515 elif localns is None:
516 localns = globalns
517 self.__forward_value__ = _type_check(
518 eval(self.__forward_code__, globalns, localns),
519 "Forward references must evaluate to types.",
520 is_argument=self.__forward_is_argument__)
521 self.__forward_evaluated__ = True
522 return self.__forward_value__
524 def __eq__(self, other):
525 if not isinstance(other, ForwardRef):
526 return NotImplemented
527 if self.__forward_evaluated__ and other.__forward_evaluated__:
528 return (self.__forward_arg__ == other.__forward_arg__ and
529 self.__forward_value__ == other.__forward_value__)
530 return self.__forward_arg__ == other.__forward_arg__
532 def __hash__(self):
533 return hash(self.__forward_arg__)
535 def __repr__(self):
536 return f'ForwardRef({self.__forward_arg__!r})'
539class TypeVar(_Final, _Immutable, _root=True):
540 """Type variable.
542 Usage::
544 T = TypeVar('T') # Can be anything
545 A = TypeVar('A', str, bytes) # Must be str or bytes
547 Type variables exist primarily for the benefit of static type
548 checkers. They serve as the parameters for generic types as well
549 as for generic function definitions. See class Generic for more
550 information on generic types. Generic functions work as follows:
552 def repeat(x: T, n: int) -> List[T]:
553 '''Return a list containing n references to x.'''
554 return [x]*n
556 def longest(x: A, y: A) -> A:
557 '''Return the longest of two strings.'''
558 return x if len(x) >= len(y) else y
560 The latter example's signature is essentially the overloading
561 of (str, str) -> str and (bytes, bytes) -> bytes. Also note
562 that if the arguments are instances of some subclass of str,
563 the return type is still plain str.
565 At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
567 Type variables defined with covariant=True or contravariant=True
568 can be used to declare covariant or contravariant generic types.
569 See PEP 484 for more details. By default generic types are invariant
570 in all type variables.
572 Type variables can be introspected. e.g.:
574 T.__name__ == 'T'
575 T.__constraints__ == ()
576 T.__covariant__ == False
577 T.__contravariant__ = False
578 A.__constraints__ == (str, bytes)
580 Note that only type variables defined in global scope can be pickled.
581 """
583 __slots__ = ('__name__', '__bound__', '__constraints__',
584 '__covariant__', '__contravariant__')
586 def __init__(self, name, *constraints, bound=None,
587 covariant=False, contravariant=False):
588 self.__name__ = name
589 if covariant and contravariant:
590 raise ValueError("Bivariant types are not supported.")
591 self.__covariant__ = bool(covariant)
592 self.__contravariant__ = bool(contravariant)
593 if constraints and bound is not None:
594 raise TypeError("Constraints cannot be combined with bound=...")
595 if constraints and len(constraints) == 1:
596 raise TypeError("A single constraint is not allowed")
597 msg = "TypeVar(name, constraint, ...): constraints must be types."
598 self.__constraints__ = tuple(_type_check(t, msg) for t in constraints)
599 if bound:
600 self.__bound__ = _type_check(bound, "Bound must be a type.")
601 else:
602 self.__bound__ = None
603 try:
604 def_mod = sys._getframe(1).f_globals.get('__name__', '__main__') # for pickling
605 except (AttributeError, ValueError):
606 def_mod = None
607 if def_mod != 'typing':
608 self.__module__ = def_mod
610 def __repr__(self):
611 if self.__covariant__:
612 prefix = '+'
613 elif self.__contravariant__:
614 prefix = '-'
615 else:
616 prefix = '~'
617 return prefix + self.__name__
619 def __reduce__(self):
620 return self.__name__
623# Special typing constructs Union, Optional, Generic, Callable and Tuple
624# use three special attributes for internal bookkeeping of generic types:
625# * __parameters__ is a tuple of unique free type parameters of a generic
626# type, for example, Dict[T, T].__parameters__ == (T,);
627# * __origin__ keeps a reference to a type that was subscripted,
628# e.g., Union[T, int].__origin__ == Union, or the non-generic version of
629# the type.
630# * __args__ is a tuple of all arguments used in subscripting,
631# e.g., Dict[T, int].__args__ == (T, int).
634# Mapping from non-generic type names that have a generic alias in typing
635# but with a different name.
636_normalize_alias = {'list': 'List',
637 'tuple': 'Tuple',
638 'dict': 'Dict',
639 'set': 'Set',
640 'frozenset': 'FrozenSet',
641 'deque': 'Deque',
642 'defaultdict': 'DefaultDict',
643 'type': 'Type',
644 'Set': 'AbstractSet'}
646def _is_dunder(attr):
647 return attr.startswith('__') and attr.endswith('__')
650class _GenericAlias(_Final, _root=True):
651 """The central part of internal API.
653 This represents a generic version of type 'origin' with type arguments 'params'.
654 There are two kind of these aliases: user defined and special. The special ones
655 are wrappers around builtin collections and ABCs in collections.abc. These must
656 have 'name' always set. If 'inst' is False, then the alias can't be instantiated,
657 this is used by e.g. typing.List and typing.Dict.
658 """
659 def __init__(self, origin, params, *, inst=True, special=False, name=None):
660 self._inst = inst
661 self._special = special
662 if special and name is None:
663 orig_name = origin.__name__
664 name = _normalize_alias.get(orig_name, orig_name)
665 self._name = name
666 if not isinstance(params, tuple):
667 params = (params,)
668 self.__origin__ = origin
669 self.__args__ = tuple(... if a is _TypingEllipsis else
670 () if a is _TypingEmpty else
671 a for a in params)
672 self.__parameters__ = _collect_type_vars(params)
673 self.__slots__ = None # This is not documented.
674 if not name:
675 self.__module__ = origin.__module__
677 @_tp_cache
678 def __getitem__(self, params):
679 if self.__origin__ in (Generic, Protocol):
680 # Can't subscript Generic[...] or Protocol[...].
681 raise TypeError(f"Cannot subscript already-subscripted {self}")
682 if not isinstance(params, tuple):
683 params = (params,)
684 msg = "Parameters to generic types must be types."
685 params = tuple(_type_check(p, msg) for p in params)
686 _check_generic(self, params)
687 return _subs_tvars(self, self.__parameters__, params)
689 def copy_with(self, params):
690 # We don't copy self._special.
691 return _GenericAlias(self.__origin__, params, name=self._name, inst=self._inst)
693 def __repr__(self):
694 if (self._name != 'Callable' or
695 len(self.__args__) == 2 and self.__args__[0] is Ellipsis):
696 if self._name:
697 name = 'typing.' + self._name
698 else:
699 name = _type_repr(self.__origin__)
700 if not self._special:
701 args = f'[{", ".join([_type_repr(a) for a in self.__args__])}]'
702 else:
703 args = ''
704 return (f'{name}{args}')
705 if self._special:
706 return 'typing.Callable'
707 return (f'typing.Callable'
708 f'[[{", ".join([_type_repr(a) for a in self.__args__[:-1]])}], '
709 f'{_type_repr(self.__args__[-1])}]')
711 def __eq__(self, other):
712 if not isinstance(other, _GenericAlias):
713 return NotImplemented
714 if self.__origin__ != other.__origin__:
715 return False
716 if self.__origin__ is Union and other.__origin__ is Union:
717 return frozenset(self.__args__) == frozenset(other.__args__)
718 return self.__args__ == other.__args__
720 def __hash__(self):
721 if self.__origin__ is Union:
722 return hash((Union, frozenset(self.__args__)))
723 return hash((self.__origin__, self.__args__))
725 def __call__(self, *args, **kwargs):
726 if not self._inst:
727 raise TypeError(f"Type {self._name} cannot be instantiated; "
728 f"use {self._name.lower()}() instead")
729 result = self.__origin__(*args, **kwargs)
730 try:
731 result.__orig_class__ = self
732 except AttributeError:
733 pass
734 return result
736 def __mro_entries__(self, bases):
737 if self._name: # generic version of an ABC or built-in class
738 res = []
739 if self.__origin__ not in bases:
740 res.append(self.__origin__)
741 i = bases.index(self)
742 if not any(isinstance(b, _GenericAlias) or issubclass(b, Generic)
743 for b in bases[i+1:]):
744 res.append(Generic)
745 return tuple(res)
746 if self.__origin__ is Generic:
747 if Protocol in bases:
748 return ()
749 i = bases.index(self)
750 for b in bases[i+1:]:
751 if isinstance(b, _GenericAlias) and b is not self:
752 return ()
753 return (self.__origin__,)
755 def __getattr__(self, attr):
756 # We are careful for copy and pickle.
757 # Also for simplicity we just don't relay all dunder names
758 if '__origin__' in self.__dict__ and not _is_dunder(attr):
759 return getattr(self.__origin__, attr)
760 raise AttributeError(attr)
762 def __setattr__(self, attr, val):
763 if _is_dunder(attr) or attr in ('_name', '_inst', '_special'):
764 super().__setattr__(attr, val)
765 else:
766 setattr(self.__origin__, attr, val)
768 def __instancecheck__(self, obj):
769 return self.__subclasscheck__(type(obj))
771 def __subclasscheck__(self, cls):
772 if self._special:
773 if not isinstance(cls, _GenericAlias):
774 return issubclass(cls, self.__origin__)
775 if cls._special:
776 return issubclass(cls.__origin__, self.__origin__)
777 raise TypeError("Subscripted generics cannot be used with"
778 " class and instance checks")
780 def __reduce__(self):
781 if self._special:
782 return self._name
784 if self._name:
785 origin = globals()[self._name]
786 else:
787 origin = self.__origin__
788 if (origin is Callable and
789 not (len(self.__args__) == 2 and self.__args__[0] is Ellipsis)):
790 args = list(self.__args__[:-1]), self.__args__[-1]
791 else:
792 args = tuple(self.__args__)
793 if len(args) == 1 and not isinstance(args[0], tuple):
794 args, = args
795 return operator.getitem, (origin, args)
798class _VariadicGenericAlias(_GenericAlias, _root=True):
799 """Same as _GenericAlias above but for variadic aliases. Currently,
800 this is used only by special internal aliases: Tuple and Callable.
801 """
802 def __getitem__(self, params):
803 if self._name != 'Callable' or not self._special:
804 return self.__getitem_inner__(params)
805 if not isinstance(params, tuple) or len(params) != 2:
806 raise TypeError("Callable must be used as "
807 "Callable[[arg, ...], result].")
808 args, result = params
809 if args is Ellipsis:
810 params = (Ellipsis, result)
811 else:
812 if not isinstance(args, list):
813 raise TypeError(f"Callable[args, result]: args must be a list."
814 f" Got {args}")
815 params = (tuple(args), result)
816 return self.__getitem_inner__(params)
818 @_tp_cache
819 def __getitem_inner__(self, params):
820 if self.__origin__ is tuple and self._special:
821 if params == ():
822 return self.copy_with((_TypingEmpty,))
823 if not isinstance(params, tuple):
824 params = (params,)
825 if len(params) == 2 and params[1] is ...:
826 msg = "Tuple[t, ...]: t must be a type."
827 p = _type_check(params[0], msg)
828 return self.copy_with((p, _TypingEllipsis))
829 msg = "Tuple[t0, t1, ...]: each t must be a type."
830 params = tuple(_type_check(p, msg) for p in params)
831 return self.copy_with(params)
832 if self.__origin__ is collections.abc.Callable and self._special:
833 args, result = params
834 msg = "Callable[args, result]: result must be a type."
835 result = _type_check(result, msg)
836 if args is Ellipsis:
837 return self.copy_with((_TypingEllipsis, result))
838 msg = "Callable[[arg, ...], result]: each arg must be a type."
839 args = tuple(_type_check(arg, msg) for arg in args)
840 params = args + (result,)
841 return self.copy_with(params)
842 return super().__getitem__(params)
845class Generic:
846 """Abstract base class for generic types.
848 A generic type is typically declared by inheriting from
849 this class parameterized with one or more type variables.
850 For example, a generic mapping type might be defined as::
852 class Mapping(Generic[KT, VT]):
853 def __getitem__(self, key: KT) -> VT:
854 ...
855 # Etc.
857 This class can then be used as follows::
859 def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
860 try:
861 return mapping[key]
862 except KeyError:
863 return default
864 """
865 __slots__ = ()
866 _is_protocol = False
868 def __new__(cls, *args, **kwds):
869 if cls in (Generic, Protocol):
870 raise TypeError(f"Type {cls.__name__} cannot be instantiated; "
871 "it can be used only as a base class")
872 if super().__new__ is object.__new__ and cls.__init__ is not object.__init__:
873 obj = super().__new__(cls)
874 else:
875 obj = super().__new__(cls, *args, **kwds)
876 return obj
878 @_tp_cache
879 def __class_getitem__(cls, params):
880 if not isinstance(params, tuple):
881 params = (params,)
882 if not params and cls is not Tuple:
883 raise TypeError(
884 f"Parameter list to {cls.__qualname__}[...] cannot be empty")
885 msg = "Parameters to generic types must be types."
886 params = tuple(_type_check(p, msg) for p in params)
887 if cls in (Generic, Protocol):
888 # Generic and Protocol can only be subscripted with unique type variables.
889 if not all(isinstance(p, TypeVar) for p in params):
890 raise TypeError(
891 f"Parameters to {cls.__name__}[...] must all be type variables")
892 if len(set(params)) != len(params):
893 raise TypeError(
894 f"Parameters to {cls.__name__}[...] must all be unique")
895 else:
896 # Subscripting a regular Generic subclass.
897 _check_generic(cls, params)
898 return _GenericAlias(cls, params)
900 def __init_subclass__(cls, *args, **kwargs):
901 super().__init_subclass__(*args, **kwargs)
902 tvars = []
903 if '__orig_bases__' in cls.__dict__:
904 error = Generic in cls.__orig_bases__
905 else:
906 error = Generic in cls.__bases__ and cls.__name__ != 'Protocol'
907 if error:
908 raise TypeError("Cannot inherit from plain Generic")
909 if '__orig_bases__' in cls.__dict__:
910 tvars = _collect_type_vars(cls.__orig_bases__)
911 # Look for Generic[T1, ..., Tn].
912 # If found, tvars must be a subset of it.
913 # If not found, tvars is it.
914 # Also check for and reject plain Generic,
915 # and reject multiple Generic[...].
916 gvars = None
917 for base in cls.__orig_bases__:
918 if (isinstance(base, _GenericAlias) and
919 base.__origin__ is Generic):
920 if gvars is not None:
921 raise TypeError(
922 "Cannot inherit from Generic[...] multiple types.")
923 gvars = base.__parameters__
924 if gvars is not None:
925 tvarset = set(tvars)
926 gvarset = set(gvars)
927 if not tvarset <= gvarset:
928 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset)
929 s_args = ', '.join(str(g) for g in gvars)
930 raise TypeError(f"Some type variables ({s_vars}) are"
931 f" not listed in Generic[{s_args}]")
932 tvars = gvars
933 cls.__parameters__ = tuple(tvars)
936class _TypingEmpty:
937 """Internal placeholder for () or []. Used by TupleMeta and CallableMeta
938 to allow empty list/tuple in specific places, without allowing them
939 to sneak in where prohibited.
940 """
943class _TypingEllipsis:
944 """Internal placeholder for ... (ellipsis)."""
947_TYPING_INTERNALS = ['__parameters__', '__orig_bases__', '__orig_class__',
948 '_is_protocol', '_is_runtime_protocol']
950_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__',
951 '__init__', '__module__', '__new__', '__slots__',
952 '__subclasshook__', '__weakref__']
954# These special attributes will be not collected as protocol members.
955EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker']
958def _get_protocol_attrs(cls):
959 """Collect protocol members from a protocol class objects.
961 This includes names actually defined in the class dictionary, as well
962 as names that appear in annotations. Special names (above) are skipped.
963 """
964 attrs = set()
965 for base in cls.__mro__[:-1]: # without object
966 if base.__name__ in ('Protocol', 'Generic'):
967 continue
968 annotations = getattr(base, '__annotations__', {})
969 for attr in list(base.__dict__.keys()) + list(annotations.keys()):
970 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES:
971 attrs.add(attr)
972 return attrs
975def _is_callable_members_only(cls):
976 # PEP 544 prohibits using issubclass() with protocols that have non-method members.
977 return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls))
980def _no_init(self, *args, **kwargs):
981 if type(self)._is_protocol:
982 raise TypeError('Protocols cannot be instantiated')
985def _allow_reckless_class_cheks():
986 """Allow instnance and class checks for special stdlib modules.
988 The abc and functools modules indiscriminately call isinstance() and
989 issubclass() on the whole MRO of a user class, which may contain protocols.
990 """
991 try:
992 return sys._getframe(3).f_globals['__name__'] in ['abc', 'functools']
993 except (AttributeError, ValueError): # For platforms without _getframe().
994 return True
997_PROTO_WHITELIST = {
998 'collections.abc': [
999 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
1000 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible',
1001 ],
1002 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
1003}
1006class _ProtocolMeta(ABCMeta):
1007 # This metaclass is really unfortunate and exists only because of
1008 # the lack of __instancehook__.
1009 def __instancecheck__(cls, instance):
1010 # We need this method for situations where attributes are
1011 # assigned in __init__.
1012 if ((not getattr(cls, '_is_protocol', False) or
1013 _is_callable_members_only(cls)) and
1014 issubclass(instance.__class__, cls)):
1015 return True
1016 if cls._is_protocol:
1017 if all(hasattr(instance, attr) and
1018 # All *methods* can be blocked by setting them to None.
1019 (not callable(getattr(cls, attr, None)) or
1020 getattr(instance, attr) is not None)
1021 for attr in _get_protocol_attrs(cls)):
1022 return True
1023 return super().__instancecheck__(instance)
1026class Protocol(Generic, metaclass=_ProtocolMeta):
1027 """Base class for protocol classes.
1029 Protocol classes are defined as::
1031 class Proto(Protocol):
1032 def meth(self) -> int:
1033 ...
1035 Such classes are primarily used with static type checkers that recognize
1036 structural subtyping (static duck-typing), for example::
1038 class C:
1039 def meth(self) -> int:
1040 return 0
1042 def func(x: Proto) -> int:
1043 return x.meth()
1045 func(C()) # Passes static type check
1047 See PEP 544 for details. Protocol classes decorated with
1048 @typing.runtime_checkable act as simple-minded runtime protocols that check
1049 only the presence of given attributes, ignoring their type signatures.
1050 Protocol classes can be generic, they are defined as::
1052 class GenProto(Protocol[T]):
1053 def meth(self) -> T:
1054 ...
1055 """
1056 __slots__ = ()
1057 _is_protocol = True
1058 _is_runtime_protocol = False
1060 def __init_subclass__(cls, *args, **kwargs):
1061 super().__init_subclass__(*args, **kwargs)
1063 # Determine if this is a protocol or a concrete subclass.
1064 if not cls.__dict__.get('_is_protocol', False):
1065 cls._is_protocol = any(b is Protocol for b in cls.__bases__)
1067 # Set (or override) the protocol subclass hook.
1068 def _proto_hook(other):
1069 if not cls.__dict__.get('_is_protocol', False):
1070 return NotImplemented
1072 # First, perform various sanity checks.
1073 if not getattr(cls, '_is_runtime_protocol', False):
1074 if _allow_reckless_class_cheks():
1075 return NotImplemented
1076 raise TypeError("Instance and class checks can only be used with"
1077 " @runtime_checkable protocols")
1078 if not _is_callable_members_only(cls):
1079 if _allow_reckless_class_cheks():
1080 return NotImplemented
1081 raise TypeError("Protocols with non-method members"
1082 " don't support issubclass()")
1083 if not isinstance(other, type):
1084 # Same error message as for issubclass(1, int).
1085 raise TypeError('issubclass() arg 1 must be a class')
1087 # Second, perform the actual structural compatibility check.
1088 for attr in _get_protocol_attrs(cls):
1089 for base in other.__mro__:
1090 # Check if the members appears in the class dictionary...
1091 if attr in base.__dict__:
1092 if base.__dict__[attr] is None:
1093 return NotImplemented
1094 break
1096 # ...or in annotations, if it is a sub-protocol.
1097 annotations = getattr(base, '__annotations__', {})
1098 if (isinstance(annotations, collections.abc.Mapping) and
1099 attr in annotations and
1100 issubclass(other, Generic) and other._is_protocol):
1101 break
1102 else:
1103 return NotImplemented
1104 return True
1106 if '__subclasshook__' not in cls.__dict__:
1107 cls.__subclasshook__ = _proto_hook
1109 # We have nothing more to do for non-protocols...
1110 if not cls._is_protocol:
1111 return
1113 # ... otherwise check consistency of bases, and prohibit instantiation.
1114 for base in cls.__bases__:
1115 if not (base in (object, Generic) or
1116 base.__module__ in _PROTO_WHITELIST and
1117 base.__name__ in _PROTO_WHITELIST[base.__module__] or
1118 issubclass(base, Generic) and base._is_protocol):
1119 raise TypeError('Protocols can only inherit from other'
1120 ' protocols, got %r' % base)
1121 cls.__init__ = _no_init
1124def runtime_checkable(cls):
1125 """Mark a protocol class as a runtime protocol.
1127 Such protocol can be used with isinstance() and issubclass().
1128 Raise TypeError if applied to a non-protocol class.
1129 This allows a simple-minded structural check very similar to
1130 one trick ponies in collections.abc such as Iterable.
1131 For example::
1133 @runtime_checkable
1134 class Closable(Protocol):
1135 def close(self): ...
1137 assert isinstance(open('/some/file'), Closable)
1139 Warning: this will check only the presence of the required methods,
1140 not their type signatures!
1141 """
1142 if not issubclass(cls, Generic) or not cls._is_protocol:
1143 raise TypeError('@runtime_checkable can be only applied to protocol classes,'
1144 ' got %r' % cls)
1145 cls._is_runtime_protocol = True
1146 return cls
1149def cast(typ, val):
1150 """Cast a value to a type.
1152 This returns the value unchanged. To the type checker this
1153 signals that the return value has the designated type, but at
1154 runtime we intentionally don't check anything (we want this
1155 to be as fast as possible).
1156 """
1157 return val
1160def _get_defaults(func):
1161 """Internal helper to extract the default arguments, by name."""
1162 try:
1163 code = func.__code__
1164 except AttributeError:
1165 # Some built-in functions don't have __code__, __defaults__, etc.
1166 return {}
1167 pos_count = code.co_argcount
1168 arg_names = code.co_varnames
1169 arg_names = arg_names[:pos_count]
1170 defaults = func.__defaults__ or ()
1171 kwdefaults = func.__kwdefaults__
1172 res = dict(kwdefaults) if kwdefaults else {}
1173 pos_offset = pos_count - len(defaults)
1174 for name, value in zip(arg_names[pos_offset:], defaults):
1175 assert name not in res
1176 res[name] = value
1177 return res
1180_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
1181 types.MethodType, types.ModuleType,
1182 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
1185def get_type_hints(obj, globalns=None, localns=None):
1186 """Return type hints for an object.
1188 This is often the same as obj.__annotations__, but it handles
1189 forward references encoded as string literals, and if necessary
1190 adds Optional[t] if a default value equal to None is set.
1192 The argument may be a module, class, method, or function. The annotations
1193 are returned as a dictionary. For classes, annotations include also
1194 inherited members.
1196 TypeError is raised if the argument is not of a type that can contain
1197 annotations, and an empty dictionary is returned if no annotations are
1198 present.
1200 BEWARE -- the behavior of globalns and localns is counterintuitive
1201 (unless you are familiar with how eval() and exec() work). The
1202 search order is locals first, then globals.
1204 - If no dict arguments are passed, an attempt is made to use the
1205 globals from obj (or the respective module's globals for classes),
1206 and these are also used as the locals. If the object does not appear
1207 to have globals, an empty dictionary is used.
1209 - If one dict argument is passed, it is used for both globals and
1210 locals.
1212 - If two dict arguments are passed, they specify globals and
1213 locals, respectively.
1214 """
1216 if getattr(obj, '__no_type_check__', None):
1217 return {}
1218 # Classes require a special treatment.
1219 if isinstance(obj, type):
1220 hints = {}
1221 for base in reversed(obj.__mro__):
1222 if globalns is None:
1223 base_globals = sys.modules[base.__module__].__dict__
1224 else:
1225 base_globals = globalns
1226 ann = base.__dict__.get('__annotations__', {})
1227 for name, value in ann.items():
1228 if value is None:
1229 value = type(None)
1230 if isinstance(value, str):
1231 value = ForwardRef(value, is_argument=False)
1232 value = _eval_type(value, base_globals, localns)
1233 hints[name] = value
1234 return hints
1236 if globalns is None:
1237 if isinstance(obj, types.ModuleType):
1238 globalns = obj.__dict__
1239 else:
1240 nsobj = obj
1241 # Find globalns for the unwrapped object.
1242 while hasattr(nsobj, '__wrapped__'):
1243 nsobj = nsobj.__wrapped__
1244 globalns = getattr(nsobj, '__globals__', {})
1245 if localns is None:
1246 localns = globalns
1247 elif localns is None:
1248 localns = globalns
1249 hints = getattr(obj, '__annotations__', None)
1250 if hints is None:
1251 # Return empty annotations for something that _could_ have them.
1252 if isinstance(obj, _allowed_types):
1253 return {}
1254 else:
1255 raise TypeError('{!r} is not a module, class, method, '
1256 'or function.'.format(obj))
1257 defaults = _get_defaults(obj)
1258 hints = dict(hints)
1259 for name, value in hints.items():
1260 if value is None:
1261 value = type(None)
1262 if isinstance(value, str):
1263 value = ForwardRef(value)
1264 value = _eval_type(value, globalns, localns)
1265 if name in defaults and defaults[name] is None:
1266 value = Optional[value]
1267 hints[name] = value
1268 return hints
1271def get_origin(tp):
1272 """Get the unsubscripted version of a type.
1274 This supports generic types, Callable, Tuple, Union, Literal, Final and ClassVar.
1275 Return None for unsupported types. Examples::
1277 get_origin(Literal[42]) is Literal
1278 get_origin(int) is None
1279 get_origin(ClassVar[int]) is ClassVar
1280 get_origin(Generic) is Generic
1281 get_origin(Generic[T]) is Generic
1282 get_origin(Union[T, int]) is Union
1283 get_origin(List[Tuple[T, T]][int]) == list
1284 """
1285 if isinstance(tp, _GenericAlias):
1286 return tp.__origin__
1287 if tp is Generic:
1288 return Generic
1289 return None
1292def get_args(tp):
1293 """Get type arguments with all substitutions performed.
1295 For unions, basic simplifications used by Union constructor are performed.
1296 Examples::
1297 get_args(Dict[str, int]) == (str, int)
1298 get_args(int) == ()
1299 get_args(Union[int, Union[T, int], str][int]) == (int, str)
1300 get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
1301 get_args(Callable[[], T][int]) == ([], int)
1302 """
1303 if isinstance(tp, _GenericAlias) and not tp._special:
1304 res = tp.__args__
1305 if get_origin(tp) is collections.abc.Callable and res[0] is not Ellipsis:
1306 res = (list(res[:-1]), res[-1])
1307 return res
1308 return ()
1311def no_type_check(arg):
1312 """Decorator to indicate that annotations are not type hints.
1314 The argument must be a class or function; if it is a class, it
1315 applies recursively to all methods and classes defined in that class
1316 (but not to methods defined in its superclasses or subclasses).
1318 This mutates the function(s) or class(es) in place.
1319 """
1320 if isinstance(arg, type):
1321 arg_attrs = arg.__dict__.copy()
1322 for attr, val in arg.__dict__.items():
1323 if val in arg.__bases__ + (arg,):
1324 arg_attrs.pop(attr)
1325 for obj in arg_attrs.values():
1326 if isinstance(obj, types.FunctionType):
1327 obj.__no_type_check__ = True
1328 if isinstance(obj, type):
1329 no_type_check(obj)
1330 try:
1331 arg.__no_type_check__ = True
1332 except TypeError: # built-in classes
1333 pass
1334 return arg
1337def no_type_check_decorator(decorator):
1338 """Decorator to give another decorator the @no_type_check effect.
1340 This wraps the decorator with something that wraps the decorated
1341 function in @no_type_check.
1342 """
1344 @functools.wraps(decorator)
1345 def wrapped_decorator(*args, **kwds):
1346 func = decorator(*args, **kwds)
1347 func = no_type_check(func)
1348 return func
1350 return wrapped_decorator
1353def _overload_dummy(*args, **kwds):
1354 """Helper for @overload to raise when called."""
1355 raise NotImplementedError(
1356 "You should not call an overloaded function. "
1357 "A series of @overload-decorated functions "
1358 "outside a stub module should always be followed "
1359 "by an implementation that is not @overload-ed.")
1362def overload(func):
1363 """Decorator for overloaded functions/methods.
1365 In a stub file, place two or more stub definitions for the same
1366 function in a row, each decorated with @overload. For example:
1368 @overload
1369 def utf8(value: None) -> None: ...
1370 @overload
1371 def utf8(value: bytes) -> bytes: ...
1372 @overload
1373 def utf8(value: str) -> bytes: ...
1375 In a non-stub file (i.e. a regular .py file), do the same but
1376 follow it with an implementation. The implementation should *not*
1377 be decorated with @overload. For example:
1379 @overload
1380 def utf8(value: None) -> None: ...
1381 @overload
1382 def utf8(value: bytes) -> bytes: ...
1383 @overload
1384 def utf8(value: str) -> bytes: ...
1385 def utf8(value):
1386 # implementation goes here
1387 """
1388 return _overload_dummy
1391def final(f):
1392 """A decorator to indicate final methods and final classes.
1394 Use this decorator to indicate to type checkers that the decorated
1395 method cannot be overridden, and decorated class cannot be subclassed.
1396 For example:
1398 class Base:
1399 @final
1400 def done(self) -> None:
1401 ...
1402 class Sub(Base):
1403 def done(self) -> None: # Error reported by type checker
1404 ...
1406 @final
1407 class Leaf:
1408 ...
1409 class Other(Leaf): # Error reported by type checker
1410 ...
1412 There is no runtime checking of these properties.
1413 """
1414 return f
1417# Some unconstrained type variables. These are used by the container types.
1418# (These are not for export.)
1419T = TypeVar('T') # Any type.
1420KT = TypeVar('KT') # Key type.
1421VT = TypeVar('VT') # Value type.
1422T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
1423V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
1424VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
1425T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant.
1426# Internal type variable used for Type[].
1427CT_co = TypeVar('CT_co', covariant=True, bound=type)
1429# A useful type variable with constraints. This represents string types.
1430# (This one *is* for export!)
1431AnyStr = TypeVar('AnyStr', bytes, str)
1434# Various ABCs mimicking those in collections.abc.
1435def _alias(origin, params, inst=True):
1436 return _GenericAlias(origin, params, special=True, inst=inst)
1438Hashable = _alias(collections.abc.Hashable, ()) # Not generic.
1439Awaitable = _alias(collections.abc.Awaitable, T_co)
1440Coroutine = _alias(collections.abc.Coroutine, (T_co, T_contra, V_co))
1441AsyncIterable = _alias(collections.abc.AsyncIterable, T_co)
1442AsyncIterator = _alias(collections.abc.AsyncIterator, T_co)
1443Iterable = _alias(collections.abc.Iterable, T_co)
1444Iterator = _alias(collections.abc.Iterator, T_co)
1445Reversible = _alias(collections.abc.Reversible, T_co)
1446Sized = _alias(collections.abc.Sized, ()) # Not generic.
1447Container = _alias(collections.abc.Container, T_co)
1448Collection = _alias(collections.abc.Collection, T_co)
1449Callable = _VariadicGenericAlias(collections.abc.Callable, (), special=True)
1450Callable.__doc__ = \
1451 """Callable type; Callable[[int], str] is a function of (int) -> str.
1453 The subscription syntax must always be used with exactly two
1454 values: the argument list and the return type. The argument list
1455 must be a list of types or ellipsis; the return type must be a single type.
1457 There is no syntax to indicate optional or keyword arguments,
1458 such function types are rarely used as callback types.
1459 """
1460AbstractSet = _alias(collections.abc.Set, T_co)
1461MutableSet = _alias(collections.abc.MutableSet, T)
1462# NOTE: Mapping is only covariant in the value type.
1463Mapping = _alias(collections.abc.Mapping, (KT, VT_co))
1464MutableMapping = _alias(collections.abc.MutableMapping, (KT, VT))
1465Sequence = _alias(collections.abc.Sequence, T_co)
1466MutableSequence = _alias(collections.abc.MutableSequence, T)
1467ByteString = _alias(collections.abc.ByteString, ()) # Not generic
1468Tuple = _VariadicGenericAlias(tuple, (), inst=False, special=True)
1469Tuple.__doc__ = \
1470 """Tuple type; Tuple[X, Y] is the cross-product type of X and Y.
1472 Example: Tuple[T1, T2] is a tuple of two elements corresponding
1473 to type variables T1 and T2. Tuple[int, float, str] is a tuple
1474 of an int, a float and a string.
1476 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
1477 """
1478List = _alias(list, T, inst=False)
1479Deque = _alias(collections.deque, T)
1480Set = _alias(set, T, inst=False)
1481FrozenSet = _alias(frozenset, T_co, inst=False)
1482MappingView = _alias(collections.abc.MappingView, T_co)
1483KeysView = _alias(collections.abc.KeysView, KT)
1484ItemsView = _alias(collections.abc.ItemsView, (KT, VT_co))
1485ValuesView = _alias(collections.abc.ValuesView, VT_co)
1486ContextManager = _alias(contextlib.AbstractContextManager, T_co)
1487AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, T_co)
1488Dict = _alias(dict, (KT, VT), inst=False)
1489DefaultDict = _alias(collections.defaultdict, (KT, VT))
1490OrderedDict = _alias(collections.OrderedDict, (KT, VT))
1491Counter = _alias(collections.Counter, T)
1492ChainMap = _alias(collections.ChainMap, (KT, VT))
1493Generator = _alias(collections.abc.Generator, (T_co, T_contra, V_co))
1494AsyncGenerator = _alias(collections.abc.AsyncGenerator, (T_co, T_contra))
1495Type = _alias(type, CT_co, inst=False)
1496Type.__doc__ = \
1497 """A special construct usable to annotate class objects.
1499 For example, suppose we have the following classes::
1501 class User: ... # Abstract base for User classes
1502 class BasicUser(User): ...
1503 class ProUser(User): ...
1504 class TeamUser(User): ...
1506 And a function that takes a class argument that's a subclass of
1507 User and returns an instance of the corresponding class::
1509 U = TypeVar('U', bound=User)
1510 def new_user(user_class: Type[U]) -> U:
1511 user = user_class()
1512 # (Here we could write the user object to a database)
1513 return user
1515 joe = new_user(BasicUser)
1517 At this point the type checker knows that joe has type BasicUser.
1518 """
1521@runtime_checkable
1522class SupportsInt(Protocol):
1523 """An ABC with one abstract method __int__."""
1524 __slots__ = ()
1526 @abstractmethod
1527 def __int__(self) -> int:
1528 pass
1531@runtime_checkable
1532class SupportsFloat(Protocol):
1533 """An ABC with one abstract method __float__."""
1534 __slots__ = ()
1536 @abstractmethod
1537 def __float__(self) -> float:
1538 pass
1541@runtime_checkable
1542class SupportsComplex(Protocol):
1543 """An ABC with one abstract method __complex__."""
1544 __slots__ = ()
1546 @abstractmethod
1547 def __complex__(self) -> complex:
1548 pass
1551@runtime_checkable
1552class SupportsBytes(Protocol):
1553 """An ABC with one abstract method __bytes__."""
1554 __slots__ = ()
1556 @abstractmethod
1557 def __bytes__(self) -> bytes:
1558 pass
1561@runtime_checkable
1562class SupportsIndex(Protocol):
1563 """An ABC with one abstract method __index__."""
1564 __slots__ = ()
1566 @abstractmethod
1567 def __index__(self) -> int:
1568 pass
1571@runtime_checkable
1572class SupportsAbs(Protocol[T_co]):
1573 """An ABC with one abstract method __abs__ that is covariant in its return type."""
1574 __slots__ = ()
1576 @abstractmethod
1577 def __abs__(self) -> T_co:
1578 pass
1581@runtime_checkable
1582class SupportsRound(Protocol[T_co]):
1583 """An ABC with one abstract method __round__ that is covariant in its return type."""
1584 __slots__ = ()
1586 @abstractmethod
1587 def __round__(self, ndigits: int = 0) -> T_co:
1588 pass
1591def _make_nmtuple(name, types):
1592 msg = "NamedTuple('Name', [(f0, t0), (f1, t1), ...]); each t must be a type"
1593 types = [(n, _type_check(t, msg)) for n, t in types]
1594 nm_tpl = collections.namedtuple(name, [n for n, t in types])
1595 # Prior to PEP 526, only _field_types attribute was assigned.
1596 # Now __annotations__ are used and _field_types is deprecated (remove in 3.9)
1597 nm_tpl.__annotations__ = nm_tpl._field_types = dict(types)
1598 try:
1599 nm_tpl.__module__ = sys._getframe(2).f_globals.get('__name__', '__main__')
1600 except (AttributeError, ValueError):
1601 pass
1602 return nm_tpl
1605# attributes prohibited to set in NamedTuple class syntax
1606_prohibited = ('__new__', '__init__', '__slots__', '__getnewargs__',
1607 '_fields', '_field_defaults', '_field_types',
1608 '_make', '_replace', '_asdict', '_source')
1610_special = ('__module__', '__name__', '__annotations__')
1613class NamedTupleMeta(type):
1615 def __new__(cls, typename, bases, ns):
1616 if ns.get('_root', False):
1617 return super().__new__(cls, typename, bases, ns)
1618 types = ns.get('__annotations__', {})
1619 nm_tpl = _make_nmtuple(typename, types.items())
1620 defaults = []
1621 defaults_dict = {}
1622 for field_name in types:
1623 if field_name in ns:
1624 default_value = ns[field_name]
1625 defaults.append(default_value)
1626 defaults_dict[field_name] = default_value
1627 elif defaults:
1628 raise TypeError("Non-default namedtuple field {field_name} cannot "
1629 "follow default field(s) {default_names}"
1630 .format(field_name=field_name,
1631 default_names=', '.join(defaults_dict.keys())))
1632 nm_tpl.__new__.__annotations__ = dict(types)
1633 nm_tpl.__new__.__defaults__ = tuple(defaults)
1634 nm_tpl._field_defaults = defaults_dict
1635 # update from user namespace without overriding special namedtuple attributes
1636 for key in ns:
1637 if key in _prohibited:
1638 raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
1639 elif key not in _special and key not in nm_tpl._fields:
1640 setattr(nm_tpl, key, ns[key])
1641 return nm_tpl
1644class NamedTuple(metaclass=NamedTupleMeta):
1645 """Typed version of namedtuple.
1647 Usage in Python versions >= 3.6::
1649 class Employee(NamedTuple):
1650 name: str
1651 id: int
1653 This is equivalent to::
1655 Employee = collections.namedtuple('Employee', ['name', 'id'])
1657 The resulting class has an extra __annotations__ attribute, giving a
1658 dict that maps field names to types. (The field names are also in
1659 the _fields attribute, which is part of the namedtuple API.)
1660 Alternative equivalent keyword syntax is also accepted::
1662 Employee = NamedTuple('Employee', name=str, id=int)
1664 In Python versions <= 3.5 use::
1666 Employee = NamedTuple('Employee', [('name', str), ('id', int)])
1667 """
1668 _root = True
1670 def __new__(*args, **kwargs):
1671 if not args:
1672 raise TypeError('NamedTuple.__new__(): not enough arguments')
1673 cls, *args = args # allow the "cls" keyword be passed
1674 if args:
1675 typename, *args = args # allow the "typename" keyword be passed
1676 elif 'typename' in kwargs:
1677 typename = kwargs.pop('typename')
1678 import warnings
1679 warnings.warn("Passing 'typename' as keyword argument is deprecated",
1680 DeprecationWarning, stacklevel=2)
1681 else:
1682 raise TypeError("NamedTuple.__new__() missing 1 required positional "
1683 "argument: 'typename'")
1684 if args:
1685 try:
1686 fields, = args # allow the "fields" keyword be passed
1687 except ValueError:
1688 raise TypeError(f'NamedTuple.__new__() takes from 2 to 3 '
1689 f'positional arguments but {len(args) + 2} '
1690 f'were given') from None
1691 elif 'fields' in kwargs and len(kwargs) == 1:
1692 fields = kwargs.pop('fields')
1693 import warnings
1694 warnings.warn("Passing 'fields' as keyword argument is deprecated",
1695 DeprecationWarning, stacklevel=2)
1696 else:
1697 fields = None
1699 if fields is None:
1700 fields = kwargs.items()
1701 elif kwargs:
1702 raise TypeError("Either list of fields or keywords"
1703 " can be provided to NamedTuple, not both")
1704 return _make_nmtuple(typename, fields)
1705 __new__.__text_signature__ = '($cls, typename, fields=None, /, **kwargs)'
1708def _dict_new(cls, /, *args, **kwargs):
1709 return dict(*args, **kwargs)
1712def _typeddict_new(cls, typename, fields=None, /, *, total=True, **kwargs):
1713 if fields is None:
1714 fields = kwargs
1715 elif kwargs:
1716 raise TypeError("TypedDict takes either a dict or keyword arguments,"
1717 " but not both")
1719 ns = {'__annotations__': dict(fields), '__total__': total}
1720 try:
1721 # Setting correct module is necessary to make typed dict classes pickleable.
1722 ns['__module__'] = sys._getframe(1).f_globals.get('__name__', '__main__')
1723 except (AttributeError, ValueError):
1724 pass
1726 return _TypedDictMeta(typename, (), ns)
1729def _check_fails(cls, other):
1730 # Typed dicts are only for static structural subtyping.
1731 raise TypeError('TypedDict does not support instance and class checks')
1734class _TypedDictMeta(type):
1735 def __new__(cls, name, bases, ns, total=True):
1736 """Create new typed dict class object.
1738 This method is called directly when TypedDict is subclassed,
1739 or via _typeddict_new when TypedDict is instantiated. This way
1740 TypedDict supports all three syntax forms described in its docstring.
1741 Subclasses and instances of TypedDict return actual dictionaries
1742 via _dict_new.
1743 """
1744 ns['__new__'] = _typeddict_new if name == 'TypedDict' else _dict_new
1745 tp_dict = super(_TypedDictMeta, cls).__new__(cls, name, (dict,), ns)
1747 anns = ns.get('__annotations__', {})
1748 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
1749 anns = {n: _type_check(tp, msg) for n, tp in anns.items()}
1750 for base in bases:
1751 anns.update(base.__dict__.get('__annotations__', {}))
1752 tp_dict.__annotations__ = anns
1753 if not hasattr(tp_dict, '__total__'):
1754 tp_dict.__total__ = total
1755 return tp_dict
1757 __instancecheck__ = __subclasscheck__ = _check_fails
1760class TypedDict(dict, metaclass=_TypedDictMeta):
1761 """A simple typed namespace. At runtime it is equivalent to a plain dict.
1763 TypedDict creates a dictionary type that expects all of its
1764 instances to have a certain set of keys, where each key is
1765 associated with a value of a consistent type. This expectation
1766 is not checked at runtime but is only enforced by type checkers.
1767 Usage::
1769 class Point2D(TypedDict):
1770 x: int
1771 y: int
1772 label: str
1774 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
1775 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
1777 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
1779 The type info can be accessed via Point2D.__annotations__. TypedDict
1780 supports two additional equivalent forms::
1782 Point2D = TypedDict('Point2D', x=int, y=int, label=str)
1783 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
1785 By default, all keys must be present in a TypedDict. It is possible
1786 to override this by specifying totality.
1787 Usage::
1789 class point2D(TypedDict, total=False):
1790 x: int
1791 y: int
1793 This means that a point2D TypedDict can have any of the keys omitted.A type
1794 checker is only expected to support a literal False or True as the value of
1795 the total argument. True is the default, and makes all items defined in the
1796 class body be required.
1798 The class syntax is only supported in Python 3.6+, while two other
1799 syntax forms work for Python 2.7 and 3.2+
1800 """
1803def NewType(name, tp):
1804 """NewType creates simple unique types with almost zero
1805 runtime overhead. NewType(name, tp) is considered a subtype of tp
1806 by static type checkers. At runtime, NewType(name, tp) returns
1807 a dummy function that simply returns its argument. Usage::
1809 UserId = NewType('UserId', int)
1811 def name_by_id(user_id: UserId) -> str:
1812 ...
1814 UserId('user') # Fails type check
1816 name_by_id(42) # Fails type check
1817 name_by_id(UserId(42)) # OK
1819 num = UserId(5) + 1 # type: int
1820 """
1822 def new_type(x):
1823 return x
1825 new_type.__name__ = name
1826 new_type.__supertype__ = tp
1827 return new_type
1830# Python-version-specific alias (Python 2: unicode; Python 3: str)
1831Text = str
1834# Constant that's True when type checking, but False here.
1835TYPE_CHECKING = False
1838class IO(Generic[AnyStr]):
1839 """Generic base class for TextIO and BinaryIO.
1841 This is an abstract, generic version of the return of open().
1843 NOTE: This does not distinguish between the different possible
1844 classes (text vs. binary, read vs. write vs. read/write,
1845 append-only, unbuffered). The TextIO and BinaryIO subclasses
1846 below capture the distinctions between text vs. binary, which is
1847 pervasive in the interface; however we currently do not offer a
1848 way to track the other distinctions in the type system.
1849 """
1851 __slots__ = ()
1853 @property
1854 @abstractmethod
1855 def mode(self) -> str:
1856 pass
1858 @property
1859 @abstractmethod
1860 def name(self) -> str:
1861 pass
1863 @abstractmethod
1864 def close(self) -> None:
1865 pass
1867 @property
1868 @abstractmethod
1869 def closed(self) -> bool:
1870 pass
1872 @abstractmethod
1873 def fileno(self) -> int:
1874 pass
1876 @abstractmethod
1877 def flush(self) -> None:
1878 pass
1880 @abstractmethod
1881 def isatty(self) -> bool:
1882 pass
1884 @abstractmethod
1885 def read(self, n: int = -1) -> AnyStr:
1886 pass
1888 @abstractmethod
1889 def readable(self) -> bool:
1890 pass
1892 @abstractmethod
1893 def readline(self, limit: int = -1) -> AnyStr:
1894 pass
1896 @abstractmethod
1897 def readlines(self, hint: int = -1) -> List[AnyStr]:
1898 pass
1900 @abstractmethod
1901 def seek(self, offset: int, whence: int = 0) -> int:
1902 pass
1904 @abstractmethod
1905 def seekable(self) -> bool:
1906 pass
1908 @abstractmethod
1909 def tell(self) -> int:
1910 pass
1912 @abstractmethod
1913 def truncate(self, size: int = None) -> int:
1914 pass
1916 @abstractmethod
1917 def writable(self) -> bool:
1918 pass
1920 @abstractmethod
1921 def write(self, s: AnyStr) -> int:
1922 pass
1924 @abstractmethod
1925 def writelines(self, lines: List[AnyStr]) -> None:
1926 pass
1928 @abstractmethod
1929 def __enter__(self) -> 'IO[AnyStr]':
1930 pass
1932 @abstractmethod
1933 def __exit__(self, type, value, traceback) -> None:
1934 pass
1937class BinaryIO(IO[bytes]):
1938 """Typed version of the return of open() in binary mode."""
1940 __slots__ = ()
1942 @abstractmethod
1943 def write(self, s: Union[bytes, bytearray]) -> int:
1944 pass
1946 @abstractmethod
1947 def __enter__(self) -> 'BinaryIO':
1948 pass
1951class TextIO(IO[str]):
1952 """Typed version of the return of open() in text mode."""
1954 __slots__ = ()
1956 @property
1957 @abstractmethod
1958 def buffer(self) -> BinaryIO:
1959 pass
1961 @property
1962 @abstractmethod
1963 def encoding(self) -> str:
1964 pass
1966 @property
1967 @abstractmethod
1968 def errors(self) -> Optional[str]:
1969 pass
1971 @property
1972 @abstractmethod
1973 def line_buffering(self) -> bool:
1974 pass
1976 @property
1977 @abstractmethod
1978 def newlines(self) -> Any:
1979 pass
1981 @abstractmethod
1982 def __enter__(self) -> 'TextIO':
1983 pass
1986class io:
1987 """Wrapper namespace for IO generic classes."""
1989 __all__ = ['IO', 'TextIO', 'BinaryIO']
1990 IO = IO
1991 TextIO = TextIO
1992 BinaryIO = BinaryIO
1995io.__name__ = __name__ + '.io'
1996sys.modules[io.__name__] = io
1998Pattern = _alias(stdlib_re.Pattern, AnyStr)
1999Match = _alias(stdlib_re.Match, AnyStr)
2001class re:
2002 """Wrapper namespace for re type aliases."""
2004 __all__ = ['Pattern', 'Match']
2005 Pattern = Pattern
2006 Match = Match
2009re.__name__ = __name__ + '.re'
2010sys.modules[re.__name__] = re