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