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