python (3.12.0)
1 """
2 The typing module: Support for gradual typing as defined by PEP 484 and subsequent PEPs.
3
4 Among other things, the module includes the following:
5 * Generic, Protocol, and internal machinery to support generic aliases.
6 All subscripted types like X[int], Union[int, str] are generic aliases.
7 * Various "special forms" that have unique meanings in type annotations:
8 NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others.
9 * Classes whose instances can be type arguments to generic classes and functions:
10 TypeVar, ParamSpec, TypeVarTuple.
11 * Public helper functions: get_type_hints, overload, cast, final, and others.
12 * Several protocols to support duck-typing:
13 SupportsFloat, SupportsIndex, SupportsAbs, and others.
14 * Special types: NewType, NamedTuple, TypedDict.
15 * Deprecated wrapper submodules for re and io related types.
16 * Deprecated aliases for builtin types and collections.abc ABCs.
17
18 Any name not present in __all__ is an implementation detail
19 that may be changed without notice. Use at your own risk!
20 """
21
22 from abc import abstractmethod, ABCMeta
23 import collections
24 from collections import defaultdict
25 import collections.abc
26 import copyreg
27 import contextlib
28 import functools
29 import operator
30 import re as stdlib_re # Avoid confusion with the re we export.
31 import sys
32 import types
33 import warnings
34 from types import WrapperDescriptorType, MethodWrapperType, MethodDescriptorType, GenericAlias
35
36 from _typing import (
37 _idfunc,
38 TypeVar,
39 ParamSpec,
40 TypeVarTuple,
41 ParamSpecArgs,
42 ParamSpecKwargs,
43 TypeAliasType,
44 Generic,
45 )
46
47 # Please keep __all__ alphabetized within each category.
48 __all__ = [
49 # Super-special typing primitives.
50 'Annotated',
51 'Any',
52 'Callable',
53 'ClassVar',
54 'Concatenate',
55 'Final',
56 'ForwardRef',
57 'Generic',
58 'Literal',
59 'Optional',
60 'ParamSpec',
61 'Protocol',
62 'Tuple',
63 'Type',
64 'TypeVar',
65 'TypeVarTuple',
66 'Union',
67
68 # ABCs (from collections.abc).
69 'AbstractSet', # collections.abc.Set.
70 'ByteString',
71 'Container',
72 'ContextManager',
73 'Hashable',
74 'ItemsView',
75 'Iterable',
76 'Iterator',
77 'KeysView',
78 'Mapping',
79 'MappingView',
80 'MutableMapping',
81 'MutableSequence',
82 'MutableSet',
83 'Sequence',
84 'Sized',
85 'ValuesView',
86 'Awaitable',
87 'AsyncIterator',
88 'AsyncIterable',
89 'Coroutine',
90 'Collection',
91 'AsyncGenerator',
92 'AsyncContextManager',
93
94 # Structural checks, a.k.a. protocols.
95 'Reversible',
96 'SupportsAbs',
97 'SupportsBytes',
98 'SupportsComplex',
99 'SupportsFloat',
100 'SupportsIndex',
101 'SupportsInt',
102 'SupportsRound',
103
104 # Concrete collection types.
105 'ChainMap',
106 'Counter',
107 'Deque',
108 'Dict',
109 'DefaultDict',
110 'List',
111 'OrderedDict',
112 'Set',
113 'FrozenSet',
114 'NamedTuple', # Not really a type.
115 'TypedDict', # Not really a type.
116 'Generator',
117
118 # Other concrete types.
119 'BinaryIO',
120 'IO',
121 'Match',
122 'Pattern',
123 'TextIO',
124
125 # One-off things.
126 'AnyStr',
127 'assert_type',
128 'assert_never',
129 'cast',
130 'clear_overloads',
131 'dataclass_transform',
132 'final',
133 'get_args',
134 'get_origin',
135 'get_overloads',
136 'get_type_hints',
137 'is_typeddict',
138 'LiteralString',
139 'Never',
140 'NewType',
141 'no_type_check',
142 'no_type_check_decorator',
143 'NoReturn',
144 'NotRequired',
145 'overload',
146 'override',
147 'ParamSpecArgs',
148 'ParamSpecKwargs',
149 'Required',
150 'reveal_type',
151 'runtime_checkable',
152 'Self',
153 'Text',
154 'TYPE_CHECKING',
155 'TypeAlias',
156 'TypeGuard',
157 'TypeAliasType',
158 'Unpack',
159 ]
160
161 # The pseudo-submodules 're' and 'io' are part of the public
162 # namespace, but excluded from __all__ because they might stomp on
163 # legitimate imports of those modules.
164
165
166 def _type_convert(arg, module=None, *, allow_special_forms=False):
167 """For converting None to type(None), and strings to ForwardRef."""
168 if arg is None:
169 return type(None)
170 if isinstance(arg, str):
171 return ForwardRef(arg, module=module, is_class=allow_special_forms)
172 return arg
173
174
175 def _type_check(arg, msg, is_argument=True, module=None, *, allow_special_forms=False):
176 """Check that the argument is a type, and return it (internal helper).
177
178 As a special case, accept None and return type(None) instead. Also wrap strings
179 into ForwardRef instances. Consider several corner cases, for example plain
180 special forms like Union are not valid, while Union[int, str] is OK, etc.
181 The msg argument is a human-readable error message, e.g.::
182
183 "Union[arg, ...]: arg should be a type."
184
185 We append the repr() of the actual value (truncated to 100 chars).
186 """
187 invalid_generic_forms = (Generic, Protocol)
188 if not allow_special_forms:
189 invalid_generic_forms += (ClassVar,)
190 if is_argument:
191 invalid_generic_forms += (Final,)
192
193 arg = _type_convert(arg, module=module, allow_special_forms=allow_special_forms)
194 if (isinstance(arg, _GenericAlias) and
195 arg.__origin__ in invalid_generic_forms):
196 raise TypeError(f"{arg} is not valid as type argument")
197 if arg in (Any, LiteralString, NoReturn, Never, Self, TypeAlias):
198 return arg
199 if allow_special_forms and arg in (ClassVar, Final):
200 return arg
201 if isinstance(arg, _SpecialForm) or arg in (Generic, Protocol):
202 raise TypeError(f"Plain {arg} is not valid as type argument")
203 if type(arg) is tuple:
204 raise TypeError(f"{msg} Got {arg!r:.100}.")
205 return arg
206
207
208 def _is_param_expr(arg):
209 return arg is ... or isinstance(arg,
210 (tuple, list, ParamSpec, _ConcatenateGenericAlias))
211
212
213 def _should_unflatten_callable_args(typ, args):
214 """Internal helper for munging collections.abc.Callable's __args__.
215
216 The canonical representation for a Callable's __args__ flattens the
217 argument types, see https://github.com/python/cpython/issues/86361.
218
219 For example::
220
221 assert collections.abc.Callable[[int, int], str].__args__ == (int, int, str)
222 assert collections.abc.Callable[ParamSpec, str].__args__ == (ParamSpec, str)
223
224 As a result, if we need to reconstruct the Callable from its __args__,
225 we need to unflatten it.
226 """
227 return (
228 typ.__origin__ is collections.abc.Callable
229 and not (len(args) == 2 and _is_param_expr(args[0]))
230 )
231
232
233 def _type_repr(obj):
234 """Return the repr() of an object, special-casing types (internal helper).
235
236 If obj is a type, we return a shorter version than the default
237 type.__repr__, based on the module and qualified name, which is
238 typically enough to uniquely identify a type. For everything
239 else, we fall back on repr(obj).
240 """
241 # When changing this function, don't forget about
242 # `_collections_abc._type_repr`, which does the same thing
243 # and must be consistent with this one.
244 if isinstance(obj, type):
245 if obj.__module__ == 'builtins':
246 return obj.__qualname__
247 return f'{obj.__module__}.{obj.__qualname__}'
248 if obj is ...:
249 return '...'
250 if isinstance(obj, types.FunctionType):
251 return obj.__name__
252 if isinstance(obj, tuple):
253 # Special case for `repr` of types with `ParamSpec`:
254 return '[' + ', '.join(_type_repr(t) for t in obj) + ']'
255 return repr(obj)
256
257
258 def _collect_parameters(args):
259 """Collect all type variables and parameter specifications in args
260 in order of first appearance (lexicographic order).
261
262 For example::
263
264 assert _collect_parameters((T, Callable[P, T])) == (T, P)
265 """
266 parameters = []
267 for t in args:
268 if isinstance(t, type):
269 # We don't want __parameters__ descriptor of a bare Python class.
270 pass
271 elif isinstance(t, tuple):
272 # `t` might be a tuple, when `ParamSpec` is substituted with
273 # `[T, int]`, or `[int, *Ts]`, etc.
274 for x in t:
275 for collected in _collect_parameters([x]):
276 if collected not in parameters:
277 parameters.append(collected)
278 elif hasattr(t, '__typing_subst__'):
279 if t not in parameters:
280 parameters.append(t)
281 else:
282 for x in getattr(t, '__parameters__', ()):
283 if x not in parameters:
284 parameters.append(x)
285 return tuple(parameters)
286
287
288 def _check_generic(cls, parameters, elen):
289 """Check correct count for parameters of a generic cls (internal helper).
290
291 This gives a nice error message in case of count mismatch.
292 """
293 if not elen:
294 raise TypeError(f"{cls} is not a generic class")
295 alen = len(parameters)
296 if alen != elen:
297 raise TypeError(f"Too {'many' if alen > elen else 'few'} arguments for {cls};"
298 f" actual {alen}, expected {elen}")
299
300 def _unpack_args(args):
301 newargs = []
302 for arg in args:
303 subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
304 if subargs is not None and not (subargs and subargs[-1] is ...):
305 newargs.extend(subargs)
306 else:
307 newargs.append(arg)
308 return newargs
309
310 def _deduplicate(params):
311 # Weed out strict duplicates, preserving the first of each occurrence.
312 all_params = set(params)
313 if len(all_params) < len(params):
314 new_params = []
315 for t in params:
316 if t in all_params:
317 new_params.append(t)
318 all_params.remove(t)
319 params = new_params
320 assert not all_params, all_params
321 return params
322
323
324 def _remove_dups_flatten(parameters):
325 """Internal helper for Union creation and substitution.
326
327 Flatten Unions among parameters, then remove duplicates.
328 """
329 # Flatten out Union[Union[...], ...].
330 params = []
331 for p in parameters:
332 if isinstance(p, (_UnionGenericAlias, types.UnionType)):
333 params.extend(p.__args__)
334 else:
335 params.append(p)
336
337 return tuple(_deduplicate(params))
338
339
340 def _flatten_literal_params(parameters):
341 """Internal helper for Literal creation: flatten Literals among parameters."""
342 params = []
343 for p in parameters:
344 if isinstance(p, _LiteralGenericAlias):
345 params.extend(p.__args__)
346 else:
347 params.append(p)
348 return tuple(params)
349
350
351 _cleanups = []
352 _caches = {}
353
354
355 def _tp_cache(func=None, /, *, typed=False):
356 """Internal wrapper caching __getitem__ of generic types.
357
358 For non-hashable arguments, the original function is used as a fallback.
359 """
360 def decorator(func):
361 # The callback 'inner' references the newly created lru_cache
362 # indirectly by performing a lookup in the global '_caches' dictionary.
363 # This breaks a reference that can be problematic when combined with
364 # C API extensions that leak references to types. See GH-98253.
365
366 cache = functools.lru_cache(typed=typed)(func)
367 _caches[func] = cache
368 _cleanups.append(cache.cache_clear)
369 del cache
370
371 @functools.wraps(func)
372 def inner(*args, **kwds):
373 try:
374 return _caches[func](*args, **kwds)
375 except TypeError:
376 pass # All real errors (not unhashable args) are raised below.
377 return func(*args, **kwds)
378 return inner
379
380 if func is not None:
381 return decorator(func)
382
383 return decorator
384
385 def _eval_type(t, globalns, localns, recursive_guard=frozenset()):
386 """Evaluate all forward references in the given type t.
387
388 For use of globalns and localns see the docstring for get_type_hints().
389 recursive_guard is used to prevent infinite recursion with a recursive
390 ForwardRef.
391 """
392 if isinstance(t, ForwardRef):
393 return t._evaluate(globalns, localns, recursive_guard)
394 if isinstance(t, (_GenericAlias, GenericAlias, types.UnionType)):
395 if isinstance(t, GenericAlias):
396 args = tuple(
397 ForwardRef(arg) if isinstance(arg, str) else arg
398 for arg in t.__args__
399 )
400 is_unpacked = t.__unpacked__
401 if _should_unflatten_callable_args(t, args):
402 t = t.__origin__[(args[:-1], args[-1])]
403 else:
404 t = t.__origin__[args]
405 if is_unpacked:
406 t = Unpack[t]
407 ev_args = tuple(_eval_type(a, globalns, localns, recursive_guard) for a in t.__args__)
408 if ev_args == t.__args__:
409 return t
410 if isinstance(t, GenericAlias):
411 return GenericAlias(t.__origin__, ev_args)
412 if isinstance(t, types.UnionType):
413 return functools.reduce(operator.or_, ev_args)
414 else:
415 return t.copy_with(ev_args)
416 return t
417
418
419 class ESC[4;38;5;81m_Final:
420 """Mixin to prohibit subclassing."""
421
422 __slots__ = ('__weakref__',)
423
424 def __init_subclass__(cls, /, *args, **kwds):
425 if '_root' not in kwds:
426 raise TypeError("Cannot subclass special typing classes")
427
428
429 class ESC[4;38;5;81m_NotIterable:
430 """Mixin to prevent iteration, without being compatible with Iterable.
431
432 That is, we could do::
433
434 def __iter__(self): raise TypeError()
435
436 But this would make users of this mixin duck type-compatible with
437 collections.abc.Iterable - isinstance(foo, Iterable) would be True.
438
439 Luckily, we can instead prevent iteration by setting __iter__ to None, which
440 is treated specially.
441 """
442
443 __slots__ = ()
444 __iter__ = None
445
446
447 # Internal indicator of special typing constructs.
448 # See __doc__ instance attribute for specific docs.
449 class ESC[4;38;5;81m_SpecialForm(ESC[4;38;5;149m_Final, ESC[4;38;5;149m_NotIterable, _root=ESC[4;38;5;149mTrue):
450 __slots__ = ('_name', '__doc__', '_getitem')
451
452 def __init__(self, getitem):
453 self._getitem = getitem
454 self._name = getitem.__name__
455 self.__doc__ = getitem.__doc__
456
457 def __getattr__(self, item):
458 if item in {'__name__', '__qualname__'}:
459 return self._name
460
461 raise AttributeError(item)
462
463 def __mro_entries__(self, bases):
464 raise TypeError(f"Cannot subclass {self!r}")
465
466 def __repr__(self):
467 return 'typing.' + self._name
468
469 def __reduce__(self):
470 return self._name
471
472 def __call__(self, *args, **kwds):
473 raise TypeError(f"Cannot instantiate {self!r}")
474
475 def __or__(self, other):
476 return Union[self, other]
477
478 def __ror__(self, other):
479 return Union[other, self]
480
481 def __instancecheck__(self, obj):
482 raise TypeError(f"{self} cannot be used with isinstance()")
483
484 def __subclasscheck__(self, cls):
485 raise TypeError(f"{self} cannot be used with issubclass()")
486
487 @_tp_cache
488 def __getitem__(self, parameters):
489 return self._getitem(self, parameters)
490
491
492 class ESC[4;38;5;81m_LiteralSpecialForm(ESC[4;38;5;149m_SpecialForm, _root=ESC[4;38;5;149mTrue):
493 def __getitem__(self, parameters):
494 if not isinstance(parameters, tuple):
495 parameters = (parameters,)
496 return self._getitem(self, *parameters)
497
498
499 class ESC[4;38;5;81m_AnyMeta(ESC[4;38;5;149mtype):
500 def __instancecheck__(self, obj):
501 if self is Any:
502 raise TypeError("typing.Any cannot be used with isinstance()")
503 return super().__instancecheck__(obj)
504
505 def __repr__(self):
506 if self is Any:
507 return "typing.Any"
508 return super().__repr__() # respect to subclasses
509
510
511 class ESC[4;38;5;81mAny(metaclass=ESC[4;38;5;149m_AnyMeta):
512 """Special type indicating an unconstrained type.
513
514 - Any is compatible with every type.
515 - Any assumed to have all methods.
516 - All values assumed to be instances of Any.
517
518 Note that all the above statements are true from the point of view of
519 static type checkers. At runtime, Any should not be used with instance
520 checks.
521 """
522
523 def __new__(cls, *args, **kwargs):
524 if cls is Any:
525 raise TypeError("Any cannot be instantiated")
526 return super().__new__(cls, *args, **kwargs)
527
528
529 @_SpecialForm
530 def NoReturn(self, parameters):
531 """Special type indicating functions that never return.
532
533 Example::
534
535 from typing import NoReturn
536
537 def stop() -> NoReturn:
538 raise Exception('no way')
539
540 NoReturn can also be used as a bottom type, a type that
541 has no values. Starting in Python 3.11, the Never type should
542 be used for this concept instead. Type checkers should treat the two
543 equivalently.
544 """
545 raise TypeError(f"{self} is not subscriptable")
546
547 # This is semantically identical to NoReturn, but it is implemented
548 # separately so that type checkers can distinguish between the two
549 # if they want.
550 @_SpecialForm
551 def Never(self, parameters):
552 """The bottom type, a type that has no members.
553
554 This can be used to define a function that should never be
555 called, or a function that never returns::
556
557 from typing import Never
558
559 def never_call_me(arg: Never) -> None:
560 pass
561
562 def int_or_str(arg: int | str) -> None:
563 never_call_me(arg) # type checker error
564 match arg:
565 case int():
566 print("It's an int")
567 case str():
568 print("It's a str")
569 case _:
570 never_call_me(arg) # OK, arg is of type Never
571 """
572 raise TypeError(f"{self} is not subscriptable")
573
574
575 @_SpecialForm
576 def Self(self, parameters):
577 """Used to spell the type of "self" in classes.
578
579 Example::
580
581 from typing import Self
582
583 class Foo:
584 def return_self(self) -> Self:
585 ...
586 return self
587
588 This is especially useful for:
589 - classmethods that are used as alternative constructors
590 - annotating an `__enter__` method which returns self
591 """
592 raise TypeError(f"{self} is not subscriptable")
593
594
595 @_SpecialForm
596 def LiteralString(self, parameters):
597 """Represents an arbitrary literal string.
598
599 Example::
600
601 from typing import LiteralString
602
603 def run_query(sql: LiteralString) -> None:
604 ...
605
606 def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
607 run_query("SELECT * FROM students") # OK
608 run_query(literal_string) # OK
609 run_query("SELECT * FROM " + literal_string) # OK
610 run_query(arbitrary_string) # type checker error
611 run_query( # type checker error
612 f"SELECT * FROM students WHERE name = {arbitrary_string}"
613 )
614
615 Only string literals and other LiteralStrings are compatible
616 with LiteralString. This provides a tool to help prevent
617 security issues such as SQL injection.
618 """
619 raise TypeError(f"{self} is not subscriptable")
620
621
622 @_SpecialForm
623 def ClassVar(self, parameters):
624 """Special type construct to mark class variables.
625
626 An annotation wrapped in ClassVar indicates that a given
627 attribute is intended to be used as a class variable and
628 should not be set on instances of that class.
629
630 Usage::
631
632 class Starship:
633 stats: ClassVar[dict[str, int]] = {} # class variable
634 damage: int = 10 # instance variable
635
636 ClassVar accepts only types and cannot be further subscribed.
637
638 Note that ClassVar is not a class itself, and should not
639 be used with isinstance() or issubclass().
640 """
641 item = _type_check(parameters, f'{self} accepts only single type.')
642 return _GenericAlias(self, (item,))
643
644 @_SpecialForm
645 def Final(self, parameters):
646 """Special typing construct to indicate final names to type checkers.
647
648 A final name cannot be re-assigned or overridden in a subclass.
649
650 For example::
651
652 MAX_SIZE: Final = 9000
653 MAX_SIZE += 1 # Error reported by type checker
654
655 class Connection:
656 TIMEOUT: Final[int] = 10
657
658 class FastConnector(Connection):
659 TIMEOUT = 1 # Error reported by type checker
660
661 There is no runtime checking of these properties.
662 """
663 item = _type_check(parameters, f'{self} accepts only single type.')
664 return _GenericAlias(self, (item,))
665
666 @_SpecialForm
667 def Union(self, parameters):
668 """Union type; Union[X, Y] means either X or Y.
669
670 On Python 3.10 and higher, the | operator
671 can also be used to denote unions;
672 X | Y means the same thing to the type checker as Union[X, Y].
673
674 To define a union, use e.g. Union[int, str]. Details:
675 - The arguments must be types and there must be at least one.
676 - None as an argument is a special case and is replaced by
677 type(None).
678 - Unions of unions are flattened, e.g.::
679
680 assert Union[Union[int, str], float] == Union[int, str, float]
681
682 - Unions of a single argument vanish, e.g.::
683
684 assert Union[int] == int # The constructor actually returns int
685
686 - Redundant arguments are skipped, e.g.::
687
688 assert Union[int, str, int] == Union[int, str]
689
690 - When comparing unions, the argument order is ignored, e.g.::
691
692 assert Union[int, str] == Union[str, int]
693
694 - You cannot subclass or instantiate a union.
695 - You can use Optional[X] as a shorthand for Union[X, None].
696 """
697 if parameters == ():
698 raise TypeError("Cannot take a Union of no types.")
699 if not isinstance(parameters, tuple):
700 parameters = (parameters,)
701 msg = "Union[arg, ...]: each arg must be a type."
702 parameters = tuple(_type_check(p, msg) for p in parameters)
703 parameters = _remove_dups_flatten(parameters)
704 if len(parameters) == 1:
705 return parameters[0]
706 if len(parameters) == 2 and type(None) in parameters:
707 return _UnionGenericAlias(self, parameters, name="Optional")
708 return _UnionGenericAlias(self, parameters)
709
710 def _make_union(left, right):
711 """Used from the C implementation of TypeVar.
712
713 TypeVar.__or__ calls this instead of returning types.UnionType
714 because we want to allow unions between TypeVars and strings
715 (forward references).
716 """
717 return Union[left, right]
718
719 @_SpecialForm
720 def Optional(self, parameters):
721 """Optional[X] is equivalent to Union[X, None]."""
722 arg = _type_check(parameters, f"{self} requires a single type.")
723 return Union[arg, type(None)]
724
725 @_LiteralSpecialForm
726 @_tp_cache(typed=True)
727 def Literal(self, *parameters):
728 """Special typing form to define literal types (a.k.a. value types).
729
730 This form can be used to indicate to type checkers that the corresponding
731 variable or function parameter has a value equivalent to the provided
732 literal (or one of several literals)::
733
734 def validate_simple(data: Any) -> Literal[True]: # always returns True
735 ...
736
737 MODE = Literal['r', 'rb', 'w', 'wb']
738 def open_helper(file: str, mode: MODE) -> str:
739 ...
740
741 open_helper('/some/path', 'r') # Passes type check
742 open_helper('/other/path', 'typo') # Error in type checker
743
744 Literal[...] cannot be subclassed. At runtime, an arbitrary value
745 is allowed as type argument to Literal[...], but type checkers may
746 impose restrictions.
747 """
748 # There is no '_type_check' call because arguments to Literal[...] are
749 # values, not types.
750 parameters = _flatten_literal_params(parameters)
751
752 try:
753 parameters = tuple(p for p, _ in _deduplicate(list(_value_and_type_iter(parameters))))
754 except TypeError: # unhashable parameters
755 pass
756
757 return _LiteralGenericAlias(self, parameters)
758
759
760 @_SpecialForm
761 def TypeAlias(self, parameters):
762 """Special form for marking type aliases.
763
764 Use TypeAlias to indicate that an assignment should
765 be recognized as a proper type alias definition by type
766 checkers.
767
768 For example::
769
770 Predicate: TypeAlias = Callable[..., bool]
771
772 It's invalid when used anywhere except as in the example above.
773 """
774 raise TypeError(f"{self} is not subscriptable")
775
776
777 @_SpecialForm
778 def Concatenate(self, parameters):
779 """Special form for annotating higher-order functions.
780
781 ``Concatenate`` can be used in conjunction with ``ParamSpec`` and
782 ``Callable`` to represent a higher-order function which adds, removes or
783 transforms the parameters of a callable.
784
785 For example::
786
787 Callable[Concatenate[int, P], int]
788
789 See PEP 612 for detailed information.
790 """
791 if parameters == ():
792 raise TypeError("Cannot take a Concatenate of no types.")
793 if not isinstance(parameters, tuple):
794 parameters = (parameters,)
795 if not (parameters[-1] is ... or isinstance(parameters[-1], ParamSpec)):
796 raise TypeError("The last parameter to Concatenate should be a "
797 "ParamSpec variable or ellipsis.")
798 msg = "Concatenate[arg, ...]: each arg must be a type."
799 parameters = (*(_type_check(p, msg) for p in parameters[:-1]), parameters[-1])
800 return _ConcatenateGenericAlias(self, parameters)
801
802
803 @_SpecialForm
804 def TypeGuard(self, parameters):
805 """Special typing construct for marking user-defined type guard functions.
806
807 ``TypeGuard`` can be used to annotate the return type of a user-defined
808 type guard function. ``TypeGuard`` only accepts a single type argument.
809 At runtime, functions marked this way should return a boolean.
810
811 ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static
812 type checkers to determine a more precise type of an expression within a
813 program's code flow. Usually type narrowing is done by analyzing
814 conditional code flow and applying the narrowing to a block of code. The
815 conditional expression here is sometimes referred to as a "type guard".
816
817 Sometimes it would be convenient to use a user-defined boolean function
818 as a type guard. Such a function should use ``TypeGuard[...]`` as its
819 return type to alert static type checkers to this intention.
820
821 Using ``-> TypeGuard`` tells the static type checker that for a given
822 function:
823
824 1. The return value is a boolean.
825 2. If the return value is ``True``, the type of its argument
826 is the type inside ``TypeGuard``.
827
828 For example::
829
830 def is_str(val: Union[str, float]):
831 # "isinstance" type guard
832 if isinstance(val, str):
833 # Type of ``val`` is narrowed to ``str``
834 ...
835 else:
836 # Else, type of ``val`` is narrowed to ``float``.
837 ...
838
839 Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower
840 form of ``TypeA`` (it can even be a wider form) and this may lead to
841 type-unsafe results. The main reason is to allow for things like
842 narrowing ``List[object]`` to ``List[str]`` even though the latter is not
843 a subtype of the former, since ``List`` is invariant. The responsibility of
844 writing type-safe type guards is left to the user.
845
846 ``TypeGuard`` also works with type variables. For more information, see
847 PEP 647 (User-Defined Type Guards).
848 """
849 item = _type_check(parameters, f'{self} accepts only single type.')
850 return _GenericAlias(self, (item,))
851
852
853 class ESC[4;38;5;81mForwardRef(ESC[4;38;5;149m_Final, _root=ESC[4;38;5;149mTrue):
854 """Internal wrapper to hold a forward reference."""
855
856 __slots__ = ('__forward_arg__', '__forward_code__',
857 '__forward_evaluated__', '__forward_value__',
858 '__forward_is_argument__', '__forward_is_class__',
859 '__forward_module__')
860
861 def __init__(self, arg, is_argument=True, module=None, *, is_class=False):
862 if not isinstance(arg, str):
863 raise TypeError(f"Forward reference must be a string -- got {arg!r}")
864
865 # If we do `def f(*args: *Ts)`, then we'll have `arg = '*Ts'`.
866 # Unfortunately, this isn't a valid expression on its own, so we
867 # do the unpacking manually.
868 if arg[0] == '*':
869 arg_to_compile = f'({arg},)[0]' # E.g. (*Ts,)[0] or (*tuple[int, int],)[0]
870 else:
871 arg_to_compile = arg
872 try:
873 code = compile(arg_to_compile, '<string>', 'eval')
874 except SyntaxError:
875 raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}")
876
877 self.__forward_arg__ = arg
878 self.__forward_code__ = code
879 self.__forward_evaluated__ = False
880 self.__forward_value__ = None
881 self.__forward_is_argument__ = is_argument
882 self.__forward_is_class__ = is_class
883 self.__forward_module__ = module
884
885 def _evaluate(self, globalns, localns, recursive_guard):
886 if self.__forward_arg__ in recursive_guard:
887 return self
888 if not self.__forward_evaluated__ or localns is not globalns:
889 if globalns is None and localns is None:
890 globalns = localns = {}
891 elif globalns is None:
892 globalns = localns
893 elif localns is None:
894 localns = globalns
895 if self.__forward_module__ is not None:
896 globalns = getattr(
897 sys.modules.get(self.__forward_module__, None), '__dict__', globalns
898 )
899 type_ = _type_check(
900 eval(self.__forward_code__, globalns, localns),
901 "Forward references must evaluate to types.",
902 is_argument=self.__forward_is_argument__,
903 allow_special_forms=self.__forward_is_class__,
904 )
905 self.__forward_value__ = _eval_type(
906 type_, globalns, localns, recursive_guard | {self.__forward_arg__}
907 )
908 self.__forward_evaluated__ = True
909 return self.__forward_value__
910
911 def __eq__(self, other):
912 if not isinstance(other, ForwardRef):
913 return NotImplemented
914 if self.__forward_evaluated__ and other.__forward_evaluated__:
915 return (self.__forward_arg__ == other.__forward_arg__ and
916 self.__forward_value__ == other.__forward_value__)
917 return (self.__forward_arg__ == other.__forward_arg__ and
918 self.__forward_module__ == other.__forward_module__)
919
920 def __hash__(self):
921 return hash((self.__forward_arg__, self.__forward_module__))
922
923 def __or__(self, other):
924 return Union[self, other]
925
926 def __ror__(self, other):
927 return Union[other, self]
928
929 def __repr__(self):
930 if self.__forward_module__ is None:
931 module_repr = ''
932 else:
933 module_repr = f', module={self.__forward_module__!r}'
934 return f'ForwardRef({self.__forward_arg__!r}{module_repr})'
935
936
937 def _is_unpacked_typevartuple(x: Any) -> bool:
938 return ((not isinstance(x, type)) and
939 getattr(x, '__typing_is_unpacked_typevartuple__', False))
940
941
942 def _is_typevar_like(x: Any) -> bool:
943 return isinstance(x, (TypeVar, ParamSpec)) or _is_unpacked_typevartuple(x)
944
945
946 class ESC[4;38;5;81m_PickleUsingNameMixin:
947 """Mixin enabling pickling based on self.__name__."""
948
949 def __reduce__(self):
950 return self.__name__
951
952
953 def _typevar_subst(self, arg):
954 msg = "Parameters to generic types must be types."
955 arg = _type_check(arg, msg, is_argument=True)
956 if ((isinstance(arg, _GenericAlias) and arg.__origin__ is Unpack) or
957 (isinstance(arg, GenericAlias) and getattr(arg, '__unpacked__', False))):
958 raise TypeError(f"{arg} is not valid as type argument")
959 return arg
960
961
962 def _typevartuple_prepare_subst(self, alias, args):
963 params = alias.__parameters__
964 typevartuple_index = params.index(self)
965 for param in params[typevartuple_index + 1:]:
966 if isinstance(param, TypeVarTuple):
967 raise TypeError(f"More than one TypeVarTuple parameter in {alias}")
968
969 alen = len(args)
970 plen = len(params)
971 left = typevartuple_index
972 right = plen - typevartuple_index - 1
973 var_tuple_index = None
974 fillarg = None
975 for k, arg in enumerate(args):
976 if not isinstance(arg, type):
977 subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
978 if subargs and len(subargs) == 2 and subargs[-1] is ...:
979 if var_tuple_index is not None:
980 raise TypeError("More than one unpacked arbitrary-length tuple argument")
981 var_tuple_index = k
982 fillarg = subargs[0]
983 if var_tuple_index is not None:
984 left = min(left, var_tuple_index)
985 right = min(right, alen - var_tuple_index - 1)
986 elif left + right > alen:
987 raise TypeError(f"Too few arguments for {alias};"
988 f" actual {alen}, expected at least {plen-1}")
989
990 return (
991 *args[:left],
992 *([fillarg]*(typevartuple_index - left)),
993 tuple(args[left: alen - right]),
994 *([fillarg]*(plen - right - left - typevartuple_index - 1)),
995 *args[alen - right:],
996 )
997
998
999 def _paramspec_subst(self, arg):
1000 if isinstance(arg, (list, tuple)):
1001 arg = tuple(_type_check(a, "Expected a type.") for a in arg)
1002 elif not _is_param_expr(arg):
1003 raise TypeError(f"Expected a list of types, an ellipsis, "
1004 f"ParamSpec, or Concatenate. Got {arg}")
1005 return arg
1006
1007
1008 def _paramspec_prepare_subst(self, alias, args):
1009 params = alias.__parameters__
1010 i = params.index(self)
1011 if i >= len(args):
1012 raise TypeError(f"Too few arguments for {alias}")
1013 # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612.
1014 if len(params) == 1 and not _is_param_expr(args[0]):
1015 assert i == 0
1016 args = (args,)
1017 # Convert lists to tuples to help other libraries cache the results.
1018 elif isinstance(args[i], list):
1019 args = (*args[:i], tuple(args[i]), *args[i+1:])
1020 return args
1021
1022
1023 @_tp_cache
1024 def _generic_class_getitem(cls, params):
1025 """Parameterizes a generic class.
1026
1027 At least, parameterizing a generic class is the *main* thing this method
1028 does. For example, for some generic class `Foo`, this is called when we
1029 do `Foo[int]` - there, with `cls=Foo` and `params=int`.
1030
1031 However, note that this method is also called when defining generic
1032 classes in the first place with `class Foo(Generic[T]): ...`.
1033 """
1034 if not isinstance(params, tuple):
1035 params = (params,)
1036
1037 params = tuple(_type_convert(p) for p in params)
1038 is_generic_or_protocol = cls in (Generic, Protocol)
1039
1040 if is_generic_or_protocol:
1041 # Generic and Protocol can only be subscripted with unique type variables.
1042 if not params:
1043 raise TypeError(
1044 f"Parameter list to {cls.__qualname__}[...] cannot be empty"
1045 )
1046 if not all(_is_typevar_like(p) for p in params):
1047 raise TypeError(
1048 f"Parameters to {cls.__name__}[...] must all be type variables "
1049 f"or parameter specification variables.")
1050 if len(set(params)) != len(params):
1051 raise TypeError(
1052 f"Parameters to {cls.__name__}[...] must all be unique")
1053 else:
1054 # Subscripting a regular Generic subclass.
1055 for param in cls.__parameters__:
1056 prepare = getattr(param, '__typing_prepare_subst__', None)
1057 if prepare is not None:
1058 params = prepare(cls, params)
1059 _check_generic(cls, params, len(cls.__parameters__))
1060
1061 new_args = []
1062 for param, new_arg in zip(cls.__parameters__, params):
1063 if isinstance(param, TypeVarTuple):
1064 new_args.extend(new_arg)
1065 else:
1066 new_args.append(new_arg)
1067 params = tuple(new_args)
1068
1069 return _GenericAlias(cls, params)
1070
1071
1072 def _generic_init_subclass(cls, *args, **kwargs):
1073 super(Generic, cls).__init_subclass__(*args, **kwargs)
1074 tvars = []
1075 if '__orig_bases__' in cls.__dict__:
1076 error = Generic in cls.__orig_bases__
1077 else:
1078 error = (Generic in cls.__bases__ and
1079 cls.__name__ != 'Protocol' and
1080 type(cls) != _TypedDictMeta)
1081 if error:
1082 raise TypeError("Cannot inherit from plain Generic")
1083 if '__orig_bases__' in cls.__dict__:
1084 tvars = _collect_parameters(cls.__orig_bases__)
1085 # Look for Generic[T1, ..., Tn].
1086 # If found, tvars must be a subset of it.
1087 # If not found, tvars is it.
1088 # Also check for and reject plain Generic,
1089 # and reject multiple Generic[...].
1090 gvars = None
1091 for base in cls.__orig_bases__:
1092 if (isinstance(base, _GenericAlias) and
1093 base.__origin__ is Generic):
1094 if gvars is not None:
1095 raise TypeError(
1096 "Cannot inherit from Generic[...] multiple times.")
1097 gvars = base.__parameters__
1098 if gvars is not None:
1099 tvarset = set(tvars)
1100 gvarset = set(gvars)
1101 if not tvarset <= gvarset:
1102 s_vars = ', '.join(str(t) for t in tvars if t not in gvarset)
1103 s_args = ', '.join(str(g) for g in gvars)
1104 raise TypeError(f"Some type variables ({s_vars}) are"
1105 f" not listed in Generic[{s_args}]")
1106 tvars = gvars
1107 cls.__parameters__ = tuple(tvars)
1108
1109
1110 def _is_dunder(attr):
1111 return attr.startswith('__') and attr.endswith('__')
1112
1113 class ESC[4;38;5;81m_BaseGenericAlias(ESC[4;38;5;149m_Final, _root=ESC[4;38;5;149mTrue):
1114 """The central part of the internal API.
1115
1116 This represents a generic version of type 'origin' with type arguments 'params'.
1117 There are two kind of these aliases: user defined and special. The special ones
1118 are wrappers around builtin collections and ABCs in collections.abc. These must
1119 have 'name' always set. If 'inst' is False, then the alias can't be instantiated;
1120 this is used by e.g. typing.List and typing.Dict.
1121 """
1122
1123 def __init__(self, origin, *, inst=True, name=None):
1124 self._inst = inst
1125 self._name = name
1126 self.__origin__ = origin
1127 self.__slots__ = None # This is not documented.
1128
1129 def __call__(self, *args, **kwargs):
1130 if not self._inst:
1131 raise TypeError(f"Type {self._name} cannot be instantiated; "
1132 f"use {self.__origin__.__name__}() instead")
1133 result = self.__origin__(*args, **kwargs)
1134 try:
1135 result.__orig_class__ = self
1136 except AttributeError:
1137 pass
1138 return result
1139
1140 def __mro_entries__(self, bases):
1141 res = []
1142 if self.__origin__ not in bases:
1143 res.append(self.__origin__)
1144 i = bases.index(self)
1145 for b in bases[i+1:]:
1146 if isinstance(b, _BaseGenericAlias) or issubclass(b, Generic):
1147 break
1148 else:
1149 res.append(Generic)
1150 return tuple(res)
1151
1152 def __getattr__(self, attr):
1153 if attr in {'__name__', '__qualname__'}:
1154 return self._name or self.__origin__.__name__
1155
1156 # We are careful for copy and pickle.
1157 # Also for simplicity we don't relay any dunder names
1158 if '__origin__' in self.__dict__ and not _is_dunder(attr):
1159 return getattr(self.__origin__, attr)
1160 raise AttributeError(attr)
1161
1162 def __setattr__(self, attr, val):
1163 if _is_dunder(attr) or attr in {'_name', '_inst', '_nparams'}:
1164 super().__setattr__(attr, val)
1165 else:
1166 setattr(self.__origin__, attr, val)
1167
1168 def __instancecheck__(self, obj):
1169 return self.__subclasscheck__(type(obj))
1170
1171 def __subclasscheck__(self, cls):
1172 raise TypeError("Subscripted generics cannot be used with"
1173 " class and instance checks")
1174
1175 def __dir__(self):
1176 return list(set(super().__dir__()
1177 + [attr for attr in dir(self.__origin__) if not _is_dunder(attr)]))
1178
1179
1180 # Special typing constructs Union, Optional, Generic, Callable and Tuple
1181 # use three special attributes for internal bookkeeping of generic types:
1182 # * __parameters__ is a tuple of unique free type parameters of a generic
1183 # type, for example, Dict[T, T].__parameters__ == (T,);
1184 # * __origin__ keeps a reference to a type that was subscripted,
1185 # e.g., Union[T, int].__origin__ == Union, or the non-generic version of
1186 # the type.
1187 # * __args__ is a tuple of all arguments used in subscripting,
1188 # e.g., Dict[T, int].__args__ == (T, int).
1189
1190
1191 class ESC[4;38;5;81m_GenericAlias(ESC[4;38;5;149m_BaseGenericAlias, _root=ESC[4;38;5;149mTrue):
1192 # The type of parameterized generics.
1193 #
1194 # That is, for example, `type(List[int])` is `_GenericAlias`.
1195 #
1196 # Objects which are instances of this class include:
1197 # * Parameterized container types, e.g. `Tuple[int]`, `List[int]`.
1198 # * Note that native container types, e.g. `tuple`, `list`, use
1199 # `types.GenericAlias` instead.
1200 # * Parameterized classes:
1201 # class C[T]: pass
1202 # # C[int] is a _GenericAlias
1203 # * `Callable` aliases, generic `Callable` aliases, and
1204 # parameterized `Callable` aliases:
1205 # T = TypeVar('T')
1206 # # _CallableGenericAlias inherits from _GenericAlias.
1207 # A = Callable[[], None] # _CallableGenericAlias
1208 # B = Callable[[T], None] # _CallableGenericAlias
1209 # C = B[int] # _CallableGenericAlias
1210 # * Parameterized `Final`, `ClassVar` and `TypeGuard`:
1211 # # All _GenericAlias
1212 # Final[int]
1213 # ClassVar[float]
1214 # TypeVar[bool]
1215
1216 def __init__(self, origin, args, *, inst=True, name=None):
1217 super().__init__(origin, inst=inst, name=name)
1218 if not isinstance(args, tuple):
1219 args = (args,)
1220 self.__args__ = tuple(... if a is _TypingEllipsis else
1221 a for a in args)
1222 self.__parameters__ = _collect_parameters(args)
1223 if not name:
1224 self.__module__ = origin.__module__
1225
1226 def __eq__(self, other):
1227 if not isinstance(other, _GenericAlias):
1228 return NotImplemented
1229 return (self.__origin__ == other.__origin__
1230 and self.__args__ == other.__args__)
1231
1232 def __hash__(self):
1233 return hash((self.__origin__, self.__args__))
1234
1235 def __or__(self, right):
1236 return Union[self, right]
1237
1238 def __ror__(self, left):
1239 return Union[left, self]
1240
1241 @_tp_cache
1242 def __getitem__(self, args):
1243 # Parameterizes an already-parameterized object.
1244 #
1245 # For example, we arrive here doing something like:
1246 # T1 = TypeVar('T1')
1247 # T2 = TypeVar('T2')
1248 # T3 = TypeVar('T3')
1249 # class A(Generic[T1]): pass
1250 # B = A[T2] # B is a _GenericAlias
1251 # C = B[T3] # Invokes _GenericAlias.__getitem__
1252 #
1253 # We also arrive here when parameterizing a generic `Callable` alias:
1254 # T = TypeVar('T')
1255 # C = Callable[[T], None]
1256 # C[int] # Invokes _GenericAlias.__getitem__
1257
1258 if self.__origin__ in (Generic, Protocol):
1259 # Can't subscript Generic[...] or Protocol[...].
1260 raise TypeError(f"Cannot subscript already-subscripted {self}")
1261 if not self.__parameters__:
1262 raise TypeError(f"{self} is not a generic class")
1263
1264 # Preprocess `args`.
1265 if not isinstance(args, tuple):
1266 args = (args,)
1267 args = tuple(_type_convert(p) for p in args)
1268 args = _unpack_args(args)
1269 new_args = self._determine_new_args(args)
1270 r = self.copy_with(new_args)
1271 return r
1272
1273 def _determine_new_args(self, args):
1274 # Determines new __args__ for __getitem__.
1275 #
1276 # For example, suppose we had:
1277 # T1 = TypeVar('T1')
1278 # T2 = TypeVar('T2')
1279 # class A(Generic[T1, T2]): pass
1280 # T3 = TypeVar('T3')
1281 # B = A[int, T3]
1282 # C = B[str]
1283 # `B.__args__` is `(int, T3)`, so `C.__args__` should be `(int, str)`.
1284 # Unfortunately, this is harder than it looks, because if `T3` is
1285 # anything more exotic than a plain `TypeVar`, we need to consider
1286 # edge cases.
1287
1288 params = self.__parameters__
1289 # In the example above, this would be {T3: str}
1290 for param in params:
1291 prepare = getattr(param, '__typing_prepare_subst__', None)
1292 if prepare is not None:
1293 args = prepare(self, args)
1294 alen = len(args)
1295 plen = len(params)
1296 if alen != plen:
1297 raise TypeError(f"Too {'many' if alen > plen else 'few'} arguments for {self};"
1298 f" actual {alen}, expected {plen}")
1299 new_arg_by_param = dict(zip(params, args))
1300 return tuple(self._make_substitution(self.__args__, new_arg_by_param))
1301
1302 def _make_substitution(self, args, new_arg_by_param):
1303 """Create a list of new type arguments."""
1304 new_args = []
1305 for old_arg in args:
1306 if isinstance(old_arg, type):
1307 new_args.append(old_arg)
1308 continue
1309
1310 substfunc = getattr(old_arg, '__typing_subst__', None)
1311 if substfunc:
1312 new_arg = substfunc(new_arg_by_param[old_arg])
1313 else:
1314 subparams = getattr(old_arg, '__parameters__', ())
1315 if not subparams:
1316 new_arg = old_arg
1317 else:
1318 subargs = []
1319 for x in subparams:
1320 if isinstance(x, TypeVarTuple):
1321 subargs.extend(new_arg_by_param[x])
1322 else:
1323 subargs.append(new_arg_by_param[x])
1324 new_arg = old_arg[tuple(subargs)]
1325
1326 if self.__origin__ == collections.abc.Callable and isinstance(new_arg, tuple):
1327 # Consider the following `Callable`.
1328 # C = Callable[[int], str]
1329 # Here, `C.__args__` should be (int, str) - NOT ([int], str).
1330 # That means that if we had something like...
1331 # P = ParamSpec('P')
1332 # T = TypeVar('T')
1333 # C = Callable[P, T]
1334 # D = C[[int, str], float]
1335 # ...we need to be careful; `new_args` should end up as
1336 # `(int, str, float)` rather than `([int, str], float)`.
1337 new_args.extend(new_arg)
1338 elif _is_unpacked_typevartuple(old_arg):
1339 # Consider the following `_GenericAlias`, `B`:
1340 # class A(Generic[*Ts]): ...
1341 # B = A[T, *Ts]
1342 # If we then do:
1343 # B[float, int, str]
1344 # The `new_arg` corresponding to `T` will be `float`, and the
1345 # `new_arg` corresponding to `*Ts` will be `(int, str)`. We
1346 # should join all these types together in a flat list
1347 # `(float, int, str)` - so again, we should `extend`.
1348 new_args.extend(new_arg)
1349 elif isinstance(old_arg, tuple):
1350 # Corner case:
1351 # P = ParamSpec('P')
1352 # T = TypeVar('T')
1353 # class Base(Generic[P]): ...
1354 # Can be substituted like this:
1355 # X = Base[[int, T]]
1356 # In this case, `old_arg` will be a tuple:
1357 new_args.append(
1358 tuple(self._make_substitution(old_arg, new_arg_by_param)),
1359 )
1360 else:
1361 new_args.append(new_arg)
1362 return new_args
1363
1364 def copy_with(self, args):
1365 return self.__class__(self.__origin__, args, name=self._name, inst=self._inst)
1366
1367 def __repr__(self):
1368 if self._name:
1369 name = 'typing.' + self._name
1370 else:
1371 name = _type_repr(self.__origin__)
1372 if self.__args__:
1373 args = ", ".join([_type_repr(a) for a in self.__args__])
1374 else:
1375 # To ensure the repr is eval-able.
1376 args = "()"
1377 return f'{name}[{args}]'
1378
1379 def __reduce__(self):
1380 if self._name:
1381 origin = globals()[self._name]
1382 else:
1383 origin = self.__origin__
1384 args = tuple(self.__args__)
1385 if len(args) == 1 and not isinstance(args[0], tuple):
1386 args, = args
1387 return operator.getitem, (origin, args)
1388
1389 def __mro_entries__(self, bases):
1390 if isinstance(self.__origin__, _SpecialForm):
1391 raise TypeError(f"Cannot subclass {self!r}")
1392
1393 if self._name: # generic version of an ABC or built-in class
1394 return super().__mro_entries__(bases)
1395 if self.__origin__ is Generic:
1396 if Protocol in bases:
1397 return ()
1398 i = bases.index(self)
1399 for b in bases[i+1:]:
1400 if isinstance(b, _BaseGenericAlias) and b is not self:
1401 return ()
1402 return (self.__origin__,)
1403
1404 def __iter__(self):
1405 yield Unpack[self]
1406
1407
1408 # _nparams is the number of accepted parameters, e.g. 0 for Hashable,
1409 # 1 for List and 2 for Dict. It may be -1 if variable number of
1410 # parameters are accepted (needs custom __getitem__).
1411
1412 class ESC[4;38;5;81m_SpecialGenericAlias(ESC[4;38;5;149m_NotIterable, ESC[4;38;5;149m_BaseGenericAlias, _root=ESC[4;38;5;149mTrue):
1413 def __init__(self, origin, nparams, *, inst=True, name=None):
1414 if name is None:
1415 name = origin.__name__
1416 super().__init__(origin, inst=inst, name=name)
1417 self._nparams = nparams
1418 if origin.__module__ == 'builtins':
1419 self.__doc__ = f'A generic version of {origin.__qualname__}.'
1420 else:
1421 self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}.'
1422
1423 @_tp_cache
1424 def __getitem__(self, params):
1425 if not isinstance(params, tuple):
1426 params = (params,)
1427 msg = "Parameters to generic types must be types."
1428 params = tuple(_type_check(p, msg) for p in params)
1429 _check_generic(self, params, self._nparams)
1430 return self.copy_with(params)
1431
1432 def copy_with(self, params):
1433 return _GenericAlias(self.__origin__, params,
1434 name=self._name, inst=self._inst)
1435
1436 def __repr__(self):
1437 return 'typing.' + self._name
1438
1439 def __subclasscheck__(self, cls):
1440 if isinstance(cls, _SpecialGenericAlias):
1441 return issubclass(cls.__origin__, self.__origin__)
1442 if not isinstance(cls, _GenericAlias):
1443 return issubclass(cls, self.__origin__)
1444 return super().__subclasscheck__(cls)
1445
1446 def __reduce__(self):
1447 return self._name
1448
1449 def __or__(self, right):
1450 return Union[self, right]
1451
1452 def __ror__(self, left):
1453 return Union[left, self]
1454
1455
1456 class ESC[4;38;5;81m_DeprecatedGenericAlias(ESC[4;38;5;149m_SpecialGenericAlias, _root=ESC[4;38;5;149mTrue):
1457 def __init__(
1458 self, origin, nparams, *, removal_version, inst=True, name=None
1459 ):
1460 super().__init__(origin, nparams, inst=inst, name=name)
1461 self._removal_version = removal_version
1462
1463 def __instancecheck__(self, inst):
1464 import warnings
1465 warnings._deprecated(
1466 f"{self.__module__}.{self._name}", remove=self._removal_version
1467 )
1468 return super().__instancecheck__(inst)
1469
1470
1471 class ESC[4;38;5;81m_CallableGenericAlias(ESC[4;38;5;149m_NotIterable, ESC[4;38;5;149m_GenericAlias, _root=ESC[4;38;5;149mTrue):
1472 def __repr__(self):
1473 assert self._name == 'Callable'
1474 args = self.__args__
1475 if len(args) == 2 and _is_param_expr(args[0]):
1476 return super().__repr__()
1477 return (f'typing.Callable'
1478 f'[[{", ".join([_type_repr(a) for a in args[:-1]])}], '
1479 f'{_type_repr(args[-1])}]')
1480
1481 def __reduce__(self):
1482 args = self.__args__
1483 if not (len(args) == 2 and _is_param_expr(args[0])):
1484 args = list(args[:-1]), args[-1]
1485 return operator.getitem, (Callable, args)
1486
1487
1488 class ESC[4;38;5;81m_CallableType(ESC[4;38;5;149m_SpecialGenericAlias, _root=ESC[4;38;5;149mTrue):
1489 def copy_with(self, params):
1490 return _CallableGenericAlias(self.__origin__, params,
1491 name=self._name, inst=self._inst)
1492
1493 def __getitem__(self, params):
1494 if not isinstance(params, tuple) or len(params) != 2:
1495 raise TypeError("Callable must be used as "
1496 "Callable[[arg, ...], result].")
1497 args, result = params
1498 # This relaxes what args can be on purpose to allow things like
1499 # PEP 612 ParamSpec. Responsibility for whether a user is using
1500 # Callable[...] properly is deferred to static type checkers.
1501 if isinstance(args, list):
1502 params = (tuple(args), result)
1503 else:
1504 params = (args, result)
1505 return self.__getitem_inner__(params)
1506
1507 @_tp_cache
1508 def __getitem_inner__(self, params):
1509 args, result = params
1510 msg = "Callable[args, result]: result must be a type."
1511 result = _type_check(result, msg)
1512 if args is Ellipsis:
1513 return self.copy_with((_TypingEllipsis, result))
1514 if not isinstance(args, tuple):
1515 args = (args,)
1516 args = tuple(_type_convert(arg) for arg in args)
1517 params = args + (result,)
1518 return self.copy_with(params)
1519
1520
1521 class ESC[4;38;5;81m_TupleType(ESC[4;38;5;149m_SpecialGenericAlias, _root=ESC[4;38;5;149mTrue):
1522 @_tp_cache
1523 def __getitem__(self, params):
1524 if not isinstance(params, tuple):
1525 params = (params,)
1526 if len(params) >= 2 and params[-1] is ...:
1527 msg = "Tuple[t, ...]: t must be a type."
1528 params = tuple(_type_check(p, msg) for p in params[:-1])
1529 return self.copy_with((*params, _TypingEllipsis))
1530 msg = "Tuple[t0, t1, ...]: each t must be a type."
1531 params = tuple(_type_check(p, msg) for p in params)
1532 return self.copy_with(params)
1533
1534
1535 class ESC[4;38;5;81m_UnionGenericAlias(ESC[4;38;5;149m_NotIterable, ESC[4;38;5;149m_GenericAlias, _root=ESC[4;38;5;149mTrue):
1536 def copy_with(self, params):
1537 return Union[params]
1538
1539 def __eq__(self, other):
1540 if not isinstance(other, (_UnionGenericAlias, types.UnionType)):
1541 return NotImplemented
1542 return set(self.__args__) == set(other.__args__)
1543
1544 def __hash__(self):
1545 return hash(frozenset(self.__args__))
1546
1547 def __repr__(self):
1548 args = self.__args__
1549 if len(args) == 2:
1550 if args[0] is type(None):
1551 return f'typing.Optional[{_type_repr(args[1])}]'
1552 elif args[1] is type(None):
1553 return f'typing.Optional[{_type_repr(args[0])}]'
1554 return super().__repr__()
1555
1556 def __instancecheck__(self, obj):
1557 return self.__subclasscheck__(type(obj))
1558
1559 def __subclasscheck__(self, cls):
1560 for arg in self.__args__:
1561 if issubclass(cls, arg):
1562 return True
1563
1564 def __reduce__(self):
1565 func, (origin, args) = super().__reduce__()
1566 return func, (Union, args)
1567
1568
1569 def _value_and_type_iter(parameters):
1570 return ((p, type(p)) for p in parameters)
1571
1572
1573 class ESC[4;38;5;81m_LiteralGenericAlias(ESC[4;38;5;149m_GenericAlias, _root=ESC[4;38;5;149mTrue):
1574 def __eq__(self, other):
1575 if not isinstance(other, _LiteralGenericAlias):
1576 return NotImplemented
1577
1578 return set(_value_and_type_iter(self.__args__)) == set(_value_and_type_iter(other.__args__))
1579
1580 def __hash__(self):
1581 return hash(frozenset(_value_and_type_iter(self.__args__)))
1582
1583
1584 class ESC[4;38;5;81m_ConcatenateGenericAlias(ESC[4;38;5;149m_GenericAlias, _root=ESC[4;38;5;149mTrue):
1585 def copy_with(self, params):
1586 if isinstance(params[-1], (list, tuple)):
1587 return (*params[:-1], *params[-1])
1588 if isinstance(params[-1], _ConcatenateGenericAlias):
1589 params = (*params[:-1], *params[-1].__args__)
1590 return super().copy_with(params)
1591
1592
1593 @_SpecialForm
1594 def Unpack(self, parameters):
1595 """Type unpack operator.
1596
1597 The type unpack operator takes the child types from some container type,
1598 such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'.
1599
1600 For example::
1601
1602 # For some generic class `Foo`:
1603 Foo[Unpack[tuple[int, str]]] # Equivalent to Foo[int, str]
1604
1605 Ts = TypeVarTuple('Ts')
1606 # Specifies that `Bar` is generic in an arbitrary number of types.
1607 # (Think of `Ts` as a tuple of an arbitrary number of individual
1608 # `TypeVar`s, which the `Unpack` is 'pulling out' directly into the
1609 # `Generic[]`.)
1610 class Bar(Generic[Unpack[Ts]]): ...
1611 Bar[int] # Valid
1612 Bar[int, str] # Also valid
1613
1614 From Python 3.11, this can also be done using the `*` operator::
1615
1616 Foo[*tuple[int, str]]
1617 class Bar(Generic[*Ts]): ...
1618
1619 And from Python 3.12, it can be done using built-in syntax for generics::
1620
1621 Foo[*tuple[int, str]]
1622 class Bar[*Ts]: ...
1623
1624 The operator can also be used along with a `TypedDict` to annotate
1625 `**kwargs` in a function signature::
1626
1627 class Movie(TypedDict):
1628 name: str
1629 year: int
1630
1631 # This function expects two keyword arguments - *name* of type `str` and
1632 # *year* of type `int`.
1633 def foo(**kwargs: Unpack[Movie]): ...
1634
1635 Note that there is only some runtime checking of this operator. Not
1636 everything the runtime allows may be accepted by static type checkers.
1637
1638 For more information, see PEPs 646 and 692.
1639 """
1640 item = _type_check(parameters, f'{self} accepts only single type.')
1641 return _UnpackGenericAlias(origin=self, args=(item,))
1642
1643
1644 class ESC[4;38;5;81m_UnpackGenericAlias(ESC[4;38;5;149m_GenericAlias, _root=ESC[4;38;5;149mTrue):
1645 def __repr__(self):
1646 # `Unpack` only takes one argument, so __args__ should contain only
1647 # a single item.
1648 return f'typing.Unpack[{_type_repr(self.__args__[0])}]'
1649
1650 def __getitem__(self, args):
1651 if self.__typing_is_unpacked_typevartuple__:
1652 return args
1653 return super().__getitem__(args)
1654
1655 @property
1656 def __typing_unpacked_tuple_args__(self):
1657 assert self.__origin__ is Unpack
1658 assert len(self.__args__) == 1
1659 arg, = self.__args__
1660 if isinstance(arg, _GenericAlias):
1661 assert arg.__origin__ is tuple
1662 return arg.__args__
1663 return None
1664
1665 @property
1666 def __typing_is_unpacked_typevartuple__(self):
1667 assert self.__origin__ is Unpack
1668 assert len(self.__args__) == 1
1669 return isinstance(self.__args__[0], TypeVarTuple)
1670
1671
1672 class ESC[4;38;5;81m_TypingEllipsis:
1673 """Internal placeholder for ... (ellipsis)."""
1674
1675
1676 _TYPING_INTERNALS = frozenset({
1677 '__parameters__', '__orig_bases__', '__orig_class__',
1678 '_is_protocol', '_is_runtime_protocol', '__protocol_attrs__',
1679 '__callable_proto_members_only__', '__type_params__',
1680 })
1681
1682 _SPECIAL_NAMES = frozenset({
1683 '__abstractmethods__', '__annotations__', '__dict__', '__doc__',
1684 '__init__', '__module__', '__new__', '__slots__',
1685 '__subclasshook__', '__weakref__', '__class_getitem__'
1686 })
1687
1688 # These special attributes will be not collected as protocol members.
1689 EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS | _SPECIAL_NAMES | {'_MutableMapping__marker'}
1690
1691
1692 def _get_protocol_attrs(cls):
1693 """Collect protocol members from a protocol class objects.
1694
1695 This includes names actually defined in the class dictionary, as well
1696 as names that appear in annotations. Special names (above) are skipped.
1697 """
1698 attrs = set()
1699 for base in cls.__mro__[:-1]: # without object
1700 if base.__name__ in {'Protocol', 'Generic'}:
1701 continue
1702 annotations = getattr(base, '__annotations__', {})
1703 for attr in (*base.__dict__, *annotations):
1704 if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES:
1705 attrs.add(attr)
1706 return attrs
1707
1708
1709 def _no_init_or_replace_init(self, *args, **kwargs):
1710 cls = type(self)
1711
1712 if cls._is_protocol:
1713 raise TypeError('Protocols cannot be instantiated')
1714
1715 # Already using a custom `__init__`. No need to calculate correct
1716 # `__init__` to call. This can lead to RecursionError. See bpo-45121.
1717 if cls.__init__ is not _no_init_or_replace_init:
1718 return
1719
1720 # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
1721 # The first instantiation of the subclass will call `_no_init_or_replace_init` which
1722 # searches for a proper new `__init__` in the MRO. The new `__init__`
1723 # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
1724 # instantiation of the protocol subclass will thus use the new
1725 # `__init__` and no longer call `_no_init_or_replace_init`.
1726 for base in cls.__mro__:
1727 init = base.__dict__.get('__init__', _no_init_or_replace_init)
1728 if init is not _no_init_or_replace_init:
1729 cls.__init__ = init
1730 break
1731 else:
1732 # should not happen
1733 cls.__init__ = object.__init__
1734
1735 cls.__init__(self, *args, **kwargs)
1736
1737
1738 def _caller(depth=1, default='__main__'):
1739 try:
1740 return sys._getframemodulename(depth + 1) or default
1741 except AttributeError: # For platforms without _getframemodulename()
1742 pass
1743 try:
1744 return sys._getframe(depth + 1).f_globals.get('__name__', default)
1745 except (AttributeError, ValueError): # For platforms without _getframe()
1746 pass
1747 return None
1748
1749 def _allow_reckless_class_checks(depth=2):
1750 """Allow instance and class checks for special stdlib modules.
1751
1752 The abc and functools modules indiscriminately call isinstance() and
1753 issubclass() on the whole MRO of a user class, which may contain protocols.
1754 """
1755 return _caller(depth) in {'abc', 'functools', None}
1756
1757
1758 _PROTO_ALLOWLIST = {
1759 'collections.abc': [
1760 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
1761 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible', 'Buffer',
1762 ],
1763 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
1764 }
1765
1766
1767 @functools.cache
1768 def _lazy_load_getattr_static():
1769 # Import getattr_static lazily so as not to slow down the import of typing.py
1770 # Cache the result so we don't slow down _ProtocolMeta.__instancecheck__ unnecessarily
1771 from inspect import getattr_static
1772 return getattr_static
1773
1774
1775 _cleanups.append(_lazy_load_getattr_static.cache_clear)
1776
1777 def _pickle_psargs(psargs):
1778 return ParamSpecArgs, (psargs.__origin__,)
1779
1780 copyreg.pickle(ParamSpecArgs, _pickle_psargs)
1781
1782 def _pickle_pskwargs(pskwargs):
1783 return ParamSpecKwargs, (pskwargs.__origin__,)
1784
1785 copyreg.pickle(ParamSpecKwargs, _pickle_pskwargs)
1786
1787 del _pickle_psargs, _pickle_pskwargs
1788
1789
1790 class ESC[4;38;5;81m_ProtocolMeta(ESC[4;38;5;149mABCMeta):
1791 # This metaclass is somewhat unfortunate,
1792 # but is necessary for several reasons...
1793 def __new__(mcls, name, bases, namespace, /, **kwargs):
1794 if name == "Protocol" and bases == (Generic,):
1795 pass
1796 elif Protocol in bases:
1797 for base in bases:
1798 if not (
1799 base in {object, Generic}
1800 or base.__name__ in _PROTO_ALLOWLIST.get(base.__module__, [])
1801 or (
1802 issubclass(base, Generic)
1803 and getattr(base, "_is_protocol", False)
1804 )
1805 ):
1806 raise TypeError(
1807 f"Protocols can only inherit from other protocols, "
1808 f"got {base!r}"
1809 )
1810 return super().__new__(mcls, name, bases, namespace, **kwargs)
1811
1812 def __init__(cls, *args, **kwargs):
1813 super().__init__(*args, **kwargs)
1814 if getattr(cls, "_is_protocol", False):
1815 cls.__protocol_attrs__ = _get_protocol_attrs(cls)
1816 # PEP 544 prohibits using issubclass()
1817 # with protocols that have non-method members.
1818 cls.__callable_proto_members_only__ = all(
1819 callable(getattr(cls, attr, None)) for attr in cls.__protocol_attrs__
1820 )
1821
1822 def __subclasscheck__(cls, other):
1823 if cls is Protocol:
1824 return type.__subclasscheck__(cls, other)
1825 if (
1826 getattr(cls, '_is_protocol', False)
1827 and not _allow_reckless_class_checks()
1828 ):
1829 if not isinstance(other, type):
1830 # Same error message as for issubclass(1, int).
1831 raise TypeError('issubclass() arg 1 must be a class')
1832 if (
1833 not cls.__callable_proto_members_only__
1834 and cls.__dict__.get("__subclasshook__") is _proto_hook
1835 ):
1836 raise TypeError(
1837 "Protocols with non-method members don't support issubclass()"
1838 )
1839 if not getattr(cls, '_is_runtime_protocol', False):
1840 raise TypeError(
1841 "Instance and class checks can only be used with "
1842 "@runtime_checkable protocols"
1843 )
1844 return super().__subclasscheck__(other)
1845
1846 def __instancecheck__(cls, instance):
1847 # We need this method for situations where attributes are
1848 # assigned in __init__.
1849 if cls is Protocol:
1850 return type.__instancecheck__(cls, instance)
1851 if not getattr(cls, "_is_protocol", False):
1852 # i.e., it's a concrete subclass of a protocol
1853 return super().__instancecheck__(instance)
1854
1855 if (
1856 not getattr(cls, '_is_runtime_protocol', False) and
1857 not _allow_reckless_class_checks()
1858 ):
1859 raise TypeError("Instance and class checks can only be used with"
1860 " @runtime_checkable protocols")
1861
1862 if super().__instancecheck__(instance):
1863 return True
1864
1865 getattr_static = _lazy_load_getattr_static()
1866 for attr in cls.__protocol_attrs__:
1867 try:
1868 val = getattr_static(instance, attr)
1869 except AttributeError:
1870 break
1871 if val is None and callable(getattr(cls, attr, None)):
1872 break
1873 else:
1874 return True
1875
1876 return False
1877
1878
1879 @classmethod
1880 def _proto_hook(cls, other):
1881 if not cls.__dict__.get('_is_protocol', False):
1882 return NotImplemented
1883
1884 for attr in cls.__protocol_attrs__:
1885 for base in other.__mro__:
1886 # Check if the members appears in the class dictionary...
1887 if attr in base.__dict__:
1888 if base.__dict__[attr] is None:
1889 return NotImplemented
1890 break
1891
1892 # ...or in annotations, if it is a sub-protocol.
1893 annotations = getattr(base, '__annotations__', {})
1894 if (isinstance(annotations, collections.abc.Mapping) and
1895 attr in annotations and
1896 issubclass(other, Generic) and getattr(other, '_is_protocol', False)):
1897 break
1898 else:
1899 return NotImplemented
1900 return True
1901
1902
1903 class ESC[4;38;5;81mProtocol(ESC[4;38;5;149mGeneric, metaclass=ESC[4;38;5;149m_ProtocolMeta):
1904 """Base class for protocol classes.
1905
1906 Protocol classes are defined as::
1907
1908 class Proto(Protocol):
1909 def meth(self) -> int:
1910 ...
1911
1912 Such classes are primarily used with static type checkers that recognize
1913 structural subtyping (static duck-typing).
1914
1915 For example::
1916
1917 class C:
1918 def meth(self) -> int:
1919 return 0
1920
1921 def func(x: Proto) -> int:
1922 return x.meth()
1923
1924 func(C()) # Passes static type check
1925
1926 See PEP 544 for details. Protocol classes decorated with
1927 @typing.runtime_checkable act as simple-minded runtime protocols that check
1928 only the presence of given attributes, ignoring their type signatures.
1929 Protocol classes can be generic, they are defined as::
1930
1931 class GenProto[T](Protocol):
1932 def meth(self) -> T:
1933 ...
1934 """
1935
1936 __slots__ = ()
1937 _is_protocol = True
1938 _is_runtime_protocol = False
1939
1940 def __init_subclass__(cls, *args, **kwargs):
1941 super().__init_subclass__(*args, **kwargs)
1942
1943 # Determine if this is a protocol or a concrete subclass.
1944 if not cls.__dict__.get('_is_protocol', False):
1945 cls._is_protocol = any(b is Protocol for b in cls.__bases__)
1946
1947 # Set (or override) the protocol subclass hook.
1948 if '__subclasshook__' not in cls.__dict__:
1949 cls.__subclasshook__ = _proto_hook
1950
1951 # Prohibit instantiation for protocol classes
1952 if cls._is_protocol and cls.__init__ is Protocol.__init__:
1953 cls.__init__ = _no_init_or_replace_init
1954
1955
1956 class ESC[4;38;5;81m_AnnotatedAlias(ESC[4;38;5;149m_NotIterable, ESC[4;38;5;149m_GenericAlias, _root=ESC[4;38;5;149mTrue):
1957 """Runtime representation of an annotated type.
1958
1959 At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
1960 with extra annotations. The alias behaves like a normal typing alias.
1961 Instantiating is the same as instantiating the underlying type; binding
1962 it to types is also the same.
1963
1964 The metadata itself is stored in a '__metadata__' attribute as a tuple.
1965 """
1966
1967 def __init__(self, origin, metadata):
1968 if isinstance(origin, _AnnotatedAlias):
1969 metadata = origin.__metadata__ + metadata
1970 origin = origin.__origin__
1971 super().__init__(origin, origin, name='Annotated')
1972 self.__metadata__ = metadata
1973
1974 def copy_with(self, params):
1975 assert len(params) == 1
1976 new_type = params[0]
1977 return _AnnotatedAlias(new_type, self.__metadata__)
1978
1979 def __repr__(self):
1980 return "typing.Annotated[{}, {}]".format(
1981 _type_repr(self.__origin__),
1982 ", ".join(repr(a) for a in self.__metadata__)
1983 )
1984
1985 def __reduce__(self):
1986 return operator.getitem, (
1987 Annotated, (self.__origin__,) + self.__metadata__
1988 )
1989
1990 def __eq__(self, other):
1991 if not isinstance(other, _AnnotatedAlias):
1992 return NotImplemented
1993 return (self.__origin__ == other.__origin__
1994 and self.__metadata__ == other.__metadata__)
1995
1996 def __hash__(self):
1997 return hash((self.__origin__, self.__metadata__))
1998
1999 def __getattr__(self, attr):
2000 if attr in {'__name__', '__qualname__'}:
2001 return 'Annotated'
2002 return super().__getattr__(attr)
2003
2004 def __mro_entries__(self, bases):
2005 return (self.__origin__,)
2006
2007
2008 class ESC[4;38;5;81mAnnotated:
2009 """Add context-specific metadata to a type.
2010
2011 Example: Annotated[int, runtime_check.Unsigned] indicates to the
2012 hypothetical runtime_check module that this type is an unsigned int.
2013 Every other consumer of this type can ignore this metadata and treat
2014 this type as int.
2015
2016 The first argument to Annotated must be a valid type.
2017
2018 Details:
2019
2020 - It's an error to call `Annotated` with less than two arguments.
2021 - Access the metadata via the ``__metadata__`` attribute::
2022
2023 assert Annotated[int, '$'].__metadata__ == ('$',)
2024
2025 - Nested Annotated types are flattened::
2026
2027 assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
2028
2029 - Instantiating an annotated type is equivalent to instantiating the
2030 underlying type::
2031
2032 assert Annotated[C, Ann1](5) == C(5)
2033
2034 - Annotated can be used as a generic type alias::
2035
2036 type Optimized[T] = Annotated[T, runtime.Optimize()]
2037 # type checker will treat Optimized[int]
2038 # as equivalent to Annotated[int, runtime.Optimize()]
2039
2040 type OptimizedList[T] = Annotated[list[T], runtime.Optimize()]
2041 # type checker will treat OptimizedList[int]
2042 # as equivalent to Annotated[list[int], runtime.Optimize()]
2043
2044 - Annotated cannot be used with an unpacked TypeVarTuple::
2045
2046 type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid
2047
2048 This would be equivalent to::
2049
2050 Annotated[T1, T2, T3, ..., Ann1]
2051
2052 where T1, T2 etc. are TypeVars, which would be invalid, because
2053 only one type should be passed to Annotated.
2054 """
2055
2056 __slots__ = ()
2057
2058 def __new__(cls, *args, **kwargs):
2059 raise TypeError("Type Annotated cannot be instantiated.")
2060
2061 @_tp_cache
2062 def __class_getitem__(cls, params):
2063 if not isinstance(params, tuple) or len(params) < 2:
2064 raise TypeError("Annotated[...] should be used "
2065 "with at least two arguments (a type and an "
2066 "annotation).")
2067 if _is_unpacked_typevartuple(params[0]):
2068 raise TypeError("Annotated[...] should not be used with an "
2069 "unpacked TypeVarTuple")
2070 msg = "Annotated[t, ...]: t must be a type."
2071 origin = _type_check(params[0], msg, allow_special_forms=True)
2072 metadata = tuple(params[1:])
2073 return _AnnotatedAlias(origin, metadata)
2074
2075 def __init_subclass__(cls, *args, **kwargs):
2076 raise TypeError(
2077 "Cannot subclass {}.Annotated".format(cls.__module__)
2078 )
2079
2080
2081 def runtime_checkable(cls):
2082 """Mark a protocol class as a runtime protocol.
2083
2084 Such protocol can be used with isinstance() and issubclass().
2085 Raise TypeError if applied to a non-protocol class.
2086 This allows a simple-minded structural check very similar to
2087 one trick ponies in collections.abc such as Iterable.
2088
2089 For example::
2090
2091 @runtime_checkable
2092 class Closable(Protocol):
2093 def close(self): ...
2094
2095 assert isinstance(open('/some/file'), Closable)
2096
2097 Warning: this will check only the presence of the required methods,
2098 not their type signatures!
2099 """
2100 if not issubclass(cls, Generic) or not getattr(cls, '_is_protocol', False):
2101 raise TypeError('@runtime_checkable can be only applied to protocol classes,'
2102 ' got %r' % cls)
2103 cls._is_runtime_protocol = True
2104 return cls
2105
2106
2107 def cast(typ, val):
2108 """Cast a value to a type.
2109
2110 This returns the value unchanged. To the type checker this
2111 signals that the return value has the designated type, but at
2112 runtime we intentionally don't check anything (we want this
2113 to be as fast as possible).
2114 """
2115 return val
2116
2117
2118 def assert_type(val, typ, /):
2119 """Ask a static type checker to confirm that the value is of the given type.
2120
2121 At runtime this does nothing: it returns the first argument unchanged with no
2122 checks or side effects, no matter the actual type of the argument.
2123
2124 When a static type checker encounters a call to assert_type(), it
2125 emits an error if the value is not of the specified type::
2126
2127 def greet(name: str) -> None:
2128 assert_type(name, str) # OK
2129 assert_type(name, int) # type checker error
2130 """
2131 return val
2132
2133
2134 _allowed_types = (types.FunctionType, types.BuiltinFunctionType,
2135 types.MethodType, types.ModuleType,
2136 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
2137
2138
2139 def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
2140 """Return type hints for an object.
2141
2142 This is often the same as obj.__annotations__, but it handles
2143 forward references encoded as string literals and recursively replaces all
2144 'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
2145
2146 The argument may be a module, class, method, or function. The annotations
2147 are returned as a dictionary. For classes, annotations include also
2148 inherited members.
2149
2150 TypeError is raised if the argument is not of a type that can contain
2151 annotations, and an empty dictionary is returned if no annotations are
2152 present.
2153
2154 BEWARE -- the behavior of globalns and localns is counterintuitive
2155 (unless you are familiar with how eval() and exec() work). The
2156 search order is locals first, then globals.
2157
2158 - If no dict arguments are passed, an attempt is made to use the
2159 globals from obj (or the respective module's globals for classes),
2160 and these are also used as the locals. If the object does not appear
2161 to have globals, an empty dictionary is used. For classes, the search
2162 order is globals first then locals.
2163
2164 - If one dict argument is passed, it is used for both globals and
2165 locals.
2166
2167 - If two dict arguments are passed, they specify globals and
2168 locals, respectively.
2169 """
2170 if getattr(obj, '__no_type_check__', None):
2171 return {}
2172 # Classes require a special treatment.
2173 if isinstance(obj, type):
2174 hints = {}
2175 for base in reversed(obj.__mro__):
2176 if globalns is None:
2177 base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {})
2178 else:
2179 base_globals = globalns
2180 ann = base.__dict__.get('__annotations__', {})
2181 if isinstance(ann, types.GetSetDescriptorType):
2182 ann = {}
2183 base_locals = dict(vars(base)) if localns is None else localns
2184 if localns is None and globalns is None:
2185 # This is surprising, but required. Before Python 3.10,
2186 # get_type_hints only evaluated the globalns of
2187 # a class. To maintain backwards compatibility, we reverse
2188 # the globalns and localns order so that eval() looks into
2189 # *base_globals* first rather than *base_locals*.
2190 # This only affects ForwardRefs.
2191 base_globals, base_locals = base_locals, base_globals
2192 for name, value in ann.items():
2193 if value is None:
2194 value = type(None)
2195 if isinstance(value, str):
2196 value = ForwardRef(value, is_argument=False, is_class=True)
2197 value = _eval_type(value, base_globals, base_locals)
2198 hints[name] = value
2199 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
2200
2201 if globalns is None:
2202 if isinstance(obj, types.ModuleType):
2203 globalns = obj.__dict__
2204 else:
2205 nsobj = obj
2206 # Find globalns for the unwrapped object.
2207 while hasattr(nsobj, '__wrapped__'):
2208 nsobj = nsobj.__wrapped__
2209 globalns = getattr(nsobj, '__globals__', {})
2210 if localns is None:
2211 localns = globalns
2212 elif localns is None:
2213 localns = globalns
2214 hints = getattr(obj, '__annotations__', None)
2215 if hints is None:
2216 # Return empty annotations for something that _could_ have them.
2217 if isinstance(obj, _allowed_types):
2218 return {}
2219 else:
2220 raise TypeError('{!r} is not a module, class, method, '
2221 'or function.'.format(obj))
2222 hints = dict(hints)
2223 for name, value in hints.items():
2224 if value is None:
2225 value = type(None)
2226 if isinstance(value, str):
2227 # class-level forward refs were handled above, this must be either
2228 # a module-level annotation or a function argument annotation
2229 value = ForwardRef(
2230 value,
2231 is_argument=not isinstance(obj, types.ModuleType),
2232 is_class=False,
2233 )
2234 hints[name] = _eval_type(value, globalns, localns)
2235 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
2236
2237
2238 def _strip_annotations(t):
2239 """Strip the annotations from a given type."""
2240 if isinstance(t, _AnnotatedAlias):
2241 return _strip_annotations(t.__origin__)
2242 if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired):
2243 return _strip_annotations(t.__args__[0])
2244 if isinstance(t, _GenericAlias):
2245 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
2246 if stripped_args == t.__args__:
2247 return t
2248 return t.copy_with(stripped_args)
2249 if isinstance(t, GenericAlias):
2250 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
2251 if stripped_args == t.__args__:
2252 return t
2253 return GenericAlias(t.__origin__, stripped_args)
2254 if isinstance(t, types.UnionType):
2255 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
2256 if stripped_args == t.__args__:
2257 return t
2258 return functools.reduce(operator.or_, stripped_args)
2259
2260 return t
2261
2262
2263 def get_origin(tp):
2264 """Get the unsubscripted version of a type.
2265
2266 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar,
2267 Annotated, and others. Return None for unsupported types.
2268
2269 Examples::
2270
2271 assert get_origin(Literal[42]) is Literal
2272 assert get_origin(int) is None
2273 assert get_origin(ClassVar[int]) is ClassVar
2274 assert get_origin(Generic) is Generic
2275 assert get_origin(Generic[T]) is Generic
2276 assert get_origin(Union[T, int]) is Union
2277 assert get_origin(List[Tuple[T, T]][int]) is list
2278 assert get_origin(P.args) is P
2279 """
2280 if isinstance(tp, _AnnotatedAlias):
2281 return Annotated
2282 if isinstance(tp, (_BaseGenericAlias, GenericAlias,
2283 ParamSpecArgs, ParamSpecKwargs)):
2284 return tp.__origin__
2285 if tp is Generic:
2286 return Generic
2287 if isinstance(tp, types.UnionType):
2288 return types.UnionType
2289 return None
2290
2291
2292 def get_args(tp):
2293 """Get type arguments with all substitutions performed.
2294
2295 For unions, basic simplifications used by Union constructor are performed.
2296
2297 Examples::
2298
2299 assert get_args(Dict[str, int]) == (str, int)
2300 assert get_args(int) == ()
2301 assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
2302 assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
2303 assert get_args(Callable[[], T][int]) == ([], int)
2304 """
2305 if isinstance(tp, _AnnotatedAlias):
2306 return (tp.__origin__,) + tp.__metadata__
2307 if isinstance(tp, (_GenericAlias, GenericAlias)):
2308 res = tp.__args__
2309 if _should_unflatten_callable_args(tp, res):
2310 res = (list(res[:-1]), res[-1])
2311 return res
2312 if isinstance(tp, types.UnionType):
2313 return tp.__args__
2314 return ()
2315
2316
2317 def is_typeddict(tp):
2318 """Check if an annotation is a TypedDict class.
2319
2320 For example::
2321
2322 class Film(TypedDict):
2323 title: str
2324 year: int
2325
2326 is_typeddict(Film) # => True
2327 is_typeddict(Union[list, str]) # => False
2328 """
2329 return isinstance(tp, _TypedDictMeta)
2330
2331
2332 _ASSERT_NEVER_REPR_MAX_LENGTH = 100
2333
2334
2335 def assert_never(arg: Never, /) -> Never:
2336 """Statically assert that a line of code is unreachable.
2337
2338 Example::
2339
2340 def int_or_str(arg: int | str) -> None:
2341 match arg:
2342 case int():
2343 print("It's an int")
2344 case str():
2345 print("It's a str")
2346 case _:
2347 assert_never(arg)
2348
2349 If a type checker finds that a call to assert_never() is
2350 reachable, it will emit an error.
2351
2352 At runtime, this throws an exception when called.
2353 """
2354 value = repr(arg)
2355 if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
2356 value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...'
2357 raise AssertionError(f"Expected code to be unreachable, but got: {value}")
2358
2359
2360 def no_type_check(arg):
2361 """Decorator to indicate that annotations are not type hints.
2362
2363 The argument must be a class or function; if it is a class, it
2364 applies recursively to all methods and classes defined in that class
2365 (but not to methods defined in its superclasses or subclasses).
2366
2367 This mutates the function(s) or class(es) in place.
2368 """
2369 if isinstance(arg, type):
2370 for key in dir(arg):
2371 obj = getattr(arg, key)
2372 if (
2373 not hasattr(obj, '__qualname__')
2374 or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}'
2375 or getattr(obj, '__module__', None) != arg.__module__
2376 ):
2377 # We only modify objects that are defined in this type directly.
2378 # If classes / methods are nested in multiple layers,
2379 # we will modify them when processing their direct holders.
2380 continue
2381 # Instance, class, and static methods:
2382 if isinstance(obj, types.FunctionType):
2383 obj.__no_type_check__ = True
2384 if isinstance(obj, types.MethodType):
2385 obj.__func__.__no_type_check__ = True
2386 # Nested types:
2387 if isinstance(obj, type):
2388 no_type_check(obj)
2389 try:
2390 arg.__no_type_check__ = True
2391 except TypeError: # built-in classes
2392 pass
2393 return arg
2394
2395
2396 def no_type_check_decorator(decorator):
2397 """Decorator to give another decorator the @no_type_check effect.
2398
2399 This wraps the decorator with something that wraps the decorated
2400 function in @no_type_check.
2401 """
2402 @functools.wraps(decorator)
2403 def wrapped_decorator(*args, **kwds):
2404 func = decorator(*args, **kwds)
2405 func = no_type_check(func)
2406 return func
2407
2408 return wrapped_decorator
2409
2410
2411 def _overload_dummy(*args, **kwds):
2412 """Helper for @overload to raise when called."""
2413 raise NotImplementedError(
2414 "You should not call an overloaded function. "
2415 "A series of @overload-decorated functions "
2416 "outside a stub module should always be followed "
2417 "by an implementation that is not @overload-ed.")
2418
2419
2420 # {module: {qualname: {firstlineno: func}}}
2421 _overload_registry = defaultdict(functools.partial(defaultdict, dict))
2422
2423
2424 def overload(func):
2425 """Decorator for overloaded functions/methods.
2426
2427 In a stub file, place two or more stub definitions for the same
2428 function in a row, each decorated with @overload.
2429
2430 For example::
2431
2432 @overload
2433 def utf8(value: None) -> None: ...
2434 @overload
2435 def utf8(value: bytes) -> bytes: ...
2436 @overload
2437 def utf8(value: str) -> bytes: ...
2438
2439 In a non-stub file (i.e. a regular .py file), do the same but
2440 follow it with an implementation. The implementation should *not*
2441 be decorated with @overload::
2442
2443 @overload
2444 def utf8(value: None) -> None: ...
2445 @overload
2446 def utf8(value: bytes) -> bytes: ...
2447 @overload
2448 def utf8(value: str) -> bytes: ...
2449 def utf8(value):
2450 ... # implementation goes here
2451
2452 The overloads for a function can be retrieved at runtime using the
2453 get_overloads() function.
2454 """
2455 # classmethod and staticmethod
2456 f = getattr(func, "__func__", func)
2457 try:
2458 _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func
2459 except AttributeError:
2460 # Not a normal function; ignore.
2461 pass
2462 return _overload_dummy
2463
2464
2465 def get_overloads(func):
2466 """Return all defined overloads for *func* as a sequence."""
2467 # classmethod and staticmethod
2468 f = getattr(func, "__func__", func)
2469 if f.__module__ not in _overload_registry:
2470 return []
2471 mod_dict = _overload_registry[f.__module__]
2472 if f.__qualname__ not in mod_dict:
2473 return []
2474 return list(mod_dict[f.__qualname__].values())
2475
2476
2477 def clear_overloads():
2478 """Clear all overloads in the registry."""
2479 _overload_registry.clear()
2480
2481
2482 def final(f):
2483 """Decorator to indicate final methods and final classes.
2484
2485 Use this decorator to indicate to type checkers that the decorated
2486 method cannot be overridden, and decorated class cannot be subclassed.
2487
2488 For example::
2489
2490 class Base:
2491 @final
2492 def done(self) -> None:
2493 ...
2494 class Sub(Base):
2495 def done(self) -> None: # Error reported by type checker
2496 ...
2497
2498 @final
2499 class Leaf:
2500 ...
2501 class Other(Leaf): # Error reported by type checker
2502 ...
2503
2504 There is no runtime checking of these properties. The decorator
2505 attempts to set the ``__final__`` attribute to ``True`` on the decorated
2506 object to allow runtime introspection.
2507 """
2508 try:
2509 f.__final__ = True
2510 except (AttributeError, TypeError):
2511 # Skip the attribute silently if it is not writable.
2512 # AttributeError happens if the object has __slots__ or a
2513 # read-only property, TypeError if it's a builtin class.
2514 pass
2515 return f
2516
2517
2518 # Some unconstrained type variables. These were initially used by the container types.
2519 # They were never meant for export and are now unused, but we keep them around to
2520 # avoid breaking compatibility with users who import them.
2521 T = TypeVar('T') # Any type.
2522 KT = TypeVar('KT') # Key type.
2523 VT = TypeVar('VT') # Value type.
2524 T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
2525 V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
2526 VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
2527 T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant.
2528 # Internal type variable used for Type[].
2529 CT_co = TypeVar('CT_co', covariant=True, bound=type)
2530
2531
2532 # A useful type variable with constraints. This represents string types.
2533 # (This one *is* for export!)
2534 AnyStr = TypeVar('AnyStr', bytes, str)
2535
2536
2537 # Various ABCs mimicking those in collections.abc.
2538 _alias = _SpecialGenericAlias
2539
2540 Hashable = _alias(collections.abc.Hashable, 0) # Not generic.
2541 Awaitable = _alias(collections.abc.Awaitable, 1)
2542 Coroutine = _alias(collections.abc.Coroutine, 3)
2543 AsyncIterable = _alias(collections.abc.AsyncIterable, 1)
2544 AsyncIterator = _alias(collections.abc.AsyncIterator, 1)
2545 Iterable = _alias(collections.abc.Iterable, 1)
2546 Iterator = _alias(collections.abc.Iterator, 1)
2547 Reversible = _alias(collections.abc.Reversible, 1)
2548 Sized = _alias(collections.abc.Sized, 0) # Not generic.
2549 Container = _alias(collections.abc.Container, 1)
2550 Collection = _alias(collections.abc.Collection, 1)
2551 Callable = _CallableType(collections.abc.Callable, 2)
2552 Callable.__doc__ = \
2553 """Deprecated alias to collections.abc.Callable.
2554
2555 Callable[[int], str] signifies a function that takes a single
2556 parameter of type int and returns a str.
2557
2558 The subscription syntax must always be used with exactly two
2559 values: the argument list and the return type.
2560 The argument list must be a list of types, a ParamSpec,
2561 Concatenate or ellipsis. The return type must be a single type.
2562
2563 There is no syntax to indicate optional or keyword arguments;
2564 such function types are rarely used as callback types.
2565 """
2566 AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet')
2567 MutableSet = _alias(collections.abc.MutableSet, 1)
2568 # NOTE: Mapping is only covariant in the value type.
2569 Mapping = _alias(collections.abc.Mapping, 2)
2570 MutableMapping = _alias(collections.abc.MutableMapping, 2)
2571 Sequence = _alias(collections.abc.Sequence, 1)
2572 MutableSequence = _alias(collections.abc.MutableSequence, 1)
2573 ByteString = _DeprecatedGenericAlias(
2574 collections.abc.ByteString, 0, removal_version=(3, 14) # Not generic.
2575 )
2576 # Tuple accepts variable number of parameters.
2577 Tuple = _TupleType(tuple, -1, inst=False, name='Tuple')
2578 Tuple.__doc__ = \
2579 """Deprecated alias to builtins.tuple.
2580
2581 Tuple[X, Y] is the cross-product type of X and Y.
2582
2583 Example: Tuple[T1, T2] is a tuple of two elements corresponding
2584 to type variables T1 and T2. Tuple[int, float, str] is a tuple
2585 of an int, a float and a string.
2586
2587 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
2588 """
2589 List = _alias(list, 1, inst=False, name='List')
2590 Deque = _alias(collections.deque, 1, name='Deque')
2591 Set = _alias(set, 1, inst=False, name='Set')
2592 FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet')
2593 MappingView = _alias(collections.abc.MappingView, 1)
2594 KeysView = _alias(collections.abc.KeysView, 1)
2595 ItemsView = _alias(collections.abc.ItemsView, 2)
2596 ValuesView = _alias(collections.abc.ValuesView, 1)
2597 ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager')
2598 AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager')
2599 Dict = _alias(dict, 2, inst=False, name='Dict')
2600 DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict')
2601 OrderedDict = _alias(collections.OrderedDict, 2)
2602 Counter = _alias(collections.Counter, 1)
2603 ChainMap = _alias(collections.ChainMap, 2)
2604 Generator = _alias(collections.abc.Generator, 3)
2605 AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2)
2606 Type = _alias(type, 1, inst=False, name='Type')
2607 Type.__doc__ = \
2608 """Deprecated alias to builtins.type.
2609
2610 builtins.type or typing.Type can be used to annotate class objects.
2611 For example, suppose we have the following classes::
2612
2613 class User: ... # Abstract base for User classes
2614 class BasicUser(User): ...
2615 class ProUser(User): ...
2616 class TeamUser(User): ...
2617
2618 And a function that takes a class argument that's a subclass of
2619 User and returns an instance of the corresponding class::
2620
2621 def new_user[U](user_class: Type[U]) -> U:
2622 user = user_class()
2623 # (Here we could write the user object to a database)
2624 return user
2625
2626 joe = new_user(BasicUser)
2627
2628 At this point the type checker knows that joe has type BasicUser.
2629 """
2630
2631
2632 @runtime_checkable
2633 class ESC[4;38;5;81mSupportsInt(ESC[4;38;5;149mProtocol):
2634 """An ABC with one abstract method __int__."""
2635
2636 __slots__ = ()
2637
2638 @abstractmethod
2639 def __int__(self) -> int:
2640 pass
2641
2642
2643 @runtime_checkable
2644 class ESC[4;38;5;81mSupportsFloat(ESC[4;38;5;149mProtocol):
2645 """An ABC with one abstract method __float__."""
2646
2647 __slots__ = ()
2648
2649 @abstractmethod
2650 def __float__(self) -> float:
2651 pass
2652
2653
2654 @runtime_checkable
2655 class ESC[4;38;5;81mSupportsComplex(ESC[4;38;5;149mProtocol):
2656 """An ABC with one abstract method __complex__."""
2657
2658 __slots__ = ()
2659
2660 @abstractmethod
2661 def __complex__(self) -> complex:
2662 pass
2663
2664
2665 @runtime_checkable
2666 class ESC[4;38;5;81mSupportsBytes(ESC[4;38;5;149mProtocol):
2667 """An ABC with one abstract method __bytes__."""
2668
2669 __slots__ = ()
2670
2671 @abstractmethod
2672 def __bytes__(self) -> bytes:
2673 pass
2674
2675
2676 @runtime_checkable
2677 class ESC[4;38;5;81mSupportsIndex(ESC[4;38;5;149mProtocol):
2678 """An ABC with one abstract method __index__."""
2679
2680 __slots__ = ()
2681
2682 @abstractmethod
2683 def __index__(self) -> int:
2684 pass
2685
2686
2687 @runtime_checkable
2688 class ESC[4;38;5;81mSupportsAbs[ESC[4;38;5;81mT](ESC[4;38;5;149mProtocol):
2689 """An ABC with one abstract method __abs__ that is covariant in its return type."""
2690
2691 __slots__ = ()
2692
2693 @abstractmethod
2694 def __abs__(self) -> T:
2695 pass
2696
2697
2698 @runtime_checkable
2699 class ESC[4;38;5;81mSupportsRound[ESC[4;38;5;81mT](ESC[4;38;5;149mProtocol):
2700 """An ABC with one abstract method __round__ that is covariant in its return type."""
2701
2702 __slots__ = ()
2703
2704 @abstractmethod
2705 def __round__(self, ndigits: int = 0) -> T:
2706 pass
2707
2708
2709 def _make_nmtuple(name, types, module, defaults = ()):
2710 fields = [n for n, t in types]
2711 types = {n: _type_check(t, f"field {n} annotation must be a type")
2712 for n, t in types}
2713 nm_tpl = collections.namedtuple(name, fields,
2714 defaults=defaults, module=module)
2715 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types
2716 return nm_tpl
2717
2718
2719 # attributes prohibited to set in NamedTuple class syntax
2720 _prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__',
2721 '_fields', '_field_defaults',
2722 '_make', '_replace', '_asdict', '_source'})
2723
2724 _special = frozenset({'__module__', '__name__', '__annotations__'})
2725
2726
2727 class ESC[4;38;5;81mNamedTupleMeta(ESC[4;38;5;149mtype):
2728 def __new__(cls, typename, bases, ns):
2729 assert _NamedTuple in bases
2730 for base in bases:
2731 if base is not _NamedTuple and base is not Generic:
2732 raise TypeError(
2733 'can only inherit from a NamedTuple type and Generic')
2734 bases = tuple(tuple if base is _NamedTuple else base for base in bases)
2735 types = ns.get('__annotations__', {})
2736 default_names = []
2737 for field_name in types:
2738 if field_name in ns:
2739 default_names.append(field_name)
2740 elif default_names:
2741 raise TypeError(f"Non-default namedtuple field {field_name} "
2742 f"cannot follow default field"
2743 f"{'s' if len(default_names) > 1 else ''} "
2744 f"{', '.join(default_names)}")
2745 nm_tpl = _make_nmtuple(typename, types.items(),
2746 defaults=[ns[n] for n in default_names],
2747 module=ns['__module__'])
2748 nm_tpl.__bases__ = bases
2749 if Generic in bases:
2750 class_getitem = _generic_class_getitem
2751 nm_tpl.__class_getitem__ = classmethod(class_getitem)
2752 # update from user namespace without overriding special namedtuple attributes
2753 for key in ns:
2754 if key in _prohibited:
2755 raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
2756 elif key not in _special and key not in nm_tpl._fields:
2757 setattr(nm_tpl, key, ns[key])
2758 if Generic in bases:
2759 nm_tpl.__init_subclass__()
2760 return nm_tpl
2761
2762
2763 def NamedTuple(typename, fields=None, /, **kwargs):
2764 """Typed version of namedtuple.
2765
2766 Usage::
2767
2768 class Employee(NamedTuple):
2769 name: str
2770 id: int
2771
2772 This is equivalent to::
2773
2774 Employee = collections.namedtuple('Employee', ['name', 'id'])
2775
2776 The resulting class has an extra __annotations__ attribute, giving a
2777 dict that maps field names to types. (The field names are also in
2778 the _fields attribute, which is part of the namedtuple API.)
2779 An alternative equivalent functional syntax is also accepted::
2780
2781 Employee = NamedTuple('Employee', [('name', str), ('id', int)])
2782 """
2783 if fields is None:
2784 fields = kwargs.items()
2785 elif kwargs:
2786 raise TypeError("Either list of fields or keywords"
2787 " can be provided to NamedTuple, not both")
2788 nt = _make_nmtuple(typename, fields, module=_caller())
2789 nt.__orig_bases__ = (NamedTuple,)
2790 return nt
2791
2792 _NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {})
2793
2794 def _namedtuple_mro_entries(bases):
2795 assert NamedTuple in bases
2796 return (_NamedTuple,)
2797
2798 NamedTuple.__mro_entries__ = _namedtuple_mro_entries
2799
2800
2801 class ESC[4;38;5;81m_TypedDictMeta(ESC[4;38;5;149mtype):
2802 def __new__(cls, name, bases, ns, total=True):
2803 """Create a new typed dict class object.
2804
2805 This method is called when TypedDict is subclassed,
2806 or when TypedDict is instantiated. This way
2807 TypedDict supports all three syntax forms described in its docstring.
2808 Subclasses and instances of TypedDict return actual dictionaries.
2809 """
2810 for base in bases:
2811 if type(base) is not _TypedDictMeta and base is not Generic:
2812 raise TypeError('cannot inherit from both a TypedDict type '
2813 'and a non-TypedDict base class')
2814
2815 if any(issubclass(b, Generic) for b in bases):
2816 generic_base = (Generic,)
2817 else:
2818 generic_base = ()
2819
2820 tp_dict = type.__new__(_TypedDictMeta, name, (*generic_base, dict), ns)
2821
2822 if not hasattr(tp_dict, '__orig_bases__'):
2823 tp_dict.__orig_bases__ = bases
2824
2825 annotations = {}
2826 own_annotations = ns.get('__annotations__', {})
2827 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
2828 own_annotations = {
2829 n: _type_check(tp, msg, module=tp_dict.__module__)
2830 for n, tp in own_annotations.items()
2831 }
2832 required_keys = set()
2833 optional_keys = set()
2834
2835 for base in bases:
2836 annotations.update(base.__dict__.get('__annotations__', {}))
2837 required_keys.update(base.__dict__.get('__required_keys__', ()))
2838 optional_keys.update(base.__dict__.get('__optional_keys__', ()))
2839
2840 annotations.update(own_annotations)
2841 for annotation_key, annotation_type in own_annotations.items():
2842 annotation_origin = get_origin(annotation_type)
2843 if annotation_origin is Annotated:
2844 annotation_args = get_args(annotation_type)
2845 if annotation_args:
2846 annotation_type = annotation_args[0]
2847 annotation_origin = get_origin(annotation_type)
2848
2849 if annotation_origin is Required:
2850 required_keys.add(annotation_key)
2851 elif annotation_origin is NotRequired:
2852 optional_keys.add(annotation_key)
2853 elif total:
2854 required_keys.add(annotation_key)
2855 else:
2856 optional_keys.add(annotation_key)
2857
2858 tp_dict.__annotations__ = annotations
2859 tp_dict.__required_keys__ = frozenset(required_keys)
2860 tp_dict.__optional_keys__ = frozenset(optional_keys)
2861 if not hasattr(tp_dict, '__total__'):
2862 tp_dict.__total__ = total
2863 return tp_dict
2864
2865 __call__ = dict # static method
2866
2867 def __subclasscheck__(cls, other):
2868 # Typed dicts are only for static structural subtyping.
2869 raise TypeError('TypedDict does not support instance and class checks')
2870
2871 __instancecheck__ = __subclasscheck__
2872
2873
2874 def TypedDict(typename, fields=None, /, *, total=True, **kwargs):
2875 """A simple typed namespace. At runtime it is equivalent to a plain dict.
2876
2877 TypedDict creates a dictionary type such that a type checker will expect all
2878 instances to have a certain set of keys, where each key is
2879 associated with a value of a consistent type. This expectation
2880 is not checked at runtime.
2881
2882 Usage::
2883
2884 class Point2D(TypedDict):
2885 x: int
2886 y: int
2887 label: str
2888
2889 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
2890 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
2891
2892 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
2893
2894 The type info can be accessed via the Point2D.__annotations__ dict, and
2895 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
2896 TypedDict supports an additional equivalent form::
2897
2898 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
2899
2900 By default, all keys must be present in a TypedDict. It is possible
2901 to override this by specifying totality::
2902
2903 class Point2D(TypedDict, total=False):
2904 x: int
2905 y: int
2906
2907 This means that a Point2D TypedDict can have any of the keys omitted. A type
2908 checker is only expected to support a literal False or True as the value of
2909 the total argument. True is the default, and makes all items defined in the
2910 class body be required.
2911
2912 The Required and NotRequired special forms can also be used to mark
2913 individual keys as being required or not required::
2914
2915 class Point2D(TypedDict):
2916 x: int # the "x" key must always be present (Required is the default)
2917 y: NotRequired[int] # the "y" key can be omitted
2918
2919 See PEP 655 for more details on Required and NotRequired.
2920 """
2921 if fields is None:
2922 fields = kwargs
2923 elif kwargs:
2924 raise TypeError("TypedDict takes either a dict or keyword arguments,"
2925 " but not both")
2926 if kwargs:
2927 warnings.warn(
2928 "The kwargs-based syntax for TypedDict definitions is deprecated "
2929 "in Python 3.11, will be removed in Python 3.13, and may not be "
2930 "understood by third-party type checkers.",
2931 DeprecationWarning,
2932 stacklevel=2,
2933 )
2934
2935 ns = {'__annotations__': dict(fields)}
2936 module = _caller()
2937 if module is not None:
2938 # Setting correct module is necessary to make typed dict classes pickleable.
2939 ns['__module__'] = module
2940
2941 td = _TypedDictMeta(typename, (), ns, total=total)
2942 td.__orig_bases__ = (TypedDict,)
2943 return td
2944
2945 _TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
2946 TypedDict.__mro_entries__ = lambda bases: (_TypedDict,)
2947
2948
2949 @_SpecialForm
2950 def Required(self, parameters):
2951 """Special typing construct to mark a TypedDict key as required.
2952
2953 This is mainly useful for total=False TypedDicts.
2954
2955 For example::
2956
2957 class Movie(TypedDict, total=False):
2958 title: Required[str]
2959 year: int
2960
2961 m = Movie(
2962 title='The Matrix', # typechecker error if key is omitted
2963 year=1999,
2964 )
2965
2966 There is no runtime checking that a required key is actually provided
2967 when instantiating a related TypedDict.
2968 """
2969 item = _type_check(parameters, f'{self._name} accepts only a single type.')
2970 return _GenericAlias(self, (item,))
2971
2972
2973 @_SpecialForm
2974 def NotRequired(self, parameters):
2975 """Special typing construct to mark a TypedDict key as potentially missing.
2976
2977 For example::
2978
2979 class Movie(TypedDict):
2980 title: str
2981 year: NotRequired[int]
2982
2983 m = Movie(
2984 title='The Matrix', # typechecker error if key is omitted
2985 year=1999,
2986 )
2987 """
2988 item = _type_check(parameters, f'{self._name} accepts only a single type.')
2989 return _GenericAlias(self, (item,))
2990
2991
2992 class ESC[4;38;5;81mNewType:
2993 """NewType creates simple unique types with almost zero runtime overhead.
2994
2995 NewType(name, tp) is considered a subtype of tp
2996 by static type checkers. At runtime, NewType(name, tp) returns
2997 a dummy callable that simply returns its argument.
2998
2999 Usage::
3000
3001 UserId = NewType('UserId', int)
3002
3003 def name_by_id(user_id: UserId) -> str:
3004 ...
3005
3006 UserId('user') # Fails type check
3007
3008 name_by_id(42) # Fails type check
3009 name_by_id(UserId(42)) # OK
3010
3011 num = UserId(5) + 1 # type: int
3012 """
3013
3014 __call__ = _idfunc
3015
3016 def __init__(self, name, tp):
3017 self.__qualname__ = name
3018 if '.' in name:
3019 name = name.rpartition('.')[-1]
3020 self.__name__ = name
3021 self.__supertype__ = tp
3022 def_mod = _caller()
3023 if def_mod != 'typing':
3024 self.__module__ = def_mod
3025
3026 def __mro_entries__(self, bases):
3027 # We defined __mro_entries__ to get a better error message
3028 # if a user attempts to subclass a NewType instance. bpo-46170
3029 superclass_name = self.__name__
3030
3031 class ESC[4;38;5;81mDummy:
3032 def __init_subclass__(cls):
3033 subclass_name = cls.__name__
3034 raise TypeError(
3035 f"Cannot subclass an instance of NewType. Perhaps you were looking for: "
3036 f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`"
3037 )
3038
3039 return (Dummy,)
3040
3041 def __repr__(self):
3042 return f'{self.__module__}.{self.__qualname__}'
3043
3044 def __reduce__(self):
3045 return self.__qualname__
3046
3047 def __or__(self, other):
3048 return Union[self, other]
3049
3050 def __ror__(self, other):
3051 return Union[other, self]
3052
3053
3054 # Python-version-specific alias (Python 2: unicode; Python 3: str)
3055 Text = str
3056
3057
3058 # Constant that's True when type checking, but False here.
3059 TYPE_CHECKING = False
3060
3061
3062 class ESC[4;38;5;81mIO(ESC[4;38;5;149mGeneric[AnyStr]):
3063 """Generic base class for TextIO and BinaryIO.
3064
3065 This is an abstract, generic version of the return of open().
3066
3067 NOTE: This does not distinguish between the different possible
3068 classes (text vs. binary, read vs. write vs. read/write,
3069 append-only, unbuffered). The TextIO and BinaryIO subclasses
3070 below capture the distinctions between text vs. binary, which is
3071 pervasive in the interface; however we currently do not offer a
3072 way to track the other distinctions in the type system.
3073 """
3074
3075 __slots__ = ()
3076
3077 @property
3078 @abstractmethod
3079 def mode(self) -> str:
3080 pass
3081
3082 @property
3083 @abstractmethod
3084 def name(self) -> str:
3085 pass
3086
3087 @abstractmethod
3088 def close(self) -> None:
3089 pass
3090
3091 @property
3092 @abstractmethod
3093 def closed(self) -> bool:
3094 pass
3095
3096 @abstractmethod
3097 def fileno(self) -> int:
3098 pass
3099
3100 @abstractmethod
3101 def flush(self) -> None:
3102 pass
3103
3104 @abstractmethod
3105 def isatty(self) -> bool:
3106 pass
3107
3108 @abstractmethod
3109 def read(self, n: int = -1) -> AnyStr:
3110 pass
3111
3112 @abstractmethod
3113 def readable(self) -> bool:
3114 pass
3115
3116 @abstractmethod
3117 def readline(self, limit: int = -1) -> AnyStr:
3118 pass
3119
3120 @abstractmethod
3121 def readlines(self, hint: int = -1) -> List[AnyStr]:
3122 pass
3123
3124 @abstractmethod
3125 def seek(self, offset: int, whence: int = 0) -> int:
3126 pass
3127
3128 @abstractmethod
3129 def seekable(self) -> bool:
3130 pass
3131
3132 @abstractmethod
3133 def tell(self) -> int:
3134 pass
3135
3136 @abstractmethod
3137 def truncate(self, size: int = None) -> int:
3138 pass
3139
3140 @abstractmethod
3141 def writable(self) -> bool:
3142 pass
3143
3144 @abstractmethod
3145 def write(self, s: AnyStr) -> int:
3146 pass
3147
3148 @abstractmethod
3149 def writelines(self, lines: List[AnyStr]) -> None:
3150 pass
3151
3152 @abstractmethod
3153 def __enter__(self) -> 'IO[AnyStr]':
3154 pass
3155
3156 @abstractmethod
3157 def __exit__(self, type, value, traceback) -> None:
3158 pass
3159
3160
3161 class ESC[4;38;5;81mBinaryIO(ESC[4;38;5;149mIO[bytes]):
3162 """Typed version of the return of open() in binary mode."""
3163
3164 __slots__ = ()
3165
3166 @abstractmethod
3167 def write(self, s: Union[bytes, bytearray]) -> int:
3168 pass
3169
3170 @abstractmethod
3171 def __enter__(self) -> 'BinaryIO':
3172 pass
3173
3174
3175 class ESC[4;38;5;81mTextIO(ESC[4;38;5;149mIO[str]):
3176 """Typed version of the return of open() in text mode."""
3177
3178 __slots__ = ()
3179
3180 @property
3181 @abstractmethod
3182 def buffer(self) -> BinaryIO:
3183 pass
3184
3185 @property
3186 @abstractmethod
3187 def encoding(self) -> str:
3188 pass
3189
3190 @property
3191 @abstractmethod
3192 def errors(self) -> Optional[str]:
3193 pass
3194
3195 @property
3196 @abstractmethod
3197 def line_buffering(self) -> bool:
3198 pass
3199
3200 @property
3201 @abstractmethod
3202 def newlines(self) -> Any:
3203 pass
3204
3205 @abstractmethod
3206 def __enter__(self) -> 'TextIO':
3207 pass
3208
3209
3210 class ESC[4;38;5;81m_DeprecatedType(ESC[4;38;5;149mtype):
3211 def __getattribute__(cls, name):
3212 if name not in ("__dict__", "__module__") and name in cls.__dict__:
3213 warnings.warn(
3214 f"{cls.__name__} is deprecated, import directly "
3215 f"from typing instead. {cls.__name__} will be removed "
3216 "in Python 3.12.",
3217 DeprecationWarning,
3218 stacklevel=2,
3219 )
3220 return super().__getattribute__(name)
3221
3222
3223 class ESC[4;38;5;81mio(metaclass=ESC[4;38;5;149m_DeprecatedType):
3224 """Wrapper namespace for IO generic classes."""
3225
3226 __all__ = ['IO', 'TextIO', 'BinaryIO']
3227 IO = IO
3228 TextIO = TextIO
3229 BinaryIO = BinaryIO
3230
3231
3232 io.__name__ = __name__ + '.io'
3233 sys.modules[io.__name__] = io
3234
3235 Pattern = _alias(stdlib_re.Pattern, 1)
3236 Match = _alias(stdlib_re.Match, 1)
3237
3238 class ESC[4;38;5;81mre(metaclass=ESC[4;38;5;149m_DeprecatedType):
3239 """Wrapper namespace for re type aliases."""
3240
3241 __all__ = ['Pattern', 'Match']
3242 Pattern = Pattern
3243 Match = Match
3244
3245
3246 re.__name__ = __name__ + '.re'
3247 sys.modules[re.__name__] = re
3248
3249
3250 def reveal_type[T](obj: T, /) -> T:
3251 """Reveal the inferred type of a variable.
3252
3253 When a static type checker encounters a call to ``reveal_type()``,
3254 it will emit the inferred type of the argument::
3255
3256 x: int = 1
3257 reveal_type(x)
3258
3259 Running a static type checker (e.g., mypy) on this example
3260 will produce output similar to 'Revealed type is "builtins.int"'.
3261
3262 At runtime, the function prints the runtime type of the
3263 argument and returns it unchanged.
3264 """
3265 print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr)
3266 return obj
3267
3268
3269 class ESC[4;38;5;81m_IdentityCallable(ESC[4;38;5;149mProtocol):
3270 def __call__[T](self, arg: T, /) -> T:
3271 ...
3272
3273
3274 def dataclass_transform(
3275 *,
3276 eq_default: bool = True,
3277 order_default: bool = False,
3278 kw_only_default: bool = False,
3279 frozen_default: bool = False,
3280 field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (),
3281 **kwargs: Any,
3282 ) -> _IdentityCallable:
3283 """Decorator to mark an object as providing dataclass-like behaviour.
3284
3285 The decorator can be applied to a function, class, or metaclass.
3286
3287 Example usage with a decorator function::
3288
3289 @dataclass_transform()
3290 def create_model[T](cls: type[T]) -> type[T]:
3291 ...
3292 return cls
3293
3294 @create_model
3295 class CustomerModel:
3296 id: int
3297 name: str
3298
3299 On a base class::
3300
3301 @dataclass_transform()
3302 class ModelBase: ...
3303
3304 class CustomerModel(ModelBase):
3305 id: int
3306 name: str
3307
3308 On a metaclass::
3309
3310 @dataclass_transform()
3311 class ModelMeta(type): ...
3312
3313 class ModelBase(metaclass=ModelMeta): ...
3314
3315 class CustomerModel(ModelBase):
3316 id: int
3317 name: str
3318
3319 The ``CustomerModel`` classes defined above will
3320 be treated by type checkers similarly to classes created with
3321 ``@dataclasses.dataclass``.
3322 For example, type checkers will assume these classes have
3323 ``__init__`` methods that accept ``id`` and ``name``.
3324
3325 The arguments to this decorator can be used to customize this behavior:
3326 - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
3327 ``True`` or ``False`` if it is omitted by the caller.
3328 - ``order_default`` indicates whether the ``order`` parameter is
3329 assumed to be True or False if it is omitted by the caller.
3330 - ``kw_only_default`` indicates whether the ``kw_only`` parameter is
3331 assumed to be True or False if it is omitted by the caller.
3332 - ``frozen_default`` indicates whether the ``frozen`` parameter is
3333 assumed to be True or False if it is omitted by the caller.
3334 - ``field_specifiers`` specifies a static list of supported classes
3335 or functions that describe fields, similar to ``dataclasses.field()``.
3336 - Arbitrary other keyword arguments are accepted in order to allow for
3337 possible future extensions.
3338
3339 At runtime, this decorator records its arguments in the
3340 ``__dataclass_transform__`` attribute on the decorated object.
3341 It has no other runtime effect.
3342
3343 See PEP 681 for more details.
3344 """
3345 def decorator(cls_or_fn):
3346 cls_or_fn.__dataclass_transform__ = {
3347 "eq_default": eq_default,
3348 "order_default": order_default,
3349 "kw_only_default": kw_only_default,
3350 "frozen_default": frozen_default,
3351 "field_specifiers": field_specifiers,
3352 "kwargs": kwargs,
3353 }
3354 return cls_or_fn
3355 return decorator
3356
3357
3358 type _Func = Callable[..., Any]
3359
3360
3361 def override[F: _Func](method: F, /) -> F:
3362 """Indicate that a method is intended to override a method in a base class.
3363
3364 Usage::
3365
3366 class Base:
3367 def method(self) -> None: ...
3368 pass
3369
3370 class Child(Base):
3371 @override
3372 def method(self) -> None:
3373 super().method()
3374
3375 When this decorator is applied to a method, the type checker will
3376 validate that it overrides a method or attribute with the same name on a
3377 base class. This helps prevent bugs that may occur when a base class is
3378 changed without an equivalent change to a child class.
3379
3380 There is no runtime checking of this property. The decorator attempts to
3381 set the ``__override__`` attribute to ``True`` on the decorated object to
3382 allow runtime introspection.
3383
3384 See PEP 698 for details.
3385 """
3386 try:
3387 method.__override__ = True
3388 except (AttributeError, TypeError):
3389 # Skip the attribute silently if it is not writable.
3390 # AttributeError happens if the object has __slots__ or a
3391 # read-only property, TypeError if it's a builtin class.
3392 pass
3393 return method
Browse
Usage
Versions