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