Coverage for /pythoncovmergedfiles/medio/medio/usr/lib/python3.9/typing.py: 13%
1046 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-10-20 07:00 +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, GenericAlias
31# Please keep __all__ alphabetized within each category.
32__all__ = [
33 # Super-special typing primitives.
34 'Annotated',
35 'Any',
36 'Callable',
37 'ClassVar',
38 'Final',
39 'ForwardRef',
40 'Generic',
41 'Literal',
42 'Optional',
43 'Protocol',
44 'Tuple',
45 'Type',
46 'TypeVar',
47 'Union',
49 # ABCs (from collections.abc).
50 'AbstractSet', # collections.abc.Set.
51 'ByteString',
52 'Container',
53 'ContextManager',
54 'Hashable',
55 'ItemsView',
56 'Iterable',
57 'Iterator',
58 'KeysView',
59 'Mapping',
60 'MappingView',
61 'MutableMapping',
62 'MutableSequence',
63 'MutableSet',
64 'Sequence',
65 'Sized',
66 'ValuesView',
67 'Awaitable',
68 'AsyncIterator',
69 'AsyncIterable',
70 'Coroutine',
71 'Collection',
72 'AsyncGenerator',
73 'AsyncContextManager',
75 # Structural checks, a.k.a. protocols.
76 'Reversible',
77 'SupportsAbs',
78 'SupportsBytes',
79 'SupportsComplex',
80 'SupportsFloat',
81 'SupportsIndex',
82 'SupportsInt',
83 'SupportsRound',
85 # Concrete collection types.
86 'ChainMap',
87 'Counter',
88 'Deque',
89 'Dict',
90 'DefaultDict',
91 'List',
92 'OrderedDict',
93 'Set',
94 'FrozenSet',
95 'NamedTuple', # Not really a type.
96 'TypedDict', # Not really a type.
97 'Generator',
99 # One-off things.
100 'AnyStr',
101 'cast',
102 'final',
103 'get_args',
104 'get_origin',
105 'get_type_hints',
106 'NewType',
107 'no_type_check',
108 'no_type_check_decorator',
109 'NoReturn',
110 'overload',
111 'runtime_checkable',
112 'Text',
113 'TYPE_CHECKING',
114]
116# The pseudo-submodules 're' and 'io' are part of the public
117# namespace, but excluded from __all__ because they might stomp on
118# legitimate imports of those modules.
121def _type_convert(arg):
122 """For converting None to type(None), and strings to ForwardRef."""
123 if arg is None:
124 return type(None)
125 if isinstance(arg, str):
126 return ForwardRef(arg)
127 return arg
130def _type_check(arg, msg, is_argument=True):
131 """Check that the argument is a type, and return it (internal helper).
133 As a special case, accept None and return type(None) instead. Also wrap strings
134 into ForwardRef instances. Consider several corner cases, for example plain
135 special forms like Union are not valid, while Union[int, str] is OK, etc.
136 The msg argument is a human-readable error message, e.g::
138 "Union[arg, ...]: arg should be a type."
140 We append the repr() of the actual value (truncated to 100 chars).
141 """
142 invalid_generic_forms = (Generic, Protocol)
143 if is_argument:
144 invalid_generic_forms = invalid_generic_forms + (ClassVar, Final)
146 arg = _type_convert(arg)
147 if (isinstance(arg, _GenericAlias) and
148 arg.__origin__ in invalid_generic_forms):
149 raise TypeError(f"{arg} is not valid as type argument")
150 if arg in (Any, NoReturn):
151 return arg
152 if isinstance(arg, _SpecialForm) or arg in (Generic, Protocol):
153 raise TypeError(f"Plain {arg} is not valid as type argument")
154 if isinstance(arg, (type, TypeVar, ForwardRef)):
155 return arg
156 if not callable(arg):
157 raise TypeError(f"{msg} Got {arg!r:.100}.")
158 return arg
161def _type_repr(obj):
162 """Return the repr() of an object, special-casing types (internal helper).
164 If obj is a type, we return a shorter version than the default
165 type.__repr__, based on the module and qualified name, which is
166 typically enough to uniquely identify a type. For everything
167 else, we fall back on repr(obj).
168 """
169 if isinstance(obj, types.GenericAlias):
170 return repr(obj)
171 if isinstance(obj, type):
172 if obj.__module__ == 'builtins':
173 return obj.__qualname__
174 return f'{obj.__module__}.{obj.__qualname__}'
175 if obj is ...:
176 return('...')
177 if isinstance(obj, types.FunctionType):
178 return obj.__name__
179 return repr(obj)
182def _collect_type_vars(types):
183 """Collect all type variable contained in types in order of
184 first appearance (lexicographic order). For example::
186 _collect_type_vars((T, List[S, T])) == (T, S)
187 """
188 tvars = []
189 for t in types:
190 if isinstance(t, TypeVar) and t not in tvars:
191 tvars.append(t)
192 if isinstance(t, (_GenericAlias, GenericAlias)):
193 tvars.extend([t for t in t.__parameters__ if t not in tvars])
194 return tuple(tvars)
197def _check_generic(cls, parameters, elen):
198 """Check correct count for parameters of a generic cls (internal helper).
199 This gives a nice error message in case of count mismatch.
200 """
201 if not elen:
202 raise TypeError(f"{cls} is not a generic class")
203 alen = len(parameters)
204 if alen != elen:
205 raise TypeError(f"Too {'many' if alen > elen else 'few'} parameters for {cls};"
206 f" actual {alen}, expected {elen}")
209def _deduplicate(params):
210 # Weed out strict duplicates, preserving the first of each occurrence.
211 all_params = set(params)
212 if len(all_params) < len(params):
213 new_params = []
214 for t in params:
215 if t in all_params:
216 new_params.append(t)
217 all_params.remove(t)
218 params = new_params
219 assert not all_params, all_params
220 return params
223def _remove_dups_flatten(parameters):
224 """An internal helper for Union creation and substitution: flatten Unions
225 among parameters, then remove duplicates.
226 """
227 # Flatten out Union[Union[...], ...].
228 params = []
229 for p in parameters:
230 if isinstance(p, _UnionGenericAlias):
231 params.extend(p.__args__)
232 elif isinstance(p, tuple) and len(p) > 0 and p[0] is Union:
233 params.extend(p[1:])
234 else:
235 params.append(p)
237 return tuple(_deduplicate(params))
240def _flatten_literal_params(parameters):
241 """An internal helper for Literal creation: flatten Literals among parameters"""
242 params = []
243 for p in parameters:
244 if isinstance(p, _LiteralGenericAlias):
245 params.extend(p.__args__)
246 else:
247 params.append(p)
248 return tuple(params)
251_cleanups = []
254def _tp_cache(func=None, /, *, typed=False):
255 """Internal wrapper caching __getitem__ of generic types with a fallback to
256 original function for non-hashable arguments.
257 """
258 def decorator(func):
259 cached = functools.lru_cache(typed=typed)(func)
260 _cleanups.append(cached.cache_clear)
262 @functools.wraps(func)
263 def inner(*args, **kwds):
264 try:
265 return cached(*args, **kwds)
266 except TypeError:
267 pass # All real errors (not unhashable args) are raised below.
268 return func(*args, **kwds)
269 return inner
271 if func is not None:
272 return decorator(func)
274 return decorator
276def _eval_type(t, globalns, localns, recursive_guard=frozenset()):
277 """Evaluate all forward references in the given type t.
278 For use of globalns and localns see the docstring for get_type_hints().
279 recursive_guard is used to prevent prevent infinite recursion
280 with recursive ForwardRef.
281 """
282 if isinstance(t, ForwardRef):
283 return t._evaluate(globalns, localns, recursive_guard)
284 if isinstance(t, (_GenericAlias, GenericAlias)):
285 ev_args = tuple(_eval_type(a, globalns, localns, recursive_guard) for a in t.__args__)
286 if ev_args == t.__args__:
287 return t
288 if isinstance(t, GenericAlias):
289 return GenericAlias(t.__origin__, ev_args)
290 else:
291 return t.copy_with(ev_args)
292 return t
295class _Final:
296 """Mixin to prohibit subclassing"""
298 __slots__ = ('__weakref__',)
300 def __init_subclass__(self, /, *args, **kwds):
301 if '_root' not in kwds:
302 raise TypeError("Cannot subclass special typing classes")
304class _Immutable:
305 """Mixin to indicate that object should not be copied."""
306 __slots__ = ()
308 def __copy__(self):
309 return self
311 def __deepcopy__(self, memo):
312 return self
315# Internal indicator of special typing constructs.
316# See __doc__ instance attribute for specific docs.
317class _SpecialForm(_Final, _root=True):
318 __slots__ = ('_name', '__doc__', '_getitem')
320 def __init__(self, getitem):
321 self._getitem = getitem
322 self._name = getitem.__name__
323 self.__doc__ = getitem.__doc__
325 def __mro_entries__(self, bases):
326 raise TypeError(f"Cannot subclass {self!r}")
328 def __repr__(self):
329 return 'typing.' + self._name
331 def __reduce__(self):
332 return self._name
334 def __call__(self, *args, **kwds):
335 raise TypeError(f"Cannot instantiate {self!r}")
337 def __instancecheck__(self, obj):
338 raise TypeError(f"{self} cannot be used with isinstance()")
340 def __subclasscheck__(self, cls):
341 raise TypeError(f"{self} cannot be used with issubclass()")
343 @_tp_cache
344 def __getitem__(self, parameters):
345 return self._getitem(self, parameters)
348class _LiteralSpecialForm(_SpecialForm, _root=True):
349 @_tp_cache(typed=True)
350 def __getitem__(self, parameters):
351 return self._getitem(self, parameters)
354@_SpecialForm
355def Any(self, parameters):
356 """Special type indicating an unconstrained type.
358 - Any is compatible with every type.
359 - Any assumed to have all methods.
360 - All values assumed to be instances of Any.
362 Note that all the above statements are true from the point of view of
363 static type checkers. At runtime, Any should not be used with instance
364 or class checks.
365 """
366 raise TypeError(f"{self} is not subscriptable")
368@_SpecialForm
369def NoReturn(self, parameters):
370 """Special type indicating functions that never return.
371 Example::
373 from typing import NoReturn
375 def stop() -> NoReturn:
376 raise Exception('no way')
378 This type is invalid in other positions, e.g., ``List[NoReturn]``
379 will fail in static type checkers.
380 """
381 raise TypeError(f"{self} is not subscriptable")
383@_SpecialForm
384def ClassVar(self, parameters):
385 """Special type construct to mark class variables.
387 An annotation wrapped in ClassVar indicates that a given
388 attribute is intended to be used as a class variable and
389 should not be set on instances of that class. Usage::
391 class Starship:
392 stats: ClassVar[Dict[str, int]] = {} # class variable
393 damage: int = 10 # instance variable
395 ClassVar accepts only types and cannot be further subscribed.
397 Note that ClassVar is not a class itself, and should not
398 be used with isinstance() or issubclass().
399 """
400 item = _type_check(parameters, f'{self} accepts only single type.')
401 return _GenericAlias(self, (item,))
403@_SpecialForm
404def Final(self, parameters):
405 """Special typing construct to indicate final names to type checkers.
407 A final name cannot be re-assigned or overridden in a subclass.
408 For example:
410 MAX_SIZE: Final = 9000
411 MAX_SIZE += 1 # Error reported by type checker
413 class Connection:
414 TIMEOUT: Final[int] = 10
416 class FastConnector(Connection):
417 TIMEOUT = 1 # Error reported by type checker
419 There is no runtime checking of these properties.
420 """
421 item = _type_check(parameters, f'{self} accepts only single type.')
422 return _GenericAlias(self, (item,))
424@_SpecialForm
425def Union(self, parameters):
426 """Union type; Union[X, Y] means either X or Y.
428 To define a union, use e.g. Union[int, str]. Details:
429 - The arguments must be types and there must be at least one.
430 - None as an argument is a special case and is replaced by
431 type(None).
432 - Unions of unions are flattened, e.g.::
434 Union[Union[int, str], float] == Union[int, str, float]
436 - Unions of a single argument vanish, e.g.::
438 Union[int] == int # The constructor actually returns int
440 - Redundant arguments are skipped, e.g.::
442 Union[int, str, int] == Union[int, str]
444 - When comparing unions, the argument order is ignored, e.g.::
446 Union[int, str] == Union[str, int]
448 - You cannot subclass or instantiate a union.
449 - You can use Optional[X] as a shorthand for Union[X, None].
450 """
451 if parameters == ():
452 raise TypeError("Cannot take a Union of no types.")
453 if not isinstance(parameters, tuple):
454 parameters = (parameters,)
455 msg = "Union[arg, ...]: each arg must be a type."
456 parameters = tuple(_type_check(p, msg) for p in parameters)
457 parameters = _remove_dups_flatten(parameters)
458 if len(parameters) == 1:
459 return parameters[0]
460 return _UnionGenericAlias(self, parameters)
462@_SpecialForm
463def Optional(self, parameters):
464 """Optional type.
466 Optional[X] is equivalent to Union[X, None].
467 """
468 arg = _type_check(parameters, f"{self} requires a single type.")
469 return Union[arg, type(None)]
471@_LiteralSpecialForm
472def Literal(self, parameters):
473 """Special typing form to define literal types (a.k.a. value types).
475 This form can be used to indicate to type checkers that the corresponding
476 variable or function parameter has a value equivalent to the provided
477 literal (or one of several literals):
479 def validate_simple(data: Any) -> Literal[True]: # always returns True
480 ...
482 MODE = Literal['r', 'rb', 'w', 'wb']
483 def open_helper(file: str, mode: MODE) -> str:
484 ...
486 open_helper('/some/path', 'r') # Passes type check
487 open_helper('/other/path', 'typo') # Error in type checker
489 Literal[...] cannot be subclassed. At runtime, an arbitrary value
490 is allowed as type argument to Literal[...], but type checkers may
491 impose restrictions.
492 """
493 # There is no '_type_check' call because arguments to Literal[...] are
494 # values, not types.
495 if not isinstance(parameters, tuple):
496 parameters = (parameters,)
498 parameters = _flatten_literal_params(parameters)
500 try:
501 parameters = tuple(p for p, _ in _deduplicate(list(_value_and_type_iter(parameters))))
502 except TypeError: # unhashable parameters
503 pass
505 return _LiteralGenericAlias(self, parameters)
508class ForwardRef(_Final, _root=True):
509 """Internal wrapper to hold a forward reference."""
511 __slots__ = ('__forward_arg__', '__forward_code__',
512 '__forward_evaluated__', '__forward_value__',
513 '__forward_is_argument__')
515 def __init__(self, arg, is_argument=True):
516 if not isinstance(arg, str):
517 raise TypeError(f"Forward reference must be a string -- got {arg!r}")
518 try:
519 code = compile(arg, '<string>', 'eval')
520 except SyntaxError:
521 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}")
522 self.__forward_arg__ = arg
523 self.__forward_code__ = code
524 self.__forward_evaluated__ = False
525 self.__forward_value__ = None
526 self.__forward_is_argument__ = is_argument
528 def _evaluate(self, globalns, localns, recursive_guard):
529 if self.__forward_arg__ in recursive_guard:
530 return self
531 if not self.__forward_evaluated__ or localns is not globalns:
532 if globalns is None and localns is None:
533 globalns = localns = {}
534 elif globalns is None:
535 globalns = localns
536 elif localns is None:
537 localns = globalns
538 type_ =_type_check(
539 eval(self.__forward_code__, globalns, localns),
540 "Forward references must evaluate to types.",
541 is_argument=self.__forward_is_argument__,
542 )
543 self.__forward_value__ = _eval_type(
544 type_, globalns, localns, recursive_guard | {self.__forward_arg__}
545 )
546 self.__forward_evaluated__ = True
547 return self.__forward_value__
549 def __eq__(self, other):
550 if not isinstance(other, ForwardRef):
551 return NotImplemented
552 if self.__forward_evaluated__ and other.__forward_evaluated__:
553 return (self.__forward_arg__ == other.__forward_arg__ and
554 self.__forward_value__ == other.__forward_value__)
555 return self.__forward_arg__ == other.__forward_arg__
557 def __hash__(self):
558 return hash(self.__forward_arg__)
560 def __repr__(self):
561 return f'ForwardRef({self.__forward_arg__!r})'
564class TypeVar(_Final, _Immutable, _root=True):
565 """Type variable.
567 Usage::
569 T = TypeVar('T') # Can be anything
570 A = TypeVar('A', str, bytes) # Must be str or bytes
572 Type variables exist primarily for the benefit of static type
573 checkers. They serve as the parameters for generic types as well
574 as for generic function definitions. See class Generic for more
575 information on generic types. Generic functions work as follows:
577 def repeat(x: T, n: int) -> List[T]:
578 '''Return a list containing n references to x.'''
579 return [x]*n
581 def longest(x: A, y: A) -> A:
582 '''Return the longest of two strings.'''
583 return x if len(x) >= len(y) else y
585 The latter example's signature is essentially the overloading
586 of (str, str) -> str and (bytes, bytes) -> bytes. Also note
587 that if the arguments are instances of some subclass of str,
588 the return type is still plain str.
590 At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
592 Type variables defined with covariant=True or contravariant=True
593 can be used to declare covariant or contravariant generic types.
594 See PEP 484 for more details. By default generic types are invariant
595 in all type variables.
597 Type variables can be introspected. e.g.:
599 T.__name__ == 'T'
600 T.__constraints__ == ()
601 T.__covariant__ == False
602 T.__contravariant__ = False
603 A.__constraints__ == (str, bytes)
605 Note that only type variables defined in global scope can be pickled.
606 """
608 __slots__ = ('__name__', '__bound__', '__constraints__',
609 '__covariant__', '__contravariant__', '__dict__')
611 def __init__(self, name, *constraints, bound=None,
612 covariant=False, contravariant=False):
613 self.__name__ = name
614 if covariant and contravariant:
615 raise ValueError("Bivariant types are not supported.")
616 self.__covariant__ = bool(covariant)
617 self.__contravariant__ = bool(contravariant)
618 if constraints and bound is not None:
619 raise TypeError("Constraints cannot be combined with bound=...")
620 if constraints and len(constraints) == 1:
621 raise TypeError("A single constraint is not allowed")
622 msg = "TypeVar(name, constraint, ...): constraints must be types."
623 self.__constraints__ = tuple(_type_check(t, msg) for t in constraints)
624 if bound:
625 self.__bound__ = _type_check(bound, "Bound must be a type.")
626 else:
627 self.__bound__ = None
628 try:
629 def_mod = sys._getframe(1).f_globals.get('__name__', '__main__') # for pickling
630 except (AttributeError, ValueError):
631 def_mod = None
632 if def_mod != 'typing':
633 self.__module__ = def_mod
635 def __repr__(self):
636 if self.__covariant__:
637 prefix = '+'
638 elif self.__contravariant__:
639 prefix = '-'
640 else:
641 prefix = '~'
642 return prefix + self.__name__
644 def __reduce__(self):
645 return self.__name__
648def _is_dunder(attr):
649 return attr.startswith('__') and attr.endswith('__')
651class _BaseGenericAlias(_Final, _root=True):
652 """The central part of internal API.
654 This represents a generic version of type 'origin' with type arguments 'params'.
655 There are two kind of these aliases: user defined and special. The special ones
656 are wrappers around builtin collections and ABCs in collections.abc. These must
657 have 'name' always set. If 'inst' is False, then the alias can't be instantiated,
658 this is used by e.g. typing.List and typing.Dict.
659 """
660 def __init__(self, origin, *, inst=True, name=None):
661 self._inst = inst
662 self._name = name
663 self.__origin__ = origin
664 self.__slots__ = None # This is not documented.
666 def __call__(self, *args, **kwargs):
667 if not self._inst:
668 raise TypeError(f"Type {self._name} cannot be instantiated; "
669 f"use {self.__origin__.__name__}() instead")
670 result = self.__origin__(*args, **kwargs)
671 try:
672 result.__orig_class__ = self
673 except AttributeError:
674 pass
675 return result
677 def __mro_entries__(self, bases):
678 res = []
679 if self.__origin__ not in bases:
680 res.append(self.__origin__)
681 i = bases.index(self)
682 for b in bases[i+1:]:
683 if isinstance(b, _BaseGenericAlias) or issubclass(b, Generic):
684 break
685 else:
686 res.append(Generic)
687 return tuple(res)
689 def __getattr__(self, attr):
690 # We are careful for copy and pickle.
691 # Also for simplicity we just don't relay all dunder names
692 if '__origin__' in self.__dict__ and not _is_dunder(attr):
693 return getattr(self.__origin__, attr)
694 raise AttributeError(attr)
696 def __setattr__(self, attr, val):
697 if _is_dunder(attr) or attr in ('_name', '_inst', '_nparams'):
698 super().__setattr__(attr, val)
699 else:
700 setattr(self.__origin__, attr, val)
702 def __instancecheck__(self, obj):
703 return self.__subclasscheck__(type(obj))
705 def __subclasscheck__(self, cls):
706 raise TypeError("Subscripted generics cannot be used with"
707 " class and instance checks")
710# Special typing constructs Union, Optional, Generic, Callable and Tuple
711# use three special attributes for internal bookkeeping of generic types:
712# * __parameters__ is a tuple of unique free type parameters of a generic
713# type, for example, Dict[T, T].__parameters__ == (T,);
714# * __origin__ keeps a reference to a type that was subscripted,
715# e.g., Union[T, int].__origin__ == Union, or the non-generic version of
716# the type.
717# * __args__ is a tuple of all arguments used in subscripting,
718# e.g., Dict[T, int].__args__ == (T, int).
721class _GenericAlias(_BaseGenericAlias, _root=True):
722 def __init__(self, origin, params, *, inst=True, name=None):
723 super().__init__(origin, inst=inst, name=name)
724 if not isinstance(params, tuple):
725 params = (params,)
726 self.__args__ = tuple(... if a is _TypingEllipsis else
727 () if a is _TypingEmpty else
728 a for a in params)
729 self.__parameters__ = _collect_type_vars(params)
730 if not name:
731 self.__module__ = origin.__module__
733 def __eq__(self, other):
734 if not isinstance(other, _GenericAlias):
735 return NotImplemented
736 return (self.__origin__ == other.__origin__
737 and self.__args__ == other.__args__)
739 def __hash__(self):
740 return hash((self.__origin__, self.__args__))
742 @_tp_cache
743 def __getitem__(self, params):
744 if self.__origin__ in (Generic, Protocol):
745 # Can't subscript Generic[...] or Protocol[...].
746 raise TypeError(f"Cannot subscript already-subscripted {self}")
747 if not isinstance(params, tuple):
748 params = (params,)
749 msg = "Parameters to generic types must be types."
750 params = tuple(_type_check(p, msg) for p in params)
751 _check_generic(self, params, len(self.__parameters__))
753 subst = dict(zip(self.__parameters__, params))
754 new_args = []
755 for arg in self.__args__:
756 if isinstance(arg, TypeVar):
757 arg = subst[arg]
758 elif isinstance(arg, (_GenericAlias, GenericAlias)):
759 subparams = arg.__parameters__
760 if subparams:
761 subargs = tuple(subst[x] for x in subparams)
762 arg = arg[subargs]
763 new_args.append(arg)
764 return self.copy_with(tuple(new_args))
766 def copy_with(self, params):
767 return self.__class__(self.__origin__, params, name=self._name, inst=self._inst)
769 def __repr__(self):
770 if self._name:
771 name = 'typing.' + self._name
772 else:
773 name = _type_repr(self.__origin__)
774 args = ", ".join([_type_repr(a) for a in self.__args__])
775 return f'{name}[{args}]'
777 def __reduce__(self):
778 if self._name:
779 origin = globals()[self._name]
780 else:
781 origin = self.__origin__
782 args = tuple(self.__args__)
783 if len(args) == 1 and not isinstance(args[0], tuple):
784 args, = args
785 return operator.getitem, (origin, args)
787 def __mro_entries__(self, bases):
788 if self._name: # generic version of an ABC or built-in class
789 return super().__mro_entries__(bases)
790 if self.__origin__ is Generic:
791 if Protocol in bases:
792 return ()
793 i = bases.index(self)
794 for b in bases[i+1:]:
795 if isinstance(b, _BaseGenericAlias) and b is not self:
796 return ()
797 return (self.__origin__,)
800# _nparams is the number of accepted parameters, e.g. 0 for Hashable,
801# 1 for List and 2 for Dict. It may be -1 if variable number of
802# parameters are accepted (needs custom __getitem__).
804class _SpecialGenericAlias(_BaseGenericAlias, _root=True):
805 def __init__(self, origin, nparams, *, inst=True, name=None):
806 if name is None:
807 name = origin.__name__
808 super().__init__(origin, inst=inst, name=name)
809 self._nparams = nparams
810 if origin.__module__ == 'builtins':
811 self.__doc__ = f'A generic version of {origin.__qualname__}.'
812 else:
813 self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}.'
815 @_tp_cache
816 def __getitem__(self, params):
817 if not isinstance(params, tuple):
818 params = (params,)
819 msg = "Parameters to generic types must be types."
820 params = tuple(_type_check(p, msg) for p in params)
821 _check_generic(self, params, self._nparams)
822 return self.copy_with(params)
824 def copy_with(self, params):
825 return _GenericAlias(self.__origin__, params,
826 name=self._name, inst=self._inst)
828 def __repr__(self):
829 return 'typing.' + self._name
831 def __subclasscheck__(self, cls):
832 if isinstance(cls, _SpecialGenericAlias):
833 return issubclass(cls.__origin__, self.__origin__)
834 if not isinstance(cls, _GenericAlias):
835 return issubclass(cls, self.__origin__)
836 return super().__subclasscheck__(cls)
838 def __reduce__(self):
839 return self._name
842class _CallableGenericAlias(_GenericAlias, _root=True):
843 def __repr__(self):
844 assert self._name == 'Callable'
845 if len(self.__args__) == 2 and self.__args__[0] is Ellipsis:
846 return super().__repr__()
847 return (f'typing.Callable'
848 f'[[{", ".join([_type_repr(a) for a in self.__args__[:-1]])}], '
849 f'{_type_repr(self.__args__[-1])}]')
851 def __reduce__(self):
852 args = self.__args__
853 if not (len(args) == 2 and args[0] is ...):
854 args = list(args[:-1]), args[-1]
855 return operator.getitem, (Callable, args)
858class _CallableType(_SpecialGenericAlias, _root=True):
859 def copy_with(self, params):
860 return _CallableGenericAlias(self.__origin__, params,
861 name=self._name, inst=self._inst)
863 def __getitem__(self, params):
864 if not isinstance(params, tuple) or len(params) != 2:
865 raise TypeError("Callable must be used as "
866 "Callable[[arg, ...], result].")
867 args, result = params
868 # This relaxes what args can be on purpose to allow things like
869 # PEP 612 ParamSpec. Responsibility for whether a user is using
870 # Callable[...] properly is deferred to static type checkers.
871 if isinstance(args, list):
872 params = (tuple(args), result)
873 else:
874 params = (args, result)
875 return self.__getitem_inner__(params)
877 @_tp_cache
878 def __getitem_inner__(self, params):
879 args, result = params
880 msg = "Callable[args, result]: result must be a type."
881 result = _type_check(result, msg)
882 if args is Ellipsis:
883 return self.copy_with((_TypingEllipsis, result))
884 if not isinstance(args, tuple):
885 args = (args,)
886 args = tuple(_type_convert(arg) for arg in args)
887 params = args + (result,)
888 return self.copy_with(params)
891class _TupleType(_SpecialGenericAlias, _root=True):
892 @_tp_cache
893 def __getitem__(self, params):
894 if params == ():
895 return self.copy_with((_TypingEmpty,))
896 if not isinstance(params, tuple):
897 params = (params,)
898 if len(params) == 2 and params[1] is ...:
899 msg = "Tuple[t, ...]: t must be a type."
900 p = _type_check(params[0], msg)
901 return self.copy_with((p, _TypingEllipsis))
902 msg = "Tuple[t0, t1, ...]: each t must be a type."
903 params = tuple(_type_check(p, msg) for p in params)
904 return self.copy_with(params)
907class _UnionGenericAlias(_GenericAlias, _root=True):
908 def copy_with(self, params):
909 return Union[params]
911 def __eq__(self, other):
912 if not isinstance(other, _UnionGenericAlias):
913 return NotImplemented
914 return set(self.__args__) == set(other.__args__)
916 def __hash__(self):
917 return hash(frozenset(self.__args__))
919 def __repr__(self):
920 args = self.__args__
921 if len(args) == 2:
922 if args[0] is type(None):
923 return f'typing.Optional[{_type_repr(args[1])}]'
924 elif args[1] is type(None):
925 return f'typing.Optional[{_type_repr(args[0])}]'
926 return super().__repr__()
929def _value_and_type_iter(parameters):
930 return ((p, type(p)) for p in parameters)
933class _LiteralGenericAlias(_GenericAlias, _root=True):
935 def __eq__(self, other):
936 if not isinstance(other, _LiteralGenericAlias):
937 return NotImplemented
939 return set(_value_and_type_iter(self.__args__)) == set(_value_and_type_iter(other.__args__))
941 def __hash__(self):
942 return hash(frozenset(_value_and_type_iter(self.__args__)))
945class Generic:
946 """Abstract base class for generic types.
948 A generic type is typically declared by inheriting from
949 this class parameterized with one or more type variables.
950 For example, a generic mapping type might be defined as::
952 class Mapping(Generic[KT, VT]):
953 def __getitem__(self, key: KT) -> VT:
954 ...
955 # Etc.
957 This class can then be used as follows::
959 def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
960 try:
961 return mapping[key]
962 except KeyError:
963 return default
964 """
965 __slots__ = ()
966 _is_protocol = False
968 @_tp_cache
969 def __class_getitem__(cls, params):
970 if not isinstance(params, tuple):
971 params = (params,)
972 if not params and cls is not Tuple:
973 raise TypeError(
974 f"Parameter list to {cls.__qualname__}[...] cannot be empty")
975 msg = "Parameters to generic types must be types."
976 params = tuple(_type_check(p, msg) for p in params)
977 if cls in (Generic, Protocol):
978 # Generic and Protocol can only be subscripted with unique type variables.
979 if not all(isinstance(p, TypeVar) for p in params):
980 raise TypeError(
981 f"Parameters to {cls.__name__}[...] must all be type variables")
982 if len(set(params)) != len(params):
983 raise TypeError(
984 f"Parameters to {cls.__name__}[...] must all be unique")
985 else:
986 # Subscripting a regular Generic subclass.
987 _check_generic(cls, params, len(cls.__parameters__))
988 return _GenericAlias(cls, params)
990 def __init_subclass__(cls, *args, **kwargs):
991 super().__init_subclass__(*args, **kwargs)
992 tvars = []
993 if '__orig_bases__' in cls.__dict__:
994 error = Generic in cls.__orig_bases__
995 else:
996 error = Generic in cls.__bases__ and cls.__name__ != 'Protocol'
997 if error:
998 raise TypeError("Cannot inherit from plain Generic")
999 if '__orig_bases__' in cls.__dict__:
1000 tvars = _collect_type_vars(cls.__orig_bases__)
1001 # Look for Generic[T1, ..., Tn].
1002 # If found, tvars must be a subset of it.
1003 # If not found, tvars is it.
1004 # Also check for and reject plain Generic,
1005 # and reject multiple Generic[...].
1006 gvars = None
1007 for base in cls.__orig_bases__:
1008 if (isinstance(base, _GenericAlias) and
1009 base.__origin__ is Generic):
1010 if gvars is not None:
1011 raise TypeError(
1012 "Cannot inherit from Generic[...] multiple types.")
1013 gvars = base.__parameters__
1014 if gvars is not None:
1015 tvarset = set(tvars)
1016 gvarset = set(gvars)
1017 if not tvarset <= gvarset:
1018 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset)
1019 s_args = ', '.join(str(g) for g in gvars)
1020 raise TypeError(f"Some type variables ({s_vars}) are"
1021 f" not listed in Generic[{s_args}]")
1022 tvars = gvars
1023 cls.__parameters__ = tuple(tvars)
1026class _TypingEmpty:
1027 """Internal placeholder for () or []. Used by TupleMeta and CallableMeta
1028 to allow empty list/tuple in specific places, without allowing them
1029 to sneak in where prohibited.
1030 """
1033class _TypingEllipsis:
1034 """Internal placeholder for ... (ellipsis)."""
1037_TYPING_INTERNALS = ['__parameters__', '__orig_bases__', '__orig_class__',
1038 '_is_protocol', '_is_runtime_protocol']
1040_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__',
1041 '__init__', '__module__', '__new__', '__slots__',
1042 '__subclasshook__', '__weakref__', '__class_getitem__']
1044# These special attributes will be not collected as protocol members.
1045EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker']
1048def _get_protocol_attrs(cls):
1049 """Collect protocol members from a protocol class objects.
1051 This includes names actually defined in the class dictionary, as well
1052 as names that appear in annotations. Special names (above) are skipped.
1053 """
1054 attrs = set()
1055 for base in cls.__mro__[:-1]: # without object
1056 if base.__name__ in ('Protocol', 'Generic'):
1057 continue
1058 annotations = getattr(base, '__annotations__', {})
1059 for attr in list(base.__dict__.keys()) + list(annotations.keys()):
1060 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES:
1061 attrs.add(attr)
1062 return attrs
1065def _is_callable_members_only(cls):
1066 # PEP 544 prohibits using issubclass() with protocols that have non-method members.
1067 return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls))
1070def _no_init(self, *args, **kwargs):
1071 if type(self)._is_protocol:
1072 raise TypeError('Protocols cannot be instantiated')
1075def _allow_reckless_class_cheks():
1076 """Allow instance and class checks for special stdlib modules.
1078 The abc and functools modules indiscriminately call isinstance() and
1079 issubclass() on the whole MRO of a user class, which may contain protocols.
1080 """
1081 try:
1082 return sys._getframe(3).f_globals['__name__'] in ['abc', 'functools']
1083 except (AttributeError, ValueError): # For platforms without _getframe().
1084 return True
1087_PROTO_WHITELIST = {
1088 'collections.abc': [
1089 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
1090 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible',
1091 ],
1092 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
1093}
1096class _ProtocolMeta(ABCMeta):
1097 # This metaclass is really unfortunate and exists only because of
1098 # the lack of __instancehook__.
1099 def __instancecheck__(cls, instance):
1100 # We need this method for situations where attributes are
1101 # assigned in __init__.
1102 if ((not getattr(cls, '_is_protocol', False) or
1103 _is_callable_members_only(cls)) and
1104 issubclass(instance.__class__, cls)):
1105 return True
1106 if cls._is_protocol:
1107 if all(hasattr(instance, attr) and
1108 # All *methods* can be blocked by setting them to None.
1109 (not callable(getattr(cls, attr, None)) or
1110 getattr(instance, attr) is not None)
1111 for attr in _get_protocol_attrs(cls)):
1112 return True
1113 return super().__instancecheck__(instance)
1116class Protocol(Generic, metaclass=_ProtocolMeta):
1117 """Base class for protocol classes.
1119 Protocol classes are defined as::
1121 class Proto(Protocol):
1122 def meth(self) -> int:
1123 ...
1125 Such classes are primarily used with static type checkers that recognize
1126 structural subtyping (static duck-typing), for example::
1128 class C:
1129 def meth(self) -> int:
1130 return 0
1132 def func(x: Proto) -> int:
1133 return x.meth()
1135 func(C()) # Passes static type check
1137 See PEP 544 for details. Protocol classes decorated with
1138 @typing.runtime_checkable act as simple-minded runtime protocols that check
1139 only the presence of given attributes, ignoring their type signatures.
1140 Protocol classes can be generic, they are defined as::
1142 class GenProto(Protocol[T]):
1143 def meth(self) -> T:
1144 ...
1145 """
1146 __slots__ = ()
1147 _is_protocol = True
1148 _is_runtime_protocol = False
1150 def __init_subclass__(cls, *args, **kwargs):
1151 super().__init_subclass__(*args, **kwargs)
1153 # Determine if this is a protocol or a concrete subclass.
1154 if not cls.__dict__.get('_is_protocol', False):
1155 cls._is_protocol = any(b is Protocol for b in cls.__bases__)
1157 # Set (or override) the protocol subclass hook.
1158 def _proto_hook(other):
1159 if not cls.__dict__.get('_is_protocol', False):
1160 return NotImplemented
1162 # First, perform various sanity checks.
1163 if not getattr(cls, '_is_runtime_protocol', False):
1164 if _allow_reckless_class_cheks():
1165 return NotImplemented
1166 raise TypeError("Instance and class checks can only be used with"
1167 " @runtime_checkable protocols")
1168 if not _is_callable_members_only(cls):
1169 if _allow_reckless_class_cheks():
1170 return NotImplemented
1171 raise TypeError("Protocols with non-method members"
1172 " don't support issubclass()")
1173 if not isinstance(other, type):
1174 # Same error message as for issubclass(1, int).
1175 raise TypeError('issubclass() arg 1 must be a class')
1177 # Second, perform the actual structural compatibility check.
1178 for attr in _get_protocol_attrs(cls):
1179 for base in other.__mro__:
1180 # Check if the members appears in the class dictionary...
1181 if attr in base.__dict__:
1182 if base.__dict__[attr] is None:
1183 return NotImplemented
1184 break
1186 # ...or in annotations, if it is a sub-protocol.
1187 annotations = getattr(base, '__annotations__', {})
1188 if (isinstance(annotations, collections.abc.Mapping) and
1189 attr in annotations and
1190 issubclass(other, Generic) and other._is_protocol):
1191 break
1192 else:
1193 return NotImplemented
1194 return True
1196 if '__subclasshook__' not in cls.__dict__:
1197 cls.__subclasshook__ = _proto_hook
1199 # We have nothing more to do for non-protocols...
1200 if not cls._is_protocol:
1201 return
1203 # ... otherwise check consistency of bases, and prohibit instantiation.
1204 for base in cls.__bases__:
1205 if not (base in (object, Generic) or
1206 base.__module__ in _PROTO_WHITELIST and
1207 base.__name__ in _PROTO_WHITELIST[base.__module__] or
1208 issubclass(base, Generic) and base._is_protocol):
1209 raise TypeError('Protocols can only inherit from other'
1210 ' protocols, got %r' % base)
1211 cls.__init__ = _no_init
1214class _AnnotatedAlias(_GenericAlias, _root=True):
1215 """Runtime representation of an annotated type.
1217 At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
1218 with extra annotations. The alias behaves like a normal typing alias,
1219 instantiating is the same as instantiating the underlying type, binding
1220 it to types is also the same.
1221 """
1222 def __init__(self, origin, metadata):
1223 if isinstance(origin, _AnnotatedAlias):
1224 metadata = origin.__metadata__ + metadata
1225 origin = origin.__origin__
1226 super().__init__(origin, origin)
1227 self.__metadata__ = metadata
1229 def copy_with(self, params):
1230 assert len(params) == 1
1231 new_type = params[0]
1232 return _AnnotatedAlias(new_type, self.__metadata__)
1234 def __repr__(self):
1235 return "typing.Annotated[{}, {}]".format(
1236 _type_repr(self.__origin__),
1237 ", ".join(repr(a) for a in self.__metadata__)
1238 )
1240 def __reduce__(self):
1241 return operator.getitem, (
1242 Annotated, (self.__origin__,) + self.__metadata__
1243 )
1245 def __eq__(self, other):
1246 if not isinstance(other, _AnnotatedAlias):
1247 return NotImplemented
1248 return (self.__origin__ == other.__origin__
1249 and self.__metadata__ == other.__metadata__)
1251 def __hash__(self):
1252 return hash((self.__origin__, self.__metadata__))
1255class Annotated:
1256 """Add context specific metadata to a type.
1258 Example: Annotated[int, runtime_check.Unsigned] indicates to the
1259 hypothetical runtime_check module that this type is an unsigned int.
1260 Every other consumer of this type can ignore this metadata and treat
1261 this type as int.
1263 The first argument to Annotated must be a valid type.
1265 Details:
1267 - It's an error to call `Annotated` with less than two arguments.
1268 - Nested Annotated are flattened::
1270 Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
1272 - Instantiating an annotated type is equivalent to instantiating the
1273 underlying type::
1275 Annotated[C, Ann1](5) == C(5)
1277 - Annotated can be used as a generic type alias::
1279 Optimized = Annotated[T, runtime.Optimize()]
1280 Optimized[int] == Annotated[int, runtime.Optimize()]
1282 OptimizedList = Annotated[List[T], runtime.Optimize()]
1283 OptimizedList[int] == Annotated[List[int], runtime.Optimize()]
1284 """
1286 __slots__ = ()
1288 def __new__(cls, *args, **kwargs):
1289 raise TypeError("Type Annotated cannot be instantiated.")
1291 @_tp_cache
1292 def __class_getitem__(cls, params):
1293 if not isinstance(params, tuple) or len(params) < 2:
1294 raise TypeError("Annotated[...] should be used "
1295 "with at least two arguments (a type and an "
1296 "annotation).")
1297 msg = "Annotated[t, ...]: t must be a type."
1298 origin = _type_check(params[0], msg)
1299 metadata = tuple(params[1:])
1300 return _AnnotatedAlias(origin, metadata)
1302 def __init_subclass__(cls, *args, **kwargs):
1303 raise TypeError(
1304 "Cannot subclass {}.Annotated".format(cls.__module__)
1305 )
1308def runtime_checkable(cls):
1309 """Mark a protocol class as a runtime protocol.
1311 Such protocol can be used with isinstance() and issubclass().
1312 Raise TypeError if applied to a non-protocol class.
1313 This allows a simple-minded structural check very similar to
1314 one trick ponies in collections.abc such as Iterable.
1315 For example::
1317 @runtime_checkable
1318 class Closable(Protocol):
1319 def close(self): ...
1321 assert isinstance(open('/some/file'), Closable)
1323 Warning: this will check only the presence of the required methods,
1324 not their type signatures!
1325 """
1326 if not issubclass(cls, Generic) or not cls._is_protocol:
1327 raise TypeError('@runtime_checkable can be only applied to protocol classes,'
1328 ' got %r' % cls)
1329 cls._is_runtime_protocol = True
1330 return cls
1333def cast(typ, val):
1334 """Cast a value to a type.
1336 This returns the value unchanged. To the type checker this
1337 signals that the return value has the designated type, but at
1338 runtime we intentionally don't check anything (we want this
1339 to be as fast as possible).
1340 """
1341 return val
1344def _get_defaults(func):
1345 """Internal helper to extract the default arguments, by name."""
1346 try:
1347 code = func.__code__
1348 except AttributeError:
1349 # Some built-in functions don't have __code__, __defaults__, etc.
1350 return {}
1351 pos_count = code.co_argcount
1352 arg_names = code.co_varnames
1353 arg_names = arg_names[:pos_count]
1354 defaults = func.__defaults__ or ()
1355 kwdefaults = func.__kwdefaults__
1356 res = dict(kwdefaults) if kwdefaults else {}
1357 pos_offset = pos_count - len(defaults)
1358 for name, value in zip(arg_names[pos_offset:], defaults):
1359 assert name not in res
1360 res[name] = value
1361 return res
1364_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
1365 types.MethodType, types.ModuleType,
1366 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
1369def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
1370 """Return type hints for an object.
1372 This is often the same as obj.__annotations__, but it handles
1373 forward references encoded as string literals, adds Optional[t] if a
1374 default value equal to None is set and recursively replaces all
1375 'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
1377 The argument may be a module, class, method, or function. The annotations
1378 are returned as a dictionary. For classes, annotations include also
1379 inherited members.
1381 TypeError is raised if the argument is not of a type that can contain
1382 annotations, and an empty dictionary is returned if no annotations are
1383 present.
1385 BEWARE -- the behavior of globalns and localns is counterintuitive
1386 (unless you are familiar with how eval() and exec() work). The
1387 search order is locals first, then globals.
1389 - If no dict arguments are passed, an attempt is made to use the
1390 globals from obj (or the respective module's globals for classes),
1391 and these are also used as the locals. If the object does not appear
1392 to have globals, an empty dictionary is used.
1394 - If one dict argument is passed, it is used for both globals and
1395 locals.
1397 - If two dict arguments are passed, they specify globals and
1398 locals, respectively.
1399 """
1401 if getattr(obj, '__no_type_check__', None):
1402 return {}
1403 # Classes require a special treatment.
1404 if isinstance(obj, type):
1405 hints = {}
1406 for base in reversed(obj.__mro__):
1407 if globalns is None:
1408 base_globals = sys.modules[base.__module__].__dict__
1409 else:
1410 base_globals = globalns
1411 ann = base.__dict__.get('__annotations__', {})
1412 for name, value in ann.items():
1413 if value is None:
1414 value = type(None)
1415 if isinstance(value, str):
1416 value = ForwardRef(value, is_argument=False)
1417 value = _eval_type(value, base_globals, localns)
1418 hints[name] = value
1419 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
1421 if globalns is None:
1422 if isinstance(obj, types.ModuleType):
1423 globalns = obj.__dict__
1424 else:
1425 nsobj = obj
1426 # Find globalns for the unwrapped object.
1427 while hasattr(nsobj, '__wrapped__'):
1428 nsobj = nsobj.__wrapped__
1429 globalns = getattr(nsobj, '__globals__', {})
1430 if localns is None:
1431 localns = globalns
1432 elif localns is None:
1433 localns = globalns
1434 hints = getattr(obj, '__annotations__', None)
1435 if hints is None:
1436 # Return empty annotations for something that _could_ have them.
1437 if isinstance(obj, _allowed_types):
1438 return {}
1439 else:
1440 raise TypeError('{!r} is not a module, class, method, '
1441 'or function.'.format(obj))
1442 defaults = _get_defaults(obj)
1443 hints = dict(hints)
1444 for name, value in hints.items():
1445 if value is None:
1446 value = type(None)
1447 if isinstance(value, str):
1448 value = ForwardRef(value)
1449 value = _eval_type(value, globalns, localns)
1450 if name in defaults and defaults[name] is None:
1451 value = Optional[value]
1452 hints[name] = value
1453 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
1456def _strip_annotations(t):
1457 """Strips the annotations from a given type.
1458 """
1459 if isinstance(t, _AnnotatedAlias):
1460 return _strip_annotations(t.__origin__)
1461 if isinstance(t, _GenericAlias):
1462 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
1463 if stripped_args == t.__args__:
1464 return t
1465 return t.copy_with(stripped_args)
1466 if isinstance(t, GenericAlias):
1467 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
1468 if stripped_args == t.__args__:
1469 return t
1470 return GenericAlias(t.__origin__, stripped_args)
1471 return t
1474def get_origin(tp):
1475 """Get the unsubscripted version of a type.
1477 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar
1478 and Annotated. Return None for unsupported types. Examples::
1480 get_origin(Literal[42]) is Literal
1481 get_origin(int) is None
1482 get_origin(ClassVar[int]) is ClassVar
1483 get_origin(Generic) is Generic
1484 get_origin(Generic[T]) is Generic
1485 get_origin(Union[T, int]) is Union
1486 get_origin(List[Tuple[T, T]][int]) == list
1487 """
1488 if isinstance(tp, _AnnotatedAlias):
1489 return Annotated
1490 if isinstance(tp, (_BaseGenericAlias, GenericAlias)):
1491 return tp.__origin__
1492 if tp is Generic:
1493 return Generic
1494 return None
1497def get_args(tp):
1498 """Get type arguments with all substitutions performed.
1500 For unions, basic simplifications used by Union constructor are performed.
1501 Examples::
1502 get_args(Dict[str, int]) == (str, int)
1503 get_args(int) == ()
1504 get_args(Union[int, Union[T, int], str][int]) == (int, str)
1505 get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
1506 get_args(Callable[[], T][int]) == ([], int)
1507 """
1508 if isinstance(tp, _AnnotatedAlias):
1509 return (tp.__origin__,) + tp.__metadata__
1510 if isinstance(tp, (_GenericAlias, GenericAlias)):
1511 res = tp.__args__
1512 if tp.__origin__ is collections.abc.Callable and res[0] is not Ellipsis:
1513 res = (list(res[:-1]), res[-1])
1514 return res
1515 return ()
1518def no_type_check(arg):
1519 """Decorator to indicate that annotations are not type hints.
1521 The argument must be a class or function; if it is a class, it
1522 applies recursively to all methods and classes defined in that class
1523 (but not to methods defined in its superclasses or subclasses).
1525 This mutates the function(s) or class(es) in place.
1526 """
1527 if isinstance(arg, type):
1528 arg_attrs = arg.__dict__.copy()
1529 for attr, val in arg.__dict__.items():
1530 if val in arg.__bases__ + (arg,):
1531 arg_attrs.pop(attr)
1532 for obj in arg_attrs.values():
1533 if isinstance(obj, types.FunctionType):
1534 obj.__no_type_check__ = True
1535 if isinstance(obj, type):
1536 no_type_check(obj)
1537 try:
1538 arg.__no_type_check__ = True
1539 except TypeError: # built-in classes
1540 pass
1541 return arg
1544def no_type_check_decorator(decorator):
1545 """Decorator to give another decorator the @no_type_check effect.
1547 This wraps the decorator with something that wraps the decorated
1548 function in @no_type_check.
1549 """
1551 @functools.wraps(decorator)
1552 def wrapped_decorator(*args, **kwds):
1553 func = decorator(*args, **kwds)
1554 func = no_type_check(func)
1555 return func
1557 return wrapped_decorator
1560def _overload_dummy(*args, **kwds):
1561 """Helper for @overload to raise when called."""
1562 raise NotImplementedError(
1563 "You should not call an overloaded function. "
1564 "A series of @overload-decorated functions "
1565 "outside a stub module should always be followed "
1566 "by an implementation that is not @overload-ed.")
1569def overload(func):
1570 """Decorator for overloaded functions/methods.
1572 In a stub file, place two or more stub definitions for the same
1573 function in a row, each decorated with @overload. For example:
1575 @overload
1576 def utf8(value: None) -> None: ...
1577 @overload
1578 def utf8(value: bytes) -> bytes: ...
1579 @overload
1580 def utf8(value: str) -> bytes: ...
1582 In a non-stub file (i.e. a regular .py file), do the same but
1583 follow it with an implementation. The implementation should *not*
1584 be decorated with @overload. For example:
1586 @overload
1587 def utf8(value: None) -> None: ...
1588 @overload
1589 def utf8(value: bytes) -> bytes: ...
1590 @overload
1591 def utf8(value: str) -> bytes: ...
1592 def utf8(value):
1593 # implementation goes here
1594 """
1595 return _overload_dummy
1598def final(f):
1599 """A decorator to indicate final methods and final classes.
1601 Use this decorator to indicate to type checkers that the decorated
1602 method cannot be overridden, and decorated class cannot be subclassed.
1603 For example:
1605 class Base:
1606 @final
1607 def done(self) -> None:
1608 ...
1609 class Sub(Base):
1610 def done(self) -> None: # Error reported by type checker
1611 ...
1613 @final
1614 class Leaf:
1615 ...
1616 class Other(Leaf): # Error reported by type checker
1617 ...
1619 There is no runtime checking of these properties.
1620 """
1621 return f
1624# Some unconstrained type variables. These are used by the container types.
1625# (These are not for export.)
1626T = TypeVar('T') # Any type.
1627KT = TypeVar('KT') # Key type.
1628VT = TypeVar('VT') # Value type.
1629T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
1630V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
1631VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
1632T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant.
1633# Internal type variable used for Type[].
1634CT_co = TypeVar('CT_co', covariant=True, bound=type)
1636# A useful type variable with constraints. This represents string types.
1637# (This one *is* for export!)
1638AnyStr = TypeVar('AnyStr', bytes, str)
1641# Various ABCs mimicking those in collections.abc.
1642_alias = _SpecialGenericAlias
1644Hashable = _alias(collections.abc.Hashable, 0) # Not generic.
1645Awaitable = _alias(collections.abc.Awaitable, 1)
1646Coroutine = _alias(collections.abc.Coroutine, 3)
1647AsyncIterable = _alias(collections.abc.AsyncIterable, 1)
1648AsyncIterator = _alias(collections.abc.AsyncIterator, 1)
1649Iterable = _alias(collections.abc.Iterable, 1)
1650Iterator = _alias(collections.abc.Iterator, 1)
1651Reversible = _alias(collections.abc.Reversible, 1)
1652Sized = _alias(collections.abc.Sized, 0) # Not generic.
1653Container = _alias(collections.abc.Container, 1)
1654Collection = _alias(collections.abc.Collection, 1)
1655Callable = _CallableType(collections.abc.Callable, 2)
1656Callable.__doc__ = \
1657 """Callable type; Callable[[int], str] is a function of (int) -> str.
1659 The subscription syntax must always be used with exactly two
1660 values: the argument list and the return type. The argument list
1661 must be a list of types or ellipsis; the return type must be a single type.
1663 There is no syntax to indicate optional or keyword arguments,
1664 such function types are rarely used as callback types.
1665 """
1666AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet')
1667MutableSet = _alias(collections.abc.MutableSet, 1)
1668# NOTE: Mapping is only covariant in the value type.
1669Mapping = _alias(collections.abc.Mapping, 2)
1670MutableMapping = _alias(collections.abc.MutableMapping, 2)
1671Sequence = _alias(collections.abc.Sequence, 1)
1672MutableSequence = _alias(collections.abc.MutableSequence, 1)
1673ByteString = _alias(collections.abc.ByteString, 0) # Not generic
1674# Tuple accepts variable number of parameters.
1675Tuple = _TupleType(tuple, -1, inst=False, name='Tuple')
1676Tuple.__doc__ = \
1677 """Tuple type; Tuple[X, Y] is the cross-product type of X and Y.
1679 Example: Tuple[T1, T2] is a tuple of two elements corresponding
1680 to type variables T1 and T2. Tuple[int, float, str] is a tuple
1681 of an int, a float and a string.
1683 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
1684 """
1685List = _alias(list, 1, inst=False, name='List')
1686Deque = _alias(collections.deque, 1, name='Deque')
1687Set = _alias(set, 1, inst=False, name='Set')
1688FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet')
1689MappingView = _alias(collections.abc.MappingView, 1)
1690KeysView = _alias(collections.abc.KeysView, 1)
1691ItemsView = _alias(collections.abc.ItemsView, 2)
1692ValuesView = _alias(collections.abc.ValuesView, 1)
1693ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager')
1694AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager')
1695Dict = _alias(dict, 2, inst=False, name='Dict')
1696DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict')
1697OrderedDict = _alias(collections.OrderedDict, 2)
1698Counter = _alias(collections.Counter, 1)
1699ChainMap = _alias(collections.ChainMap, 2)
1700Generator = _alias(collections.abc.Generator, 3)
1701AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2)
1702Type = _alias(type, 1, inst=False, name='Type')
1703Type.__doc__ = \
1704 """A special construct usable to annotate class objects.
1706 For example, suppose we have the following classes::
1708 class User: ... # Abstract base for User classes
1709 class BasicUser(User): ...
1710 class ProUser(User): ...
1711 class TeamUser(User): ...
1713 And a function that takes a class argument that's a subclass of
1714 User and returns an instance of the corresponding class::
1716 U = TypeVar('U', bound=User)
1717 def new_user(user_class: Type[U]) -> U:
1718 user = user_class()
1719 # (Here we could write the user object to a database)
1720 return user
1722 joe = new_user(BasicUser)
1724 At this point the type checker knows that joe has type BasicUser.
1725 """
1728@runtime_checkable
1729class SupportsInt(Protocol):
1730 """An ABC with one abstract method __int__."""
1731 __slots__ = ()
1733 @abstractmethod
1734 def __int__(self) -> int:
1735 pass
1738@runtime_checkable
1739class SupportsFloat(Protocol):
1740 """An ABC with one abstract method __float__."""
1741 __slots__ = ()
1743 @abstractmethod
1744 def __float__(self) -> float:
1745 pass
1748@runtime_checkable
1749class SupportsComplex(Protocol):
1750 """An ABC with one abstract method __complex__."""
1751 __slots__ = ()
1753 @abstractmethod
1754 def __complex__(self) -> complex:
1755 pass
1758@runtime_checkable
1759class SupportsBytes(Protocol):
1760 """An ABC with one abstract method __bytes__."""
1761 __slots__ = ()
1763 @abstractmethod
1764 def __bytes__(self) -> bytes:
1765 pass
1768@runtime_checkable
1769class SupportsIndex(Protocol):
1770 """An ABC with one abstract method __index__."""
1771 __slots__ = ()
1773 @abstractmethod
1774 def __index__(self) -> int:
1775 pass
1778@runtime_checkable
1779class SupportsAbs(Protocol[T_co]):
1780 """An ABC with one abstract method __abs__ that is covariant in its return type."""
1781 __slots__ = ()
1783 @abstractmethod
1784 def __abs__(self) -> T_co:
1785 pass
1788@runtime_checkable
1789class SupportsRound(Protocol[T_co]):
1790 """An ABC with one abstract method __round__ that is covariant in its return type."""
1791 __slots__ = ()
1793 @abstractmethod
1794 def __round__(self, ndigits: int = 0) -> T_co:
1795 pass
1798def _make_nmtuple(name, types, module, defaults = ()):
1799 fields = [n for n, t in types]
1800 types = {n: _type_check(t, f"field {n} annotation must be a type")
1801 for n, t in types}
1802 nm_tpl = collections.namedtuple(name, fields,
1803 defaults=defaults, module=module)
1804 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types
1805 return nm_tpl
1808# attributes prohibited to set in NamedTuple class syntax
1809_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__',
1810 '_fields', '_field_defaults',
1811 '_make', '_replace', '_asdict', '_source'})
1813_special = frozenset({'__module__', '__name__', '__annotations__'})
1816class NamedTupleMeta(type):
1818 def __new__(cls, typename, bases, ns):
1819 assert bases[0] is _NamedTuple
1820 types = ns.get('__annotations__', {})
1821 default_names = []
1822 for field_name in types:
1823 if field_name in ns:
1824 default_names.append(field_name)
1825 elif default_names:
1826 raise TypeError(f"Non-default namedtuple field {field_name} "
1827 f"cannot follow default field"
1828 f"{'s' if len(default_names) > 1 else ''} "
1829 f"{', '.join(default_names)}")
1830 nm_tpl = _make_nmtuple(typename, types.items(),
1831 defaults=[ns[n] for n in default_names],
1832 module=ns['__module__'])
1833 # update from user namespace without overriding special namedtuple attributes
1834 for key in ns:
1835 if key in _prohibited:
1836 raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
1837 elif key not in _special and key not in nm_tpl._fields:
1838 setattr(nm_tpl, key, ns[key])
1839 return nm_tpl
1842def NamedTuple(typename, fields=None, /, **kwargs):
1843 """Typed version of namedtuple.
1845 Usage in Python versions >= 3.6::
1847 class Employee(NamedTuple):
1848 name: str
1849 id: int
1851 This is equivalent to::
1853 Employee = collections.namedtuple('Employee', ['name', 'id'])
1855 The resulting class has an extra __annotations__ attribute, giving a
1856 dict that maps field names to types. (The field names are also in
1857 the _fields attribute, which is part of the namedtuple API.)
1858 Alternative equivalent keyword syntax is also accepted::
1860 Employee = NamedTuple('Employee', name=str, id=int)
1862 In Python versions <= 3.5 use::
1864 Employee = NamedTuple('Employee', [('name', str), ('id', int)])
1865 """
1866 if fields is None:
1867 fields = kwargs.items()
1868 elif kwargs:
1869 raise TypeError("Either list of fields or keywords"
1870 " can be provided to NamedTuple, not both")
1871 try:
1872 module = sys._getframe(1).f_globals.get('__name__', '__main__')
1873 except (AttributeError, ValueError):
1874 module = None
1875 return _make_nmtuple(typename, fields, module=module)
1877_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {})
1879def _namedtuple_mro_entries(bases):
1880 if len(bases) > 1:
1881 raise TypeError("Multiple inheritance with NamedTuple is not supported")
1882 assert bases[0] is NamedTuple
1883 return (_NamedTuple,)
1885NamedTuple.__mro_entries__ = _namedtuple_mro_entries
1888class _TypedDictMeta(type):
1889 def __new__(cls, name, bases, ns, total=True):
1890 """Create new typed dict class object.
1892 This method is called when TypedDict is subclassed,
1893 or when TypedDict is instantiated. This way
1894 TypedDict supports all three syntax forms described in its docstring.
1895 Subclasses and instances of TypedDict return actual dictionaries.
1896 """
1897 for base in bases:
1898 if type(base) is not _TypedDictMeta:
1899 raise TypeError('cannot inherit from both a TypedDict type '
1900 'and a non-TypedDict base class')
1901 tp_dict = type.__new__(_TypedDictMeta, name, (dict,), ns)
1903 annotations = {}
1904 own_annotations = ns.get('__annotations__', {})
1905 own_annotation_keys = set(own_annotations.keys())
1906 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
1907 own_annotations = {
1908 n: _type_check(tp, msg) for n, tp in own_annotations.items()
1909 }
1910 required_keys = set()
1911 optional_keys = set()
1913 for base in bases:
1914 annotations.update(base.__dict__.get('__annotations__', {}))
1915 required_keys.update(base.__dict__.get('__required_keys__', ()))
1916 optional_keys.update(base.__dict__.get('__optional_keys__', ()))
1918 annotations.update(own_annotations)
1919 if total:
1920 required_keys.update(own_annotation_keys)
1921 else:
1922 optional_keys.update(own_annotation_keys)
1924 tp_dict.__annotations__ = annotations
1925 tp_dict.__required_keys__ = frozenset(required_keys)
1926 tp_dict.__optional_keys__ = frozenset(optional_keys)
1927 if not hasattr(tp_dict, '__total__'):
1928 tp_dict.__total__ = total
1929 return tp_dict
1931 __call__ = dict # static method
1933 def __subclasscheck__(cls, other):
1934 # Typed dicts are only for static structural subtyping.
1935 raise TypeError('TypedDict does not support instance and class checks')
1937 __instancecheck__ = __subclasscheck__
1940def TypedDict(typename, fields=None, /, *, total=True, **kwargs):
1941 """A simple typed namespace. At runtime it is equivalent to a plain dict.
1943 TypedDict creates a dictionary type that expects all of its
1944 instances to have a certain set of keys, where each key is
1945 associated with a value of a consistent type. This expectation
1946 is not checked at runtime but is only enforced by type checkers.
1947 Usage::
1949 class Point2D(TypedDict):
1950 x: int
1951 y: int
1952 label: str
1954 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
1955 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
1957 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
1959 The type info can be accessed via the Point2D.__annotations__ dict, and
1960 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
1961 TypedDict supports two additional equivalent forms::
1963 Point2D = TypedDict('Point2D', x=int, y=int, label=str)
1964 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
1966 By default, all keys must be present in a TypedDict. It is possible
1967 to override this by specifying totality.
1968 Usage::
1970 class point2D(TypedDict, total=False):
1971 x: int
1972 y: int
1974 This means that a point2D TypedDict can have any of the keys omitted.A type
1975 checker is only expected to support a literal False or True as the value of
1976 the total argument. True is the default, and makes all items defined in the
1977 class body be required.
1979 The class syntax is only supported in Python 3.6+, while two other
1980 syntax forms work for Python 2.7 and 3.2+
1981 """
1982 if fields is None:
1983 fields = kwargs
1984 elif kwargs:
1985 raise TypeError("TypedDict takes either a dict or keyword arguments,"
1986 " but not both")
1988 ns = {'__annotations__': dict(fields)}
1989 try:
1990 # Setting correct module is necessary to make typed dict classes pickleable.
1991 ns['__module__'] = sys._getframe(1).f_globals.get('__name__', '__main__')
1992 except (AttributeError, ValueError):
1993 pass
1995 return _TypedDictMeta(typename, (), ns, total=total)
1997_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
1998TypedDict.__mro_entries__ = lambda bases: (_TypedDict,)
2001def NewType(name, tp):
2002 """NewType creates simple unique types with almost zero
2003 runtime overhead. NewType(name, tp) is considered a subtype of tp
2004 by static type checkers. At runtime, NewType(name, tp) returns
2005 a dummy function that simply returns its argument. Usage::
2007 UserId = NewType('UserId', int)
2009 def name_by_id(user_id: UserId) -> str:
2010 ...
2012 UserId('user') # Fails type check
2014 name_by_id(42) # Fails type check
2015 name_by_id(UserId(42)) # OK
2017 num = UserId(5) + 1 # type: int
2018 """
2020 def new_type(x):
2021 return x
2023 new_type.__name__ = name
2024 new_type.__supertype__ = tp
2025 return new_type
2028# Python-version-specific alias (Python 2: unicode; Python 3: str)
2029Text = str
2032# Constant that's True when type checking, but False here.
2033TYPE_CHECKING = False
2036class IO(Generic[AnyStr]):
2037 """Generic base class for TextIO and BinaryIO.
2039 This is an abstract, generic version of the return of open().
2041 NOTE: This does not distinguish between the different possible
2042 classes (text vs. binary, read vs. write vs. read/write,
2043 append-only, unbuffered). The TextIO and BinaryIO subclasses
2044 below capture the distinctions between text vs. binary, which is
2045 pervasive in the interface; however we currently do not offer a
2046 way to track the other distinctions in the type system.
2047 """
2049 __slots__ = ()
2051 @property
2052 @abstractmethod
2053 def mode(self) -> str:
2054 pass
2056 @property
2057 @abstractmethod
2058 def name(self) -> str:
2059 pass
2061 @abstractmethod
2062 def close(self) -> None:
2063 pass
2065 @property
2066 @abstractmethod
2067 def closed(self) -> bool:
2068 pass
2070 @abstractmethod
2071 def fileno(self) -> int:
2072 pass
2074 @abstractmethod
2075 def flush(self) -> None:
2076 pass
2078 @abstractmethod
2079 def isatty(self) -> bool:
2080 pass
2082 @abstractmethod
2083 def read(self, n: int = -1) -> AnyStr:
2084 pass
2086 @abstractmethod
2087 def readable(self) -> bool:
2088 pass
2090 @abstractmethod
2091 def readline(self, limit: int = -1) -> AnyStr:
2092 pass
2094 @abstractmethod
2095 def readlines(self, hint: int = -1) -> List[AnyStr]:
2096 pass
2098 @abstractmethod
2099 def seek(self, offset: int, whence: int = 0) -> int:
2100 pass
2102 @abstractmethod
2103 def seekable(self) -> bool:
2104 pass
2106 @abstractmethod
2107 def tell(self) -> int:
2108 pass
2110 @abstractmethod
2111 def truncate(self, size: int = None) -> int:
2112 pass
2114 @abstractmethod
2115 def writable(self) -> bool:
2116 pass
2118 @abstractmethod
2119 def write(self, s: AnyStr) -> int:
2120 pass
2122 @abstractmethod
2123 def writelines(self, lines: List[AnyStr]) -> None:
2124 pass
2126 @abstractmethod
2127 def __enter__(self) -> 'IO[AnyStr]':
2128 pass
2130 @abstractmethod
2131 def __exit__(self, type, value, traceback) -> None:
2132 pass
2135class BinaryIO(IO[bytes]):
2136 """Typed version of the return of open() in binary mode."""
2138 __slots__ = ()
2140 @abstractmethod
2141 def write(self, s: Union[bytes, bytearray]) -> int:
2142 pass
2144 @abstractmethod
2145 def __enter__(self) -> 'BinaryIO':
2146 pass
2149class TextIO(IO[str]):
2150 """Typed version of the return of open() in text mode."""
2152 __slots__ = ()
2154 @property
2155 @abstractmethod
2156 def buffer(self) -> BinaryIO:
2157 pass
2159 @property
2160 @abstractmethod
2161 def encoding(self) -> str:
2162 pass
2164 @property
2165 @abstractmethod
2166 def errors(self) -> Optional[str]:
2167 pass
2169 @property
2170 @abstractmethod
2171 def line_buffering(self) -> bool:
2172 pass
2174 @property
2175 @abstractmethod
2176 def newlines(self) -> Any:
2177 pass
2179 @abstractmethod
2180 def __enter__(self) -> 'TextIO':
2181 pass
2184class io:
2185 """Wrapper namespace for IO generic classes."""
2187 __all__ = ['IO', 'TextIO', 'BinaryIO']
2188 IO = IO
2189 TextIO = TextIO
2190 BinaryIO = BinaryIO
2193io.__name__ = __name__ + '.io'
2194sys.modules[io.__name__] = io
2196Pattern = _alias(stdlib_re.Pattern, 1)
2197Match = _alias(stdlib_re.Match, 1)
2199class re:
2200 """Wrapper namespace for re type aliases."""
2202 __all__ = ['Pattern', 'Match']
2203 Pattern = Pattern
2204 Match = Match
2207re.__name__ = __name__ + '.re'
2208sys.modules[re.__name__] = re