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