Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/typing_extensions.py: 28%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1import abc
2import builtins
3import collections
4import collections.abc
5import contextlib
6import enum
7import functools
8import inspect
9import io
10import keyword
11import operator
12import sys
13import types as _types
14import typing
15import warnings
17# Breakpoint: https://github.com/python/cpython/pull/119891
18if sys.version_info >= (3, 14):
19 import annotationlib
21__all__ = [
22 # Super-special typing primitives.
23 'Any',
24 'ClassVar',
25 'Concatenate',
26 'Final',
27 'LiteralString',
28 'ParamSpec',
29 'ParamSpecArgs',
30 'ParamSpecKwargs',
31 'Self',
32 'Type',
33 'TypeVar',
34 'TypeVarTuple',
35 'Unpack',
37 # ABCs (from collections.abc).
38 'Awaitable',
39 'AsyncIterator',
40 'AsyncIterable',
41 'Coroutine',
42 'AsyncGenerator',
43 'AsyncContextManager',
44 'Buffer',
45 'ChainMap',
47 # Concrete collection types.
48 'ContextManager',
49 'Counter',
50 'Deque',
51 'DefaultDict',
52 'NamedTuple',
53 'OrderedDict',
54 'TypedDict',
56 # Structural checks, a.k.a. protocols.
57 'SupportsAbs',
58 'SupportsBytes',
59 'SupportsComplex',
60 'SupportsFloat',
61 'SupportsIndex',
62 'SupportsInt',
63 'SupportsRound',
64 'Reader',
65 'Writer',
67 # One-off things.
68 'Annotated',
69 'assert_never',
70 'assert_type',
71 'clear_overloads',
72 'dataclass_transform',
73 'deprecated',
74 'disjoint_base',
75 'Doc',
76 'evaluate_forward_ref',
77 'get_overloads',
78 'final',
79 'Format',
80 'get_annotations',
81 'get_args',
82 'get_origin',
83 'get_original_bases',
84 'get_protocol_members',
85 'get_type_hints',
86 'IntVar',
87 'is_protocol',
88 'is_typeddict',
89 'Literal',
90 'NewType',
91 'overload',
92 'override',
93 'Protocol',
94 'Sentinel',
95 'reveal_type',
96 'runtime',
97 'runtime_checkable',
98 'Text',
99 'TypeAlias',
100 'TypeAliasType',
101 'TypeForm',
102 'TypeGuard',
103 'TypeIs',
104 'TYPE_CHECKING',
105 'type_repr',
106 'Never',
107 'NoReturn',
108 'ReadOnly',
109 'Required',
110 'NotRequired',
111 'NoDefault',
112 'NoExtraItems',
114 # Pure aliases, have always been in typing
115 'AbstractSet',
116 'AnyStr',
117 'BinaryIO',
118 'Callable',
119 'Collection',
120 'Container',
121 'Dict',
122 'ForwardRef',
123 'FrozenSet',
124 'Generator',
125 'Generic',
126 'Hashable',
127 'IO',
128 'ItemsView',
129 'Iterable',
130 'Iterator',
131 'KeysView',
132 'List',
133 'Mapping',
134 'MappingView',
135 'Match',
136 'MutableMapping',
137 'MutableSequence',
138 'MutableSet',
139 'Optional',
140 'Pattern',
141 'Reversible',
142 'Sequence',
143 'Set',
144 'Sized',
145 'TextIO',
146 'Tuple',
147 'Union',
148 'ValuesView',
149 'cast',
150 'no_type_check',
151 'no_type_check_decorator',
152]
154# for backward compatibility
155PEP_560 = True
156GenericMeta = type
157# Breakpoint: https://github.com/python/cpython/pull/116129
158_PEP_696_IMPLEMENTED = sys.version_info >= (3, 13, 0, "beta")
160# Added with bpo-45166 to 3.10.1+ and some 3.9 versions
161_FORWARD_REF_HAS_CLASS = "__forward_is_class__" in typing.ForwardRef.__slots__
163class Sentinel:
164 """Create a unique sentinel object.
166 *name* should be the name of the variable to which the return value shall be assigned.
168 *repr*, if supplied, will be used for the repr of the sentinel object.
169 If not provided, "<name>" will be used.
170 """
172 def __init__(
173 self,
174 name: str,
175 repr: typing.Optional[str] = None,
176 ):
177 self._name = name
178 self._repr = repr if repr is not None else f'<{name}>'
180 def __repr__(self):
181 return self._repr
183 if sys.version_info < (3, 11):
184 # The presence of this method convinces typing._type_check
185 # that Sentinels are types.
186 def __call__(self, *args, **kwargs):
187 raise TypeError(f"{type(self).__name__!r} object is not callable")
189 # Breakpoint: https://github.com/python/cpython/pull/21515
190 if sys.version_info >= (3, 10):
191 def __or__(self, other):
192 return typing.Union[self, other]
194 def __ror__(self, other):
195 return typing.Union[other, self]
197 def __getstate__(self):
198 raise TypeError(f"Cannot pickle {type(self).__name__!r} object")
201_marker = Sentinel("sentinel")
203# The functions below are modified copies of typing internal helpers.
204# They are needed by _ProtocolMeta and they provide support for PEP 646.
206# Breakpoint: https://github.com/python/cpython/pull/27342
207if sys.version_info >= (3, 10):
208 def _should_collect_from_parameters(t):
209 return isinstance(
210 t, (typing._GenericAlias, _types.GenericAlias, _types.UnionType)
211 )
212else:
213 def _should_collect_from_parameters(t):
214 return isinstance(t, (typing._GenericAlias, _types.GenericAlias))
217NoReturn = typing.NoReturn
219# Some unconstrained type variables. These are used by the container types.
220# (These are not for export.)
221T = typing.TypeVar('T') # Any type.
222KT = typing.TypeVar('KT') # Key type.
223VT = typing.TypeVar('VT') # Value type.
224T_co = typing.TypeVar('T_co', covariant=True) # Any type covariant containers.
225T_contra = typing.TypeVar('T_contra', contravariant=True) # Ditto contravariant.
228# Breakpoint: https://github.com/python/cpython/pull/31841
229if sys.version_info >= (3, 11):
230 from typing import Any
231else:
233 class _AnyMeta(type):
234 def __instancecheck__(self, obj):
235 if self is Any:
236 raise TypeError("typing_extensions.Any cannot be used with isinstance()")
237 return super().__instancecheck__(obj)
239 def __repr__(self):
240 if self is Any:
241 return "typing_extensions.Any"
242 return super().__repr__()
244 class Any(metaclass=_AnyMeta):
245 """Special type indicating an unconstrained type.
246 - Any is compatible with every type.
247 - Any assumed to have all methods.
248 - All values assumed to be instances of Any.
249 Note that all the above statements are true from the point of view of
250 static type checkers. At runtime, Any should not be used with instance
251 checks.
252 """
253 def __new__(cls, *args, **kwargs):
254 if cls is Any:
255 raise TypeError("Any cannot be instantiated")
256 return super().__new__(cls, *args, **kwargs)
259ClassVar = typing.ClassVar
261# Vendored from cpython typing._SpecialFrom
262# Having a separate class means that instances will not be rejected by
263# typing._type_check.
264class _SpecialForm(typing._Final, _root=True):
265 __slots__ = ('_name', '__doc__', '_getitem')
267 def __init__(self, getitem):
268 self._getitem = getitem
269 self._name = getitem.__name__
270 self.__doc__ = getitem.__doc__
272 def __getattr__(self, item):
273 if item in {'__name__', '__qualname__'}:
274 return self._name
276 raise AttributeError(item)
278 def __mro_entries__(self, bases):
279 raise TypeError(f"Cannot subclass {self!r}")
281 def __repr__(self):
282 return f'typing_extensions.{self._name}'
284 def __reduce__(self):
285 return self._name
287 def __call__(self, *args, **kwds):
288 raise TypeError(f"Cannot instantiate {self!r}")
290 def __or__(self, other):
291 return typing.Union[self, other]
293 def __ror__(self, other):
294 return typing.Union[other, self]
296 def __instancecheck__(self, obj):
297 raise TypeError(f"{self} cannot be used with isinstance()")
299 def __subclasscheck__(self, cls):
300 raise TypeError(f"{self} cannot be used with issubclass()")
302 @typing._tp_cache
303 def __getitem__(self, parameters):
304 return self._getitem(self, parameters)
307# Note that inheriting from this class means that the object will be
308# rejected by typing._type_check, so do not use it if the special form
309# is arguably valid as a type by itself.
310class _ExtensionsSpecialForm(typing._SpecialForm, _root=True):
311 def __repr__(self):
312 return 'typing_extensions.' + self._name
315Final = typing.Final
317# Breakpoint: https://github.com/python/cpython/pull/30530
318if sys.version_info >= (3, 11):
319 final = typing.final
320else:
321 # @final exists in 3.8+, but we backport it for all versions
322 # before 3.11 to keep support for the __final__ attribute.
323 # See https://bugs.python.org/issue46342
324 def final(f):
325 """This decorator can be used to indicate to type checkers that
326 the decorated method cannot be overridden, and decorated class
327 cannot be subclassed. For example:
329 class Base:
330 @final
331 def done(self) -> None:
332 ...
333 class Sub(Base):
334 def done(self) -> None: # Error reported by type checker
335 ...
336 @final
337 class Leaf:
338 ...
339 class Other(Leaf): # Error reported by type checker
340 ...
342 There is no runtime checking of these properties. The decorator
343 sets the ``__final__`` attribute to ``True`` on the decorated object
344 to allow runtime introspection.
345 """
346 try:
347 f.__final__ = True
348 except (AttributeError, TypeError):
349 # Skip the attribute silently if it is not writable.
350 # AttributeError happens if the object has __slots__ or a
351 # read-only property, TypeError if it's a builtin class.
352 pass
353 return f
356if hasattr(typing, "disjoint_base"): # 3.15
357 disjoint_base = typing.disjoint_base
358else:
359 def disjoint_base(cls):
360 """This decorator marks a class as a disjoint base.
362 Child classes of a disjoint base cannot inherit from other disjoint bases that are
363 not parent classes of the disjoint base.
365 For example:
367 @disjoint_base
368 class Disjoint1: pass
370 @disjoint_base
371 class Disjoint2: pass
373 class Disjoint3(Disjoint1, Disjoint2): pass # Type checker error
375 Type checkers can use knowledge of disjoint bases to detect unreachable code
376 and determine when two types can overlap.
378 See PEP 800."""
379 cls.__disjoint_base__ = True
380 return cls
383def IntVar(name):
384 return typing.TypeVar(name)
387# A Literal bug was fixed in 3.11.0, 3.10.1 and 3.9.8
388# Breakpoint: https://github.com/python/cpython/pull/29334
389if sys.version_info >= (3, 10, 1):
390 Literal = typing.Literal
391else:
392 def _flatten_literal_params(parameters):
393 """An internal helper for Literal creation: flatten Literals among parameters"""
394 params = []
395 for p in parameters:
396 if isinstance(p, _LiteralGenericAlias):
397 params.extend(p.__args__)
398 else:
399 params.append(p)
400 return tuple(params)
402 def _value_and_type_iter(params):
403 for p in params:
404 yield p, type(p)
406 class _LiteralGenericAlias(typing._GenericAlias, _root=True):
407 def __eq__(self, other):
408 if not isinstance(other, _LiteralGenericAlias):
409 return NotImplemented
410 these_args_deduped = set(_value_and_type_iter(self.__args__))
411 other_args_deduped = set(_value_and_type_iter(other.__args__))
412 return these_args_deduped == other_args_deduped
414 def __hash__(self):
415 return hash(frozenset(_value_and_type_iter(self.__args__)))
417 class _LiteralForm(_ExtensionsSpecialForm, _root=True):
418 def __init__(self, doc: str):
419 self._name = 'Literal'
420 self._doc = self.__doc__ = doc
422 def __getitem__(self, parameters):
423 if not isinstance(parameters, tuple):
424 parameters = (parameters,)
426 parameters = _flatten_literal_params(parameters)
428 val_type_pairs = list(_value_and_type_iter(parameters))
429 try:
430 deduped_pairs = set(val_type_pairs)
431 except TypeError:
432 # unhashable parameters
433 pass
434 else:
435 # similar logic to typing._deduplicate on Python 3.9+
436 if len(deduped_pairs) < len(val_type_pairs):
437 new_parameters = []
438 for pair in val_type_pairs:
439 if pair in deduped_pairs:
440 new_parameters.append(pair[0])
441 deduped_pairs.remove(pair)
442 assert not deduped_pairs, deduped_pairs
443 parameters = tuple(new_parameters)
445 return _LiteralGenericAlias(self, parameters)
447 Literal = _LiteralForm(doc="""\
448 A type that can be used to indicate to type checkers
449 that the corresponding value has a value literally equivalent
450 to the provided parameter. For example:
452 var: Literal[4] = 4
454 The type checker understands that 'var' is literally equal to
455 the value 4 and no other value.
457 Literal[...] cannot be subclassed. There is no runtime
458 checking verifying that the parameter is actually a value
459 instead of a type.""")
462_overload_dummy = typing._overload_dummy
465if hasattr(typing, "get_overloads"): # 3.11+
466 overload = typing.overload
467 get_overloads = typing.get_overloads
468 clear_overloads = typing.clear_overloads
469else:
470 # {module: {qualname: {firstlineno: func}}}
471 _overload_registry = collections.defaultdict(
472 functools.partial(collections.defaultdict, dict)
473 )
475 def overload(func):
476 """Decorator for overloaded functions/methods.
478 In a stub file, place two or more stub definitions for the same
479 function in a row, each decorated with @overload. For example:
481 @overload
482 def utf8(value: None) -> None: ...
483 @overload
484 def utf8(value: bytes) -> bytes: ...
485 @overload
486 def utf8(value: str) -> bytes: ...
488 In a non-stub file (i.e. a regular .py file), do the same but
489 follow it with an implementation. The implementation should *not*
490 be decorated with @overload. For example:
492 @overload
493 def utf8(value: None) -> None: ...
494 @overload
495 def utf8(value: bytes) -> bytes: ...
496 @overload
497 def utf8(value: str) -> bytes: ...
498 def utf8(value):
499 # implementation goes here
501 The overloads for a function can be retrieved at runtime using the
502 get_overloads() function.
503 """
504 # classmethod and staticmethod
505 f = getattr(func, "__func__", func)
506 try:
507 _overload_registry[f.__module__][f.__qualname__][
508 f.__code__.co_firstlineno
509 ] = func
510 except AttributeError:
511 # Not a normal function; ignore.
512 pass
513 return _overload_dummy
515 def get_overloads(func):
516 """Return all defined overloads for *func* as a sequence."""
517 # classmethod and staticmethod
518 f = getattr(func, "__func__", func)
519 if f.__module__ not in _overload_registry:
520 return []
521 mod_dict = _overload_registry[f.__module__]
522 if f.__qualname__ not in mod_dict:
523 return []
524 return list(mod_dict[f.__qualname__].values())
526 def clear_overloads():
527 """Clear all overloads in the registry."""
528 _overload_registry.clear()
531# This is not a real generic class. Don't use outside annotations.
532Type = typing.Type
534# Various ABCs mimicking those in collections.abc.
535# A few are simply re-exported for completeness.
536Awaitable = typing.Awaitable
537Coroutine = typing.Coroutine
538AsyncIterable = typing.AsyncIterable
539AsyncIterator = typing.AsyncIterator
540Deque = typing.Deque
541DefaultDict = typing.DefaultDict
542OrderedDict = typing.OrderedDict
543Counter = typing.Counter
544ChainMap = typing.ChainMap
545Text = typing.Text
546TYPE_CHECKING = typing.TYPE_CHECKING
549# Breakpoint: https://github.com/python/cpython/pull/118681
550if sys.version_info >= (3, 13, 0, "beta"):
551 from typing import AsyncContextManager, AsyncGenerator, ContextManager, Generator
552else:
553 def _is_dunder(attr):
554 return attr.startswith('__') and attr.endswith('__')
557 class _SpecialGenericAlias(typing._SpecialGenericAlias, _root=True):
558 def __init__(self, origin, nparams, *, defaults, inst=True, name=None):
559 assert nparams > 0, "`nparams` must be a positive integer"
560 assert defaults, "Must always specify a non-empty sequence for `defaults`"
561 super().__init__(origin, nparams, inst=inst, name=name)
562 self._defaults = defaults
564 def __setattr__(self, attr, val):
565 allowed_attrs = {'_name', '_inst', '_nparams', '_defaults'}
566 if _is_dunder(attr) or attr in allowed_attrs:
567 object.__setattr__(self, attr, val)
568 else:
569 setattr(self.__origin__, attr, val)
571 @typing._tp_cache
572 def __getitem__(self, params):
573 if not isinstance(params, tuple):
574 params = (params,)
575 msg = "Parameters to generic types must be types."
576 params = tuple(typing._type_check(p, msg) for p in params)
577 if (
578 len(params) < self._nparams
579 and len(params) + len(self._defaults) >= self._nparams
580 ):
581 params = (*params, *self._defaults[len(params) - self._nparams:])
582 actual_len = len(params)
584 if actual_len != self._nparams:
585 expected = f"at least {self._nparams - len(self._defaults)}"
586 raise TypeError(
587 f"Too {'many' if actual_len > self._nparams else 'few'}"
588 f" arguments for {self};"
589 f" actual {actual_len}, expected {expected}"
590 )
591 return self.copy_with(params)
593 _NoneType = type(None)
594 Generator = _SpecialGenericAlias(
595 collections.abc.Generator, 3, defaults=(_NoneType, _NoneType)
596 )
597 AsyncGenerator = _SpecialGenericAlias(
598 collections.abc.AsyncGenerator, 2, defaults=(_NoneType,)
599 )
600 ContextManager = _SpecialGenericAlias(
601 contextlib.AbstractContextManager,
602 2,
603 name="ContextManager",
604 defaults=(typing.Optional[bool],)
605 )
606 AsyncContextManager = _SpecialGenericAlias(
607 contextlib.AbstractAsyncContextManager,
608 2,
609 name="AsyncContextManager",
610 defaults=(typing.Optional[bool],)
611 )
614_PROTO_ALLOWLIST = {
615 'collections.abc': [
616 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
617 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible', 'Buffer',
618 ],
619 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
620 'typing_extensions': ['Buffer'],
621}
624_EXCLUDED_ATTRS = frozenset(typing.EXCLUDED_ATTRIBUTES) | {
625 "__match_args__", "__protocol_attrs__", "__non_callable_proto_members__",
626 "__final__",
627}
630def _get_protocol_attrs(cls):
631 attrs = set()
632 for base in cls.__mro__[:-1]: # without object
633 if base.__name__ in {'Protocol', 'Generic'}:
634 continue
635 annotations = getattr(base, '__annotations__', {})
636 for attr in (*base.__dict__, *annotations):
637 if (not attr.startswith('_abc_') and attr not in _EXCLUDED_ATTRS):
638 attrs.add(attr)
639 return attrs
642def _caller(depth=1, default='__main__'):
643 try:
644 return sys._getframemodulename(depth + 1) or default
645 except AttributeError: # For platforms without _getframemodulename()
646 pass
647 try:
648 return sys._getframe(depth + 1).f_globals.get('__name__', default)
649 except (AttributeError, ValueError): # For platforms without _getframe()
650 pass
651 return None
654# `__match_args__` attribute was removed from protocol members in 3.13,
655# we want to backport this change to older Python versions.
656# Breakpoint: https://github.com/python/cpython/pull/110683
657if sys.version_info >= (3, 13):
658 Protocol = typing.Protocol
659else:
660 def _allow_reckless_class_checks(depth=2):
661 """Allow instance and class checks for special stdlib modules.
662 The abc and functools modules indiscriminately call isinstance() and
663 issubclass() on the whole MRO of a user class, which may contain protocols.
664 """
665 return _caller(depth) in {'abc', 'functools', None}
667 def _no_init(self, *args, **kwargs):
668 if type(self)._is_protocol:
669 raise TypeError('Protocols cannot be instantiated')
671 def _type_check_issubclass_arg_1(arg):
672 """Raise TypeError if `arg` is not an instance of `type`
673 in `issubclass(arg, <protocol>)`.
675 In most cases, this is verified by type.__subclasscheck__.
676 Checking it again unnecessarily would slow down issubclass() checks,
677 so, we don't perform this check unless we absolutely have to.
679 For various error paths, however,
680 we want to ensure that *this* error message is shown to the user
681 where relevant, rather than a typing.py-specific error message.
682 """
683 if not isinstance(arg, type):
684 # Same error message as for issubclass(1, int).
685 raise TypeError('issubclass() arg 1 must be a class')
687 # Inheriting from typing._ProtocolMeta isn't actually desirable,
688 # but is necessary to allow typing.Protocol and typing_extensions.Protocol
689 # to mix without getting TypeErrors about "metaclass conflict"
690 class _ProtocolMeta(type(typing.Protocol)):
691 # This metaclass is somewhat unfortunate,
692 # but is necessary for several reasons...
693 #
694 # NOTE: DO NOT call super() in any methods in this class
695 # That would call the methods on typing._ProtocolMeta on Python <=3.11
696 # and those are slow
697 def __new__(mcls, name, bases, namespace, **kwargs):
698 if name == "Protocol" and len(bases) < 2:
699 pass
700 elif {Protocol, typing.Protocol} & set(bases):
701 for base in bases:
702 if not (
703 base in {object, typing.Generic, Protocol, typing.Protocol}
704 or base.__name__ in _PROTO_ALLOWLIST.get(base.__module__, [])
705 or is_protocol(base)
706 ):
707 raise TypeError(
708 f"Protocols can only inherit from other protocols, "
709 f"got {base!r}"
710 )
711 return abc.ABCMeta.__new__(mcls, name, bases, namespace, **kwargs)
713 def __init__(cls, *args, **kwargs):
714 abc.ABCMeta.__init__(cls, *args, **kwargs)
715 if getattr(cls, "_is_protocol", False):
716 cls.__protocol_attrs__ = _get_protocol_attrs(cls)
718 def __subclasscheck__(cls, other):
719 if cls is Protocol:
720 return type.__subclasscheck__(cls, other)
721 if (
722 getattr(cls, '_is_protocol', False)
723 and not _allow_reckless_class_checks()
724 ):
725 if not getattr(cls, '_is_runtime_protocol', False):
726 _type_check_issubclass_arg_1(other)
727 raise TypeError(
728 "Instance and class checks can only be used with "
729 "@runtime_checkable protocols"
730 )
731 if (
732 # this attribute is set by @runtime_checkable:
733 cls.__non_callable_proto_members__
734 and cls.__dict__.get("__subclasshook__") is _proto_hook
735 ):
736 _type_check_issubclass_arg_1(other)
737 non_method_attrs = sorted(cls.__non_callable_proto_members__)
738 raise TypeError(
739 "Protocols with non-method members don't support issubclass()."
740 f" Non-method members: {str(non_method_attrs)[1:-1]}."
741 )
742 return abc.ABCMeta.__subclasscheck__(cls, other)
744 def __instancecheck__(cls, instance):
745 # We need this method for situations where attributes are
746 # assigned in __init__.
747 if cls is Protocol:
748 return type.__instancecheck__(cls, instance)
749 if not getattr(cls, "_is_protocol", False):
750 # i.e., it's a concrete subclass of a protocol
751 return abc.ABCMeta.__instancecheck__(cls, instance)
753 if (
754 not getattr(cls, '_is_runtime_protocol', False) and
755 not _allow_reckless_class_checks()
756 ):
757 raise TypeError("Instance and class checks can only be used with"
758 " @runtime_checkable protocols")
760 if abc.ABCMeta.__instancecheck__(cls, instance):
761 return True
763 for attr in cls.__protocol_attrs__:
764 try:
765 val = inspect.getattr_static(instance, attr)
766 except AttributeError:
767 break
768 # this attribute is set by @runtime_checkable:
769 if val is None and attr not in cls.__non_callable_proto_members__:
770 break
771 else:
772 return True
774 return False
776 def __eq__(cls, other):
777 # Hack so that typing.Generic.__class_getitem__
778 # treats typing_extensions.Protocol
779 # as equivalent to typing.Protocol
780 if abc.ABCMeta.__eq__(cls, other) is True:
781 return True
782 return cls is Protocol and other is typing.Protocol
784 # This has to be defined, or the abc-module cache
785 # complains about classes with this metaclass being unhashable,
786 # if we define only __eq__!
787 def __hash__(cls) -> int:
788 return type.__hash__(cls)
790 @classmethod
791 def _proto_hook(cls, other):
792 if not cls.__dict__.get('_is_protocol', False):
793 return NotImplemented
795 for attr in cls.__protocol_attrs__:
796 for base in other.__mro__:
797 # Check if the members appears in the class dictionary...
798 if attr in base.__dict__:
799 if base.__dict__[attr] is None:
800 return NotImplemented
801 break
803 # ...or in annotations, if it is a sub-protocol.
804 annotations = getattr(base, '__annotations__', {})
805 if (
806 isinstance(annotations, collections.abc.Mapping)
807 and attr in annotations
808 and is_protocol(other)
809 ):
810 break
811 else:
812 return NotImplemented
813 return True
815 class Protocol(typing.Generic, metaclass=_ProtocolMeta):
816 __doc__ = typing.Protocol.__doc__
817 __slots__ = ()
818 _is_protocol = True
819 _is_runtime_protocol = False
821 def __init_subclass__(cls, *args, **kwargs):
822 super().__init_subclass__(*args, **kwargs)
824 # Determine if this is a protocol or a concrete subclass.
825 if not cls.__dict__.get('_is_protocol', False):
826 cls._is_protocol = any(b is Protocol for b in cls.__bases__)
828 # Set (or override) the protocol subclass hook.
829 if '__subclasshook__' not in cls.__dict__:
830 cls.__subclasshook__ = _proto_hook
832 # Prohibit instantiation for protocol classes
833 if cls._is_protocol and cls.__init__ is Protocol.__init__:
834 cls.__init__ = _no_init
837# Breakpoint: https://github.com/python/cpython/pull/113401
838if sys.version_info >= (3, 13):
839 runtime_checkable = typing.runtime_checkable
840else:
841 def runtime_checkable(cls):
842 """Mark a protocol class as a runtime protocol.
844 Such protocol can be used with isinstance() and issubclass().
845 Raise TypeError if applied to a non-protocol class.
846 This allows a simple-minded structural check very similar to
847 one trick ponies in collections.abc such as Iterable.
849 For example::
851 @runtime_checkable
852 class Closable(Protocol):
853 def close(self): ...
855 assert isinstance(open('/some/file'), Closable)
857 Warning: this will check only the presence of the required methods,
858 not their type signatures!
859 """
860 if not issubclass(cls, typing.Generic) or not getattr(cls, '_is_protocol', False):
861 raise TypeError(f'@runtime_checkable can be only applied to protocol classes,'
862 f' got {cls!r}')
863 cls._is_runtime_protocol = True
865 # typing.Protocol classes on <=3.11 break if we execute this block,
866 # because typing.Protocol classes on <=3.11 don't have a
867 # `__protocol_attrs__` attribute, and this block relies on the
868 # `__protocol_attrs__` attribute. Meanwhile, typing.Protocol classes on 3.12.2+
869 # break if we *don't* execute this block, because *they* assume that all
870 # protocol classes have a `__non_callable_proto_members__` attribute
871 # (which this block sets)
872 if isinstance(cls, _ProtocolMeta) or sys.version_info >= (3, 12, 2):
873 # PEP 544 prohibits using issubclass()
874 # with protocols that have non-method members.
875 # See gh-113320 for why we compute this attribute here,
876 # rather than in `_ProtocolMeta.__init__`
877 cls.__non_callable_proto_members__ = set()
878 for attr in cls.__protocol_attrs__:
879 try:
880 is_callable = callable(getattr(cls, attr, None))
881 except Exception as e:
882 raise TypeError(
883 f"Failed to determine whether protocol member {attr!r} "
884 "is a method member"
885 ) from e
886 else:
887 if not is_callable:
888 cls.__non_callable_proto_members__.add(attr)
890 return cls
893# The "runtime" alias exists for backwards compatibility.
894runtime = runtime_checkable
897# Our version of runtime-checkable protocols is faster on Python <=3.11
898# Breakpoint: https://github.com/python/cpython/pull/112717
899if sys.version_info >= (3, 12):
900 SupportsInt = typing.SupportsInt
901 SupportsFloat = typing.SupportsFloat
902 SupportsComplex = typing.SupportsComplex
903 SupportsBytes = typing.SupportsBytes
904 SupportsIndex = typing.SupportsIndex
905 SupportsAbs = typing.SupportsAbs
906 SupportsRound = typing.SupportsRound
907else:
908 @runtime_checkable
909 class SupportsInt(Protocol):
910 """An ABC with one abstract method __int__."""
911 __slots__ = ()
913 @abc.abstractmethod
914 def __int__(self) -> int:
915 pass
917 @runtime_checkable
918 class SupportsFloat(Protocol):
919 """An ABC with one abstract method __float__."""
920 __slots__ = ()
922 @abc.abstractmethod
923 def __float__(self) -> float:
924 pass
926 @runtime_checkable
927 class SupportsComplex(Protocol):
928 """An ABC with one abstract method __complex__."""
929 __slots__ = ()
931 @abc.abstractmethod
932 def __complex__(self) -> complex:
933 pass
935 @runtime_checkable
936 class SupportsBytes(Protocol):
937 """An ABC with one abstract method __bytes__."""
938 __slots__ = ()
940 @abc.abstractmethod
941 def __bytes__(self) -> bytes:
942 pass
944 @runtime_checkable
945 class SupportsIndex(Protocol):
946 __slots__ = ()
948 @abc.abstractmethod
949 def __index__(self) -> int:
950 pass
952 @runtime_checkable
953 class SupportsAbs(Protocol[T_co]):
954 """
955 An ABC with one abstract method __abs__ that is covariant in its return type.
956 """
957 __slots__ = ()
959 @abc.abstractmethod
960 def __abs__(self) -> T_co:
961 pass
963 @runtime_checkable
964 class SupportsRound(Protocol[T_co]):
965 """
966 An ABC with one abstract method __round__ that is covariant in its return type.
967 """
968 __slots__ = ()
970 @abc.abstractmethod
971 def __round__(self, ndigits: int = 0) -> T_co:
972 pass
975if hasattr(io, "Reader") and hasattr(io, "Writer"):
976 Reader = io.Reader
977 Writer = io.Writer
978else:
979 @runtime_checkable
980 class Reader(Protocol[T_co]):
981 """Protocol for simple I/O reader instances.
983 This protocol only supports blocking I/O.
984 """
986 __slots__ = ()
988 @abc.abstractmethod
989 def read(self, size: int = ..., /) -> T_co:
990 """Read data from the input stream and return it.
992 If *size* is specified, at most *size* items (bytes/characters) will be
993 read.
994 """
996 @runtime_checkable
997 class Writer(Protocol[T_contra]):
998 """Protocol for simple I/O writer instances.
1000 This protocol only supports blocking I/O.
1001 """
1003 __slots__ = ()
1005 @abc.abstractmethod
1006 def write(self, data: T_contra, /) -> int:
1007 """Write *data* to the output stream and return the number of items written.""" # noqa: E501
1010_NEEDS_SINGLETONMETA = (
1011 not hasattr(typing, "NoDefault") or not hasattr(typing, "NoExtraItems")
1012)
1014if _NEEDS_SINGLETONMETA:
1015 class SingletonMeta(type):
1016 def __setattr__(cls, attr, value):
1017 # TypeError is consistent with the behavior of NoneType
1018 raise TypeError(
1019 f"cannot set {attr!r} attribute of immutable type {cls.__name__!r}"
1020 )
1023if hasattr(typing, "NoDefault"):
1024 NoDefault = typing.NoDefault
1025else:
1026 class NoDefaultType(metaclass=SingletonMeta):
1027 """The type of the NoDefault singleton."""
1029 __slots__ = ()
1031 def __new__(cls):
1032 return globals().get("NoDefault") or object.__new__(cls)
1034 def __repr__(self):
1035 return "typing_extensions.NoDefault"
1037 def __reduce__(self):
1038 return "NoDefault"
1040 NoDefault = NoDefaultType()
1041 del NoDefaultType
1043if hasattr(typing, "NoExtraItems"):
1044 NoExtraItems = typing.NoExtraItems
1045else:
1046 class NoExtraItemsType(metaclass=SingletonMeta):
1047 """The type of the NoExtraItems singleton."""
1049 __slots__ = ()
1051 def __new__(cls):
1052 return globals().get("NoExtraItems") or object.__new__(cls)
1054 def __repr__(self):
1055 return "typing_extensions.NoExtraItems"
1057 def __reduce__(self):
1058 return "NoExtraItems"
1060 NoExtraItems = NoExtraItemsType()
1061 del NoExtraItemsType
1063if _NEEDS_SINGLETONMETA:
1064 del SingletonMeta
1067# Update this to something like >=3.13.0b1 if and when
1068# PEP 728 is implemented in CPython
1069_PEP_728_IMPLEMENTED = False
1071if _PEP_728_IMPLEMENTED:
1072 # The standard library TypedDict in Python 3.9.0/1 does not honour the "total"
1073 # keyword with old-style TypedDict(). See https://bugs.python.org/issue42059
1074 # The standard library TypedDict below Python 3.11 does not store runtime
1075 # information about optional and required keys when using Required or NotRequired.
1076 # Generic TypedDicts are also impossible using typing.TypedDict on Python <3.11.
1077 # Aaaand on 3.12 we add __orig_bases__ to TypedDict
1078 # to enable better runtime introspection.
1079 # On 3.13 we deprecate some odd ways of creating TypedDicts.
1080 # Also on 3.13, PEP 705 adds the ReadOnly[] qualifier.
1081 # PEP 728 (still pending) makes more changes.
1082 TypedDict = typing.TypedDict
1083 _TypedDictMeta = typing._TypedDictMeta
1084 is_typeddict = typing.is_typeddict
1085else:
1086 # 3.10.0 and later
1087 _TAKES_MODULE = "module" in inspect.signature(typing._type_check).parameters
1089 def _get_typeddict_qualifiers(annotation_type):
1090 while True:
1091 annotation_origin = get_origin(annotation_type)
1092 if annotation_origin is Annotated:
1093 annotation_args = get_args(annotation_type)
1094 if annotation_args:
1095 annotation_type = annotation_args[0]
1096 else:
1097 break
1098 elif annotation_origin is Required:
1099 yield Required
1100 annotation_type, = get_args(annotation_type)
1101 elif annotation_origin is NotRequired:
1102 yield NotRequired
1103 annotation_type, = get_args(annotation_type)
1104 elif annotation_origin is ReadOnly:
1105 yield ReadOnly
1106 annotation_type, = get_args(annotation_type)
1107 else:
1108 break
1110 class _TypedDictMeta(type):
1112 def __new__(cls, name, bases, ns, *, total=True, closed=None,
1113 extra_items=NoExtraItems):
1114 """Create new typed dict class object.
1116 This method is called when TypedDict is subclassed,
1117 or when TypedDict is instantiated. This way
1118 TypedDict supports all three syntax forms described in its docstring.
1119 Subclasses and instances of TypedDict return actual dictionaries.
1120 """
1121 for base in bases:
1122 if type(base) is not _TypedDictMeta and base is not typing.Generic:
1123 raise TypeError('cannot inherit from both a TypedDict type '
1124 'and a non-TypedDict base class')
1125 if closed is not None and extra_items is not NoExtraItems:
1126 raise TypeError(f"Cannot combine closed={closed!r} and extra_items")
1128 if any(issubclass(b, typing.Generic) for b in bases):
1129 generic_base = (typing.Generic,)
1130 else:
1131 generic_base = ()
1133 ns_annotations = ns.pop('__annotations__', None)
1135 # typing.py generally doesn't let you inherit from plain Generic, unless
1136 # the name of the class happens to be "Protocol"
1137 tp_dict = type.__new__(_TypedDictMeta, "Protocol", (*generic_base, dict), ns)
1138 tp_dict.__name__ = name
1139 if tp_dict.__qualname__ == "Protocol":
1140 tp_dict.__qualname__ = name
1142 if not hasattr(tp_dict, '__orig_bases__'):
1143 tp_dict.__orig_bases__ = bases
1145 annotations = {}
1146 own_annotate = None
1147 if ns_annotations is not None:
1148 own_annotations = ns_annotations
1149 elif sys.version_info >= (3, 14):
1150 if hasattr(annotationlib, "get_annotate_from_class_namespace"):
1151 own_annotate = annotationlib.get_annotate_from_class_namespace(ns)
1152 else:
1153 # 3.14.0a7 and earlier
1154 own_annotate = ns.get("__annotate__")
1155 if own_annotate is not None:
1156 own_annotations = annotationlib.call_annotate_function(
1157 own_annotate, Format.FORWARDREF, owner=tp_dict
1158 )
1159 else:
1160 own_annotations = {}
1161 else:
1162 own_annotations = {}
1163 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
1164 if _TAKES_MODULE:
1165 own_checked_annotations = {
1166 n: typing._type_check(tp, msg, module=tp_dict.__module__)
1167 for n, tp in own_annotations.items()
1168 }
1169 else:
1170 own_checked_annotations = {
1171 n: typing._type_check(tp, msg)
1172 for n, tp in own_annotations.items()
1173 }
1174 required_keys = set()
1175 optional_keys = set()
1176 readonly_keys = set()
1177 mutable_keys = set()
1178 extra_items_type = extra_items
1180 for base in bases:
1181 base_dict = base.__dict__
1183 if sys.version_info <= (3, 14):
1184 annotations.update(base_dict.get('__annotations__', {}))
1185 required_keys.update(base_dict.get('__required_keys__', ()))
1186 optional_keys.update(base_dict.get('__optional_keys__', ()))
1187 readonly_keys.update(base_dict.get('__readonly_keys__', ()))
1188 mutable_keys.update(base_dict.get('__mutable_keys__', ()))
1190 # This was specified in an earlier version of PEP 728. Support
1191 # is retained for backwards compatibility, but only for Python
1192 # 3.13 and lower.
1193 if (closed and sys.version_info < (3, 14)
1194 and "__extra_items__" in own_checked_annotations):
1195 annotation_type = own_checked_annotations.pop("__extra_items__")
1196 qualifiers = set(_get_typeddict_qualifiers(annotation_type))
1197 if Required in qualifiers:
1198 raise TypeError(
1199 "Special key __extra_items__ does not support "
1200 "Required"
1201 )
1202 if NotRequired in qualifiers:
1203 raise TypeError(
1204 "Special key __extra_items__ does not support "
1205 "NotRequired"
1206 )
1207 extra_items_type = annotation_type
1209 annotations.update(own_checked_annotations)
1210 for annotation_key, annotation_type in own_checked_annotations.items():
1211 qualifiers = set(_get_typeddict_qualifiers(annotation_type))
1213 if Required in qualifiers:
1214 required_keys.add(annotation_key)
1215 elif NotRequired in qualifiers:
1216 optional_keys.add(annotation_key)
1217 elif total:
1218 required_keys.add(annotation_key)
1219 else:
1220 optional_keys.add(annotation_key)
1221 if ReadOnly in qualifiers:
1222 mutable_keys.discard(annotation_key)
1223 readonly_keys.add(annotation_key)
1224 else:
1225 mutable_keys.add(annotation_key)
1226 readonly_keys.discard(annotation_key)
1228 # Breakpoint: https://github.com/python/cpython/pull/119891
1229 if sys.version_info >= (3, 14):
1230 def __annotate__(format):
1231 annos = {}
1232 for base in bases:
1233 if base is Generic:
1234 continue
1235 base_annotate = base.__annotate__
1236 if base_annotate is None:
1237 continue
1238 base_annos = annotationlib.call_annotate_function(
1239 base_annotate, format, owner=base)
1240 annos.update(base_annos)
1241 if own_annotate is not None:
1242 own = annotationlib.call_annotate_function(
1243 own_annotate, format, owner=tp_dict)
1244 if format != Format.STRING:
1245 own = {
1246 n: typing._type_check(tp, msg, module=tp_dict.__module__)
1247 for n, tp in own.items()
1248 }
1249 elif format == Format.STRING:
1250 own = annotationlib.annotations_to_string(own_annotations)
1251 elif format in (Format.FORWARDREF, Format.VALUE):
1252 own = own_checked_annotations
1253 else:
1254 raise NotImplementedError(format)
1255 annos.update(own)
1256 return annos
1258 tp_dict.__annotate__ = __annotate__
1259 else:
1260 tp_dict.__annotations__ = annotations
1261 tp_dict.__required_keys__ = frozenset(required_keys)
1262 tp_dict.__optional_keys__ = frozenset(optional_keys)
1263 tp_dict.__readonly_keys__ = frozenset(readonly_keys)
1264 tp_dict.__mutable_keys__ = frozenset(mutable_keys)
1265 tp_dict.__total__ = total
1266 tp_dict.__closed__ = closed
1267 tp_dict.__extra_items__ = extra_items_type
1268 return tp_dict
1270 __call__ = dict # static method
1272 def __subclasscheck__(cls, other):
1273 # Typed dicts are only for static structural subtyping.
1274 raise TypeError('TypedDict does not support instance and class checks')
1276 __instancecheck__ = __subclasscheck__
1278 _TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
1280 def _create_typeddict(
1281 typename,
1282 fields,
1283 /,
1284 *,
1285 typing_is_inline,
1286 total,
1287 closed,
1288 extra_items,
1289 **kwargs,
1290 ):
1291 if fields is _marker or fields is None:
1292 if fields is _marker:
1293 deprecated_thing = (
1294 "Failing to pass a value for the 'fields' parameter"
1295 )
1296 else:
1297 deprecated_thing = "Passing `None` as the 'fields' parameter"
1299 example = f"`{typename} = TypedDict({typename!r}, {{}})`"
1300 deprecation_msg = (
1301 f"{deprecated_thing} is deprecated and will be disallowed in "
1302 "Python 3.15. To create a TypedDict class with 0 fields "
1303 "using the functional syntax, pass an empty dictionary, e.g. "
1304 ) + example + "."
1305 warnings.warn(deprecation_msg, DeprecationWarning, stacklevel=2)
1306 # Support a field called "closed"
1307 if closed is not False and closed is not True and closed is not None:
1308 kwargs["closed"] = closed
1309 closed = None
1310 # Or "extra_items"
1311 if extra_items is not NoExtraItems:
1312 kwargs["extra_items"] = extra_items
1313 extra_items = NoExtraItems
1314 fields = kwargs
1315 elif kwargs:
1316 raise TypeError("TypedDict takes either a dict or keyword arguments,"
1317 " but not both")
1318 if kwargs:
1319 # Breakpoint: https://github.com/python/cpython/pull/104891
1320 if sys.version_info >= (3, 13):
1321 raise TypeError("TypedDict takes no keyword arguments")
1322 warnings.warn(
1323 "The kwargs-based syntax for TypedDict definitions is deprecated "
1324 "in Python 3.11, will be removed in Python 3.13, and may not be "
1325 "understood by third-party type checkers.",
1326 DeprecationWarning,
1327 stacklevel=2,
1328 )
1330 ns = {'__annotations__': dict(fields)}
1331 module = _caller(depth=4 if typing_is_inline else 2)
1332 if module is not None:
1333 # Setting correct module is necessary to make typed dict classes
1334 # pickleable.
1335 ns['__module__'] = module
1337 td = _TypedDictMeta(typename, (), ns, total=total, closed=closed,
1338 extra_items=extra_items)
1339 td.__orig_bases__ = (TypedDict,)
1340 return td
1342 class _TypedDictSpecialForm(_SpecialForm, _root=True):
1343 def __call__(
1344 self,
1345 typename,
1346 fields=_marker,
1347 /,
1348 *,
1349 total=True,
1350 closed=None,
1351 extra_items=NoExtraItems,
1352 **kwargs
1353 ):
1354 return _create_typeddict(
1355 typename,
1356 fields,
1357 typing_is_inline=False,
1358 total=total,
1359 closed=closed,
1360 extra_items=extra_items,
1361 **kwargs,
1362 )
1364 def __mro_entries__(self, bases):
1365 return (_TypedDict,)
1367 @_TypedDictSpecialForm
1368 def TypedDict(self, args):
1369 """A simple typed namespace. At runtime it is equivalent to a plain dict.
1371 TypedDict creates a dictionary type such that a type checker will expect all
1372 instances to have a certain set of keys, where each key is
1373 associated with a value of a consistent type. This expectation
1374 is not checked at runtime.
1376 Usage::
1378 class Point2D(TypedDict):
1379 x: int
1380 y: int
1381 label: str
1383 a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
1384 b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
1386 assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
1388 The type info can be accessed via the Point2D.__annotations__ dict, and
1389 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
1390 TypedDict supports an additional equivalent form::
1392 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
1394 By default, all keys must be present in a TypedDict. It is possible
1395 to override this by specifying totality::
1397 class Point2D(TypedDict, total=False):
1398 x: int
1399 y: int
1401 This means that a Point2D TypedDict can have any of the keys omitted. A type
1402 checker is only expected to support a literal False or True as the value of
1403 the total argument. True is the default, and makes all items defined in the
1404 class body be required.
1406 The Required and NotRequired special forms can also be used to mark
1407 individual keys as being required or not required::
1409 class Point2D(TypedDict):
1410 x: int # the "x" key must always be present (Required is the default)
1411 y: NotRequired[int] # the "y" key can be omitted
1413 See PEP 655 for more details on Required and NotRequired.
1414 """
1415 # This runs when creating inline TypedDicts:
1416 if not isinstance(args, dict):
1417 raise TypeError(
1418 "TypedDict[...] should be used with a single dict argument"
1419 )
1421 return _create_typeddict(
1422 "<inline TypedDict>",
1423 args,
1424 typing_is_inline=True,
1425 total=True,
1426 closed=True,
1427 extra_items=NoExtraItems,
1428 )
1430 _TYPEDDICT_TYPES = (typing._TypedDictMeta, _TypedDictMeta)
1432 def is_typeddict(tp):
1433 """Check if an annotation is a TypedDict class
1435 For example::
1436 class Film(TypedDict):
1437 title: str
1438 year: int
1440 is_typeddict(Film) # => True
1441 is_typeddict(Union[list, str]) # => False
1442 """
1443 return isinstance(tp, _TYPEDDICT_TYPES)
1446if hasattr(typing, "assert_type"):
1447 assert_type = typing.assert_type
1449else:
1450 def assert_type(val, typ, /):
1451 """Assert (to the type checker) that the value is of the given type.
1453 When the type checker encounters a call to assert_type(), it
1454 emits an error if the value is not of the specified type::
1456 def greet(name: str) -> None:
1457 assert_type(name, str) # ok
1458 assert_type(name, int) # type checker error
1460 At runtime this returns the first argument unchanged and otherwise
1461 does nothing.
1462 """
1463 return val
1466if hasattr(typing, "ReadOnly"): # 3.13+
1467 get_type_hints = typing.get_type_hints
1468else: # <=3.13
1469 # replaces _strip_annotations()
1470 def _strip_extras(t):
1471 """Strips Annotated, Required and NotRequired from a given type."""
1472 if isinstance(t, typing._AnnotatedAlias):
1473 return _strip_extras(t.__origin__)
1474 if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired, ReadOnly):
1475 return _strip_extras(t.__args__[0])
1476 if isinstance(t, typing._GenericAlias):
1477 stripped_args = tuple(_strip_extras(a) for a in t.__args__)
1478 if stripped_args == t.__args__:
1479 return t
1480 return t.copy_with(stripped_args)
1481 if hasattr(_types, "GenericAlias") and isinstance(t, _types.GenericAlias):
1482 stripped_args = tuple(_strip_extras(a) for a in t.__args__)
1483 if stripped_args == t.__args__:
1484 return t
1485 return _types.GenericAlias(t.__origin__, stripped_args)
1486 if hasattr(_types, "UnionType") and isinstance(t, _types.UnionType):
1487 stripped_args = tuple(_strip_extras(a) for a in t.__args__)
1488 if stripped_args == t.__args__:
1489 return t
1490 return functools.reduce(operator.or_, stripped_args)
1492 return t
1494 def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
1495 """Return type hints for an object.
1497 This is often the same as obj.__annotations__, but it handles
1498 forward references encoded as string literals, adds Optional[t] if a
1499 default value equal to None is set and recursively replaces all
1500 'Annotated[T, ...]', 'Required[T]' or 'NotRequired[T]' with 'T'
1501 (unless 'include_extras=True').
1503 The argument may be a module, class, method, or function. The annotations
1504 are returned as a dictionary. For classes, annotations include also
1505 inherited members.
1507 TypeError is raised if the argument is not of a type that can contain
1508 annotations, and an empty dictionary is returned if no annotations are
1509 present.
1511 BEWARE -- the behavior of globalns and localns is counterintuitive
1512 (unless you are familiar with how eval() and exec() work). The
1513 search order is locals first, then globals.
1515 - If no dict arguments are passed, an attempt is made to use the
1516 globals from obj (or the respective module's globals for classes),
1517 and these are also used as the locals. If the object does not appear
1518 to have globals, an empty dictionary is used.
1520 - If one dict argument is passed, it is used for both globals and
1521 locals.
1523 - If two dict arguments are passed, they specify globals and
1524 locals, respectively.
1525 """
1526 hint = typing.get_type_hints(
1527 obj, globalns=globalns, localns=localns, include_extras=True
1528 )
1529 # Breakpoint: https://github.com/python/cpython/pull/30304
1530 if sys.version_info < (3, 11):
1531 _clean_optional(obj, hint, globalns, localns)
1532 if include_extras:
1533 return hint
1534 return {k: _strip_extras(t) for k, t in hint.items()}
1536 _NoneType = type(None)
1538 def _could_be_inserted_optional(t):
1539 """detects Union[..., None] pattern"""
1540 if not isinstance(t, typing._UnionGenericAlias):
1541 return False
1542 # Assume if last argument is not None they are user defined
1543 if t.__args__[-1] is not _NoneType:
1544 return False
1545 return True
1547 # < 3.11
1548 def _clean_optional(obj, hints, globalns=None, localns=None):
1549 # reverts injected Union[..., None] cases from typing.get_type_hints
1550 # when a None default value is used.
1551 # see https://github.com/python/typing_extensions/issues/310
1552 if not hints or isinstance(obj, type):
1553 return
1554 defaults = typing._get_defaults(obj) # avoid accessing __annotations___
1555 if not defaults:
1556 return
1557 original_hints = obj.__annotations__
1558 for name, value in hints.items():
1559 # Not a Union[..., None] or replacement conditions not fullfilled
1560 if (not _could_be_inserted_optional(value)
1561 or name not in defaults
1562 or defaults[name] is not None
1563 ):
1564 continue
1565 original_value = original_hints[name]
1566 # value=NoneType should have caused a skip above but check for safety
1567 if original_value is None:
1568 original_value = _NoneType
1569 # Forward reference
1570 if isinstance(original_value, str):
1571 if globalns is None:
1572 if isinstance(obj, _types.ModuleType):
1573 globalns = obj.__dict__
1574 else:
1575 nsobj = obj
1576 # Find globalns for the unwrapped object.
1577 while hasattr(nsobj, '__wrapped__'):
1578 nsobj = nsobj.__wrapped__
1579 globalns = getattr(nsobj, '__globals__', {})
1580 if localns is None:
1581 localns = globalns
1582 elif localns is None:
1583 localns = globalns
1585 original_value = ForwardRef(
1586 original_value,
1587 is_argument=not isinstance(obj, _types.ModuleType)
1588 )
1589 original_evaluated = typing._eval_type(original_value, globalns, localns)
1590 # Compare if values differ. Note that even if equal
1591 # value might be cached by typing._tp_cache contrary to original_evaluated
1592 if original_evaluated != value or (
1593 # 3.10: ForwardRefs of UnionType might be turned into _UnionGenericAlias
1594 hasattr(_types, "UnionType")
1595 and isinstance(original_evaluated, _types.UnionType)
1596 and not isinstance(value, _types.UnionType)
1597 ):
1598 hints[name] = original_evaluated
1600# Python 3.9 has get_origin() and get_args() but those implementations don't support
1601# ParamSpecArgs and ParamSpecKwargs, so only Python 3.10's versions will do.
1602# Breakpoint: https://github.com/python/cpython/pull/25298
1603if sys.version_info >= (3, 10):
1604 get_origin = typing.get_origin
1605 get_args = typing.get_args
1606# 3.9
1607else:
1608 def get_origin(tp):
1609 """Get the unsubscripted version of a type.
1611 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar
1612 and Annotated. Return None for unsupported types. Examples::
1614 get_origin(Literal[42]) is Literal
1615 get_origin(int) is None
1616 get_origin(ClassVar[int]) is ClassVar
1617 get_origin(Generic) is Generic
1618 get_origin(Generic[T]) is Generic
1619 get_origin(Union[T, int]) is Union
1620 get_origin(List[Tuple[T, T]][int]) == list
1621 get_origin(P.args) is P
1622 """
1623 if isinstance(tp, typing._AnnotatedAlias):
1624 return Annotated
1625 if isinstance(tp, (typing._BaseGenericAlias, _types.GenericAlias,
1626 ParamSpecArgs, ParamSpecKwargs)):
1627 return tp.__origin__
1628 if tp is typing.Generic:
1629 return typing.Generic
1630 return None
1632 def get_args(tp):
1633 """Get type arguments with all substitutions performed.
1635 For unions, basic simplifications used by Union constructor are performed.
1636 Examples::
1637 get_args(Dict[str, int]) == (str, int)
1638 get_args(int) == ()
1639 get_args(Union[int, Union[T, int], str][int]) == (int, str)
1640 get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
1641 get_args(Callable[[], T][int]) == ([], int)
1642 """
1643 if isinstance(tp, typing._AnnotatedAlias):
1644 return (tp.__origin__, *tp.__metadata__)
1645 if isinstance(tp, (typing._GenericAlias, _types.GenericAlias)):
1646 res = tp.__args__
1647 if get_origin(tp) is collections.abc.Callable and res[0] is not Ellipsis:
1648 res = (list(res[:-1]), res[-1])
1649 return res
1650 return ()
1653# 3.10+
1654if hasattr(typing, 'TypeAlias'):
1655 TypeAlias = typing.TypeAlias
1656# 3.9
1657else:
1658 @_ExtensionsSpecialForm
1659 def TypeAlias(self, parameters):
1660 """Special marker indicating that an assignment should
1661 be recognized as a proper type alias definition by type
1662 checkers.
1664 For example::
1666 Predicate: TypeAlias = Callable[..., bool]
1668 It's invalid when used anywhere except as in the example above.
1669 """
1670 raise TypeError(f"{self} is not subscriptable")
1673def _set_default(type_param, default):
1674 type_param.has_default = lambda: default is not NoDefault
1675 type_param.__default__ = default
1678def _set_module(typevarlike):
1679 # for pickling:
1680 def_mod = _caller(depth=2)
1681 if def_mod != 'typing_extensions':
1682 typevarlike.__module__ = def_mod
1685class _DefaultMixin:
1686 """Mixin for TypeVarLike defaults."""
1688 __slots__ = ()
1689 __init__ = _set_default
1692# Classes using this metaclass must provide a _backported_typevarlike ClassVar
1693class _TypeVarLikeMeta(type):
1694 def __instancecheck__(cls, __instance: Any) -> bool:
1695 return isinstance(__instance, cls._backported_typevarlike)
1698if _PEP_696_IMPLEMENTED:
1699 from typing import TypeVar
1700else:
1701 # Add default and infer_variance parameters from PEP 696 and 695
1702 class TypeVar(metaclass=_TypeVarLikeMeta):
1703 """Type variable."""
1705 _backported_typevarlike = typing.TypeVar
1707 def __new__(cls, name, *constraints, bound=None,
1708 covariant=False, contravariant=False,
1709 default=NoDefault, infer_variance=False):
1710 if hasattr(typing, "TypeAliasType"):
1711 # PEP 695 implemented (3.12+), can pass infer_variance to typing.TypeVar
1712 typevar = typing.TypeVar(name, *constraints, bound=bound,
1713 covariant=covariant, contravariant=contravariant,
1714 infer_variance=infer_variance)
1715 else:
1716 typevar = typing.TypeVar(name, *constraints, bound=bound,
1717 covariant=covariant, contravariant=contravariant)
1718 if infer_variance and (covariant or contravariant):
1719 raise ValueError("Variance cannot be specified with infer_variance.")
1720 typevar.__infer_variance__ = infer_variance
1722 _set_default(typevar, default)
1723 _set_module(typevar)
1725 def _tvar_prepare_subst(alias, args):
1726 if (
1727 typevar.has_default()
1728 and alias.__parameters__.index(typevar) == len(args)
1729 ):
1730 args += (typevar.__default__,)
1731 return args
1733 typevar.__typing_prepare_subst__ = _tvar_prepare_subst
1734 return typevar
1736 def __init_subclass__(cls) -> None:
1737 raise TypeError(f"type '{__name__}.TypeVar' is not an acceptable base type")
1740# Python 3.10+ has PEP 612
1741if hasattr(typing, 'ParamSpecArgs'):
1742 ParamSpecArgs = typing.ParamSpecArgs
1743 ParamSpecKwargs = typing.ParamSpecKwargs
1744# 3.9
1745else:
1746 class _Immutable:
1747 """Mixin to indicate that object should not be copied."""
1748 __slots__ = ()
1750 def __copy__(self):
1751 return self
1753 def __deepcopy__(self, memo):
1754 return self
1756 class ParamSpecArgs(_Immutable):
1757 """The args for a ParamSpec object.
1759 Given a ParamSpec object P, P.args is an instance of ParamSpecArgs.
1761 ParamSpecArgs objects have a reference back to their ParamSpec:
1763 P.args.__origin__ is P
1765 This type is meant for runtime introspection and has no special meaning to
1766 static type checkers.
1767 """
1768 def __init__(self, origin):
1769 self.__origin__ = origin
1771 def __repr__(self):
1772 return f"{self.__origin__.__name__}.args"
1774 def __eq__(self, other):
1775 if not isinstance(other, ParamSpecArgs):
1776 return NotImplemented
1777 return self.__origin__ == other.__origin__
1779 class ParamSpecKwargs(_Immutable):
1780 """The kwargs for a ParamSpec object.
1782 Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs.
1784 ParamSpecKwargs objects have a reference back to their ParamSpec:
1786 P.kwargs.__origin__ is P
1788 This type is meant for runtime introspection and has no special meaning to
1789 static type checkers.
1790 """
1791 def __init__(self, origin):
1792 self.__origin__ = origin
1794 def __repr__(self):
1795 return f"{self.__origin__.__name__}.kwargs"
1797 def __eq__(self, other):
1798 if not isinstance(other, ParamSpecKwargs):
1799 return NotImplemented
1800 return self.__origin__ == other.__origin__
1803if _PEP_696_IMPLEMENTED:
1804 from typing import ParamSpec
1806# 3.10+
1807elif hasattr(typing, 'ParamSpec'):
1809 # Add default parameter - PEP 696
1810 class ParamSpec(metaclass=_TypeVarLikeMeta):
1811 """Parameter specification."""
1813 _backported_typevarlike = typing.ParamSpec
1815 def __new__(cls, name, *, bound=None,
1816 covariant=False, contravariant=False,
1817 infer_variance=False, default=NoDefault):
1818 if hasattr(typing, "TypeAliasType"):
1819 # PEP 695 implemented, can pass infer_variance to typing.TypeVar
1820 paramspec = typing.ParamSpec(name, bound=bound,
1821 covariant=covariant,
1822 contravariant=contravariant,
1823 infer_variance=infer_variance)
1824 else:
1825 paramspec = typing.ParamSpec(name, bound=bound,
1826 covariant=covariant,
1827 contravariant=contravariant)
1828 paramspec.__infer_variance__ = infer_variance
1830 _set_default(paramspec, default)
1831 _set_module(paramspec)
1833 def _paramspec_prepare_subst(alias, args):
1834 params = alias.__parameters__
1835 i = params.index(paramspec)
1836 if i == len(args) and paramspec.has_default():
1837 args = [*args, paramspec.__default__]
1838 if i >= len(args):
1839 raise TypeError(f"Too few arguments for {alias}")
1840 # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612.
1841 if len(params) == 1 and not typing._is_param_expr(args[0]):
1842 assert i == 0
1843 args = (args,)
1844 # Convert lists to tuples to help other libraries cache the results.
1845 elif isinstance(args[i], list):
1846 args = (*args[:i], tuple(args[i]), *args[i + 1:])
1847 return args
1849 paramspec.__typing_prepare_subst__ = _paramspec_prepare_subst
1850 return paramspec
1852 def __init_subclass__(cls) -> None:
1853 raise TypeError(f"type '{__name__}.ParamSpec' is not an acceptable base type")
1855# 3.9
1856else:
1858 # Inherits from list as a workaround for Callable checks in Python < 3.9.2.
1859 class ParamSpec(list, _DefaultMixin):
1860 """Parameter specification variable.
1862 Usage::
1864 P = ParamSpec('P')
1866 Parameter specification variables exist primarily for the benefit of static
1867 type checkers. They are used to forward the parameter types of one
1868 callable to another callable, a pattern commonly found in higher order
1869 functions and decorators. They are only valid when used in ``Concatenate``,
1870 or s the first argument to ``Callable``. In Python 3.10 and higher,
1871 they are also supported in user-defined Generics at runtime.
1872 See class Generic for more information on generic types. An
1873 example for annotating a decorator::
1875 T = TypeVar('T')
1876 P = ParamSpec('P')
1878 def add_logging(f: Callable[P, T]) -> Callable[P, T]:
1879 '''A type-safe decorator to add logging to a function.'''
1880 def inner(*args: P.args, **kwargs: P.kwargs) -> T:
1881 logging.info(f'{f.__name__} was called')
1882 return f(*args, **kwargs)
1883 return inner
1885 @add_logging
1886 def add_two(x: float, y: float) -> float:
1887 '''Add two numbers together.'''
1888 return x + y
1890 Parameter specification variables defined with covariant=True or
1891 contravariant=True can be used to declare covariant or contravariant
1892 generic types. These keyword arguments are valid, but their actual semantics
1893 are yet to be decided. See PEP 612 for details.
1895 Parameter specification variables can be introspected. e.g.:
1897 P.__name__ == 'T'
1898 P.__bound__ == None
1899 P.__covariant__ == False
1900 P.__contravariant__ == False
1902 Note that only parameter specification variables defined in global scope can
1903 be pickled.
1904 """
1906 # Trick Generic __parameters__.
1907 __class__ = typing.TypeVar
1909 @property
1910 def args(self):
1911 return ParamSpecArgs(self)
1913 @property
1914 def kwargs(self):
1915 return ParamSpecKwargs(self)
1917 def __init__(self, name, *, bound=None, covariant=False, contravariant=False,
1918 infer_variance=False, default=NoDefault):
1919 list.__init__(self, [self])
1920 self.__name__ = name
1921 self.__covariant__ = bool(covariant)
1922 self.__contravariant__ = bool(contravariant)
1923 self.__infer_variance__ = bool(infer_variance)
1924 if bound:
1925 self.__bound__ = typing._type_check(bound, 'Bound must be a type.')
1926 else:
1927 self.__bound__ = None
1928 _DefaultMixin.__init__(self, default)
1930 # for pickling:
1931 def_mod = _caller()
1932 if def_mod != 'typing_extensions':
1933 self.__module__ = def_mod
1935 def __repr__(self):
1936 if self.__infer_variance__:
1937 prefix = ''
1938 elif self.__covariant__:
1939 prefix = '+'
1940 elif self.__contravariant__:
1941 prefix = '-'
1942 else:
1943 prefix = '~'
1944 return prefix + self.__name__
1946 def __hash__(self):
1947 return object.__hash__(self)
1949 def __eq__(self, other):
1950 return self is other
1952 def __reduce__(self):
1953 return self.__name__
1955 # Hack to get typing._type_check to pass.
1956 def __call__(self, *args, **kwargs):
1957 pass
1959 def __init_subclass__(cls) -> None:
1960 raise TypeError(f"type '{__name__}.ParamSpec' is not an acceptable base type")
1963# 3.9
1964if not hasattr(typing, 'Concatenate'):
1965 # Inherits from list as a workaround for Callable checks in Python < 3.9.2.
1967 # 3.9.0-1
1968 if not hasattr(typing, '_type_convert'):
1969 def _type_convert(arg, module=None, *, allow_special_forms=False):
1970 """For converting None to type(None), and strings to ForwardRef."""
1971 if arg is None:
1972 return type(None)
1973 if isinstance(arg, str):
1974 if sys.version_info <= (3, 9, 6):
1975 return ForwardRef(arg)
1976 if sys.version_info <= (3, 9, 7):
1977 return ForwardRef(arg, module=module)
1978 return ForwardRef(arg, module=module, is_class=allow_special_forms)
1979 return arg
1980 else:
1981 _type_convert = typing._type_convert
1983 class _ConcatenateGenericAlias(list):
1985 # Trick Generic into looking into this for __parameters__.
1986 __class__ = typing._GenericAlias
1988 def __init__(self, origin, args):
1989 super().__init__(args)
1990 self.__origin__ = origin
1991 self.__args__ = args
1993 def __repr__(self):
1994 _type_repr = typing._type_repr
1995 return (f'{_type_repr(self.__origin__)}'
1996 f'[{", ".join(_type_repr(arg) for arg in self.__args__)}]')
1998 def __hash__(self):
1999 return hash((self.__origin__, self.__args__))
2001 # Hack to get typing._type_check to pass in Generic.
2002 def __call__(self, *args, **kwargs):
2003 pass
2005 @property
2006 def __parameters__(self):
2007 return tuple(
2008 tp for tp in self.__args__ if isinstance(tp, (typing.TypeVar, ParamSpec))
2009 )
2011 # 3.9 used by __getitem__ below
2012 def copy_with(self, params):
2013 if isinstance(params[-1], _ConcatenateGenericAlias):
2014 params = (*params[:-1], *params[-1].__args__)
2015 elif isinstance(params[-1], (list, tuple)):
2016 return (*params[:-1], *params[-1])
2017 elif (not (params[-1] is ... or isinstance(params[-1], ParamSpec))):
2018 raise TypeError("The last parameter to Concatenate should be a "
2019 "ParamSpec variable or ellipsis.")
2020 return self.__class__(self.__origin__, params)
2022 # 3.9; accessed during GenericAlias.__getitem__ when substituting
2023 def __getitem__(self, args):
2024 if self.__origin__ in (Generic, Protocol):
2025 # Can't subscript Generic[...] or Protocol[...].
2026 raise TypeError(f"Cannot subscript already-subscripted {self}")
2027 if not self.__parameters__:
2028 raise TypeError(f"{self} is not a generic class")
2030 if not isinstance(args, tuple):
2031 args = (args,)
2032 args = _unpack_args(*(_type_convert(p) for p in args))
2033 params = self.__parameters__
2034 for param in params:
2035 prepare = getattr(param, "__typing_prepare_subst__", None)
2036 if prepare is not None:
2037 args = prepare(self, args)
2038 # 3.9 & typing.ParamSpec
2039 elif isinstance(param, ParamSpec):
2040 i = params.index(param)
2041 if (
2042 i == len(args)
2043 and getattr(param, '__default__', NoDefault) is not NoDefault
2044 ):
2045 args = [*args, param.__default__]
2046 if i >= len(args):
2047 raise TypeError(f"Too few arguments for {self}")
2048 # Special case for Z[[int, str, bool]] == Z[int, str, bool]
2049 if len(params) == 1 and not _is_param_expr(args[0]):
2050 assert i == 0
2051 args = (args,)
2052 elif (
2053 isinstance(args[i], list)
2054 # 3.9
2055 # This class inherits from list do not convert
2056 and not isinstance(args[i], _ConcatenateGenericAlias)
2057 ):
2058 args = (*args[:i], tuple(args[i]), *args[i + 1:])
2060 alen = len(args)
2061 plen = len(params)
2062 if alen != plen:
2063 raise TypeError(
2064 f"Too {'many' if alen > plen else 'few'} arguments for {self};"
2065 f" actual {alen}, expected {plen}"
2066 )
2068 subst = dict(zip(self.__parameters__, args))
2069 # determine new args
2070 new_args = []
2071 for arg in self.__args__:
2072 if isinstance(arg, type):
2073 new_args.append(arg)
2074 continue
2075 if isinstance(arg, TypeVar):
2076 arg = subst[arg]
2077 if (
2078 (isinstance(arg, typing._GenericAlias) and _is_unpack(arg))
2079 or (
2080 hasattr(_types, "GenericAlias")
2081 and isinstance(arg, _types.GenericAlias)
2082 and getattr(arg, "__unpacked__", False)
2083 )
2084 ):
2085 raise TypeError(f"{arg} is not valid as type argument")
2087 elif isinstance(arg,
2088 typing._GenericAlias
2089 if not hasattr(_types, "GenericAlias") else
2090 (typing._GenericAlias, _types.GenericAlias)
2091 ):
2092 subparams = arg.__parameters__
2093 if subparams:
2094 subargs = tuple(subst[x] for x in subparams)
2095 arg = arg[subargs]
2096 new_args.append(arg)
2097 return self.copy_with(tuple(new_args))
2099# 3.10+
2100else:
2101 _ConcatenateGenericAlias = typing._ConcatenateGenericAlias
2103 # 3.10
2104 if sys.version_info < (3, 11):
2106 class _ConcatenateGenericAlias(typing._ConcatenateGenericAlias, _root=True):
2107 # needed for checks in collections.abc.Callable to accept this class
2108 __module__ = "typing"
2110 def copy_with(self, params):
2111 if isinstance(params[-1], (list, tuple)):
2112 return (*params[:-1], *params[-1])
2113 if isinstance(params[-1], typing._ConcatenateGenericAlias):
2114 params = (*params[:-1], *params[-1].__args__)
2115 elif not (params[-1] is ... or isinstance(params[-1], ParamSpec)):
2116 raise TypeError("The last parameter to Concatenate should be a "
2117 "ParamSpec variable or ellipsis.")
2118 return super(typing._ConcatenateGenericAlias, self).copy_with(params)
2120 def __getitem__(self, args):
2121 value = super().__getitem__(args)
2122 if isinstance(value, tuple) and any(_is_unpack(t) for t in value):
2123 return tuple(_unpack_args(*(n for n in value)))
2124 return value
2127# 3.9.2
2128class _EllipsisDummy: ...
2131# <=3.10
2132def _create_concatenate_alias(origin, parameters):
2133 if parameters[-1] is ... and sys.version_info < (3, 9, 2):
2134 # Hack: Arguments must be types, replace it with one.
2135 parameters = (*parameters[:-1], _EllipsisDummy)
2136 if sys.version_info >= (3, 10, 3):
2137 concatenate = _ConcatenateGenericAlias(origin, parameters,
2138 _typevar_types=(TypeVar, ParamSpec),
2139 _paramspec_tvars=True)
2140 else:
2141 concatenate = _ConcatenateGenericAlias(origin, parameters)
2142 if parameters[-1] is not _EllipsisDummy:
2143 return concatenate
2144 # Remove dummy again
2145 concatenate.__args__ = tuple(p if p is not _EllipsisDummy else ...
2146 for p in concatenate.__args__)
2147 if sys.version_info < (3, 10):
2148 # backport needs __args__ adjustment only
2149 return concatenate
2150 concatenate.__parameters__ = tuple(p for p in concatenate.__parameters__
2151 if p is not _EllipsisDummy)
2152 return concatenate
2155# <=3.10
2156@typing._tp_cache
2157def _concatenate_getitem(self, parameters):
2158 if parameters == ():
2159 raise TypeError("Cannot take a Concatenate of no types.")
2160 if not isinstance(parameters, tuple):
2161 parameters = (parameters,)
2162 if not (parameters[-1] is ... or isinstance(parameters[-1], ParamSpec)):
2163 raise TypeError("The last parameter to Concatenate should be a "
2164 "ParamSpec variable or ellipsis.")
2165 msg = "Concatenate[arg, ...]: each arg must be a type."
2166 parameters = (*(typing._type_check(p, msg) for p in parameters[:-1]),
2167 parameters[-1])
2168 return _create_concatenate_alias(self, parameters)
2171# 3.11+; Concatenate does not accept ellipsis in 3.10
2172# Breakpoint: https://github.com/python/cpython/pull/30969
2173if sys.version_info >= (3, 11):
2174 Concatenate = typing.Concatenate
2175# <=3.10
2176else:
2177 @_ExtensionsSpecialForm
2178 def Concatenate(self, parameters):
2179 """Used in conjunction with ``ParamSpec`` and ``Callable`` to represent a
2180 higher order function which adds, removes or transforms parameters of a
2181 callable.
2183 For example::
2185 Callable[Concatenate[int, P], int]
2187 See PEP 612 for detailed information.
2188 """
2189 return _concatenate_getitem(self, parameters)
2192# 3.10+
2193if hasattr(typing, 'TypeGuard'):
2194 TypeGuard = typing.TypeGuard
2195# 3.9
2196else:
2197 @_ExtensionsSpecialForm
2198 def TypeGuard(self, parameters):
2199 """Special typing form used to annotate the return type of a user-defined
2200 type guard function. ``TypeGuard`` only accepts a single type argument.
2201 At runtime, functions marked this way should return a boolean.
2203 ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static
2204 type checkers to determine a more precise type of an expression within a
2205 program's code flow. Usually type narrowing is done by analyzing
2206 conditional code flow and applying the narrowing to a block of code. The
2207 conditional expression here is sometimes referred to as a "type guard".
2209 Sometimes it would be convenient to use a user-defined boolean function
2210 as a type guard. Such a function should use ``TypeGuard[...]`` as its
2211 return type to alert static type checkers to this intention.
2213 Using ``-> TypeGuard`` tells the static type checker that for a given
2214 function:
2216 1. The return value is a boolean.
2217 2. If the return value is ``True``, the type of its argument
2218 is the type inside ``TypeGuard``.
2220 For example::
2222 def is_str(val: Union[str, float]):
2223 # "isinstance" type guard
2224 if isinstance(val, str):
2225 # Type of ``val`` is narrowed to ``str``
2226 ...
2227 else:
2228 # Else, type of ``val`` is narrowed to ``float``.
2229 ...
2231 Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower
2232 form of ``TypeA`` (it can even be a wider form) and this may lead to
2233 type-unsafe results. The main reason is to allow for things like
2234 narrowing ``List[object]`` to ``List[str]`` even though the latter is not
2235 a subtype of the former, since ``List`` is invariant. The responsibility of
2236 writing type-safe type guards is left to the user.
2238 ``TypeGuard`` also works with type variables. For more information, see
2239 PEP 647 (User-Defined Type Guards).
2240 """
2241 item = typing._type_check(parameters, f'{self} accepts only a single type.')
2242 return typing._GenericAlias(self, (item,))
2245# 3.13+
2246if hasattr(typing, 'TypeIs'):
2247 TypeIs = typing.TypeIs
2248# <=3.12
2249else:
2250 @_ExtensionsSpecialForm
2251 def TypeIs(self, parameters):
2252 """Special typing form used to annotate the return type of a user-defined
2253 type narrower function. ``TypeIs`` only accepts a single type argument.
2254 At runtime, functions marked this way should return a boolean.
2256 ``TypeIs`` aims to benefit *type narrowing* -- a technique used by static
2257 type checkers to determine a more precise type of an expression within a
2258 program's code flow. Usually type narrowing is done by analyzing
2259 conditional code flow and applying the narrowing to a block of code. The
2260 conditional expression here is sometimes referred to as a "type guard".
2262 Sometimes it would be convenient to use a user-defined boolean function
2263 as a type guard. Such a function should use ``TypeIs[...]`` as its
2264 return type to alert static type checkers to this intention.
2266 Using ``-> TypeIs`` tells the static type checker that for a given
2267 function:
2269 1. The return value is a boolean.
2270 2. If the return value is ``True``, the type of its argument
2271 is the intersection of the type inside ``TypeIs`` and the argument's
2272 previously known type.
2274 For example::
2276 def is_awaitable(val: object) -> TypeIs[Awaitable[Any]]:
2277 return hasattr(val, '__await__')
2279 def f(val: Union[int, Awaitable[int]]) -> int:
2280 if is_awaitable(val):
2281 assert_type(val, Awaitable[int])
2282 else:
2283 assert_type(val, int)
2285 ``TypeIs`` also works with type variables. For more information, see
2286 PEP 742 (Narrowing types with TypeIs).
2287 """
2288 item = typing._type_check(parameters, f'{self} accepts only a single type.')
2289 return typing._GenericAlias(self, (item,))
2292# 3.14+?
2293if hasattr(typing, 'TypeForm'):
2294 TypeForm = typing.TypeForm
2295# <=3.13
2296else:
2297 class _TypeFormForm(_ExtensionsSpecialForm, _root=True):
2298 # TypeForm(X) is equivalent to X but indicates to the type checker
2299 # that the object is a TypeForm.
2300 def __call__(self, obj, /):
2301 return obj
2303 @_TypeFormForm
2304 def TypeForm(self, parameters):
2305 """A special form representing the value that results from the evaluation
2306 of a type expression. This value encodes the information supplied in the
2307 type expression, and it represents the type described by that type expression.
2309 When used in a type expression, TypeForm describes a set of type form objects.
2310 It accepts a single type argument, which must be a valid type expression.
2311 ``TypeForm[T]`` describes the set of all type form objects that represent
2312 the type T or types that are assignable to T.
2314 Usage:
2316 def cast[T](typ: TypeForm[T], value: Any) -> T: ...
2318 reveal_type(cast(int, "x")) # int
2320 See PEP 747 for more information.
2321 """
2322 item = typing._type_check(parameters, f'{self} accepts only a single type.')
2323 return typing._GenericAlias(self, (item,))
2328if hasattr(typing, "LiteralString"): # 3.11+
2329 LiteralString = typing.LiteralString
2330else:
2331 @_SpecialForm
2332 def LiteralString(self, params):
2333 """Represents an arbitrary literal string.
2335 Example::
2337 from typing_extensions import LiteralString
2339 def query(sql: LiteralString) -> ...:
2340 ...
2342 query("SELECT * FROM table") # ok
2343 query(f"SELECT * FROM {input()}") # not ok
2345 See PEP 675 for details.
2347 """
2348 raise TypeError(f"{self} is not subscriptable")
2351if hasattr(typing, "Self"): # 3.11+
2352 Self = typing.Self
2353else:
2354 @_SpecialForm
2355 def Self(self, params):
2356 """Used to spell the type of "self" in classes.
2358 Example::
2360 from typing import Self
2362 class ReturnsSelf:
2363 def parse(self, data: bytes) -> Self:
2364 ...
2365 return self
2367 """
2369 raise TypeError(f"{self} is not subscriptable")
2372if hasattr(typing, "Never"): # 3.11+
2373 Never = typing.Never
2374else:
2375 @_SpecialForm
2376 def Never(self, params):
2377 """The bottom type, a type that has no members.
2379 This can be used to define a function that should never be
2380 called, or a function that never returns::
2382 from typing_extensions import Never
2384 def never_call_me(arg: Never) -> None:
2385 pass
2387 def int_or_str(arg: int | str) -> None:
2388 never_call_me(arg) # type checker error
2389 match arg:
2390 case int():
2391 print("It's an int")
2392 case str():
2393 print("It's a str")
2394 case _:
2395 never_call_me(arg) # ok, arg is of type Never
2397 """
2399 raise TypeError(f"{self} is not subscriptable")
2402if hasattr(typing, 'Required'): # 3.11+
2403 Required = typing.Required
2404 NotRequired = typing.NotRequired
2405else: # <=3.10
2406 @_ExtensionsSpecialForm
2407 def Required(self, parameters):
2408 """A special typing construct to mark a key of a total=False TypedDict
2409 as required. For example:
2411 class Movie(TypedDict, total=False):
2412 title: Required[str]
2413 year: int
2415 m = Movie(
2416 title='The Matrix', # typechecker error if key is omitted
2417 year=1999,
2418 )
2420 There is no runtime checking that a required key is actually provided
2421 when instantiating a related TypedDict.
2422 """
2423 item = typing._type_check(parameters, f'{self._name} accepts only a single type.')
2424 return typing._GenericAlias(self, (item,))
2426 @_ExtensionsSpecialForm
2427 def NotRequired(self, parameters):
2428 """A special typing construct to mark a key of a TypedDict as
2429 potentially missing. For example:
2431 class Movie(TypedDict):
2432 title: str
2433 year: NotRequired[int]
2435 m = Movie(
2436 title='The Matrix', # typechecker error if key is omitted
2437 year=1999,
2438 )
2439 """
2440 item = typing._type_check(parameters, f'{self._name} accepts only a single type.')
2441 return typing._GenericAlias(self, (item,))
2444if hasattr(typing, 'ReadOnly'):
2445 ReadOnly = typing.ReadOnly
2446else: # <=3.12
2447 @_ExtensionsSpecialForm
2448 def ReadOnly(self, parameters):
2449 """A special typing construct to mark an item of a TypedDict as read-only.
2451 For example:
2453 class Movie(TypedDict):
2454 title: ReadOnly[str]
2455 year: int
2457 def mutate_movie(m: Movie) -> None:
2458 m["year"] = 1992 # allowed
2459 m["title"] = "The Matrix" # typechecker error
2461 There is no runtime checking for this property.
2462 """
2463 item = typing._type_check(parameters, f'{self._name} accepts only a single type.')
2464 return typing._GenericAlias(self, (item,))
2467_UNPACK_DOC = """\
2468Type unpack operator.
2470The type unpack operator takes the child types from some container type,
2471such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'. For
2472example:
2474 # For some generic class `Foo`:
2475 Foo[Unpack[tuple[int, str]]] # Equivalent to Foo[int, str]
2477 Ts = TypeVarTuple('Ts')
2478 # Specifies that `Bar` is generic in an arbitrary number of types.
2479 # (Think of `Ts` as a tuple of an arbitrary number of individual
2480 # `TypeVar`s, which the `Unpack` is 'pulling out' directly into the
2481 # `Generic[]`.)
2482 class Bar(Generic[Unpack[Ts]]): ...
2483 Bar[int] # Valid
2484 Bar[int, str] # Also valid
2486From Python 3.11, this can also be done using the `*` operator:
2488 Foo[*tuple[int, str]]
2489 class Bar(Generic[*Ts]): ...
2491The operator can also be used along with a `TypedDict` to annotate
2492`**kwargs` in a function signature. For instance:
2494 class Movie(TypedDict):
2495 name: str
2496 year: int
2498 # This function expects two keyword arguments - *name* of type `str` and
2499 # *year* of type `int`.
2500 def foo(**kwargs: Unpack[Movie]): ...
2502Note that there is only some runtime checking of this operator. Not
2503everything the runtime allows may be accepted by static type checkers.
2505For more information, see PEP 646 and PEP 692.
2506"""
2509# PEP 692 changed the repr of Unpack[]
2510# Breakpoint: https://github.com/python/cpython/pull/104048
2511if sys.version_info >= (3, 12):
2512 Unpack = typing.Unpack
2514 def _is_unpack(obj):
2515 return get_origin(obj) is Unpack
2517else: # <=3.11
2518 class _UnpackSpecialForm(_ExtensionsSpecialForm, _root=True):
2519 def __init__(self, getitem):
2520 super().__init__(getitem)
2521 self.__doc__ = _UNPACK_DOC
2523 class _UnpackAlias(typing._GenericAlias, _root=True):
2524 if sys.version_info < (3, 11):
2525 # needed for compatibility with Generic[Unpack[Ts]]
2526 __class__ = typing.TypeVar
2528 @property
2529 def __typing_unpacked_tuple_args__(self):
2530 assert self.__origin__ is Unpack
2531 assert len(self.__args__) == 1
2532 arg, = self.__args__
2533 if isinstance(arg, (typing._GenericAlias, _types.GenericAlias)):
2534 if arg.__origin__ is not tuple:
2535 raise TypeError("Unpack[...] must be used with a tuple type")
2536 return arg.__args__
2537 return None
2539 @property
2540 def __typing_is_unpacked_typevartuple__(self):
2541 assert self.__origin__ is Unpack
2542 assert len(self.__args__) == 1
2543 return isinstance(self.__args__[0], TypeVarTuple)
2545 def __getitem__(self, args):
2546 if self.__typing_is_unpacked_typevartuple__:
2547 return args
2548 return super().__getitem__(args)
2550 @_UnpackSpecialForm
2551 def Unpack(self, parameters):
2552 item = typing._type_check(parameters, f'{self._name} accepts only a single type.')
2553 return _UnpackAlias(self, (item,))
2555 def _is_unpack(obj):
2556 return isinstance(obj, _UnpackAlias)
2559def _unpack_args(*args):
2560 newargs = []
2561 for arg in args:
2562 subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
2563 if subargs is not None and (not (subargs and subargs[-1] is ...)):
2564 newargs.extend(subargs)
2565 else:
2566 newargs.append(arg)
2567 return newargs
2570if _PEP_696_IMPLEMENTED:
2571 from typing import TypeVarTuple
2573elif hasattr(typing, "TypeVarTuple"): # 3.11+
2575 # Add default parameter - PEP 696
2576 class TypeVarTuple(metaclass=_TypeVarLikeMeta):
2577 """Type variable tuple."""
2579 _backported_typevarlike = typing.TypeVarTuple
2581 def __new__(cls, name, *, default=NoDefault):
2582 tvt = typing.TypeVarTuple(name)
2583 _set_default(tvt, default)
2584 _set_module(tvt)
2586 def _typevartuple_prepare_subst(alias, args):
2587 params = alias.__parameters__
2588 typevartuple_index = params.index(tvt)
2589 for param in params[typevartuple_index + 1:]:
2590 if isinstance(param, TypeVarTuple):
2591 raise TypeError(
2592 f"More than one TypeVarTuple parameter in {alias}"
2593 )
2595 alen = len(args)
2596 plen = len(params)
2597 left = typevartuple_index
2598 right = plen - typevartuple_index - 1
2599 var_tuple_index = None
2600 fillarg = None
2601 for k, arg in enumerate(args):
2602 if not isinstance(arg, type):
2603 subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
2604 if subargs and len(subargs) == 2 and subargs[-1] is ...:
2605 if var_tuple_index is not None:
2606 raise TypeError(
2607 "More than one unpacked "
2608 "arbitrary-length tuple argument"
2609 )
2610 var_tuple_index = k
2611 fillarg = subargs[0]
2612 if var_tuple_index is not None:
2613 left = min(left, var_tuple_index)
2614 right = min(right, alen - var_tuple_index - 1)
2615 elif left + right > alen:
2616 raise TypeError(f"Too few arguments for {alias};"
2617 f" actual {alen}, expected at least {plen - 1}")
2618 if left == alen - right and tvt.has_default():
2619 replacement = _unpack_args(tvt.__default__)
2620 else:
2621 replacement = args[left: alen - right]
2623 return (
2624 *args[:left],
2625 *([fillarg] * (typevartuple_index - left)),
2626 replacement,
2627 *([fillarg] * (plen - right - left - typevartuple_index - 1)),
2628 *args[alen - right:],
2629 )
2631 tvt.__typing_prepare_subst__ = _typevartuple_prepare_subst
2632 return tvt
2634 def __init_subclass__(self, *args, **kwds):
2635 raise TypeError("Cannot subclass special typing classes")
2637else: # <=3.10
2638 class TypeVarTuple(_DefaultMixin):
2639 """Type variable tuple.
2641 Usage::
2643 Ts = TypeVarTuple('Ts')
2645 In the same way that a normal type variable is a stand-in for a single
2646 type such as ``int``, a type variable *tuple* is a stand-in for a *tuple*
2647 type such as ``Tuple[int, str]``.
2649 Type variable tuples can be used in ``Generic`` declarations.
2650 Consider the following example::
2652 class Array(Generic[*Ts]): ...
2654 The ``Ts`` type variable tuple here behaves like ``tuple[T1, T2]``,
2655 where ``T1`` and ``T2`` are type variables. To use these type variables
2656 as type parameters of ``Array``, we must *unpack* the type variable tuple using
2657 the star operator: ``*Ts``. The signature of ``Array`` then behaves
2658 as if we had simply written ``class Array(Generic[T1, T2]): ...``.
2659 In contrast to ``Generic[T1, T2]``, however, ``Generic[*Shape]`` allows
2660 us to parameterise the class with an *arbitrary* number of type parameters.
2662 Type variable tuples can be used anywhere a normal ``TypeVar`` can.
2663 This includes class definitions, as shown above, as well as function
2664 signatures and variable annotations::
2666 class Array(Generic[*Ts]):
2668 def __init__(self, shape: Tuple[*Ts]):
2669 self._shape: Tuple[*Ts] = shape
2671 def get_shape(self) -> Tuple[*Ts]:
2672 return self._shape
2674 shape = (Height(480), Width(640))
2675 x: Array[Height, Width] = Array(shape)
2676 y = abs(x) # Inferred type is Array[Height, Width]
2677 z = x + x # ... is Array[Height, Width]
2678 x.get_shape() # ... is tuple[Height, Width]
2680 """
2682 # Trick Generic __parameters__.
2683 __class__ = typing.TypeVar
2685 def __iter__(self):
2686 yield self.__unpacked__
2688 def __init__(self, name, *, default=NoDefault):
2689 self.__name__ = name
2690 _DefaultMixin.__init__(self, default)
2692 # for pickling:
2693 def_mod = _caller()
2694 if def_mod != 'typing_extensions':
2695 self.__module__ = def_mod
2697 self.__unpacked__ = Unpack[self]
2699 def __repr__(self):
2700 return self.__name__
2702 def __hash__(self):
2703 return object.__hash__(self)
2705 def __eq__(self, other):
2706 return self is other
2708 def __reduce__(self):
2709 return self.__name__
2711 def __init_subclass__(self, *args, **kwds):
2712 if '_root' not in kwds:
2713 raise TypeError("Cannot subclass special typing classes")
2716if hasattr(typing, "reveal_type"): # 3.11+
2717 reveal_type = typing.reveal_type
2718else: # <=3.10
2719 def reveal_type(obj: T, /) -> T:
2720 """Reveal the inferred type of a variable.
2722 When a static type checker encounters a call to ``reveal_type()``,
2723 it will emit the inferred type of the argument::
2725 x: int = 1
2726 reveal_type(x)
2728 Running a static type checker (e.g., ``mypy``) on this example
2729 will produce output similar to 'Revealed type is "builtins.int"'.
2731 At runtime, the function prints the runtime type of the
2732 argument and returns it unchanged.
2734 """
2735 print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr)
2736 return obj
2739if hasattr(typing, "_ASSERT_NEVER_REPR_MAX_LENGTH"): # 3.11+
2740 _ASSERT_NEVER_REPR_MAX_LENGTH = typing._ASSERT_NEVER_REPR_MAX_LENGTH
2741else: # <=3.10
2742 _ASSERT_NEVER_REPR_MAX_LENGTH = 100
2745if hasattr(typing, "assert_never"): # 3.11+
2746 assert_never = typing.assert_never
2747else: # <=3.10
2748 def assert_never(arg: Never, /) -> Never:
2749 """Assert to the type checker that a line of code is unreachable.
2751 Example::
2753 def int_or_str(arg: int | str) -> None:
2754 match arg:
2755 case int():
2756 print("It's an int")
2757 case str():
2758 print("It's a str")
2759 case _:
2760 assert_never(arg)
2762 If a type checker finds that a call to assert_never() is
2763 reachable, it will emit an error.
2765 At runtime, this throws an exception when called.
2767 """
2768 value = repr(arg)
2769 if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
2770 value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...'
2771 raise AssertionError(f"Expected code to be unreachable, but got: {value}")
2774# dataclass_transform exists in 3.11 but lacks the frozen_default parameter
2775# Breakpoint: https://github.com/python/cpython/pull/99958
2776if sys.version_info >= (3, 12): # 3.12+
2777 dataclass_transform = typing.dataclass_transform
2778else: # <=3.11
2779 def dataclass_transform(
2780 *,
2781 eq_default: bool = True,
2782 order_default: bool = False,
2783 kw_only_default: bool = False,
2784 frozen_default: bool = False,
2785 field_specifiers: typing.Tuple[
2786 typing.Union[typing.Type[typing.Any], typing.Callable[..., typing.Any]],
2787 ...
2788 ] = (),
2789 **kwargs: typing.Any,
2790 ) -> typing.Callable[[T], T]:
2791 """Decorator that marks a function, class, or metaclass as providing
2792 dataclass-like behavior.
2794 Example:
2796 from typing_extensions import dataclass_transform
2798 _T = TypeVar("_T")
2800 # Used on a decorator function
2801 @dataclass_transform()
2802 def create_model(cls: type[_T]) -> type[_T]:
2803 ...
2804 return cls
2806 @create_model
2807 class CustomerModel:
2808 id: int
2809 name: str
2811 # Used on a base class
2812 @dataclass_transform()
2813 class ModelBase: ...
2815 class CustomerModel(ModelBase):
2816 id: int
2817 name: str
2819 # Used on a metaclass
2820 @dataclass_transform()
2821 class ModelMeta(type): ...
2823 class ModelBase(metaclass=ModelMeta): ...
2825 class CustomerModel(ModelBase):
2826 id: int
2827 name: str
2829 Each of the ``CustomerModel`` classes defined in this example will now
2830 behave similarly to a dataclass created with the ``@dataclasses.dataclass``
2831 decorator. For example, the type checker will synthesize an ``__init__``
2832 method.
2834 The arguments to this decorator can be used to customize this behavior:
2835 - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
2836 True or False if it is omitted by the caller.
2837 - ``order_default`` indicates whether the ``order`` parameter is
2838 assumed to be True or False if it is omitted by the caller.
2839 - ``kw_only_default`` indicates whether the ``kw_only`` parameter is
2840 assumed to be True or False if it is omitted by the caller.
2841 - ``frozen_default`` indicates whether the ``frozen`` parameter is
2842 assumed to be True or False if it is omitted by the caller.
2843 - ``field_specifiers`` specifies a static list of supported classes
2844 or functions that describe fields, similar to ``dataclasses.field()``.
2846 At runtime, this decorator records its arguments in the
2847 ``__dataclass_transform__`` attribute on the decorated object.
2849 See PEP 681 for details.
2851 """
2852 def decorator(cls_or_fn):
2853 cls_or_fn.__dataclass_transform__ = {
2854 "eq_default": eq_default,
2855 "order_default": order_default,
2856 "kw_only_default": kw_only_default,
2857 "frozen_default": frozen_default,
2858 "field_specifiers": field_specifiers,
2859 "kwargs": kwargs,
2860 }
2861 return cls_or_fn
2862 return decorator
2865if hasattr(typing, "override"): # 3.12+
2866 override = typing.override
2867else: # <=3.11
2868 _F = typing.TypeVar("_F", bound=typing.Callable[..., typing.Any])
2870 def override(arg: _F, /) -> _F:
2871 """Indicate that a method is intended to override a method in a base class.
2873 Usage:
2875 class Base:
2876 def method(self) -> None:
2877 pass
2879 class Child(Base):
2880 @override
2881 def method(self) -> None:
2882 super().method()
2884 When this decorator is applied to a method, the type checker will
2885 validate that it overrides a method with the same name on a base class.
2886 This helps prevent bugs that may occur when a base class is changed
2887 without an equivalent change to a child class.
2889 There is no runtime checking of these properties. The decorator
2890 sets the ``__override__`` attribute to ``True`` on the decorated object
2891 to allow runtime introspection.
2893 See PEP 698 for details.
2895 """
2896 try:
2897 arg.__override__ = True
2898 except (AttributeError, TypeError):
2899 # Skip the attribute silently if it is not writable.
2900 # AttributeError happens if the object has __slots__ or a
2901 # read-only property, TypeError if it's a builtin class.
2902 pass
2903 return arg
2906# Python 3.13.3+ contains a fix for the wrapped __new__
2907# Breakpoint: https://github.com/python/cpython/pull/132160
2908if sys.version_info >= (3, 13, 3):
2909 deprecated = warnings.deprecated
2910else:
2911 _T = typing.TypeVar("_T")
2913 class deprecated:
2914 """Indicate that a class, function or overload is deprecated.
2916 When this decorator is applied to an object, the type checker
2917 will generate a diagnostic on usage of the deprecated object.
2919 Usage:
2921 @deprecated("Use B instead")
2922 class A:
2923 pass
2925 @deprecated("Use g instead")
2926 def f():
2927 pass
2929 @overload
2930 @deprecated("int support is deprecated")
2931 def g(x: int) -> int: ...
2932 @overload
2933 def g(x: str) -> int: ...
2935 The warning specified by *category* will be emitted at runtime
2936 on use of deprecated objects. For functions, that happens on calls;
2937 for classes, on instantiation and on creation of subclasses.
2938 If the *category* is ``None``, no warning is emitted at runtime.
2939 The *stacklevel* determines where the
2940 warning is emitted. If it is ``1`` (the default), the warning
2941 is emitted at the direct caller of the deprecated object; if it
2942 is higher, it is emitted further up the stack.
2943 Static type checker behavior is not affected by the *category*
2944 and *stacklevel* arguments.
2946 The deprecation message passed to the decorator is saved in the
2947 ``__deprecated__`` attribute on the decorated object.
2948 If applied to an overload, the decorator
2949 must be after the ``@overload`` decorator for the attribute to
2950 exist on the overload as returned by ``get_overloads()``.
2952 See PEP 702 for details.
2954 """
2955 def __init__(
2956 self,
2957 message: str,
2958 /,
2959 *,
2960 category: typing.Optional[typing.Type[Warning]] = DeprecationWarning,
2961 stacklevel: int = 1,
2962 ) -> None:
2963 if not isinstance(message, str):
2964 raise TypeError(
2965 "Expected an object of type str for 'message', not "
2966 f"{type(message).__name__!r}"
2967 )
2968 self.message = message
2969 self.category = category
2970 self.stacklevel = stacklevel
2972 def __call__(self, arg: _T, /) -> _T:
2973 # Make sure the inner functions created below don't
2974 # retain a reference to self.
2975 msg = self.message
2976 category = self.category
2977 stacklevel = self.stacklevel
2978 if category is None:
2979 arg.__deprecated__ = msg
2980 return arg
2981 elif isinstance(arg, type):
2982 import functools
2983 from types import MethodType
2985 original_new = arg.__new__
2987 @functools.wraps(original_new)
2988 def __new__(cls, /, *args, **kwargs):
2989 if cls is arg:
2990 warnings.warn(msg, category=category, stacklevel=stacklevel + 1)
2991 if original_new is not object.__new__:
2992 return original_new(cls, *args, **kwargs)
2993 # Mirrors a similar check in object.__new__.
2994 elif cls.__init__ is object.__init__ and (args or kwargs):
2995 raise TypeError(f"{cls.__name__}() takes no arguments")
2996 else:
2997 return original_new(cls)
2999 arg.__new__ = staticmethod(__new__)
3001 original_init_subclass = arg.__init_subclass__
3002 # We need slightly different behavior if __init_subclass__
3003 # is a bound method (likely if it was implemented in Python)
3004 if isinstance(original_init_subclass, MethodType):
3005 original_init_subclass = original_init_subclass.__func__
3007 @functools.wraps(original_init_subclass)
3008 def __init_subclass__(*args, **kwargs):
3009 warnings.warn(msg, category=category, stacklevel=stacklevel + 1)
3010 return original_init_subclass(*args, **kwargs)
3012 arg.__init_subclass__ = classmethod(__init_subclass__)
3013 # Or otherwise, which likely means it's a builtin such as
3014 # object's implementation of __init_subclass__.
3015 else:
3016 @functools.wraps(original_init_subclass)
3017 def __init_subclass__(*args, **kwargs):
3018 warnings.warn(msg, category=category, stacklevel=stacklevel + 1)
3019 return original_init_subclass(*args, **kwargs)
3021 arg.__init_subclass__ = __init_subclass__
3023 arg.__deprecated__ = __new__.__deprecated__ = msg
3024 __init_subclass__.__deprecated__ = msg
3025 return arg
3026 elif callable(arg):
3027 import asyncio.coroutines
3028 import functools
3029 import inspect
3031 @functools.wraps(arg)
3032 def wrapper(*args, **kwargs):
3033 warnings.warn(msg, category=category, stacklevel=stacklevel + 1)
3034 return arg(*args, **kwargs)
3036 if asyncio.coroutines.iscoroutinefunction(arg):
3037 # Breakpoint: https://github.com/python/cpython/pull/99247
3038 if sys.version_info >= (3, 12):
3039 wrapper = inspect.markcoroutinefunction(wrapper)
3040 else:
3041 wrapper._is_coroutine = asyncio.coroutines._is_coroutine
3043 arg.__deprecated__ = wrapper.__deprecated__ = msg
3044 return wrapper
3045 else:
3046 raise TypeError(
3047 "@deprecated decorator with non-None category must be applied to "
3048 f"a class or callable, not {arg!r}"
3049 )
3051# Breakpoint: https://github.com/python/cpython/pull/23702
3052if sys.version_info < (3, 10):
3053 def _is_param_expr(arg):
3054 return arg is ... or isinstance(
3055 arg, (tuple, list, ParamSpec, _ConcatenateGenericAlias)
3056 )
3057else:
3058 def _is_param_expr(arg):
3059 return arg is ... or isinstance(
3060 arg,
3061 (
3062 tuple,
3063 list,
3064 ParamSpec,
3065 _ConcatenateGenericAlias,
3066 typing._ConcatenateGenericAlias,
3067 ),
3068 )
3071# We have to do some monkey patching to deal with the dual nature of
3072# Unpack/TypeVarTuple:
3073# - We want Unpack to be a kind of TypeVar so it gets accepted in
3074# Generic[Unpack[Ts]]
3075# - We want it to *not* be treated as a TypeVar for the purposes of
3076# counting generic parameters, so that when we subscript a generic,
3077# the runtime doesn't try to substitute the Unpack with the subscripted type.
3078if not hasattr(typing, "TypeVarTuple"):
3079 def _check_generic(cls, parameters, elen=_marker):
3080 """Check correct count for parameters of a generic cls (internal helper).
3082 This gives a nice error message in case of count mismatch.
3083 """
3084 # If substituting a single ParamSpec with multiple arguments
3085 # we do not check the count
3086 if (inspect.isclass(cls) and issubclass(cls, typing.Generic)
3087 and len(cls.__parameters__) == 1
3088 and isinstance(cls.__parameters__[0], ParamSpec)
3089 and parameters
3090 and not _is_param_expr(parameters[0])
3091 ):
3092 # Generic modifies parameters variable, but here we cannot do this
3093 return
3095 if not elen:
3096 raise TypeError(f"{cls} is not a generic class")
3097 if elen is _marker:
3098 if not hasattr(cls, "__parameters__") or not cls.__parameters__:
3099 raise TypeError(f"{cls} is not a generic class")
3100 elen = len(cls.__parameters__)
3101 alen = len(parameters)
3102 if alen != elen:
3103 expect_val = elen
3104 if hasattr(cls, "__parameters__"):
3105 parameters = [p for p in cls.__parameters__ if not _is_unpack(p)]
3106 num_tv_tuples = sum(isinstance(p, TypeVarTuple) for p in parameters)
3107 if (num_tv_tuples > 0) and (alen >= elen - num_tv_tuples):
3108 return
3110 # deal with TypeVarLike defaults
3111 # required TypeVarLikes cannot appear after a defaulted one.
3112 if alen < elen:
3113 # since we validate TypeVarLike default in _collect_type_vars
3114 # or _collect_parameters we can safely check parameters[alen]
3115 if (
3116 getattr(parameters[alen], '__default__', NoDefault)
3117 is not NoDefault
3118 ):
3119 return
3121 num_default_tv = sum(getattr(p, '__default__', NoDefault)
3122 is not NoDefault for p in parameters)
3124 elen -= num_default_tv
3126 expect_val = f"at least {elen}"
3128 # Breakpoint: https://github.com/python/cpython/pull/27515
3129 things = "arguments" if sys.version_info >= (3, 10) else "parameters"
3130 raise TypeError(f"Too {'many' if alen > elen else 'few'} {things}"
3131 f" for {cls}; actual {alen}, expected {expect_val}")
3132else:
3133 # Python 3.11+
3135 def _check_generic(cls, parameters, elen):
3136 """Check correct count for parameters of a generic cls (internal helper).
3138 This gives a nice error message in case of count mismatch.
3139 """
3140 if not elen:
3141 raise TypeError(f"{cls} is not a generic class")
3142 alen = len(parameters)
3143 if alen != elen:
3144 expect_val = elen
3145 if hasattr(cls, "__parameters__"):
3146 parameters = [p for p in cls.__parameters__ if not _is_unpack(p)]
3148 # deal with TypeVarLike defaults
3149 # required TypeVarLikes cannot appear after a defaulted one.
3150 if alen < elen:
3151 # since we validate TypeVarLike default in _collect_type_vars
3152 # or _collect_parameters we can safely check parameters[alen]
3153 if (
3154 getattr(parameters[alen], '__default__', NoDefault)
3155 is not NoDefault
3156 ):
3157 return
3159 num_default_tv = sum(getattr(p, '__default__', NoDefault)
3160 is not NoDefault for p in parameters)
3162 elen -= num_default_tv
3164 expect_val = f"at least {elen}"
3166 raise TypeError(f"Too {'many' if alen > elen else 'few'} arguments"
3167 f" for {cls}; actual {alen}, expected {expect_val}")
3169if not _PEP_696_IMPLEMENTED:
3170 typing._check_generic = _check_generic
3173def _has_generic_or_protocol_as_origin() -> bool:
3174 try:
3175 frame = sys._getframe(2)
3176 # - Catch AttributeError: not all Python implementations have sys._getframe()
3177 # - Catch ValueError: maybe we're called from an unexpected module
3178 # and the call stack isn't deep enough
3179 except (AttributeError, ValueError):
3180 return False # err on the side of leniency
3181 else:
3182 # If we somehow get invoked from outside typing.py,
3183 # also err on the side of leniency
3184 if frame.f_globals.get("__name__") != "typing":
3185 return False
3186 origin = frame.f_locals.get("origin")
3187 # Cannot use "in" because origin may be an object with a buggy __eq__ that
3188 # throws an error.
3189 return origin is typing.Generic or origin is Protocol or origin is typing.Protocol
3192_TYPEVARTUPLE_TYPES = {TypeVarTuple, getattr(typing, "TypeVarTuple", None)}
3195def _is_unpacked_typevartuple(x) -> bool:
3196 if get_origin(x) is not Unpack:
3197 return False
3198 args = get_args(x)
3199 return (
3200 bool(args)
3201 and len(args) == 1
3202 and type(args[0]) in _TYPEVARTUPLE_TYPES
3203 )
3206# Python 3.11+ _collect_type_vars was renamed to _collect_parameters
3207if hasattr(typing, '_collect_type_vars'):
3208 def _collect_type_vars(types, typevar_types=None):
3209 """Collect all type variable contained in types in order of
3210 first appearance (lexicographic order). For example::
3212 _collect_type_vars((T, List[S, T])) == (T, S)
3213 """
3214 if typevar_types is None:
3215 typevar_types = typing.TypeVar
3216 tvars = []
3218 # A required TypeVarLike cannot appear after a TypeVarLike with a default
3219 # if it was a direct call to `Generic[]` or `Protocol[]`
3220 enforce_default_ordering = _has_generic_or_protocol_as_origin()
3221 default_encountered = False
3223 # Also, a TypeVarLike with a default cannot appear after a TypeVarTuple
3224 type_var_tuple_encountered = False
3226 for t in types:
3227 if _is_unpacked_typevartuple(t):
3228 type_var_tuple_encountered = True
3229 elif (
3230 isinstance(t, typevar_types) and not isinstance(t, _UnpackAlias)
3231 and t not in tvars
3232 ):
3233 if enforce_default_ordering:
3234 has_default = getattr(t, '__default__', NoDefault) is not NoDefault
3235 if has_default:
3236 if type_var_tuple_encountered:
3237 raise TypeError('Type parameter with a default'
3238 ' follows TypeVarTuple')
3239 default_encountered = True
3240 elif default_encountered:
3241 raise TypeError(f'Type parameter {t!r} without a default'
3242 ' follows type parameter with a default')
3244 tvars.append(t)
3245 if _should_collect_from_parameters(t):
3246 tvars.extend([t for t in t.__parameters__ if t not in tvars])
3247 elif isinstance(t, tuple):
3248 # Collect nested type_vars
3249 # tuple wrapped by _prepare_paramspec_params(cls, params)
3250 for x in t:
3251 for collected in _collect_type_vars([x]):
3252 if collected not in tvars:
3253 tvars.append(collected)
3254 return tuple(tvars)
3256 typing._collect_type_vars = _collect_type_vars
3257else:
3258 def _collect_parameters(args):
3259 """Collect all type variables and parameter specifications in args
3260 in order of first appearance (lexicographic order).
3262 For example::
3264 assert _collect_parameters((T, Callable[P, T])) == (T, P)
3265 """
3266 parameters = []
3268 # A required TypeVarLike cannot appear after a TypeVarLike with default
3269 # if it was a direct call to `Generic[]` or `Protocol[]`
3270 enforce_default_ordering = _has_generic_or_protocol_as_origin()
3271 default_encountered = False
3273 # Also, a TypeVarLike with a default cannot appear after a TypeVarTuple
3274 type_var_tuple_encountered = False
3276 for t in args:
3277 if isinstance(t, type):
3278 # We don't want __parameters__ descriptor of a bare Python class.
3279 pass
3280 elif isinstance(t, tuple):
3281 # `t` might be a tuple, when `ParamSpec` is substituted with
3282 # `[T, int]`, or `[int, *Ts]`, etc.
3283 for x in t:
3284 for collected in _collect_parameters([x]):
3285 if collected not in parameters:
3286 parameters.append(collected)
3287 elif hasattr(t, '__typing_subst__'):
3288 if t not in parameters:
3289 if enforce_default_ordering:
3290 has_default = (
3291 getattr(t, '__default__', NoDefault) is not NoDefault
3292 )
3294 if type_var_tuple_encountered and has_default:
3295 raise TypeError('Type parameter with a default'
3296 ' follows TypeVarTuple')
3298 if has_default:
3299 default_encountered = True
3300 elif default_encountered:
3301 raise TypeError(f'Type parameter {t!r} without a default'
3302 ' follows type parameter with a default')
3304 parameters.append(t)
3305 else:
3306 if _is_unpacked_typevartuple(t):
3307 type_var_tuple_encountered = True
3308 for x in getattr(t, '__parameters__', ()):
3309 if x not in parameters:
3310 parameters.append(x)
3312 return tuple(parameters)
3314 if not _PEP_696_IMPLEMENTED:
3315 typing._collect_parameters = _collect_parameters
3317# Backport typing.NamedTuple as it exists in Python 3.13.
3318# In 3.11, the ability to define generic `NamedTuple`s was supported.
3319# This was explicitly disallowed in 3.9-3.10, and only half-worked in <=3.8.
3320# On 3.12, we added __orig_bases__ to call-based NamedTuples
3321# On 3.13, we deprecated kwargs-based NamedTuples
3322# Breakpoint: https://github.com/python/cpython/pull/105609
3323if sys.version_info >= (3, 13):
3324 NamedTuple = typing.NamedTuple
3325else:
3326 def _make_nmtuple(name, types, module, defaults=()):
3327 fields = [n for n, t in types]
3328 annotations = {n: typing._type_check(t, f"field {n} annotation must be a type")
3329 for n, t in types}
3330 nm_tpl = collections.namedtuple(name, fields,
3331 defaults=defaults, module=module)
3332 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = annotations
3333 return nm_tpl
3335 _prohibited_namedtuple_fields = typing._prohibited
3336 _special_namedtuple_fields = frozenset({'__module__', '__name__', '__annotations__'})
3338 class _NamedTupleMeta(type):
3339 def __new__(cls, typename, bases, ns):
3340 assert _NamedTuple in bases
3341 for base in bases:
3342 if base is not _NamedTuple and base is not typing.Generic:
3343 raise TypeError(
3344 'can only inherit from a NamedTuple type and Generic')
3345 bases = tuple(tuple if base is _NamedTuple else base for base in bases)
3346 if "__annotations__" in ns:
3347 types = ns["__annotations__"]
3348 elif "__annotate__" in ns:
3349 # TODO: Use inspect.VALUE here, and make the annotations lazily evaluated
3350 types = ns["__annotate__"](1)
3351 else:
3352 types = {}
3353 default_names = []
3354 for field_name in types:
3355 if field_name in ns:
3356 default_names.append(field_name)
3357 elif default_names:
3358 raise TypeError(f"Non-default namedtuple field {field_name} "
3359 f"cannot follow default field"
3360 f"{'s' if len(default_names) > 1 else ''} "
3361 f"{', '.join(default_names)}")
3362 nm_tpl = _make_nmtuple(
3363 typename, types.items(),
3364 defaults=[ns[n] for n in default_names],
3365 module=ns['__module__']
3366 )
3367 nm_tpl.__bases__ = bases
3368 if typing.Generic in bases:
3369 if hasattr(typing, '_generic_class_getitem'): # 3.12+
3370 nm_tpl.__class_getitem__ = classmethod(typing._generic_class_getitem)
3371 else:
3372 class_getitem = typing.Generic.__class_getitem__.__func__
3373 nm_tpl.__class_getitem__ = classmethod(class_getitem)
3374 # update from user namespace without overriding special namedtuple attributes
3375 for key, val in ns.items():
3376 if key in _prohibited_namedtuple_fields:
3377 raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
3378 elif key not in _special_namedtuple_fields:
3379 if key not in nm_tpl._fields:
3380 setattr(nm_tpl, key, ns[key])
3381 try:
3382 set_name = type(val).__set_name__
3383 except AttributeError:
3384 pass
3385 else:
3386 try:
3387 set_name(val, nm_tpl, key)
3388 except BaseException as e:
3389 msg = (
3390 f"Error calling __set_name__ on {type(val).__name__!r} "
3391 f"instance {key!r} in {typename!r}"
3392 )
3393 # BaseException.add_note() existed on py311,
3394 # but the __set_name__ machinery didn't start
3395 # using add_note() until py312.
3396 # Making sure exceptions are raised in the same way
3397 # as in "normal" classes seems most important here.
3398 # Breakpoint: https://github.com/python/cpython/pull/95915
3399 if sys.version_info >= (3, 12):
3400 e.add_note(msg)
3401 raise
3402 else:
3403 raise RuntimeError(msg) from e
3405 if typing.Generic in bases:
3406 nm_tpl.__init_subclass__()
3407 return nm_tpl
3409 _NamedTuple = type.__new__(_NamedTupleMeta, 'NamedTuple', (), {})
3411 def _namedtuple_mro_entries(bases):
3412 assert NamedTuple in bases
3413 return (_NamedTuple,)
3415 def NamedTuple(typename, fields=_marker, /, **kwargs):
3416 """Typed version of namedtuple.
3418 Usage::
3420 class Employee(NamedTuple):
3421 name: str
3422 id: int
3424 This is equivalent to::
3426 Employee = collections.namedtuple('Employee', ['name', 'id'])
3428 The resulting class has an extra __annotations__ attribute, giving a
3429 dict that maps field names to types. (The field names are also in
3430 the _fields attribute, which is part of the namedtuple API.)
3431 An alternative equivalent functional syntax is also accepted::
3433 Employee = NamedTuple('Employee', [('name', str), ('id', int)])
3434 """
3435 if fields is _marker:
3436 if kwargs:
3437 deprecated_thing = "Creating NamedTuple classes using keyword arguments"
3438 deprecation_msg = (
3439 "{name} is deprecated and will be disallowed in Python {remove}. "
3440 "Use the class-based or functional syntax instead."
3441 )
3442 else:
3443 deprecated_thing = "Failing to pass a value for the 'fields' parameter"
3444 example = f"`{typename} = NamedTuple({typename!r}, [])`"
3445 deprecation_msg = (
3446 "{name} is deprecated and will be disallowed in Python {remove}. "
3447 "To create a NamedTuple class with 0 fields "
3448 "using the functional syntax, "
3449 "pass an empty list, e.g. "
3450 ) + example + "."
3451 elif fields is None:
3452 if kwargs:
3453 raise TypeError(
3454 "Cannot pass `None` as the 'fields' parameter "
3455 "and also specify fields using keyword arguments"
3456 )
3457 else:
3458 deprecated_thing = "Passing `None` as the 'fields' parameter"
3459 example = f"`{typename} = NamedTuple({typename!r}, [])`"
3460 deprecation_msg = (
3461 "{name} is deprecated and will be disallowed in Python {remove}. "
3462 "To create a NamedTuple class with 0 fields "
3463 "using the functional syntax, "
3464 "pass an empty list, e.g. "
3465 ) + example + "."
3466 elif kwargs:
3467 raise TypeError("Either list of fields or keywords"
3468 " can be provided to NamedTuple, not both")
3469 if fields is _marker or fields is None:
3470 warnings.warn(
3471 deprecation_msg.format(name=deprecated_thing, remove="3.15"),
3472 DeprecationWarning,
3473 stacklevel=2,
3474 )
3475 fields = kwargs.items()
3476 nt = _make_nmtuple(typename, fields, module=_caller())
3477 nt.__orig_bases__ = (NamedTuple,)
3478 return nt
3480 NamedTuple.__mro_entries__ = _namedtuple_mro_entries
3483if hasattr(collections.abc, "Buffer"):
3484 Buffer = collections.abc.Buffer
3485else:
3486 class Buffer(abc.ABC): # noqa: B024
3487 """Base class for classes that implement the buffer protocol.
3489 The buffer protocol allows Python objects to expose a low-level
3490 memory buffer interface. Before Python 3.12, it is not possible
3491 to implement the buffer protocol in pure Python code, or even
3492 to check whether a class implements the buffer protocol. In
3493 Python 3.12 and higher, the ``__buffer__`` method allows access
3494 to the buffer protocol from Python code, and the
3495 ``collections.abc.Buffer`` ABC allows checking whether a class
3496 implements the buffer protocol.
3498 To indicate support for the buffer protocol in earlier versions,
3499 inherit from this ABC, either in a stub file or at runtime,
3500 or use ABC registration. This ABC provides no methods, because
3501 there is no Python-accessible methods shared by pre-3.12 buffer
3502 classes. It is useful primarily for static checks.
3504 """
3506 # As a courtesy, register the most common stdlib buffer classes.
3507 Buffer.register(memoryview)
3508 Buffer.register(bytearray)
3509 Buffer.register(bytes)
3512# Backport of types.get_original_bases, available on 3.12+ in CPython
3513if hasattr(_types, "get_original_bases"):
3514 get_original_bases = _types.get_original_bases
3515else:
3516 def get_original_bases(cls, /):
3517 """Return the class's "original" bases prior to modification by `__mro_entries__`.
3519 Examples::
3521 from typing import TypeVar, Generic
3522 from typing_extensions import NamedTuple, TypedDict
3524 T = TypeVar("T")
3525 class Foo(Generic[T]): ...
3526 class Bar(Foo[int], float): ...
3527 class Baz(list[str]): ...
3528 Eggs = NamedTuple("Eggs", [("a", int), ("b", str)])
3529 Spam = TypedDict("Spam", {"a": int, "b": str})
3531 assert get_original_bases(Bar) == (Foo[int], float)
3532 assert get_original_bases(Baz) == (list[str],)
3533 assert get_original_bases(Eggs) == (NamedTuple,)
3534 assert get_original_bases(Spam) == (TypedDict,)
3535 assert get_original_bases(int) == (object,)
3536 """
3537 try:
3538 return cls.__dict__.get("__orig_bases__", cls.__bases__)
3539 except AttributeError:
3540 raise TypeError(
3541 f'Expected an instance of type, not {type(cls).__name__!r}'
3542 ) from None
3545# NewType is a class on Python 3.10+, making it pickleable
3546# The error message for subclassing instances of NewType was improved on 3.11+
3547# Breakpoint: https://github.com/python/cpython/pull/30268
3548if sys.version_info >= (3, 11):
3549 NewType = typing.NewType
3550else:
3551 class NewType:
3552 """NewType creates simple unique types with almost zero
3553 runtime overhead. NewType(name, tp) is considered a subtype of tp
3554 by static type checkers. At runtime, NewType(name, tp) returns
3555 a dummy callable that simply returns its argument. Usage::
3556 UserId = NewType('UserId', int)
3557 def name_by_id(user_id: UserId) -> str:
3558 ...
3559 UserId('user') # Fails type check
3560 name_by_id(42) # Fails type check
3561 name_by_id(UserId(42)) # OK
3562 num = UserId(5) + 1 # type: int
3563 """
3565 def __call__(self, obj, /):
3566 return obj
3568 def __init__(self, name, tp):
3569 self.__qualname__ = name
3570 if '.' in name:
3571 name = name.rpartition('.')[-1]
3572 self.__name__ = name
3573 self.__supertype__ = tp
3574 def_mod = _caller()
3575 if def_mod != 'typing_extensions':
3576 self.__module__ = def_mod
3578 def __mro_entries__(self, bases):
3579 # We defined __mro_entries__ to get a better error message
3580 # if a user attempts to subclass a NewType instance. bpo-46170
3581 supercls_name = self.__name__
3583 class Dummy:
3584 def __init_subclass__(cls):
3585 subcls_name = cls.__name__
3586 raise TypeError(
3587 f"Cannot subclass an instance of NewType. "
3588 f"Perhaps you were looking for: "
3589 f"`{subcls_name} = NewType({subcls_name!r}, {supercls_name})`"
3590 )
3592 return (Dummy,)
3594 def __repr__(self):
3595 return f'{self.__module__}.{self.__qualname__}'
3597 def __reduce__(self):
3598 return self.__qualname__
3600 # Breakpoint: https://github.com/python/cpython/pull/21515
3601 if sys.version_info >= (3, 10):
3602 # PEP 604 methods
3603 # It doesn't make sense to have these methods on Python <3.10
3605 def __or__(self, other):
3606 return typing.Union[self, other]
3608 def __ror__(self, other):
3609 return typing.Union[other, self]
3612# Breakpoint: https://github.com/python/cpython/pull/124795
3613if sys.version_info >= (3, 14):
3614 TypeAliasType = typing.TypeAliasType
3615# <=3.13
3616else:
3617 # Breakpoint: https://github.com/python/cpython/pull/103764
3618 if sys.version_info >= (3, 12):
3619 # 3.12-3.13
3620 def _is_unionable(obj):
3621 """Corresponds to is_unionable() in unionobject.c in CPython."""
3622 return obj is None or isinstance(obj, (
3623 type,
3624 _types.GenericAlias,
3625 _types.UnionType,
3626 typing.TypeAliasType,
3627 TypeAliasType,
3628 ))
3629 else:
3630 # <=3.11
3631 def _is_unionable(obj):
3632 """Corresponds to is_unionable() in unionobject.c in CPython."""
3633 return obj is None or isinstance(obj, (
3634 type,
3635 _types.GenericAlias,
3636 _types.UnionType,
3637 TypeAliasType,
3638 ))
3640 if sys.version_info < (3, 10):
3641 # Copied and pasted from https://github.com/python/cpython/blob/986a4e1b6fcae7fe7a1d0a26aea446107dd58dd2/Objects/genericaliasobject.c#L568-L582,
3642 # so that we emulate the behaviour of `types.GenericAlias`
3643 # on the latest versions of CPython
3644 _ATTRIBUTE_DELEGATION_EXCLUSIONS = frozenset({
3645 "__class__",
3646 "__bases__",
3647 "__origin__",
3648 "__args__",
3649 "__unpacked__",
3650 "__parameters__",
3651 "__typing_unpacked_tuple_args__",
3652 "__mro_entries__",
3653 "__reduce_ex__",
3654 "__reduce__",
3655 "__copy__",
3656 "__deepcopy__",
3657 })
3659 class _TypeAliasGenericAlias(typing._GenericAlias, _root=True):
3660 def __getattr__(self, attr):
3661 if attr in _ATTRIBUTE_DELEGATION_EXCLUSIONS:
3662 return object.__getattr__(self, attr)
3663 return getattr(self.__origin__, attr)
3666 class TypeAliasType:
3667 """Create named, parameterized type aliases.
3669 This provides a backport of the new `type` statement in Python 3.12:
3671 type ListOrSet[T] = list[T] | set[T]
3673 is equivalent to:
3675 T = TypeVar("T")
3676 ListOrSet = TypeAliasType("ListOrSet", list[T] | set[T], type_params=(T,))
3678 The name ListOrSet can then be used as an alias for the type it refers to.
3680 The type_params argument should contain all the type parameters used
3681 in the value of the type alias. If the alias is not generic, this
3682 argument is omitted.
3684 Static type checkers should only support type aliases declared using
3685 TypeAliasType that follow these rules:
3687 - The first argument (the name) must be a string literal.
3688 - The TypeAliasType instance must be immediately assigned to a variable
3689 of the same name. (For example, 'X = TypeAliasType("Y", int)' is invalid,
3690 as is 'X, Y = TypeAliasType("X", int), TypeAliasType("Y", int)').
3692 """
3694 def __init__(self, name: str, value, *, type_params=()):
3695 if not isinstance(name, str):
3696 raise TypeError("TypeAliasType name must be a string")
3697 if not isinstance(type_params, tuple):
3698 raise TypeError("type_params must be a tuple")
3699 self.__value__ = value
3700 self.__type_params__ = type_params
3702 default_value_encountered = False
3703 parameters = []
3704 for type_param in type_params:
3705 if (
3706 not isinstance(type_param, (TypeVar, TypeVarTuple, ParamSpec))
3707 # <=3.11
3708 # Unpack Backport passes isinstance(type_param, TypeVar)
3709 or _is_unpack(type_param)
3710 ):
3711 raise TypeError(f"Expected a type param, got {type_param!r}")
3712 has_default = (
3713 getattr(type_param, '__default__', NoDefault) is not NoDefault
3714 )
3715 if default_value_encountered and not has_default:
3716 raise TypeError(f"non-default type parameter '{type_param!r}'"
3717 " follows default type parameter")
3718 if has_default:
3719 default_value_encountered = True
3720 if isinstance(type_param, TypeVarTuple):
3721 parameters.extend(type_param)
3722 else:
3723 parameters.append(type_param)
3724 self.__parameters__ = tuple(parameters)
3725 def_mod = _caller()
3726 if def_mod != 'typing_extensions':
3727 self.__module__ = def_mod
3728 # Setting this attribute closes the TypeAliasType from further modification
3729 self.__name__ = name
3731 def __setattr__(self, name: str, value: object, /) -> None:
3732 if hasattr(self, "__name__"):
3733 self._raise_attribute_error(name)
3734 super().__setattr__(name, value)
3736 def __delattr__(self, name: str, /) -> Never:
3737 self._raise_attribute_error(name)
3739 def _raise_attribute_error(self, name: str) -> Never:
3740 # Match the Python 3.12 error messages exactly
3741 if name == "__name__":
3742 raise AttributeError("readonly attribute")
3743 elif name in {"__value__", "__type_params__", "__parameters__", "__module__"}:
3744 raise AttributeError(
3745 f"attribute '{name}' of 'typing.TypeAliasType' objects "
3746 "is not writable"
3747 )
3748 else:
3749 raise AttributeError(
3750 f"'typing.TypeAliasType' object has no attribute '{name}'"
3751 )
3753 def __repr__(self) -> str:
3754 return self.__name__
3756 if sys.version_info < (3, 11):
3757 def _check_single_param(self, param, recursion=0):
3758 # Allow [], [int], [int, str], [int, ...], [int, T]
3759 if param is ...:
3760 return ...
3761 if param is None:
3762 return None
3763 # Note in <= 3.9 _ConcatenateGenericAlias inherits from list
3764 if isinstance(param, list) and recursion == 0:
3765 return [self._check_single_param(arg, recursion+1)
3766 for arg in param]
3767 return typing._type_check(
3768 param, f'Subscripting {self.__name__} requires a type.'
3769 )
3771 def _check_parameters(self, parameters):
3772 if sys.version_info < (3, 11):
3773 return tuple(
3774 self._check_single_param(item)
3775 for item in parameters
3776 )
3777 return tuple(typing._type_check(
3778 item, f'Subscripting {self.__name__} requires a type.'
3779 )
3780 for item in parameters
3781 )
3783 def __getitem__(self, parameters):
3784 if not self.__type_params__:
3785 raise TypeError("Only generic type aliases are subscriptable")
3786 if not isinstance(parameters, tuple):
3787 parameters = (parameters,)
3788 # Using 3.9 here will create problems with Concatenate
3789 if sys.version_info >= (3, 10):
3790 return _types.GenericAlias(self, parameters)
3791 type_vars = _collect_type_vars(parameters)
3792 parameters = self._check_parameters(parameters)
3793 alias = _TypeAliasGenericAlias(self, parameters)
3794 # alias.__parameters__ is not complete if Concatenate is present
3795 # as it is converted to a list from which no parameters are extracted.
3796 if alias.__parameters__ != type_vars:
3797 alias.__parameters__ = type_vars
3798 return alias
3800 def __reduce__(self):
3801 return self.__name__
3803 def __init_subclass__(cls, *args, **kwargs):
3804 raise TypeError(
3805 "type 'typing_extensions.TypeAliasType' is not an acceptable base type"
3806 )
3808 # The presence of this method convinces typing._type_check
3809 # that TypeAliasTypes are types.
3810 def __call__(self):
3811 raise TypeError("Type alias is not callable")
3813 # Breakpoint: https://github.com/python/cpython/pull/21515
3814 if sys.version_info >= (3, 10):
3815 def __or__(self, right):
3816 # For forward compatibility with 3.12, reject Unions
3817 # that are not accepted by the built-in Union.
3818 if not _is_unionable(right):
3819 return NotImplemented
3820 return typing.Union[self, right]
3822 def __ror__(self, left):
3823 if not _is_unionable(left):
3824 return NotImplemented
3825 return typing.Union[left, self]
3828if hasattr(typing, "is_protocol"):
3829 is_protocol = typing.is_protocol
3830 get_protocol_members = typing.get_protocol_members
3831else:
3832 def is_protocol(tp: type, /) -> bool:
3833 """Return True if the given type is a Protocol.
3835 Example::
3837 >>> from typing_extensions import Protocol, is_protocol
3838 >>> class P(Protocol):
3839 ... def a(self) -> str: ...
3840 ... b: int
3841 >>> is_protocol(P)
3842 True
3843 >>> is_protocol(int)
3844 False
3845 """
3846 return (
3847 isinstance(tp, type)
3848 and getattr(tp, '_is_protocol', False)
3849 and tp is not Protocol
3850 and tp is not typing.Protocol
3851 )
3853 def get_protocol_members(tp: type, /) -> typing.FrozenSet[str]:
3854 """Return the set of members defined in a Protocol.
3856 Example::
3858 >>> from typing_extensions import Protocol, get_protocol_members
3859 >>> class P(Protocol):
3860 ... def a(self) -> str: ...
3861 ... b: int
3862 >>> get_protocol_members(P)
3863 frozenset({'a', 'b'})
3865 Raise a TypeError for arguments that are not Protocols.
3866 """
3867 if not is_protocol(tp):
3868 raise TypeError(f'{tp!r} is not a Protocol')
3869 if hasattr(tp, '__protocol_attrs__'):
3870 return frozenset(tp.__protocol_attrs__)
3871 return frozenset(_get_protocol_attrs(tp))
3874if hasattr(typing, "Doc"):
3875 Doc = typing.Doc
3876else:
3877 class Doc:
3878 """Define the documentation of a type annotation using ``Annotated``, to be
3879 used in class attributes, function and method parameters, return values,
3880 and variables.
3882 The value should be a positional-only string literal to allow static tools
3883 like editors and documentation generators to use it.
3885 This complements docstrings.
3887 The string value passed is available in the attribute ``documentation``.
3889 Example::
3891 >>> from typing_extensions import Annotated, Doc
3892 >>> def hi(to: Annotated[str, Doc("Who to say hi to")]) -> None: ...
3893 """
3894 def __init__(self, documentation: str, /) -> None:
3895 self.documentation = documentation
3897 def __repr__(self) -> str:
3898 return f"Doc({self.documentation!r})"
3900 def __hash__(self) -> int:
3901 return hash(self.documentation)
3903 def __eq__(self, other: object) -> bool:
3904 if not isinstance(other, Doc):
3905 return NotImplemented
3906 return self.documentation == other.documentation
3909_CapsuleType = getattr(_types, "CapsuleType", None)
3911if _CapsuleType is None:
3912 try:
3913 import _socket
3914 except ImportError:
3915 pass
3916 else:
3917 _CAPI = getattr(_socket, "CAPI", None)
3918 if _CAPI is not None:
3919 _CapsuleType = type(_CAPI)
3921if _CapsuleType is not None:
3922 CapsuleType = _CapsuleType
3923 __all__.append("CapsuleType")
3926if sys.version_info >= (3, 14):
3927 from annotationlib import Format, get_annotations
3928else:
3929 # Available since Python 3.14.0a3
3930 # PR: https://github.com/python/cpython/pull/124415
3931 class Format(enum.IntEnum):
3932 VALUE = 1
3933 VALUE_WITH_FAKE_GLOBALS = 2
3934 FORWARDREF = 3
3935 STRING = 4
3937 # Available since Python 3.14.0a1
3938 # PR: https://github.com/python/cpython/pull/119891
3939 def get_annotations(obj, *, globals=None, locals=None, eval_str=False,
3940 format=Format.VALUE):
3941 """Compute the annotations dict for an object.
3943 obj may be a callable, class, or module.
3944 Passing in an object of any other type raises TypeError.
3946 Returns a dict. get_annotations() returns a new dict every time
3947 it's called; calling it twice on the same object will return two
3948 different but equivalent dicts.
3950 This is a backport of `inspect.get_annotations`, which has been
3951 in the standard library since Python 3.10. See the standard library
3952 documentation for more:
3954 https://docs.python.org/3/library/inspect.html#inspect.get_annotations
3956 This backport adds the *format* argument introduced by PEP 649. The
3957 three formats supported are:
3958 * VALUE: the annotations are returned as-is. This is the default and
3959 it is compatible with the behavior on previous Python versions.
3960 * FORWARDREF: return annotations as-is if possible, but replace any
3961 undefined names with ForwardRef objects. The implementation proposed by
3962 PEP 649 relies on language changes that cannot be backported; the
3963 typing-extensions implementation simply returns the same result as VALUE.
3964 * STRING: return annotations as strings, in a format close to the original
3965 source. Again, this behavior cannot be replicated directly in a backport.
3966 As an approximation, typing-extensions retrieves the annotations under
3967 VALUE semantics and then stringifies them.
3969 The purpose of this backport is to allow users who would like to use
3970 FORWARDREF or STRING semantics once PEP 649 is implemented, but who also
3971 want to support earlier Python versions, to simply write:
3973 typing_extensions.get_annotations(obj, format=Format.FORWARDREF)
3975 """
3976 format = Format(format)
3977 if format is Format.VALUE_WITH_FAKE_GLOBALS:
3978 raise ValueError(
3979 "The VALUE_WITH_FAKE_GLOBALS format is for internal use only"
3980 )
3982 if eval_str and format is not Format.VALUE:
3983 raise ValueError("eval_str=True is only supported with format=Format.VALUE")
3985 if isinstance(obj, type):
3986 # class
3987 obj_dict = getattr(obj, '__dict__', None)
3988 if obj_dict and hasattr(obj_dict, 'get'):
3989 ann = obj_dict.get('__annotations__', None)
3990 if isinstance(ann, _types.GetSetDescriptorType):
3991 ann = None
3992 else:
3993 ann = None
3995 obj_globals = None
3996 module_name = getattr(obj, '__module__', None)
3997 if module_name:
3998 module = sys.modules.get(module_name, None)
3999 if module:
4000 obj_globals = getattr(module, '__dict__', None)
4001 obj_locals = dict(vars(obj))
4002 unwrap = obj
4003 elif isinstance(obj, _types.ModuleType):
4004 # module
4005 ann = getattr(obj, '__annotations__', None)
4006 obj_globals = obj.__dict__
4007 obj_locals = None
4008 unwrap = None
4009 elif callable(obj):
4010 # this includes types.Function, types.BuiltinFunctionType,
4011 # types.BuiltinMethodType, functools.partial, functools.singledispatch,
4012 # "class funclike" from Lib/test/test_inspect... on and on it goes.
4013 ann = getattr(obj, '__annotations__', None)
4014 obj_globals = getattr(obj, '__globals__', None)
4015 obj_locals = None
4016 unwrap = obj
4017 elif hasattr(obj, '__annotations__'):
4018 ann = obj.__annotations__
4019 obj_globals = obj_locals = unwrap = None
4020 else:
4021 raise TypeError(f"{obj!r} is not a module, class, or callable.")
4023 if ann is None:
4024 return {}
4026 if not isinstance(ann, dict):
4027 raise ValueError(f"{obj!r}.__annotations__ is neither a dict nor None")
4029 if not ann:
4030 return {}
4032 if not eval_str:
4033 if format is Format.STRING:
4034 return {
4035 key: value if isinstance(value, str) else typing._type_repr(value)
4036 for key, value in ann.items()
4037 }
4038 return dict(ann)
4040 if unwrap is not None:
4041 while True:
4042 if hasattr(unwrap, '__wrapped__'):
4043 unwrap = unwrap.__wrapped__
4044 continue
4045 if isinstance(unwrap, functools.partial):
4046 unwrap = unwrap.func
4047 continue
4048 break
4049 if hasattr(unwrap, "__globals__"):
4050 obj_globals = unwrap.__globals__
4052 if globals is None:
4053 globals = obj_globals
4054 if locals is None:
4055 locals = obj_locals or {}
4057 # "Inject" type parameters into the local namespace
4058 # (unless they are shadowed by assignments *in* the local namespace),
4059 # as a way of emulating annotation scopes when calling `eval()`
4060 if type_params := getattr(obj, "__type_params__", ()):
4061 locals = {param.__name__: param for param in type_params} | locals
4063 return_value = {key:
4064 value if not isinstance(value, str) else eval(value, globals, locals)
4065 for key, value in ann.items() }
4066 return return_value
4069if hasattr(typing, "evaluate_forward_ref"):
4070 evaluate_forward_ref = typing.evaluate_forward_ref
4071else:
4072 # Implements annotationlib.ForwardRef.evaluate
4073 def _eval_with_owner(
4074 forward_ref, *, owner=None, globals=None, locals=None, type_params=None
4075 ):
4076 if forward_ref.__forward_evaluated__:
4077 return forward_ref.__forward_value__
4078 if getattr(forward_ref, "__cell__", None) is not None:
4079 try:
4080 value = forward_ref.__cell__.cell_contents
4081 except ValueError:
4082 pass
4083 else:
4084 forward_ref.__forward_evaluated__ = True
4085 forward_ref.__forward_value__ = value
4086 return value
4087 if owner is None:
4088 owner = getattr(forward_ref, "__owner__", None)
4090 if (
4091 globals is None
4092 and getattr(forward_ref, "__forward_module__", None) is not None
4093 ):
4094 globals = getattr(
4095 sys.modules.get(forward_ref.__forward_module__, None), "__dict__", None
4096 )
4097 if globals is None:
4098 globals = getattr(forward_ref, "__globals__", None)
4099 if globals is None:
4100 if isinstance(owner, type):
4101 module_name = getattr(owner, "__module__", None)
4102 if module_name:
4103 module = sys.modules.get(module_name, None)
4104 if module:
4105 globals = getattr(module, "__dict__", None)
4106 elif isinstance(owner, _types.ModuleType):
4107 globals = getattr(owner, "__dict__", None)
4108 elif callable(owner):
4109 globals = getattr(owner, "__globals__", None)
4111 # If we pass None to eval() below, the globals of this module are used.
4112 if globals is None:
4113 globals = {}
4115 if locals is None:
4116 locals = {}
4117 if isinstance(owner, type):
4118 locals.update(vars(owner))
4120 if type_params is None and owner is not None:
4121 # "Inject" type parameters into the local namespace
4122 # (unless they are shadowed by assignments *in* the local namespace),
4123 # as a way of emulating annotation scopes when calling `eval()`
4124 type_params = getattr(owner, "__type_params__", None)
4126 # Type parameters exist in their own scope, which is logically
4127 # between the locals and the globals. We simulate this by adding
4128 # them to the globals.
4129 if type_params is not None:
4130 globals = dict(globals)
4131 for param in type_params:
4132 globals[param.__name__] = param
4134 arg = forward_ref.__forward_arg__
4135 if arg.isidentifier() and not keyword.iskeyword(arg):
4136 if arg in locals:
4137 value = locals[arg]
4138 elif arg in globals:
4139 value = globals[arg]
4140 elif hasattr(builtins, arg):
4141 return getattr(builtins, arg)
4142 else:
4143 raise NameError(arg)
4144 else:
4145 code = forward_ref.__forward_code__
4146 value = eval(code, globals, locals)
4147 forward_ref.__forward_evaluated__ = True
4148 forward_ref.__forward_value__ = value
4149 return value
4151 def evaluate_forward_ref(
4152 forward_ref,
4153 *,
4154 owner=None,
4155 globals=None,
4156 locals=None,
4157 type_params=None,
4158 format=None,
4159 _recursive_guard=frozenset(),
4160 ):
4161 """Evaluate a forward reference as a type hint.
4163 This is similar to calling the ForwardRef.evaluate() method,
4164 but unlike that method, evaluate_forward_ref() also:
4166 * Recursively evaluates forward references nested within the type hint.
4167 * Rejects certain objects that are not valid type hints.
4168 * Replaces type hints that evaluate to None with types.NoneType.
4169 * Supports the *FORWARDREF* and *STRING* formats.
4171 *forward_ref* must be an instance of ForwardRef. *owner*, if given,
4172 should be the object that holds the annotations that the forward reference
4173 derived from, such as a module, class object, or function. It is used to
4174 infer the namespaces to use for looking up names. *globals* and *locals*
4175 can also be explicitly given to provide the global and local namespaces.
4176 *type_params* is a tuple of type parameters that are in scope when
4177 evaluating the forward reference. This parameter must be provided (though
4178 it may be an empty tuple) if *owner* is not given and the forward reference
4179 does not already have an owner set. *format* specifies the format of the
4180 annotation and is a member of the annotationlib.Format enum.
4182 """
4183 if format == Format.STRING:
4184 return forward_ref.__forward_arg__
4185 if forward_ref.__forward_arg__ in _recursive_guard:
4186 return forward_ref
4188 # Evaluate the forward reference
4189 try:
4190 value = _eval_with_owner(
4191 forward_ref,
4192 owner=owner,
4193 globals=globals,
4194 locals=locals,
4195 type_params=type_params,
4196 )
4197 except NameError:
4198 if format == Format.FORWARDREF:
4199 return forward_ref
4200 else:
4201 raise
4203 if isinstance(value, str):
4204 value = ForwardRef(value)
4206 # Recursively evaluate the type
4207 if isinstance(value, ForwardRef):
4208 if getattr(value, "__forward_module__", True) is not None:
4209 globals = None
4210 return evaluate_forward_ref(
4211 value,
4212 globals=globals,
4213 locals=locals,
4214 type_params=type_params, owner=owner,
4215 _recursive_guard=_recursive_guard, format=format
4216 )
4217 if sys.version_info < (3, 12, 5) and type_params:
4218 # Make use of type_params
4219 locals = dict(locals) if locals else {}
4220 for tvar in type_params:
4221 if tvar.__name__ not in locals: # lets not overwrite something present
4222 locals[tvar.__name__] = tvar
4223 if sys.version_info < (3, 12, 5):
4224 return typing._eval_type(
4225 value,
4226 globals,
4227 locals,
4228 recursive_guard=_recursive_guard | {forward_ref.__forward_arg__},
4229 )
4230 else:
4231 return typing._eval_type(
4232 value,
4233 globals,
4234 locals,
4235 type_params,
4236 recursive_guard=_recursive_guard | {forward_ref.__forward_arg__},
4237 )
4240if sys.version_info >= (3, 14, 0, "beta"):
4241 type_repr = annotationlib.type_repr
4242else:
4243 def type_repr(value):
4244 """Convert a Python value to a format suitable for use with the STRING format.
4246 This is intended as a helper for tools that support the STRING format but do
4247 not have access to the code that originally produced the annotations. It uses
4248 repr() for most objects.
4250 """
4251 if isinstance(value, (type, _types.FunctionType, _types.BuiltinFunctionType)):
4252 if value.__module__ == "builtins":
4253 return value.__qualname__
4254 return f"{value.__module__}.{value.__qualname__}"
4255 if value is ...:
4256 return "..."
4257 return repr(value)
4260# Aliases for items that are in typing in all supported versions.
4261# We use hasattr() checks so this library will continue to import on
4262# future versions of Python that may remove these names.
4263_typing_names = [
4264 "AbstractSet",
4265 "AnyStr",
4266 "BinaryIO",
4267 "Callable",
4268 "Collection",
4269 "Container",
4270 "Dict",
4271 "FrozenSet",
4272 "Hashable",
4273 "IO",
4274 "ItemsView",
4275 "Iterable",
4276 "Iterator",
4277 "KeysView",
4278 "List",
4279 "Mapping",
4280 "MappingView",
4281 "Match",
4282 "MutableMapping",
4283 "MutableSequence",
4284 "MutableSet",
4285 "Optional",
4286 "Pattern",
4287 "Reversible",
4288 "Sequence",
4289 "Set",
4290 "Sized",
4291 "TextIO",
4292 "Tuple",
4293 "Union",
4294 "ValuesView",
4295 "cast",
4296 "no_type_check",
4297 "no_type_check_decorator",
4298 # This is private, but it was defined by typing_extensions for a long time
4299 # and some users rely on it.
4300 "_AnnotatedAlias",
4301]
4302globals().update(
4303 {name: getattr(typing, name) for name in _typing_names if hasattr(typing, name)}
4304)
4305# These are defined unconditionally because they are used in
4306# typing-extensions itself.
4307Generic = typing.Generic
4308ForwardRef = typing.ForwardRef
4309Annotated = typing.Annotated