1815_PROTO_ALLOWLIST = {
1816 'collections.abc': [
1817 'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
-1818 'Hashable', 'Sized', 'Container', 'Collection', 'Reversible', 'Buffer',
-1819 ],
-1820 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
-1821}
-1822
+1818 'AsyncIterator', 'Hashable', 'Sized', 'Container', 'Collection',
+1819 'Reversible', 'Buffer',
+1820 ],
+1821 'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
+1822}
1823
-1824@functools.cache
-1825def _lazy_load_getattr_static():
-1826 # Import getattr_static lazily so as not to slow down the import of typing.py
-1827 # Cache the result so we don't slow down _ProtocolMeta.__instancecheck__ unnecessarily
-1828 from inspect import getattr_static
-1829 return getattr_static
-1830
+1824
+1825@functools.cache
+1826def _lazy_load_getattr_static():
+1827 # Import getattr_static lazily so as not to slow down the import of typing.py
+1828 # Cache the result so we don't slow down _ProtocolMeta.__instancecheck__ unnecessarily
+1829 from inspect import getattr_static
+1830 return getattr_static
1831
-1832_cleanups.append(_lazy_load_getattr_static.cache_clear)
-1833
-1834def _pickle_psargs(psargs):
-1835 return ParamSpecArgs, (psargs.__origin__,)
-1836
-1837copyreg.pickle(ParamSpecArgs, _pickle_psargs)
-1838
-1839def _pickle_pskwargs(pskwargs):
-1840 return ParamSpecKwargs, (pskwargs.__origin__,)
-1841
-1842copyreg.pickle(ParamSpecKwargs, _pickle_pskwargs)
-1843
-1844del _pickle_psargs, _pickle_pskwargs
-1845
+1832
+1833_cleanups.append(_lazy_load_getattr_static.cache_clear)
+1834
+1835def _pickle_psargs(psargs):
+1836 return ParamSpecArgs, (psargs.__origin__,)
+1837
+1838copyreg.pickle(ParamSpecArgs, _pickle_psargs)
+1839
+1840def _pickle_pskwargs(pskwargs):
+1841 return ParamSpecKwargs, (pskwargs.__origin__,)
+1842
+1843copyreg.pickle(ParamSpecKwargs, _pickle_pskwargs)
+1844
+1845del _pickle_psargs, _pickle_pskwargs
1846
-1847class _ProtocolMeta(ABCMeta):
-1848 # This metaclass is somewhat unfortunate,
-1849 # but is necessary for several reasons...
-1850 def __new__(mcls, name, bases, namespace, /, **kwargs):
-1851 if name == "Protocol" and bases == (Generic,):
-1852 pass
-1853 elif Protocol in bases:
-1854 for base in bases:
-1855 if not (
-1856 base in {object, Generic}
-1857 or base.__name__ in _PROTO_ALLOWLIST.get(base.__module__, [])
-1858 or (
-1859 issubclass(base, Generic)
-1860 and getattr(base, "_is_protocol", False)
-1861 )
-1862 ):
-1863 raise TypeError(
-1864 f"Protocols can only inherit from other protocols, "
-1865 f"got {base!r}"
-1866 )
-1867 return super().__new__(mcls, name, bases, namespace, **kwargs)
-1868
-1869 def __init__(cls, *args, **kwargs):
-1870 super().__init__(*args, **kwargs)
-1871 if getattr(cls, "_is_protocol", False):
-1872 cls.__protocol_attrs__ = _get_protocol_attrs(cls)
-1873
-1874 def __subclasscheck__(cls, other):
-1875 if cls is Protocol:
-1876 return type.__subclasscheck__(cls, other)
-1877 if (
-1878 getattr(cls, '_is_protocol', False)
-1879 and not _allow_reckless_class_checks()
-1880 ):
-1881 if not isinstance(other, type):
-1882 # Same error message as for issubclass(1, int).
-1883 raise TypeError('issubclass() arg 1 must be a class')
-1884 if not getattr(cls, '_is_runtime_protocol', False):
-1885 raise TypeError(
-1886 "Instance and class checks can only be used with "
-1887 "@runtime_checkable protocols"
-1888 )
-1889 if (
-1890 # this attribute is set by @runtime_checkable:
-1891 cls.__non_callable_proto_members__
-1892 and cls.__dict__.get("__subclasshook__") is _proto_hook
-1893 ):
-1894 raise TypeError(
-1895 "Protocols with non-method members don't support issubclass()"
-1896 )
-1897 return super().__subclasscheck__(other)
-1898
-1899 def __instancecheck__(cls, instance):
-1900 # We need this method for situations where attributes are
-1901 # assigned in __init__.
-1902 if cls is Protocol:
-1903 return type.__instancecheck__(cls, instance)
-1904 if not getattr(cls, "_is_protocol", False):
-1905 # i.e., it's a concrete subclass of a protocol
-1906 return super().__instancecheck__(instance)
-1907
-1908 if (
-1909 not getattr(cls, '_is_runtime_protocol', False) and
-1910 not _allow_reckless_class_checks()
-1911 ):
-1912 raise TypeError("Instance and class checks can only be used with"
-1913 " @runtime_checkable protocols")
-1914
-1915 if super().__instancecheck__(instance):
-1916 return True
-1917
-1918 getattr_static = _lazy_load_getattr_static()
-1919 for attr in cls.__protocol_attrs__:
-1920 try:
-1921 val = getattr_static(instance, attr)
-1922 except AttributeError:
-1923 break
-1924 # this attribute is set by @runtime_checkable:
-1925 if val is None and attr not in cls.__non_callable_proto_members__:
-1926 break
-1927 else:
-1928 return True
-1929
-1930 return False
-1931
+1847
+1848class _ProtocolMeta(ABCMeta):
+1849 # This metaclass is somewhat unfortunate,
+1850 # but is necessary for several reasons...
+1851 def __new__(mcls, name, bases, namespace, /, **kwargs):
+1852 if name == "Protocol" and bases == (Generic,):
+1853 pass
+1854 elif Protocol in bases:
+1855 for base in bases:
+1856 if not (
+1857 base in {object, Generic}
+1858 or base.__name__ in _PROTO_ALLOWLIST.get(base.__module__, [])
+1859 or (
+1860 issubclass(base, Generic)
+1861 and getattr(base, "_is_protocol", False)
+1862 )
+1863 ):
+1864 raise TypeError(
+1865 f"Protocols can only inherit from other protocols, "
+1866 f"got {base!r}"
+1867 )
+1868 return super().__new__(mcls, name, bases, namespace, **kwargs)
+1869
+1870 def __init__(cls, *args, **kwargs):
+1871 super().__init__(*args, **kwargs)
+1872 if getattr(cls, "_is_protocol", False):
+1873 cls.__protocol_attrs__ = _get_protocol_attrs(cls)
+1874
+1875 def __subclasscheck__(cls, other):
+1876 if cls is Protocol:
+1877 return type.__subclasscheck__(cls, other)
+1878 if (
+1879 getattr(cls, '_is_protocol', False)
+1880 and not _allow_reckless_class_checks()
+1881 ):
+1882 if not isinstance(other, type):
+1883 # Same error message as for issubclass(1, int).
+1884 raise TypeError('issubclass() arg 1 must be a class')
+1885 if not getattr(cls, '_is_runtime_protocol', False):
+1886 raise TypeError(
+1887 "Instance and class checks can only be used with "
+1888 "@runtime_checkable protocols"
+1889 )
+1890 if (
+1891 # this attribute is set by @runtime_checkable:
+1892 cls.__non_callable_proto_members__
+1893 and cls.__dict__.get("__subclasshook__") is _proto_hook
+1894 ):
+1895 raise TypeError(
+1896 "Protocols with non-method members don't support issubclass()"
+1897 )
+1898 return super().__subclasscheck__(other)
+1899
+1900 def __instancecheck__(cls, instance):
+1901 # We need this method for situations where attributes are
+1902 # assigned in __init__.
+1903 if cls is Protocol:
+1904 return type.__instancecheck__(cls, instance)
+1905 if not getattr(cls, "_is_protocol", False):
+1906 # i.e., it's a concrete subclass of a protocol
+1907 return super().__instancecheck__(instance)
+1908
+1909 if (
+1910 not getattr(cls, '_is_runtime_protocol', False) and
+1911 not _allow_reckless_class_checks()
+1912 ):
+1913 raise TypeError("Instance and class checks can only be used with"
+1914 " @runtime_checkable protocols")
+1915
+1916 if super().__instancecheck__(instance):
+1917 return True
+1918
+1919 getattr_static = _lazy_load_getattr_static()
+1920 for attr in cls.__protocol_attrs__:
+1921 try:
+1922 val = getattr_static(instance, attr)
+1923 except AttributeError:
+1924 break
+1925 # this attribute is set by @runtime_checkable:
+1926 if val is None and attr not in cls.__non_callable_proto_members__:
+1927 break
+1928 else:
+1929 return True
+1930
+1931 return False
1932
-1933@classmethod
-1934def _proto_hook(cls, other):
-1935 if not cls.__dict__.get('_is_protocol', False):
-1936 return NotImplemented
-1937
-1938 for attr in cls.__protocol_attrs__:
-1939 for base in other.__mro__:
-1940 # Check if the members appears in the class dictionary...
-1941 if attr in base.__dict__:
-1942 if base.__dict__[attr] is None:
-1943 return NotImplemented
-1944 break
-1945
-1946 # ...or in annotations, if it is a sub-protocol.
-1947 annotations = getattr(base, '__annotations__', {})
-1948 if (isinstance(annotations, collections.abc.Mapping) and
-1949 attr in annotations and
-1950 issubclass(other, Generic) and getattr(other, '_is_protocol', False)):
-1951 break
-1952 else:
-1953 return NotImplemented
-1954 return True
-1955
+1933
+1934@classmethod
+1935def _proto_hook(cls, other):
+1936 if not cls.__dict__.get('_is_protocol', False):
+1937 return NotImplemented
+1938
+1939 for attr in cls.__protocol_attrs__:
+1940 for base in other.__mro__:
+1941 # Check if the members appears in the class dictionary...
+1942 if attr in base.__dict__:
+1943 if base.__dict__[attr] is None:
+1944 return NotImplemented
+1945 break
+1946
+1947 # ...or in annotations, if it is a sub-protocol.
+1948 annotations = getattr(base, '__annotations__', {})
+1949 if (isinstance(annotations, collections.abc.Mapping) and
+1950 attr in annotations and
+1951 issubclass(other, Generic) and getattr(other, '_is_protocol', False)):
+1952 break
+1953 else:
+1954 return NotImplemented
+1955 return True
1956
-1957class Protocol(Generic, metaclass=_ProtocolMeta):
-1958 """Base class for protocol classes.
-1959
-1960 Protocol classes are defined as::
-1961
-1962 class Proto(Protocol):
-1963 def meth(self) -> int:
-1964 ...
-1965
-1966 Such classes are primarily used with static type checkers that recognize
-1967 structural subtyping (static duck-typing).
-1968
-1969 For example::
-1970
-1971 class C:
-1972 def meth(self) -> int:
-1973 return 0
-1974
-1975 def func(x: Proto) -> int:
-1976 return x.meth()
-1977
-1978 func(C()) # Passes static type check
-1979
-1980 See PEP 544 for details. Protocol classes decorated with
-1981 @typing.runtime_checkable act as simple-minded runtime protocols that check
-1982 only the presence of given attributes, ignoring their type signatures.
-1983 Protocol classes can be generic, they are defined as::
-1984
-1985 class GenProto[T](Protocol):
-1986 def meth(self) -> T:
-1987 ...
-1988 """
-1989
-1990 __slots__ = ()
-1991 _is_protocol = True
-1992 _is_runtime_protocol = False
-1993
-1994 def __init_subclass__(cls, *args, **kwargs):
-1995 super().__init_subclass__(*args, **kwargs)
-1996
-1997 # Determine if this is a protocol or a concrete subclass.
-1998 if not cls.__dict__.get('_is_protocol', False):
-1999 cls._is_protocol = any(b is Protocol for b in cls.__bases__)
-2000
-2001 # Set (or override) the protocol subclass hook.
-2002 if '__subclasshook__' not in cls.__dict__:
-2003 cls.__subclasshook__ = _proto_hook
-2004
-2005 # Prohibit instantiation for protocol classes
-2006 if cls._is_protocol and cls.__init__ is Protocol.__init__:
-2007 cls.__init__ = _no_init_or_replace_init
-2008
+1957
+1958class Protocol(Generic, metaclass=_ProtocolMeta):
+1959 """Base class for protocol classes.
+1960
+1961 Protocol classes are defined as::
+1962
+1963 class Proto(Protocol):
+1964 def meth(self) -> int:
+1965 ...
+1966
+1967 Such classes are primarily used with static type checkers that recognize
+1968 structural subtyping (static duck-typing).
+1969
+1970 For example::
+1971
+1972 class C:
+1973 def meth(self) -> int:
+1974 return 0
+1975
+1976 def func(x: Proto) -> int:
+1977 return x.meth()
+1978
+1979 func(C()) # Passes static type check
+1980
+1981 See PEP 544 for details. Protocol classes decorated with
+1982 @typing.runtime_checkable act as simple-minded runtime protocols that check
+1983 only the presence of given attributes, ignoring their type signatures.
+1984 Protocol classes can be generic, they are defined as::
+1985
+1986 class GenProto[T](Protocol):
+1987 def meth(self) -> T:
+1988 ...
+1989 """
+1990
+1991 __slots__ = ()
+1992 _is_protocol = True
+1993 _is_runtime_protocol = False
+1994
+1995 def __init_subclass__(cls, *args, **kwargs):
+1996 super().__init_subclass__(*args, **kwargs)
+1997
+1998 # Determine if this is a protocol or a concrete subclass.
+1999 if not cls.__dict__.get('_is_protocol', False):
+2000 cls._is_protocol = any(b is Protocol for b in cls.__bases__)
+2001
+2002 # Set (or override) the protocol subclass hook.
+2003 if '__subclasshook__' not in cls.__dict__:
+2004 cls.__subclasshook__ = _proto_hook
+2005
+2006 # Prohibit instantiation for protocol classes
+2007 if cls._is_protocol and cls.__init__ is Protocol.__init__:
+2008 cls.__init__ = _no_init_or_replace_init
2009
-2010class _AnnotatedAlias(_NotIterable, _GenericAlias, _root=True):
-2011 """Runtime representation of an annotated type.
-2012
-2013 At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
-2014 with extra annotations. The alias behaves like a normal typing alias.
-2015 Instantiating is the same as instantiating the underlying type; binding
-2016 it to types is also the same.
-2017
-2018 The metadata itself is stored in a '__metadata__' attribute as a tuple.
-2019 """
-2020
-2021 def __init__(self, origin, metadata):
-2022 if isinstance(origin, _AnnotatedAlias):
-2023 metadata = origin.__metadata__ + metadata
-2024 origin = origin.__origin__
-2025 super().__init__(origin, origin, name='Annotated')
-2026 self.__metadata__ = metadata
-2027
-2028 def copy_with(self, params):
-2029 assert len(params) == 1
-2030 new_type = params[0]
-2031 return _AnnotatedAlias(new_type, self.__metadata__)
-2032
-2033 def __repr__(self):
-2034 return "typing.Annotated[{}, {}]".format(
-2035 _type_repr(self.__origin__),
-2036 ", ".join(repr(a) for a in self.__metadata__)
-2037 )
-2038
-2039 def __reduce__(self):
-2040 return operator.getitem, (
-2041 Annotated, (self.__origin__,) + self.__metadata__
-2042 )
-2043
-2044 def __eq__(self, other):
-2045 if not isinstance(other, _AnnotatedAlias):
-2046 return NotImplemented
-2047 return (self.__origin__ == other.__origin__
-2048 and self.__metadata__ == other.__metadata__)
-2049
-2050 def __hash__(self):
-2051 return hash((self.__origin__, self.__metadata__))
-2052
-2053 def __getattr__(self, attr):
-2054 if attr in {'__name__', '__qualname__'}:
-2055 return 'Annotated'
-2056 return super().__getattr__(attr)
-2057
-2058 def __mro_entries__(self, bases):
-2059 return (self.__origin__,)
-2060
+2010
+2011class _AnnotatedAlias(_NotIterable, _GenericAlias, _root=True):
+2012 """Runtime representation of an annotated type.
+2013
+2014 At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
+2015 with extra annotations. The alias behaves like a normal typing alias.
+2016 Instantiating is the same as instantiating the underlying type; binding
+2017 it to types is also the same.
+2018
+2019 The metadata itself is stored in a '__metadata__' attribute as a tuple.
+2020 """
+2021
+2022 def __init__(self, origin, metadata):
+2023 if isinstance(origin, _AnnotatedAlias):
+2024 metadata = origin.__metadata__ + metadata
+2025 origin = origin.__origin__
+2026 super().__init__(origin, origin, name='Annotated')
+2027 self.__metadata__ = metadata
+2028
+2029 def copy_with(self, params):
+2030 assert len(params) == 1
+2031 new_type = params[0]
+2032 return _AnnotatedAlias(new_type, self.__metadata__)
+2033
+2034 def __repr__(self):
+2035 return "typing.Annotated[{}, {}]".format(
+2036 _type_repr(self.__origin__),
+2037 ", ".join(repr(a) for a in self.__metadata__)
+2038 )
+2039
+2040 def __reduce__(self):
+2041 return operator.getitem, (
+2042 Annotated, (self.__origin__,) + self.__metadata__
+2043 )
+2044
+2045 def __eq__(self, other):
+2046 if not isinstance(other, _AnnotatedAlias):
+2047 return NotImplemented
+2048 return (self.__origin__ == other.__origin__
+2049 and self.__metadata__ == other.__metadata__)
+2050
+2051 def __hash__(self):
+2052 return hash((self.__origin__, self.__metadata__))
+2053
+2054 def __getattr__(self, attr):
+2055 if attr in {'__name__', '__qualname__'}:
+2056 return 'Annotated'
+2057 return super().__getattr__(attr)
+2058
+2059 def __mro_entries__(self, bases):
+2060 return (self.__origin__,)
2061
-2062class Annotated:
-2063 """Add context-specific metadata to a type.
-2064
-2065 Example: Annotated[int, runtime_check.Unsigned] indicates to the
-2066 hypothetical runtime_check module that this type is an unsigned int.
-2067 Every other consumer of this type can ignore this metadata and treat
-2068 this type as int.
-2069
-2070 The first argument to Annotated must be a valid type.
-2071
-2072 Details:
-2073
-2074 - It's an error to call `Annotated` with less than two arguments.
-2075 - Access the metadata via the ``__metadata__`` attribute::
-2076
-2077 assert Annotated[int, '$'].__metadata__ == ('$',)
-2078
-2079 - Nested Annotated types are flattened::
-2080
-2081 assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
-2082
-2083 - Instantiating an annotated type is equivalent to instantiating the
-2084 underlying type::
-2085
-2086 assert Annotated[C, Ann1](5) == C(5)
-2087
-2088 - Annotated can be used as a generic type alias::
-2089
-2090 type Optimized[T] = Annotated[T, runtime.Optimize()]
-2091 # type checker will treat Optimized[int]
-2092 # as equivalent to Annotated[int, runtime.Optimize()]
-2093
-2094 type OptimizedList[T] = Annotated[list[T], runtime.Optimize()]
-2095 # type checker will treat OptimizedList[int]
-2096 # as equivalent to Annotated[list[int], runtime.Optimize()]
-2097
-2098 - Annotated cannot be used with an unpacked TypeVarTuple::
-2099
-2100 type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid
-2101
-2102 This would be equivalent to::
-2103
-2104 Annotated[T1, T2, T3, ..., Ann1]
-2105
-2106 where T1, T2 etc. are TypeVars, which would be invalid, because
-2107 only one type should be passed to Annotated.
-2108 """
-2109
-2110 __slots__ = ()
-2111
-2112 def __new__(cls, *args, **kwargs):
-2113 raise TypeError("Type Annotated cannot be instantiated.")
-2114
-2115 def __class_getitem__(cls, params):
-2116 if not isinstance(params, tuple):
-2117 params = (params,)
-2118 return cls._class_getitem_inner(cls, *params)
-2119
-2120 @_tp_cache(typed=True)
-2121 def _class_getitem_inner(cls, *params):
-2122 if len(params) < 2:
-2123 raise TypeError("Annotated[...] should be used "
-2124 "with at least two arguments (a type and an "
-2125 "annotation).")
-2126 if _is_unpacked_typevartuple(params[0]):
-2127 raise TypeError("Annotated[...] should not be used with an "
-2128 "unpacked TypeVarTuple")
-2129 msg = "Annotated[t, ...]: t must be a type."
-2130 origin = _type_check(params[0], msg, allow_special_forms=True)
-2131 metadata = tuple(params[1:])
-2132 return _AnnotatedAlias(origin, metadata)
-2133
-2134 def __init_subclass__(cls, *args, **kwargs):
-2135 raise TypeError(
-2136 "Cannot subclass {}.Annotated".format(cls.__module__)
-2137 )
-2138
+2062
+2063class Annotated:
+2064 """Add context-specific metadata to a type.
+2065
+2066 Example: Annotated[int, runtime_check.Unsigned] indicates to the
+2067 hypothetical runtime_check module that this type is an unsigned int.
+2068 Every other consumer of this type can ignore this metadata and treat
+2069 this type as int.
+2070
+2071 The first argument to Annotated must be a valid type.
+2072
+2073 Details:
+2074
+2075 - It's an error to call `Annotated` with less than two arguments.
+2076 - Access the metadata via the ``__metadata__`` attribute::
+2077
+2078 assert Annotated[int, '$'].__metadata__ == ('$',)
+2079
+2080 - Nested Annotated types are flattened::
+2081
+2082 assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
+2083
+2084 - Instantiating an annotated type is equivalent to instantiating the
+2085 underlying type::
+2086
+2087 assert Annotated[C, Ann1](5) == C(5)
+2088
+2089 - Annotated can be used as a generic type alias::
+2090
+2091 type Optimized[T] = Annotated[T, runtime.Optimize()]
+2092 # type checker will treat Optimized[int]
+2093 # as equivalent to Annotated[int, runtime.Optimize()]
+2094
+2095 type OptimizedList[T] = Annotated[list[T], runtime.Optimize()]
+2096 # type checker will treat OptimizedList[int]
+2097 # as equivalent to Annotated[list[int], runtime.Optimize()]
+2098
+2099 - Annotated cannot be used with an unpacked TypeVarTuple::
+2100
+2101 type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid
+2102
+2103 This would be equivalent to::
+2104
+2105 Annotated[T1, T2, T3, ..., Ann1]
+2106
+2107 where T1, T2 etc. are TypeVars, which would be invalid, because
+2108 only one type should be passed to Annotated.
+2109 """
+2110
+2111 __slots__ = ()
+2112
+2113 def __new__(cls, *args, **kwargs):
+2114 raise TypeError("Type Annotated cannot be instantiated.")
+2115
+2116 def __class_getitem__(cls, params):
+2117 if not isinstance(params, tuple):
+2118 params = (params,)
+2119 return cls._class_getitem_inner(cls, *params)
+2120
+2121 @_tp_cache(typed=True)
+2122 def _class_getitem_inner(cls, *params):
+2123 if len(params) < 2:
+2124 raise TypeError("Annotated[...] should be used "
+2125 "with at least two arguments (a type and an "
+2126 "annotation).")
+2127 if _is_unpacked_typevartuple(params[0]):
+2128 raise TypeError("Annotated[...] should not be used with an "
+2129 "unpacked TypeVarTuple")
+2130 msg = "Annotated[t, ...]: t must be a type."
+2131 origin = _type_check(params[0], msg, allow_special_forms=True)
+2132 metadata = tuple(params[1:])
+2133 return _AnnotatedAlias(origin, metadata)
+2134
+2135 def __init_subclass__(cls, *args, **kwargs):
+2136 raise TypeError(
+2137 "Cannot subclass {}.Annotated".format(cls.__module__)
+2138 )
2139
-2140def runtime_checkable(cls):
-2141 """Mark a protocol class as a runtime protocol.
-2142
-2143 Such protocol can be used with isinstance() and issubclass().
-2144 Raise TypeError if applied to a non-protocol class.
-2145 This allows a simple-minded structural check very similar to
-2146 one trick ponies in collections.abc such as Iterable.
-2147
-2148 For example::
-2149
-2150 @runtime_checkable
-2151 class Closable(Protocol):
-2152 def close(self): ...
-2153
-2154 assert isinstance(open('/some/file'), Closable)
-2155
-2156 Warning: this will check only the presence of the required methods,
-2157 not their type signatures!
-2158 """
-2159 if not issubclass(cls, Generic) or not getattr(cls, '_is_protocol', False):
-2160 raise TypeError('@runtime_checkable can be only applied to protocol classes,'
-2161 ' got %r' % cls)
-2162 cls._is_runtime_protocol = True
-2163 # PEP 544 prohibits using issubclass()
-2164 # with protocols that have non-method members.
-2165 # See gh-113320 for why we compute this attribute here,
-2166 # rather than in `_ProtocolMeta.__init__`
-2167 cls.__non_callable_proto_members__ = set()
-2168 for attr in cls.__protocol_attrs__:
-2169 try:
-2170 is_callable = callable(getattr(cls, attr, None))
-2171 except Exception as e:
-2172 raise TypeError(
-2173 f"Failed to determine whether protocol member {attr!r} "
-2174 "is a method member"
-2175 ) from e
-2176 else:
-2177 if not is_callable:
-2178 cls.__non_callable_proto_members__.add(attr)
-2179 return cls
-2180
+2140
+2141def runtime_checkable(cls):
+2142 """Mark a protocol class as a runtime protocol.
+2143
+2144 Such protocol can be used with isinstance() and issubclass().
+2145 Raise TypeError if applied to a non-protocol class.
+2146 This allows a simple-minded structural check very similar to
+2147 one trick ponies in collections.abc such as Iterable.
+2148
+2149 For example::
+2150
+2151 @runtime_checkable
+2152 class Closable(Protocol):
+2153 def close(self): ...
+2154
+2155 assert isinstance(open('/some/file'), Closable)
+2156
+2157 Warning: this will check only the presence of the required methods,
+2158 not their type signatures!
+2159 """
+2160 if not issubclass(cls, Generic) or not getattr(cls, '_is_protocol', False):
+2161 raise TypeError('@runtime_checkable can be only applied to protocol classes,'
+2162 ' got %r' % cls)
+2163 cls._is_runtime_protocol = True
+2164 # PEP 544 prohibits using issubclass()
+2165 # with protocols that have non-method members.
+2166 # See gh-113320 for why we compute this attribute here,
+2167 # rather than in `_ProtocolMeta.__init__`
+2168 cls.__non_callable_proto_members__ = set()
+2169 for attr in cls.__protocol_attrs__:
+2170 try:
+2171 is_callable = callable(getattr(cls, attr, None))
+2172 except Exception as e:
+2173 raise TypeError(
+2174 f"Failed to determine whether protocol member {attr!r} "
+2175 "is a method member"
+2176 ) from e
+2177 else:
+2178 if not is_callable:
+2179 cls.__non_callable_proto_members__.add(attr)
+2180 return cls
2181
-2182def cast(typ, val):
-2183 """Cast a value to a type.
-2184
-2185 This returns the value unchanged. To the type checker this
-2186 signals that the return value has the designated type, but at
-2187 runtime we intentionally don't check anything (we want this
-2188 to be as fast as possible).
-2189 """
-2190 return val
-2191
+2182
+2183def cast(typ, val):
+2184 """Cast a value to a type.
+2185
+2186 This returns the value unchanged. To the type checker this
+2187 signals that the return value has the designated type, but at
+2188 runtime we intentionally don't check anything (we want this
+2189 to be as fast as possible).
+2190 """
+2191 return val
2192
-2193def assert_type(val, typ, /):
-2194 """Ask a static type checker to confirm that the value is of the given type.
-2195
-2196 At runtime this does nothing: it returns the first argument unchanged with no
-2197 checks or side effects, no matter the actual type of the argument.
-2198
-2199 When a static type checker encounters a call to assert_type(), it
-2200 emits an error if the value is not of the specified type::
-2201
-2202 def greet(name: str) -> None:
-2203 assert_type(name, str) # OK
-2204 assert_type(name, int) # type checker error
-2205 """
-2206 return val
-2207
+2193
+2194def assert_type(val, typ, /):
+2195 """Ask a static type checker to confirm that the value is of the given type.
+2196
+2197 At runtime this does nothing: it returns the first argument unchanged with no
+2198 checks or side effects, no matter the actual type of the argument.
+2199
+2200 When a static type checker encounters a call to assert_type(), it
+2201 emits an error if the value is not of the specified type::
+2202
+2203 def greet(name: str) -> None:
+2204 assert_type(name, str) # OK
+2205 assert_type(name, int) # type checker error
+2206 """
+2207 return val
2208
-2209_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
-2210 types.MethodType, types.ModuleType,
-2211 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
-2212
+2209
+2210_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
+2211 types.MethodType, types.ModuleType,
+2212 WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
2213
-2214def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
-2215 """Return type hints for an object.
-2216
-2217 This is often the same as obj.__annotations__, but it handles
-2218 forward references encoded as string literals and recursively replaces all
-2219 'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
-2220
-2221 The argument may be a module, class, method, or function. The annotations
-2222 are returned as a dictionary. For classes, annotations include also
-2223 inherited members.
-2224
-2225 TypeError is raised if the argument is not of a type that can contain
-2226 annotations, and an empty dictionary is returned if no annotations are
-2227 present.
-2228
-2229 BEWARE -- the behavior of globalns and localns is counterintuitive
-2230 (unless you are familiar with how eval() and exec() work). The
-2231 search order is locals first, then globals.
-2232
-2233 - If no dict arguments are passed, an attempt is made to use the
-2234 globals from obj (or the respective module's globals for classes),
-2235 and these are also used as the locals. If the object does not appear
-2236 to have globals, an empty dictionary is used. For classes, the search
-2237 order is globals first then locals.
-2238
-2239 - If one dict argument is passed, it is used for both globals and
-2240 locals.
-2241
-2242 - If two dict arguments are passed, they specify globals and
-2243 locals, respectively.
-2244 """
-2245 if getattr(obj, '__no_type_check__', None):
-2246 return {}
-2247 # Classes require a special treatment.
-2248 if isinstance(obj, type):
-2249 hints = {}
-2250 for base in reversed(obj.__mro__):
-2251 if globalns is None:
-2252 base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {})
-2253 else:
-2254 base_globals = globalns
-2255 ann = base.__dict__.get('__annotations__', {})
-2256 if isinstance(ann, types.GetSetDescriptorType):
-2257 ann = {}
-2258 base_locals = dict(vars(base)) if localns is None else localns
-2259 if localns is None and globalns is None:
-2260 # This is surprising, but required. Before Python 3.10,
-2261 # get_type_hints only evaluated the globalns of
-2262 # a class. To maintain backwards compatibility, we reverse
-2263 # the globalns and localns order so that eval() looks into
-2264 # *base_globals* first rather than *base_locals*.
-2265 # This only affects ForwardRefs.
-2266 base_globals, base_locals = base_locals, base_globals
-2267 for name, value in ann.items():
-2268 if value is None:
-2269 value = type(None)
-2270 if isinstance(value, str):
-2271 value = ForwardRef(value, is_argument=False, is_class=True)
-2272 value = _eval_type(value, base_globals, base_locals, base.__type_params__)
-2273 hints[name] = value
-2274 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
-2275
-2276 if globalns is None:
-2277 if isinstance(obj, types.ModuleType):
-2278 globalns = obj.__dict__
-2279 else:
-2280 nsobj = obj
-2281 # Find globalns for the unwrapped object.
-2282 while hasattr(nsobj, '__wrapped__'):
-2283 nsobj = nsobj.__wrapped__
-2284 globalns = getattr(nsobj, '__globals__', {})
-2285 if localns is None:
-2286 localns = globalns
-2287 elif localns is None:
-2288 localns = globalns
-2289 hints = getattr(obj, '__annotations__', None)
-2290 if hints is None:
-2291 # Return empty annotations for something that _could_ have them.
-2292 if isinstance(obj, _allowed_types):
-2293 return {}
-2294 else:
-2295 raise TypeError('{!r} is not a module, class, method, '
-2296 'or function.'.format(obj))
-2297 hints = dict(hints)
-2298 type_params = getattr(obj, "__type_params__", ())
-2299 for name, value in hints.items():
-2300 if value is None:
-2301 value = type(None)
-2302 if isinstance(value, str):
-2303 # class-level forward refs were handled above, this must be either
-2304 # a module-level annotation or a function argument annotation
-2305 value = ForwardRef(
-2306 value,
-2307 is_argument=not isinstance(obj, types.ModuleType),
-2308 is_class=False,
-2309 )
-2310 hints[name] = _eval_type(value, globalns, localns, type_params)
-2311 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
-2312
+2214
+2215def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
+2216 """Return type hints for an object.
+2217
+2218 This is often the same as obj.__annotations__, but it handles
+2219 forward references encoded as string literals and recursively replaces all
+2220 'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
+2221
+2222 The argument may be a module, class, method, or function. The annotations
+2223 are returned as a dictionary. For classes, annotations include also
+2224 inherited members.
+2225
+2226 TypeError is raised if the argument is not of a type that can contain
+2227 annotations, and an empty dictionary is returned if no annotations are
+2228 present.
+2229
+2230 BEWARE -- the behavior of globalns and localns is counterintuitive
+2231 (unless you are familiar with how eval() and exec() work). The
+2232 search order is locals first, then globals.
+2233
+2234 - If no dict arguments are passed, an attempt is made to use the
+2235 globals from obj (or the respective module's globals for classes),
+2236 and these are also used as the locals. If the object does not appear
+2237 to have globals, an empty dictionary is used. For classes, the search
+2238 order is globals first then locals.
+2239
+2240 - If one dict argument is passed, it is used for both globals and
+2241 locals.
+2242
+2243 - If two dict arguments are passed, they specify globals and
+2244 locals, respectively.
+2245 """
+2246 if getattr(obj, '__no_type_check__', None):
+2247 return {}
+2248 # Classes require a special treatment.
+2249 if isinstance(obj, type):
+2250 hints = {}
+2251 for base in reversed(obj.__mro__):
+2252 if globalns is None:
+2253 base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {})
+2254 else:
+2255 base_globals = globalns
+2256 ann = base.__dict__.get('__annotations__', {})
+2257 if isinstance(ann, types.GetSetDescriptorType):
+2258 ann = {}
+2259 base_locals = dict(vars(base)) if localns is None else localns
+2260 if localns is None and globalns is None:
+2261 # This is surprising, but required. Before Python 3.10,
+2262 # get_type_hints only evaluated the globalns of
+2263 # a class. To maintain backwards compatibility, we reverse
+2264 # the globalns and localns order so that eval() looks into
+2265 # *base_globals* first rather than *base_locals*.
+2266 # This only affects ForwardRefs.
+2267 base_globals, base_locals = base_locals, base_globals
+2268 for name, value in ann.items():
+2269 if value is None:
+2270 value = type(None)
+2271 if isinstance(value, str):
+2272 value = ForwardRef(value, is_argument=False, is_class=True)
+2273 value = _eval_type(value, base_globals, base_locals, base.__type_params__)
+2274 hints[name] = value
+2275 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
+2276
+2277 if globalns is None:
+2278 if isinstance(obj, types.ModuleType):
+2279 globalns = obj.__dict__
+2280 else:
+2281 nsobj = obj
+2282 # Find globalns for the unwrapped object.
+2283 while hasattr(nsobj, '__wrapped__'):
+2284 nsobj = nsobj.__wrapped__
+2285 globalns = getattr(nsobj, '__globals__', {})
+2286 if localns is None:
+2287 localns = globalns
+2288 elif localns is None:
+2289 localns = globalns
+2290 hints = getattr(obj, '__annotations__', None)
+2291 if hints is None:
+2292 # Return empty annotations for something that _could_ have them.
+2293 if isinstance(obj, _allowed_types):
+2294 return {}
+2295 else:
+2296 raise TypeError('{!r} is not a module, class, method, '
+2297 'or function.'.format(obj))
+2298 hints = dict(hints)
+2299 type_params = getattr(obj, "__type_params__", ())
+2300 for name, value in hints.items():
+2301 if value is None:
+2302 value = type(None)
+2303 if isinstance(value, str):
+2304 # class-level forward refs were handled above, this must be either
+2305 # a module-level annotation or a function argument annotation
+2306 value = ForwardRef(
+2307 value,
+2308 is_argument=not isinstance(obj, types.ModuleType),
+2309 is_class=False,
+2310 )
+2311 hints[name] = _eval_type(value, globalns, localns, type_params)
+2312 return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
2313
-2314def _strip_annotations(t):
-2315 """Strip the annotations from a given type."""
-2316 if isinstance(t, _AnnotatedAlias):
-2317 return _strip_annotations(t.__origin__)
-2318 if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired):
-2319 return _strip_annotations(t.__args__[0])
-2320 if isinstance(t, _GenericAlias):
-2321 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
-2322 if stripped_args == t.__args__:
-2323 return t
-2324 return t.copy_with(stripped_args)
-2325 if isinstance(t, GenericAlias):
-2326 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
-2327 if stripped_args == t.__args__:
-2328 return t
-2329 return GenericAlias(t.__origin__, stripped_args)
-2330 if isinstance(t, types.UnionType):
-2331 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
-2332 if stripped_args == t.__args__:
-2333 return t
-2334 return functools.reduce(operator.or_, stripped_args)
-2335
-2336 return t
-2337
+2314
+2315def _strip_annotations(t):
+2316 """Strip the annotations from a given type."""
+2317 if isinstance(t, _AnnotatedAlias):
+2318 return _strip_annotations(t.__origin__)
+2319 if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired):
+2320 return _strip_annotations(t.__args__[0])
+2321 if isinstance(t, _GenericAlias):
+2322 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
+2323 if stripped_args == t.__args__:
+2324 return t
+2325 return t.copy_with(stripped_args)
+2326 if isinstance(t, GenericAlias):
+2327 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
+2328 if stripped_args == t.__args__:
+2329 return t
+2330 return GenericAlias(t.__origin__, stripped_args)
+2331 if isinstance(t, types.UnionType):
+2332 stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
+2333 if stripped_args == t.__args__:
+2334 return t
+2335 return functools.reduce(operator.or_, stripped_args)
+2336
+2337 return t
2338
-2339def get_origin(tp):
-2340 """Get the unsubscripted version of a type.
-2341
-2342 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar,
-2343 Annotated, and others. Return None for unsupported types.
-2344
-2345 Examples::
-2346
-2347 >>> P = ParamSpec('P')
-2348 >>> assert get_origin(Literal[42]) is Literal
-2349 >>> assert get_origin(int) is None
-2350 >>> assert get_origin(ClassVar[int]) is ClassVar
-2351 >>> assert get_origin(Generic) is Generic
-2352 >>> assert get_origin(Generic[T]) is Generic
-2353 >>> assert get_origin(Union[T, int]) is Union
-2354 >>> assert get_origin(List[Tuple[T, T]][int]) is list
-2355 >>> assert get_origin(P.args) is P
-2356 """
-2357 if isinstance(tp, _AnnotatedAlias):
-2358 return Annotated
-2359 if isinstance(tp, (_BaseGenericAlias, GenericAlias,
-2360 ParamSpecArgs, ParamSpecKwargs)):
-2361 return tp.__origin__
-2362 if tp is Generic:
-2363 return Generic
-2364 if isinstance(tp, types.UnionType):
-2365 return types.UnionType
-2366 return None
-2367
+2339
+2340def get_origin(tp):
+2341 """Get the unsubscripted version of a type.
+2342
+2343 This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar,
+2344 Annotated, and others. Return None for unsupported types.
+2345
+2346 Examples::
+2347
+2348 >>> P = ParamSpec('P')
+2349 >>> assert get_origin(Literal[42]) is Literal
+2350 >>> assert get_origin(int) is None
+2351 >>> assert get_origin(ClassVar[int]) is ClassVar
+2352 >>> assert get_origin(Generic) is Generic
+2353 >>> assert get_origin(Generic[T]) is Generic
+2354 >>> assert get_origin(Union[T, int]) is Union
+2355 >>> assert get_origin(List[Tuple[T, T]][int]) is list
+2356 >>> assert get_origin(P.args) is P
+2357 """
+2358 if isinstance(tp, _AnnotatedAlias):
+2359 return Annotated
+2360 if isinstance(tp, (_BaseGenericAlias, GenericAlias,
+2361 ParamSpecArgs, ParamSpecKwargs)):
+2362 return tp.__origin__
+2363 if tp is Generic:
+2364 return Generic
+2365 if isinstance(tp, types.UnionType):
+2366 return types.UnionType
+2367 return None
2368
-2369def get_args(tp):
-2370 """Get type arguments with all substitutions performed.
-2371
-2372 For unions, basic simplifications used by Union constructor are performed.
-2373
-2374 Examples::
-2375
-2376 >>> T = TypeVar('T')
-2377 >>> assert get_args(Dict[str, int]) == (str, int)
-2378 >>> assert get_args(int) == ()
-2379 >>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
-2380 >>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
-2381 >>> assert get_args(Callable[[], T][int]) == ([], int)
-2382 """
-2383 if isinstance(tp, _AnnotatedAlias):
-2384 return (tp.__origin__,) + tp.__metadata__
-2385 if isinstance(tp, (_GenericAlias, GenericAlias)):
-2386 res = tp.__args__
-2387 if _should_unflatten_callable_args(tp, res):
-2388 res = (list(res[:-1]), res[-1])
-2389 return res
-2390 if isinstance(tp, types.UnionType):
-2391 return tp.__args__
-2392 return ()
-2393
+2369
+2370def get_args(tp):
+2371 """Get type arguments with all substitutions performed.
+2372
+2373 For unions, basic simplifications used by Union constructor are performed.
+2374
+2375 Examples::
+2376
+2377 >>> T = TypeVar('T')
+2378 >>> assert get_args(Dict[str, int]) == (str, int)
+2379 >>> assert get_args(int) == ()
+2380 >>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
+2381 >>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
+2382 >>> assert get_args(Callable[[], T][int]) == ([], int)
+2383 """
+2384 if isinstance(tp, _AnnotatedAlias):
+2385 return (tp.__origin__,) + tp.__metadata__
+2386 if isinstance(tp, (_GenericAlias, GenericAlias)):
+2387 res = tp.__args__
+2388 if _should_unflatten_callable_args(tp, res):
+2389 res = (list(res[:-1]), res[-1])
+2390 return res
+2391 if isinstance(tp, types.UnionType):
+2392 return tp.__args__
+2393 return ()
2394
-2395def is_typeddict(tp):
-2396 """Check if an annotation is a TypedDict class.
-2397
-2398 For example::
-2399
-2400 >>> from typing import TypedDict
-2401 >>> class Film(TypedDict):
-2402 ... title: str
-2403 ... year: int
-2404 ...
-2405 >>> is_typeddict(Film)
-2406 True
-2407 >>> is_typeddict(dict)
-2408 False
-2409 """
-2410 return isinstance(tp, _TypedDictMeta)
-2411
+2395
+2396def is_typeddict(tp):
+2397 """Check if an annotation is a TypedDict class.
+2398
+2399 For example::
+2400
+2401 >>> from typing import TypedDict
+2402 >>> class Film(TypedDict):
+2403 ... title: str
+2404 ... year: int
+2405 ...
+2406 >>> is_typeddict(Film)
+2407 True
+2408 >>> is_typeddict(dict)
+2409 False
+2410 """
+2411 return isinstance(tp, _TypedDictMeta)
2412
-2413_ASSERT_NEVER_REPR_MAX_LENGTH = 100
-2414
+2413
+2414_ASSERT_NEVER_REPR_MAX_LENGTH = 100
2415
-2416def assert_never(arg: Never, /) -> Never:
-2417 """Statically assert that a line of code is unreachable.
-2418
-2419 Example::
-2420
-2421 def int_or_str(arg: int | str) -> None:
-2422 match arg:
-2423 case int():
-2424 print("It's an int")
-2425 case str():
-2426 print("It's a str")
-2427 case _:
-2428 assert_never(arg)
-2429
-2430 If a type checker finds that a call to assert_never() is
-2431 reachable, it will emit an error.
-2432
-2433 At runtime, this throws an exception when called.
-2434 """
-2435 value = repr(arg)
-2436 if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
-2437 value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...'
-2438 raise AssertionError(f"Expected code to be unreachable, but got: {value}")
-2439
+2416
+2417def assert_never(arg: Never, /) -> Never:
+2418 """Statically assert that a line of code is unreachable.
+2419
+2420 Example::
+2421
+2422 def int_or_str(arg: int | str) -> None:
+2423 match arg:
+2424 case int():
+2425 print("It's an int")
+2426 case str():
+2427 print("It's a str")
+2428 case _:
+2429 assert_never(arg)
+2430
+2431 If a type checker finds that a call to assert_never() is
+2432 reachable, it will emit an error.
+2433
+2434 At runtime, this throws an exception when called.
+2435 """
+2436 value = repr(arg)
+2437 if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
+2438 value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...'
+2439 raise AssertionError(f"Expected code to be unreachable, but got: {value}")
2440
-2441def no_type_check(arg):
-2442 """Decorator to indicate that annotations are not type hints.
-2443
-2444 The argument must be a class or function; if it is a class, it
-2445 applies recursively to all methods and classes defined in that class
-2446 (but not to methods defined in its superclasses or subclasses).
-2447
-2448 This mutates the function(s) or class(es) in place.
-2449 """
-2450 if isinstance(arg, type):
-2451 for key in dir(arg):
-2452 obj = getattr(arg, key)
-2453 if (
-2454 not hasattr(obj, '__qualname__')
-2455 or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}'
-2456 or getattr(obj, '__module__', None) != arg.__module__
-2457 ):
-2458 # We only modify objects that are defined in this type directly.
-2459 # If classes / methods are nested in multiple layers,
-2460 # we will modify them when processing their direct holders.
-2461 continue
-2462 # Instance, class, and static methods:
-2463 if isinstance(obj, types.FunctionType):
-2464 obj.__no_type_check__ = True
-2465 if isinstance(obj, types.MethodType):
-2466 obj.__func__.__no_type_check__ = True
-2467 # Nested types:
-2468 if isinstance(obj, type):
-2469 no_type_check(obj)
-2470 try:
-2471 arg.__no_type_check__ = True
-2472 except TypeError: # built-in classes
-2473 pass
-2474 return arg
-2475
+2441
+2442def no_type_check(arg):
+2443 """Decorator to indicate that annotations are not type hints.
+2444
+2445 The argument must be a class or function; if it is a class, it
+2446 applies recursively to all methods and classes defined in that class
+2447 (but not to methods defined in its superclasses or subclasses).
+2448
+2449 This mutates the function(s) or class(es) in place.
+2450 """
+2451 if isinstance(arg, type):
+2452 for key in dir(arg):
+2453 obj = getattr(arg, key)
+2454 if (
+2455 not hasattr(obj, '__qualname__')
+2456 or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}'
+2457 or getattr(obj, '__module__', None) != arg.__module__
+2458 ):
+2459 # We only modify objects that are defined in this type directly.
+2460 # If classes / methods are nested in multiple layers,
+2461 # we will modify them when processing their direct holders.
+2462 continue
+2463 # Instance, class, and static methods:
+2464 if isinstance(obj, types.FunctionType):
+2465 obj.__no_type_check__ = True
+2466 if isinstance(obj, types.MethodType):
+2467 obj.__func__.__no_type_check__ = True
+2468 # Nested types:
+2469 if isinstance(obj, type):
+2470 no_type_check(obj)
+2471 try:
+2472 arg.__no_type_check__ = True
+2473 except TypeError: # built-in classes
+2474 pass
+2475 return arg
2476
-2477def no_type_check_decorator(decorator):
-2478 """Decorator to give another decorator the @no_type_check effect.
-2479
-2480 This wraps the decorator with something that wraps the decorated
-2481 function in @no_type_check.
-2482 """
-2483 @functools.wraps(decorator)
-2484 def wrapped_decorator(*args, **kwds):
-2485 func = decorator(*args, **kwds)
-2486 func = no_type_check(func)
-2487 return func
-2488
-2489 return wrapped_decorator
-2490
+2477
+2478def no_type_check_decorator(decorator):
+2479 """Decorator to give another decorator the @no_type_check effect.
+2480
+2481 This wraps the decorator with something that wraps the decorated
+2482 function in @no_type_check.
+2483 """
+2484 @functools.wraps(decorator)
+2485 def wrapped_decorator(*args, **kwds):
+2486 func = decorator(*args, **kwds)
+2487 func = no_type_check(func)
+2488 return func
+2489
+2490 return wrapped_decorator
2491
-2492def _overload_dummy(*args, **kwds):
-2493 """Helper for @overload to raise when called."""
-2494 raise NotImplementedError(
-2495 "You should not call an overloaded function. "
-2496 "A series of @overload-decorated functions "
-2497 "outside a stub module should always be followed "
-2498 "by an implementation that is not @overload-ed.")
-2499
+2492
+2493def _overload_dummy(*args, **kwds):
+2494 """Helper for @overload to raise when called."""
+2495 raise NotImplementedError(
+2496 "You should not call an overloaded function. "
+2497 "A series of @overload-decorated functions "
+2498 "outside a stub module should always be followed "
+2499 "by an implementation that is not @overload-ed.")
2500
-2501# {module: {qualname: {firstlineno: func}}}
-2502_overload_registry = defaultdict(functools.partial(defaultdict, dict))
-2503
+2501
+2502# {module: {qualname: {firstlineno: func}}}
+2503_overload_registry = defaultdict(functools.partial(defaultdict, dict))
2504
-2505def overload(func):
-2506 """Decorator for overloaded functions/methods.
-2507
-2508 In a stub file, place two or more stub definitions for the same
-2509 function in a row, each decorated with @overload.
-2510
-2511 For example::
-2512
-2513 @overload
-2514 def utf8(value: None) -> None: ...
-2515 @overload
-2516 def utf8(value: bytes) -> bytes: ...
-2517 @overload
-2518 def utf8(value: str) -> bytes: ...
-2519
-2520 In a non-stub file (i.e. a regular .py file), do the same but
-2521 follow it with an implementation. The implementation should *not*
-2522 be decorated with @overload::
-2523
-2524 @overload
-2525 def utf8(value: None) -> None: ...
-2526 @overload
-2527 def utf8(value: bytes) -> bytes: ...
-2528 @overload
-2529 def utf8(value: str) -> bytes: ...
-2530 def utf8(value):
-2531 ... # implementation goes here
-2532
-2533 The overloads for a function can be retrieved at runtime using the
-2534 get_overloads() function.
-2535 """
-2536 # classmethod and staticmethod
-2537 f = getattr(func, "__func__", func)
-2538 try:
-2539 _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func
-2540 except AttributeError:
-2541 # Not a normal function; ignore.
-2542 pass
-2543 return _overload_dummy
-2544
+2505
+2506def overload(func):
+2507 """Decorator for overloaded functions/methods.
+2508
+2509 In a stub file, place two or more stub definitions for the same
+2510 function in a row, each decorated with @overload.
+2511
+2512 For example::
+2513
+2514 @overload
+2515 def utf8(value: None) -> None: ...
+2516 @overload
+2517 def utf8(value: bytes) -> bytes: ...
+2518 @overload
+2519 def utf8(value: str) -> bytes: ...
+2520
+2521 In a non-stub file (i.e. a regular .py file), do the same but
+2522 follow it with an implementation. The implementation should *not*
+2523 be decorated with @overload::
+2524
+2525 @overload
+2526 def utf8(value: None) -> None: ...
+2527 @overload
+2528 def utf8(value: bytes) -> bytes: ...
+2529 @overload
+2530 def utf8(value: str) -> bytes: ...
+2531 def utf8(value):
+2532 ... # implementation goes here
+2533
+2534 The overloads for a function can be retrieved at runtime using the
+2535 get_overloads() function.
+2536 """
+2537 # classmethod and staticmethod
+2538 f = getattr(func, "__func__", func)
+2539 try:
+2540 _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func
+2541 except AttributeError:
+2542 # Not a normal function; ignore.
+2543 pass
+2544 return _overload_dummy
2545
-2546def get_overloads(func):
-2547 """Return all defined overloads for *func* as a sequence."""
-2548 # classmethod and staticmethod
-2549 f = getattr(func, "__func__", func)
-2550 if f.__module__ not in _overload_registry:
-2551 return []
-2552 mod_dict = _overload_registry[f.__module__]
-2553 if f.__qualname__ not in mod_dict:
-2554 return []
-2555 return list(mod_dict[f.__qualname__].values())
-2556
+2546
+2547def get_overloads(func):
+2548 """Return all defined overloads for *func* as a sequence."""
+2549 # classmethod and staticmethod
+2550 f = getattr(func, "__func__", func)
+2551 if f.__module__ not in _overload_registry:
+2552 return []
+2553 mod_dict = _overload_registry[f.__module__]
+2554 if f.__qualname__ not in mod_dict:
+2555 return []
+2556 return list(mod_dict[f.__qualname__].values())
2557
-2558def clear_overloads():
-2559 """Clear all overloads in the registry."""
-2560 _overload_registry.clear()
-2561
+2558
+2559def clear_overloads():
+2560 """Clear all overloads in the registry."""
+2561 _overload_registry.clear()
2562
-2563def final(f):
-2564 """Decorator to indicate final methods and final classes.
-2565
-2566 Use this decorator to indicate to type checkers that the decorated
-2567 method cannot be overridden, and decorated class cannot be subclassed.
-2568
-2569 For example::
-2570
-2571 class Base:
-2572 @final
-2573 def done(self) -> None:
-2574 ...
-2575 class Sub(Base):
-2576 def done(self) -> None: # Error reported by type checker
-2577 ...
-2578
-2579 @final
-2580 class Leaf:
-2581 ...
-2582 class Other(Leaf): # Error reported by type checker
-2583 ...
-2584
-2585 There is no runtime checking of these properties. The decorator
-2586 attempts to set the ``__final__`` attribute to ``True`` on the decorated
-2587 object to allow runtime introspection.
-2588 """
-2589 try:
-2590 f.__final__ = True
-2591 except (AttributeError, TypeError):
-2592 # Skip the attribute silently if it is not writable.
-2593 # AttributeError happens if the object has __slots__ or a
-2594 # read-only property, TypeError if it's a builtin class.
-2595 pass
-2596 return f
-2597
+2563
+2564def final(f):
+2565 """Decorator to indicate final methods and final classes.
+2566
+2567 Use this decorator to indicate to type checkers that the decorated
+2568 method cannot be overridden, and decorated class cannot be subclassed.
+2569
+2570 For example::
+2571
+2572 class Base:
+2573 @final
+2574 def done(self) -> None:
+2575 ...
+2576 class Sub(Base):
+2577 def done(self) -> None: # Error reported by type checker
+2578 ...
+2579
+2580 @final
+2581 class Leaf:
+2582 ...
+2583 class Other(Leaf): # Error reported by type checker
+2584 ...
+2585
+2586 There is no runtime checking of these properties. The decorator
+2587 attempts to set the ``__final__`` attribute to ``True`` on the decorated
+2588 object to allow runtime introspection.
+2589 """
+2590 try:
+2591 f.__final__ = True
+2592 except (AttributeError, TypeError):
+2593 # Skip the attribute silently if it is not writable.
+2594 # AttributeError happens if the object has __slots__ or a
+2595 # read-only property, TypeError if it's a builtin class.
+2596 pass
+2597 return f
2598
-2599# Some unconstrained type variables. These were initially used by the container types.
-2600# They were never meant for export and are now unused, but we keep them around to
-2601# avoid breaking compatibility with users who import them.
-2602T = TypeVar('T') # Any type.
-2603KT = TypeVar('KT') # Key type.
-2604VT = TypeVar('VT') # Value type.
-2605T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
-2606V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
-2607VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
-2608T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant.
-2609# Internal type variable used for Type[].
-2610CT_co = TypeVar('CT_co', covariant=True, bound=type)
-2611
+2599
+2600# Some unconstrained type variables. These were initially used by the container types.
+2601# They were never meant for export and are now unused, but we keep them around to
+2602# avoid breaking compatibility with users who import them.
+2603T = TypeVar('T') # Any type.
+2604KT = TypeVar('KT') # Key type.
+2605VT = TypeVar('VT') # Value type.
+2606T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
+2607V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
+2608VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
+2609T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant.
+2610# Internal type variable used for Type[].
+2611CT_co = TypeVar('CT_co', covariant=True, bound=type)
2612
-2613# A useful type variable with constraints. This represents string types.
-2614# (This one *is* for export!)
-2615AnyStr = TypeVar('AnyStr', bytes, str)
-2616
+2613
+2614# A useful type variable with constraints. This represents string types.
+2615# (This one *is* for export!)
+2616AnyStr = TypeVar('AnyStr', bytes, str)
2617
-2618# Various ABCs mimicking those in collections.abc.
-2619_alias = _SpecialGenericAlias
-2620
-2621Hashable = _alias(collections.abc.Hashable, 0) # Not generic.
-2622Awaitable = _alias(collections.abc.Awaitable, 1)
-2623Coroutine = _alias(collections.abc.Coroutine, 3)
-2624AsyncIterable = _alias(collections.abc.AsyncIterable, 1)
-2625AsyncIterator = _alias(collections.abc.AsyncIterator, 1)
-2626Iterable = _alias(collections.abc.Iterable, 1)
-2627Iterator = _alias(collections.abc.Iterator, 1)
-2628Reversible = _alias(collections.abc.Reversible, 1)
-2629Sized = _alias(collections.abc.Sized, 0) # Not generic.
-2630Container = _alias(collections.abc.Container, 1)
-2631Collection = _alias(collections.abc.Collection, 1)
-2632Callable = _CallableType(collections.abc.Callable, 2)
-2633Callable.__doc__ = \
-2634 """Deprecated alias to collections.abc.Callable.
-2635
-2636 Callable[[int], str] signifies a function that takes a single
-2637 parameter of type int and returns a str.
-2638
-2639 The subscription syntax must always be used with exactly two
-2640 values: the argument list and the return type.
-2641 The argument list must be a list of types, a ParamSpec,
-2642 Concatenate or ellipsis. The return type must be a single type.
-2643
-2644 There is no syntax to indicate optional or keyword arguments;
-2645 such function types are rarely used as callback types.
-2646 """
-2647AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet')
-2648MutableSet = _alias(collections.abc.MutableSet, 1)
-2649# NOTE: Mapping is only covariant in the value type.
-2650Mapping = _alias(collections.abc.Mapping, 2)
-2651MutableMapping = _alias(collections.abc.MutableMapping, 2)
-2652Sequence = _alias(collections.abc.Sequence, 1)
-2653MutableSequence = _alias(collections.abc.MutableSequence, 1)
-2654ByteString = _DeprecatedGenericAlias(
-2655 collections.abc.ByteString, 0, removal_version=(3, 14) # Not generic.
-2656)
-2657# Tuple accepts variable number of parameters.
-2658Tuple = _TupleType(tuple, -1, inst=False, name='Tuple')
-2659Tuple.__doc__ = \
-2660 """Deprecated alias to builtins.tuple.
-2661
-2662 Tuple[X, Y] is the cross-product type of X and Y.
-2663
-2664 Example: Tuple[T1, T2] is a tuple of two elements corresponding
-2665 to type variables T1 and T2. Tuple[int, float, str] is a tuple
-2666 of an int, a float and a string.
-2667
-2668 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
-2669 """
-2670List = _alias(list, 1, inst=False, name='List')
-2671Deque = _alias(collections.deque, 1, name='Deque')
-2672Set = _alias(set, 1, inst=False, name='Set')
-2673FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet')
-2674MappingView = _alias(collections.abc.MappingView, 1)
-2675KeysView = _alias(collections.abc.KeysView, 1)
-2676ItemsView = _alias(collections.abc.ItemsView, 2)
-2677ValuesView = _alias(collections.abc.ValuesView, 1)
-2678ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager')
-2679AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager')
-2680Dict = _alias(dict, 2, inst=False, name='Dict')
-2681DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict')
-2682OrderedDict = _alias(collections.OrderedDict, 2)
-2683Counter = _alias(collections.Counter, 1)
-2684ChainMap = _alias(collections.ChainMap, 2)
-2685Generator = _alias(collections.abc.Generator, 3)
-2686AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2)
-2687Type = _alias(type, 1, inst=False, name='Type')
-2688Type.__doc__ = \
-2689 """Deprecated alias to builtins.type.
-2690
-2691 builtins.type or typing.Type can be used to annotate class objects.
-2692 For example, suppose we have the following classes::
-2693
-2694 class User: ... # Abstract base for User classes
-2695 class BasicUser(User): ...
-2696 class ProUser(User): ...
-2697 class TeamUser(User): ...
-2698
-2699 And a function that takes a class argument that's a subclass of
-2700 User and returns an instance of the corresponding class::
-2701
-2702 def new_user[U](user_class: Type[U]) -> U:
-2703 user = user_class()
-2704 # (Here we could write the user object to a database)
-2705 return user
-2706
-2707 joe = new_user(BasicUser)
-2708
-2709 At this point the type checker knows that joe has type BasicUser.
-2710 """
-2711
+2618
+2619# Various ABCs mimicking those in collections.abc.
+2620_alias = _SpecialGenericAlias
+2621
+2622Hashable = _alias(collections.abc.Hashable, 0) # Not generic.
+2623Awaitable = _alias(collections.abc.Awaitable, 1)
+2624Coroutine = _alias(collections.abc.Coroutine, 3)
+2625AsyncIterable = _alias(collections.abc.AsyncIterable, 1)
+2626AsyncIterator = _alias(collections.abc.AsyncIterator, 1)
+2627Iterable = _alias(collections.abc.Iterable, 1)
+2628Iterator = _alias(collections.abc.Iterator, 1)
+2629Reversible = _alias(collections.abc.Reversible, 1)
+2630Sized = _alias(collections.abc.Sized, 0) # Not generic.
+2631Container = _alias(collections.abc.Container, 1)
+2632Collection = _alias(collections.abc.Collection, 1)
+2633Callable = _CallableType(collections.abc.Callable, 2)
+2634Callable.__doc__ = \
+2635 """Deprecated alias to collections.abc.Callable.
+2636
+2637 Callable[[int], str] signifies a function that takes a single
+2638 parameter of type int and returns a str.
+2639
+2640 The subscription syntax must always be used with exactly two
+2641 values: the argument list and the return type.
+2642 The argument list must be a list of types, a ParamSpec,
+2643 Concatenate or ellipsis. The return type must be a single type.
+2644
+2645 There is no syntax to indicate optional or keyword arguments;
+2646 such function types are rarely used as callback types.
+2647 """
+2648AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet')
+2649MutableSet = _alias(collections.abc.MutableSet, 1)
+2650# NOTE: Mapping is only covariant in the value type.
+2651Mapping = _alias(collections.abc.Mapping, 2)
+2652MutableMapping = _alias(collections.abc.MutableMapping, 2)
+2653Sequence = _alias(collections.abc.Sequence, 1)
+2654MutableSequence = _alias(collections.abc.MutableSequence, 1)
+2655ByteString = _DeprecatedGenericAlias(
+2656 collections.abc.ByteString, 0, removal_version=(3, 14) # Not generic.
+2657)
+2658# Tuple accepts variable number of parameters.
+2659Tuple = _TupleType(tuple, -1, inst=False, name='Tuple')
+2660Tuple.__doc__ = \
+2661 """Deprecated alias to builtins.tuple.
+2662
+2663 Tuple[X, Y] is the cross-product type of X and Y.
+2664
+2665 Example: Tuple[T1, T2] is a tuple of two elements corresponding
+2666 to type variables T1 and T2. Tuple[int, float, str] is a tuple
+2667 of an int, a float and a string.
+2668
+2669 To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
+2670 """
+2671List = _alias(list, 1, inst=False, name='List')
+2672Deque = _alias(collections.deque, 1, name='Deque')
+2673Set = _alias(set, 1, inst=False, name='Set')
+2674FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet')
+2675MappingView = _alias(collections.abc.MappingView, 1)
+2676KeysView = _alias(collections.abc.KeysView, 1)
+2677ItemsView = _alias(collections.abc.ItemsView, 2)
+2678ValuesView = _alias(collections.abc.ValuesView, 1)
+2679ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager')
+2680AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager')
+2681Dict = _alias(dict, 2, inst=False, name='Dict')
+2682DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict')
+2683OrderedDict = _alias(collections.OrderedDict, 2)
+2684Counter = _alias(collections.Counter, 1)
+2685ChainMap = _alias(collections.ChainMap, 2)
+2686Generator = _alias(collections.abc.Generator, 3)
+2687AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2)
+2688Type = _alias(type, 1, inst=False, name='Type')
+2689Type.__doc__ = \
+2690 """Deprecated alias to builtins.type.
+2691
+2692 builtins.type or typing.Type can be used to annotate class objects.
+2693 For example, suppose we have the following classes::
+2694
+2695 class User: ... # Abstract base for User classes
+2696 class BasicUser(User): ...
+2697 class ProUser(User): ...
+2698 class TeamUser(User): ...
+2699
+2700 And a function that takes a class argument that's a subclass of
+2701 User and returns an instance of the corresponding class::
+2702
+2703 def new_user[U](user_class: Type[U]) -> U:
+2704 user = user_class()
+2705 # (Here we could write the user object to a database)
+2706 return user
+2707
+2708 joe = new_user(BasicUser)
+2709
+2710 At this point the type checker knows that joe has type BasicUser.
+2711 """
2712
-2713@runtime_checkable
-2714class SupportsInt(Protocol):
-2715 """An ABC with one abstract method __int__."""
-2716
-2717 __slots__ = ()
-2718
-2719 @abstractmethod
-2720 def __int__(self) -> int:
-2721 pass
-2722
+2713
+2714@runtime_checkable
+2715class SupportsInt(Protocol):
+2716 """An ABC with one abstract method __int__."""
+2717
+2718 __slots__ = ()
+2719
+2720 @abstractmethod
+2721 def __int__(self) -> int:
+2722 pass
2723
-2724@runtime_checkable
-2725class SupportsFloat(Protocol):
-2726 """An ABC with one abstract method __float__."""
-2727
-2728 __slots__ = ()
-2729
-2730 @abstractmethod
-2731 def __float__(self) -> float:
-2732 pass
-2733
+2724
+2725@runtime_checkable
+2726class SupportsFloat(Protocol):
+2727 """An ABC with one abstract method __float__."""
+2728
+2729 __slots__ = ()
+2730
+2731 @abstractmethod
+2732 def __float__(self) -> float:
+2733 pass
2734
-2735@runtime_checkable
-2736class SupportsComplex(Protocol):
-2737 """An ABC with one abstract method __complex__."""
-2738
-2739 __slots__ = ()
-2740
-2741 @abstractmethod
-2742 def __complex__(self) -> complex:
-2743 pass
-2744
+2735
+2736@runtime_checkable
+2737class SupportsComplex(Protocol):
+2738 """An ABC with one abstract method __complex__."""
+2739
+2740 __slots__ = ()
+2741
+2742 @abstractmethod
+2743 def __complex__(self) -> complex:
+2744 pass
2745
-2746@runtime_checkable
-2747class SupportsBytes(Protocol):
-2748 """An ABC with one abstract method __bytes__."""
-2749
-2750 __slots__ = ()
-2751
-2752 @abstractmethod
-2753 def __bytes__(self) -> bytes:
-2754 pass
-2755
+2746
+2747@runtime_checkable
+2748class SupportsBytes(Protocol):
+2749 """An ABC with one abstract method __bytes__."""
+2750
+2751 __slots__ = ()
+2752
+2753 @abstractmethod
+2754 def __bytes__(self) -> bytes:
+2755 pass
2756
-2757@runtime_checkable
-2758class SupportsIndex(Protocol):
-2759 """An ABC with one abstract method __index__."""
-2760
-2761 __slots__ = ()
-2762
-2763 @abstractmethod
-2764 def __index__(self) -> int:
-2765 pass
-2766
+2757
+2758@runtime_checkable
+2759class SupportsIndex(Protocol):
+2760 """An ABC with one abstract method __index__."""
+2761
+2762 __slots__ = ()
+2763
+2764 @abstractmethod
+2765 def __index__(self) -> int:
+2766 pass
2767
-2768@runtime_checkable
-2769class SupportsAbs[T](Protocol):
-2770 """An ABC with one abstract method __abs__ that is covariant in its return type."""
-2771
-2772 __slots__ = ()
-2773
-2774 @abstractmethod
-2775 def __abs__(self) -> T:
-2776 pass
-2777
+2768
+2769@runtime_checkable
+2770class SupportsAbs[T](Protocol):
+2771 """An ABC with one abstract method __abs__ that is covariant in its return type."""
+2772
+2773 __slots__ = ()
+2774
+2775 @abstractmethod
+2776 def __abs__(self) -> T:
+2777 pass
2778
-2779@runtime_checkable
-2780class SupportsRound[T](Protocol):
-2781 """An ABC with one abstract method __round__ that is covariant in its return type."""
-2782
-2783 __slots__ = ()
-2784
-2785 @abstractmethod
-2786 def __round__(self, ndigits: int = 0) -> T:
-2787 pass
-2788
+2779
+2780@runtime_checkable
+2781class SupportsRound[T](Protocol):
+2782 """An ABC with one abstract method __round__ that is covariant in its return type."""
+2783
+2784 __slots__ = ()
+2785
+2786 @abstractmethod
+2787 def __round__(self, ndigits: int = 0) -> T:
+2788 pass
2789
-2790def _make_nmtuple(name, types, module, defaults = ()):
-2791 fields = [n for n, t in types]
-2792 types = {n: _type_check(t, f"field {n} annotation must be a type")
-2793 for n, t in types}
-2794 nm_tpl = collections.namedtuple(name, fields,
-2795 defaults=defaults, module=module)
-2796 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types
-2797 return nm_tpl
-2798
+2790
+2791def _make_nmtuple(name, types, module, defaults = ()):
+2792 fields = [n for n, t in types]
+2793 types = {n: _type_check(t, f"field {n} annotation must be a type")
+2794 for n, t in types}
+2795 nm_tpl = collections.namedtuple(name, fields,
+2796 defaults=defaults, module=module)
+2797 nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types
+2798 return nm_tpl
2799
-2800# attributes prohibited to set in NamedTuple class syntax
-2801_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__',
-2802 '_fields', '_field_defaults',
-2803 '_make', '_replace', '_asdict', '_source'})
-2804
-2805_special = frozenset({'__module__', '__name__', '__annotations__'})
-2806
+2800
+2801# attributes prohibited to set in NamedTuple class syntax
+2802_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__',
+2803 '_fields', '_field_defaults',
+2804 '_make', '_replace', '_asdict', '_source'})
+2805
+2806_special = frozenset({'__module__', '__name__', '__annotations__'})
2807
-2808class NamedTupleMeta(type):
-2809 def __new__(cls, typename, bases, ns):
-2810 assert _NamedTuple in bases
-2811 for base in bases:
-2812 if base is not _NamedTuple and base is not Generic:
-2813 raise TypeError(
-2814 'can only inherit from a NamedTuple type and Generic')
-2815 bases = tuple(tuple if base is _NamedTuple else base for base in bases)
-2816 types = ns.get('__annotations__', {})
-2817 default_names = []
-2818 for field_name in types:
-2819 if field_name in ns:
-2820 default_names.append(field_name)
-2821 elif default_names:
-2822 raise TypeError(f"Non-default namedtuple field {field_name} "
-2823 f"cannot follow default field"
-2824 f"{'s' if len(default_names) > 1 else ''} "
-2825 f"{', '.join(default_names)}")
-2826 nm_tpl = _make_nmtuple(typename, types.items(),
-2827 defaults=[ns[n] for n in default_names],
-2828 module=ns['__module__'])
-2829 nm_tpl.__bases__ = bases
-2830 if Generic in bases:
-2831 class_getitem = _generic_class_getitem
-2832 nm_tpl.__class_getitem__ = classmethod(class_getitem)
-2833 # update from user namespace without overriding special namedtuple attributes
-2834 for key in ns:
-2835 if key in _prohibited:
-2836 raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
-2837 elif key not in _special and key not in nm_tpl._fields:
-2838 setattr(nm_tpl, key, ns[key])
-2839 if Generic in bases:
-2840 nm_tpl.__init_subclass__()
-2841 return nm_tpl
-2842
+2808
+2809class NamedTupleMeta(type):
+2810 def __new__(cls, typename, bases, ns):
+2811 assert _NamedTuple in bases
+2812 for base in bases:
+2813 if base is not _NamedTuple and base is not Generic:
+2814 raise TypeError(
+2815 'can only inherit from a NamedTuple type and Generic')
+2816 bases = tuple(tuple if base is _NamedTuple else base for base in bases)
+2817 types = ns.get('__annotations__', {})
+2818 default_names = []
+2819 for field_name in types:
+2820 if field_name in ns:
+2821 default_names.append(field_name)
+2822 elif default_names:
+2823 raise TypeError(f"Non-default namedtuple field {field_name} "
+2824 f"cannot follow default field"
+2825 f"{'s' if len(default_names) > 1 else ''} "
+2826 f"{', '.join(default_names)}")
+2827 nm_tpl = _make_nmtuple(typename, types.items(),
+2828 defaults=[ns[n] for n in default_names],
+2829 module=ns['__module__'])
+2830 nm_tpl.__bases__ = bases
+2831 if Generic in bases:
+2832 class_getitem = _generic_class_getitem
+2833 nm_tpl.__class_getitem__ = classmethod(class_getitem)
+2834 # update from user namespace without overriding special namedtuple attributes
+2835 for key in ns:
+2836 if key in _prohibited:
+2837 raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
+2838 elif key not in _special and key not in nm_tpl._fields:
+2839 setattr(nm_tpl, key, ns[key])
+2840 if Generic in bases:
+2841 nm_tpl.__init_subclass__()
+2842 return nm_tpl
2843
-2844def NamedTuple(typename, fields=None, /, **kwargs):
-2845 """Typed version of namedtuple.
-2846
-2847 Usage::
-2848
-2849 class Employee(NamedTuple):
-2850 name: str
-2851 id: int
-2852
-2853 This is equivalent to::
-2854
-2855 Employee = collections.namedtuple('Employee', ['name', 'id'])
-2856
-2857 The resulting class has an extra __annotations__ attribute, giving a
-2858 dict that maps field names to types. (The field names are also in
-2859 the _fields attribute, which is part of the namedtuple API.)
-2860 An alternative equivalent functional syntax is also accepted::
-2861
-2862 Employee = NamedTuple('Employee', [('name', str), ('id', int)])
-2863 """
-2864 if fields is None:
-2865 fields = kwargs.items()
-2866 elif kwargs:
-2867 raise TypeError("Either list of fields or keywords"
-2868 " can be provided to NamedTuple, not both")
-2869 nt = _make_nmtuple(typename, fields, module=_caller())
-2870 nt.__orig_bases__ = (NamedTuple,)
-2871 return nt
-2872
-2873_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {})
-2874
-2875def _namedtuple_mro_entries(bases):
-2876 assert NamedTuple in bases
-2877 return (_NamedTuple,)
-2878
-2879NamedTuple.__mro_entries__ = _namedtuple_mro_entries
-2880
+2844
+2845def NamedTuple(typename, fields=None, /, **kwargs):
+2846 """Typed version of namedtuple.
+2847
+2848 Usage::
+2849
+2850 class Employee(NamedTuple):
+2851 name: str
+2852 id: int
+2853
+2854 This is equivalent to::
+2855
+2856 Employee = collections.namedtuple('Employee', ['name', 'id'])
+2857
+2858 The resulting class has an extra __annotations__ attribute, giving a
+2859 dict that maps field names to types. (The field names are also in
+2860 the _fields attribute, which is part of the namedtuple API.)
+2861 An alternative equivalent functional syntax is also accepted::
+2862
+2863 Employee = NamedTuple('Employee', [('name', str), ('id', int)])
+2864 """
+2865 if fields is None:
+2866 fields = kwargs.items()
+2867 elif kwargs:
+2868 raise TypeError("Either list of fields or keywords"
+2869 " can be provided to NamedTuple, not both")
+2870 nt = _make_nmtuple(typename, fields, module=_caller())
+2871 nt.__orig_bases__ = (NamedTuple,)
+2872 return nt
+2873
+2874_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {})
+2875
+2876def _namedtuple_mro_entries(bases):
+2877 assert NamedTuple in bases
+2878 return (_NamedTuple,)
+2879
+2880NamedTuple.__mro_entries__ = _namedtuple_mro_entries
2881
-2882class _TypedDictMeta(type):
-2883 def __new__(cls, name, bases, ns, total=True):
-2884 """Create a new typed dict class object.
-2885
-2886 This method is called when TypedDict is subclassed,
-2887 or when TypedDict is instantiated. This way
-2888 TypedDict supports all three syntax forms described in its docstring.
-2889 Subclasses and instances of TypedDict return actual dictionaries.
-2890 """
-2891 for base in bases:
-2892 if type(base) is not _TypedDictMeta and base is not Generic:
-2893 raise TypeError('cannot inherit from both a TypedDict type '
-2894 'and a non-TypedDict base class')
-2895
-2896 if any(issubclass(b, Generic) for b in bases):
-2897 generic_base = (Generic,)
-2898 else:
-2899 generic_base = ()
-2900
-2901 tp_dict = type.__new__(_TypedDictMeta, name, (*generic_base, dict), ns)
-2902
-2903 if not hasattr(tp_dict, '__orig_bases__'):
-2904 tp_dict.__orig_bases__ = bases
-2905
-2906 annotations = {}
-2907 own_annotations = ns.get('__annotations__', {})
-2908 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
-2909 own_annotations = {
-2910 n: _type_check(tp, msg, module=tp_dict.__module__)
-2911 for n, tp in own_annotations.items()
-2912 }
-2913 required_keys = set()
-2914 optional_keys = set()
-2915
-2916 for base in bases:
-2917 annotations.update(base.__dict__.get('__annotations__', {}))
-2918
-2919 base_required = base.__dict__.get('__required_keys__', set())
-2920 required_keys |= base_required
-2921 optional_keys -= base_required
-2922
-2923 base_optional = base.__dict__.get('__optional_keys__', set())
-2924 required_keys -= base_optional
-2925 optional_keys |= base_optional
-2926
-2927 annotations.update(own_annotations)
-2928 for annotation_key, annotation_type in own_annotations.items():
-2929 annotation_origin = get_origin(annotation_type)
-2930 if annotation_origin is Annotated:
-2931 annotation_args = get_args(annotation_type)
-2932 if annotation_args:
-2933 annotation_type = annotation_args[0]
-2934 annotation_origin = get_origin(annotation_type)
-2935
-2936 if annotation_origin is Required:
-2937 is_required = True
-2938 elif annotation_origin is NotRequired:
-2939 is_required = False
-2940 else:
-2941 is_required = total
-2942
-2943 if is_required:
-2944 required_keys.add(annotation_key)
-2945 optional_keys.discard(annotation_key)
-2946 else:
-2947 optional_keys.add(annotation_key)
-2948 required_keys.discard(annotation_key)
-2949
-2950 assert required_keys.isdisjoint(optional_keys), (
-2951 f"Required keys overlap with optional keys in {name}:"
-2952 f" {required_keys=}, {optional_keys=}"
-2953 )
-2954 tp_dict.__annotations__ = annotations
-2955 tp_dict.__required_keys__ = frozenset(required_keys)
-2956 tp_dict.__optional_keys__ = frozenset(optional_keys)
-2957 if not hasattr(tp_dict, '__total__'):
-2958 tp_dict.__total__ = total
-2959 return tp_dict
-2960
-2961 __call__ = dict # static method
-2962
-2963 def __subclasscheck__(cls, other):
-2964 # Typed dicts are only for static structural subtyping.
-2965 raise TypeError('TypedDict does not support instance and class checks')
-2966
-2967 __instancecheck__ = __subclasscheck__
-2968
+2882
+2883class _TypedDictMeta(type):
+2884 def __new__(cls, name, bases, ns, total=True):
+2885 """Create a new typed dict class object.
+2886
+2887 This method is called when TypedDict is subclassed,
+2888 or when TypedDict is instantiated. This way
+2889 TypedDict supports all three syntax forms described in its docstring.
+2890 Subclasses and instances of TypedDict return actual dictionaries.
+2891 """
+2892 for base in bases:
+2893 if type(base) is not _TypedDictMeta and base is not Generic:
+2894 raise TypeError('cannot inherit from both a TypedDict type '
+2895 'and a non-TypedDict base class')
+2896
+2897 if any(issubclass(b, Generic) for b in bases):
+2898 generic_base = (Generic,)
+2899 else:
+2900 generic_base = ()
+2901
+2902 tp_dict = type.__new__(_TypedDictMeta, name, (*generic_base, dict), ns)
+2903
+2904 if not hasattr(tp_dict, '__orig_bases__'):
+2905 tp_dict.__orig_bases__ = bases
+2906
+2907 annotations = {}
+2908 own_annotations = ns.get('__annotations__', {})
+2909 msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
+2910 own_annotations = {
+2911 n: _type_check(tp, msg, module=tp_dict.__module__)
+2912 for n, tp in own_annotations.items()
+2913 }
+2914 required_keys = set()
+2915 optional_keys = set()
+2916
+2917 for base in bases:
+2918 annotations.update(base.__dict__.get('__annotations__', {}))
+2919
+2920 base_required = base.__dict__.get('__required_keys__', set())
+2921 required_keys |= base_required
+2922 optional_keys -= base_required
+2923
+2924 base_optional = base.__dict__.get('__optional_keys__', set())
+2925 required_keys -= base_optional
+2926 optional_keys |= base_optional
+2927
+2928 annotations.update(own_annotations)
+2929 for annotation_key, annotation_type in own_annotations.items():
+2930 annotation_origin = get_origin(annotation_type)
+2931 if annotation_origin is Annotated:
+2932 annotation_args = get_args(annotation_type)
+2933 if annotation_args:
+2934 annotation_type = annotation_args[0]
+2935 annotation_origin = get_origin(annotation_type)
+2936
+2937 if annotation_origin is Required:
+2938 is_required = True
+2939 elif annotation_origin is NotRequired:
+2940 is_required = False
+2941 else:
+2942 is_required = total
+2943
+2944 if is_required:
+2945 required_keys.add(annotation_key)
+2946 optional_keys.discard(annotation_key)
+2947 else:
+2948 optional_keys.add(annotation_key)
+2949 required_keys.discard(annotation_key)
+2950
+2951 assert required_keys.isdisjoint(optional_keys), (
+2952 f"Required keys overlap with optional keys in {name}:"
+2953 f" {required_keys=}, {optional_keys=}"
+2954 )
+2955 tp_dict.__annotations__ = annotations
+2956 tp_dict.__required_keys__ = frozenset(required_keys)
+2957 tp_dict.__optional_keys__ = frozenset(optional_keys)
+2958 if not hasattr(tp_dict, '__total__'):
+2959 tp_dict.__total__ = total
+2960 return tp_dict
+2961
+2962 __call__ = dict # static method
+2963
+2964 def __subclasscheck__(cls, other):
+2965 # Typed dicts are only for static structural subtyping.
+2966 raise TypeError('TypedDict does not support instance and class checks')
+2967
+2968 __instancecheck__ = __subclasscheck__
2969
-2970def TypedDict(typename, fields=None, /, *, total=True, **kwargs):
-2971 """A simple typed namespace. At runtime it is equivalent to a plain dict.
-2972
-2973 TypedDict creates a dictionary type such that a type checker will expect all
-2974 instances to have a certain set of keys, where each key is
-2975 associated with a value of a consistent type. This expectation
-2976 is not checked at runtime.
-2977
-2978 Usage::
-2979
-2980 >>> class Point2D(TypedDict):
-2981 ... x: int
-2982 ... y: int
-2983 ... label: str
-2984 ...
-2985 >>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
-2986 >>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
-2987 >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
-2988 True
-2989
-2990 The type info can be accessed via the Point2D.__annotations__ dict, and
-2991 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
-2992 TypedDict supports an additional equivalent form::
-2993
-2994 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
-2995
-2996 By default, all keys must be present in a TypedDict. It is possible
-2997 to override this by specifying totality::
-2998
-2999 class Point2D(TypedDict, total=False):
-3000 x: int
-3001 y: int
-3002
-3003 This means that a Point2D TypedDict can have any of the keys omitted. A type
-3004 checker is only expected to support a literal False or True as the value of
-3005 the total argument. True is the default, and makes all items defined in the
-3006 class body be required.
-3007
-3008 The Required and NotRequired special forms can also be used to mark
-3009 individual keys as being required or not required::
-3010
-3011 class Point2D(TypedDict):
-3012 x: int # the "x" key must always be present (Required is the default)
-3013 y: NotRequired[int] # the "y" key can be omitted
-3014
-3015 See PEP 655 for more details on Required and NotRequired.
-3016 """
-3017 if fields is None:
-3018 fields = kwargs
-3019 elif kwargs:
-3020 raise TypeError("TypedDict takes either a dict or keyword arguments,"
-3021 " but not both")
-3022 if kwargs:
-3023 warnings.warn(
-3024 "The kwargs-based syntax for TypedDict definitions is deprecated "
-3025 "in Python 3.11, will be removed in Python 3.13, and may not be "
-3026 "understood by third-party type checkers.",
-3027 DeprecationWarning,
-3028 stacklevel=2,
-3029 )
-3030
-3031 ns = {'__annotations__': dict(fields)}
-3032 module = _caller()
-3033 if module is not None:
-3034 # Setting correct module is necessary to make typed dict classes pickleable.
-3035 ns['__module__'] = module
-3036
-3037 td = _TypedDictMeta(typename, (), ns, total=total)
-3038 td.__orig_bases__ = (TypedDict,)
-3039 return td
-3040
-3041_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
-3042TypedDict.__mro_entries__ = lambda bases: (_TypedDict,)
-3043
+2970
+2971def TypedDict(typename, fields=None, /, *, total=True, **kwargs):
+2972 """A simple typed namespace. At runtime it is equivalent to a plain dict.
+2973
+2974 TypedDict creates a dictionary type such that a type checker will expect all
+2975 instances to have a certain set of keys, where each key is
+2976 associated with a value of a consistent type. This expectation
+2977 is not checked at runtime.
+2978
+2979 Usage::
+2980
+2981 >>> class Point2D(TypedDict):
+2982 ... x: int
+2983 ... y: int
+2984 ... label: str
+2985 ...
+2986 >>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
+2987 >>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
+2988 >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
+2989 True
+2990
+2991 The type info can be accessed via the Point2D.__annotations__ dict, and
+2992 the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
+2993 TypedDict supports an additional equivalent form::
+2994
+2995 Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
+2996
+2997 By default, all keys must be present in a TypedDict. It is possible
+2998 to override this by specifying totality::
+2999
+3000 class Point2D(TypedDict, total=False):
+3001 x: int
+3002 y: int
+3003
+3004 This means that a Point2D TypedDict can have any of the keys omitted. A type
+3005 checker is only expected to support a literal False or True as the value of
+3006 the total argument. True is the default, and makes all items defined in the
+3007 class body be required.
+3008
+3009 The Required and NotRequired special forms can also be used to mark
+3010 individual keys as being required or not required::
+3011
+3012 class Point2D(TypedDict):
+3013 x: int # the "x" key must always be present (Required is the default)
+3014 y: NotRequired[int] # the "y" key can be omitted
+3015
+3016 See PEP 655 for more details on Required and NotRequired.
+3017 """
+3018 if fields is None:
+3019 fields = kwargs
+3020 elif kwargs:
+3021 raise TypeError("TypedDict takes either a dict or keyword arguments,"
+3022 " but not both")
+3023 if kwargs:
+3024 warnings.warn(
+3025 "The kwargs-based syntax for TypedDict definitions is deprecated "
+3026 "in Python 3.11, will be removed in Python 3.13, and may not be "
+3027 "understood by third-party type checkers.",
+3028 DeprecationWarning,
+3029 stacklevel=2,
+3030 )
+3031
+3032 ns = {'__annotations__': dict(fields)}
+3033 module = _caller()
+3034 if module is not None:
+3035 # Setting correct module is necessary to make typed dict classes pickleable.
+3036 ns['__module__'] = module
+3037
+3038 td = _TypedDictMeta(typename, (), ns, total=total)
+3039 td.__orig_bases__ = (TypedDict,)
+3040 return td
+3041
+3042_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
+3043TypedDict.__mro_entries__ = lambda bases: (_TypedDict,)
3044
-3045@_SpecialForm
-3046def Required(self, parameters):
-3047 """Special typing construct to mark a TypedDict key as required.
-3048
-3049 This is mainly useful for total=False TypedDicts.
-3050
-3051 For example::
-3052
-3053 class Movie(TypedDict, total=False):
-3054 title: Required[str]
-3055 year: int
-3056
-3057 m = Movie(
-3058 title='The Matrix', # typechecker error if key is omitted
-3059 year=1999,
-3060 )
-3061
-3062 There is no runtime checking that a required key is actually provided
-3063 when instantiating a related TypedDict.
-3064 """
-3065 item = _type_check(parameters, f'{self._name} accepts only a single type.')
-3066 return _GenericAlias(self, (item,))
-3067
+3045
+3046@_SpecialForm
+3047def Required(self, parameters):
+3048 """Special typing construct to mark a TypedDict key as required.
+3049
+3050 This is mainly useful for total=False TypedDicts.
+3051
+3052 For example::
+3053
+3054 class Movie(TypedDict, total=False):
+3055 title: Required[str]
+3056 year: int
+3057
+3058 m = Movie(
+3059 title='The Matrix', # typechecker error if key is omitted
+3060 year=1999,
+3061 )
+3062
+3063 There is no runtime checking that a required key is actually provided
+3064 when instantiating a related TypedDict.
+3065 """
+3066 item = _type_check(parameters, f'{self._name} accepts only a single type.')
+3067 return _GenericAlias(self, (item,))
3068
-3069@_SpecialForm
-3070def NotRequired(self, parameters):
-3071 """Special typing construct to mark a TypedDict key as potentially missing.
-3072
-3073 For example::
-3074
-3075 class Movie(TypedDict):
-3076 title: str
-3077 year: NotRequired[int]
-3078
-3079 m = Movie(
-3080 title='The Matrix', # typechecker error if key is omitted
-3081 year=1999,
-3082 )
-3083 """
-3084 item = _type_check(parameters, f'{self._name} accepts only a single type.')
-3085 return _GenericAlias(self, (item,))
-3086
+3069
+3070@_SpecialForm
+3071def NotRequired(self, parameters):
+3072 """Special typing construct to mark a TypedDict key as potentially missing.
+3073
+3074 For example::
+3075
+3076 class Movie(TypedDict):
+3077 title: str
+3078 year: NotRequired[int]
+3079
+3080 m = Movie(
+3081 title='The Matrix', # typechecker error if key is omitted
+3082 year=1999,
+3083 )
+3084 """
+3085 item = _type_check(parameters, f'{self._name} accepts only a single type.')
+3086 return _GenericAlias(self, (item,))
3087
-3088class NewType:
-3089 """NewType creates simple unique types with almost zero runtime overhead.
-3090
-3091 NewType(name, tp) is considered a subtype of tp
-3092 by static type checkers. At runtime, NewType(name, tp) returns
-3093 a dummy callable that simply returns its argument.
-3094
-3095 Usage::
-3096
-3097 UserId = NewType('UserId', int)
-3098
-3099 def name_by_id(user_id: UserId) -> str:
-3100 ...
-3101
-3102 UserId('user') # Fails type check
-3103
-3104 name_by_id(42) # Fails type check
-3105 name_by_id(UserId(42)) # OK
-3106
-3107 num = UserId(5) + 1 # type: int
-3108 """
-3109
-3110 __call__ = _idfunc
-3111
-3112 def __init__(self, name, tp):
-3113 self.__qualname__ = name
-3114 if '.' in name:
-3115 name = name.rpartition('.')[-1]
-3116 self.__name__ = name
-3117 self.__supertype__ = tp
-3118 def_mod = _caller()
-3119 if def_mod != 'typing':
-3120 self.__module__ = def_mod
-3121
-3122 def __mro_entries__(self, bases):
-3123 # We defined __mro_entries__ to get a better error message
-3124 # if a user attempts to subclass a NewType instance. bpo-46170
-3125 superclass_name = self.__name__
-3126
-3127 class Dummy:
-3128 def __init_subclass__(cls):
-3129 subclass_name = cls.__name__
-3130 raise TypeError(
-3131 f"Cannot subclass an instance of NewType. Perhaps you were looking for: "
-3132 f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`"
-3133 )
-3134
-3135 return (Dummy,)
-3136
-3137 def __repr__(self):
-3138 return f'{self.__module__}.{self.__qualname__}'
-3139
-3140 def __reduce__(self):
-3141 return self.__qualname__
-3142
-3143 def __or__(self, other):
-3144 return Union[self, other]
-3145
-3146 def __ror__(self, other):
-3147 return Union[other, self]
-3148
+3088
+3089class NewType:
+3090 """NewType creates simple unique types with almost zero runtime overhead.
+3091
+3092 NewType(name, tp) is considered a subtype of tp
+3093 by static type checkers. At runtime, NewType(name, tp) returns
+3094 a dummy callable that simply returns its argument.
+3095
+3096 Usage::
+3097
+3098 UserId = NewType('UserId', int)
+3099
+3100 def name_by_id(user_id: UserId) -> str:
+3101 ...
+3102
+3103 UserId('user') # Fails type check
+3104
+3105 name_by_id(42) # Fails type check
+3106 name_by_id(UserId(42)) # OK
+3107
+3108 num = UserId(5) + 1 # type: int
+3109 """
+3110
+3111 __call__ = _idfunc
+3112
+3113 def __init__(self, name, tp):
+3114 self.__qualname__ = name
+3115 if '.' in name:
+3116 name = name.rpartition('.')[-1]
+3117 self.__name__ = name
+3118 self.__supertype__ = tp
+3119 def_mod = _caller()
+3120 if def_mod != 'typing':
+3121 self.__module__ = def_mod
+3122
+3123 def __mro_entries__(self, bases):
+3124 # We defined __mro_entries__ to get a better error message
+3125 # if a user attempts to subclass a NewType instance. bpo-46170
+3126 superclass_name = self.__name__
+3127
+3128 class Dummy:
+3129 def __init_subclass__(cls):
+3130 subclass_name = cls.__name__
+3131 raise TypeError(
+3132 f"Cannot subclass an instance of NewType. Perhaps you were looking for: "
+3133 f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`"
+3134 )
+3135
+3136 return (Dummy,)
+3137
+3138 def __repr__(self):
+3139 return f'{self.__module__}.{self.__qualname__}'
+3140
+3141 def __reduce__(self):
+3142 return self.__qualname__
+3143
+3144 def __or__(self, other):
+3145 return Union[self, other]
+3146
+3147 def __ror__(self, other):
+3148 return Union[other, self]
3149
-3150# Python-version-specific alias (Python 2: unicode; Python 3: str)
-3151Text = str
-3152
+3150
+3151# Python-version-specific alias (Python 2: unicode; Python 3: str)
+3152Text = str
3153
-3154# Constant that's True when type checking, but False here.
-3155TYPE_CHECKING = False
-3156
+3154
+3155# Constant that's True when type checking, but False here.
+3156TYPE_CHECKING = False
3157
-3158class IO(Generic[AnyStr]):
-3159 """Generic base class for TextIO and BinaryIO.
-3160
-3161 This is an abstract, generic version of the return of open().
-3162
-3163 NOTE: This does not distinguish between the different possible
-3164 classes (text vs. binary, read vs. write vs. read/write,
-3165 append-only, unbuffered). The TextIO and BinaryIO subclasses
-3166 below capture the distinctions between text vs. binary, which is
-3167 pervasive in the interface; however we currently do not offer a
-3168 way to track the other distinctions in the type system.
-3169 """
-3170
-3171 __slots__ = ()
-3172
-3173 @property
-3174 @abstractmethod
-3175 def mode(self) -> str:
-3176 pass
-3177
-3178 @property
-3179 @abstractmethod
-3180 def name(self) -> str:
-3181 pass
-3182
-3183 @abstractmethod
-3184 def close(self) -> None:
-3185 pass
-3186
-3187 @property
-3188 @abstractmethod
-3189 def closed(self) -> bool:
-3190 pass
-3191
-3192 @abstractmethod
-3193 def fileno(self) -> int:
-3194 pass
-3195
-3196 @abstractmethod
-3197 def flush(self) -> None:
-3198 pass
-3199
-3200 @abstractmethod
-3201 def isatty(self) -> bool:
-3202 pass
-3203
-3204 @abstractmethod
-3205 def read(self, n: int = -1) -> AnyStr:
-3206 pass
-3207
-3208 @abstractmethod
-3209 def readable(self) -> bool:
-3210 pass
-3211
-3212 @abstractmethod
-3213 def readline(self, limit: int = -1) -> AnyStr:
-3214 pass
-3215
-3216 @abstractmethod
-3217 def readlines(self, hint: int = -1) -> List[AnyStr]:
-3218 pass
-3219
-3220 @abstractmethod
-3221 def seek(self, offset: int, whence: int = 0) -> int:
-3222 pass
-3223
-3224 @abstractmethod
-3225 def seekable(self) -> bool:
-3226 pass
-3227
-3228 @abstractmethod
-3229 def tell(self) -> int:
-3230 pass
-3231
-3232 @abstractmethod
-3233 def truncate(self, size: int = None) -> int:
-3234 pass
-3235
-3236 @abstractmethod
-3237 def writable(self) -> bool:
-3238 pass
-3239
-3240 @abstractmethod
-3241 def write(self, s: AnyStr) -> int:
-3242 pass
-3243
-3244 @abstractmethod
-3245 def writelines(self, lines: List[AnyStr]) -> None:
-3246 pass
-3247
-3248 @abstractmethod
-3249 def __enter__(self) -> 'IO[AnyStr]':
-3250 pass
-3251
-3252 @abstractmethod
-3253 def __exit__(self, type, value, traceback) -> None:
-3254 pass
-3255
+3158
+3159class IO(Generic[AnyStr]):
+3160 """Generic base class for TextIO and BinaryIO.
+3161
+3162 This is an abstract, generic version of the return of open().
+3163
+3164 NOTE: This does not distinguish between the different possible
+3165 classes (text vs. binary, read vs. write vs. read/write,
+3166 append-only, unbuffered). The TextIO and BinaryIO subclasses
+3167 below capture the distinctions between text vs. binary, which is
+3168 pervasive in the interface; however we currently do not offer a
+3169 way to track the other distinctions in the type system.
+3170 """
+3171
+3172 __slots__ = ()
+3173
+3174 @property
+3175 @abstractmethod
+3176 def mode(self) -> str:
+3177 pass
+3178
+3179 @property
+3180 @abstractmethod
+3181 def name(self) -> str:
+3182 pass
+3183
+3184 @abstractmethod
+3185 def close(self) -> None:
+3186 pass
+3187
+3188 @property
+3189 @abstractmethod
+3190 def closed(self) -> bool:
+3191 pass
+3192
+3193 @abstractmethod
+3194 def fileno(self) -> int:
+3195 pass
+3196
+3197 @abstractmethod
+3198 def flush(self) -> None:
+3199 pass
+3200
+3201 @abstractmethod
+3202 def isatty(self) -> bool:
+3203 pass
+3204
+3205 @abstractmethod
+3206 def read(self, n: int = -1) -> AnyStr:
+3207 pass
+3208
+3209 @abstractmethod
+3210 def readable(self) -> bool:
+3211 pass
+3212
+3213 @abstractmethod
+3214 def readline(self, limit: int = -1) -> AnyStr:
+3215 pass
+3216
+3217 @abstractmethod
+3218 def readlines(self, hint: int = -1) -> List[AnyStr]:
+3219 pass
+3220
+3221 @abstractmethod
+3222 def seek(self, offset: int, whence: int = 0) -> int:
+3223 pass
+3224
+3225 @abstractmethod
+3226 def seekable(self) -> bool:
+3227 pass
+3228
+3229 @abstractmethod
+3230 def tell(self) -> int:
+3231 pass
+3232
+3233 @abstractmethod
+3234 def truncate(self, size: int = None) -> int:
+3235 pass
+3236
+3237 @abstractmethod
+3238 def writable(self) -> bool:
+3239 pass
+3240
+3241 @abstractmethod
+3242 def write(self, s: AnyStr) -> int:
+3243 pass
+3244
+3245 @abstractmethod
+3246 def writelines(self, lines: List[AnyStr]) -> None:
+3247 pass
+3248
+3249 @abstractmethod
+3250 def __enter__(self) -> 'IO[AnyStr]':
+3251 pass
+3252
+3253 @abstractmethod
+3254 def __exit__(self, type, value, traceback) -> None:
+3255 pass
3256
-3257class BinaryIO(IO[bytes]):
-3258 """Typed version of the return of open() in binary mode."""
-3259
-3260 __slots__ = ()
-3261
-3262 @abstractmethod
-3263 def write(self, s: Union[bytes, bytearray]) -> int:
-3264 pass
-3265
-3266 @abstractmethod
-3267 def __enter__(self) -> 'BinaryIO':
-3268 pass
-3269
+3257
+3258class BinaryIO(IO[bytes]):
+3259 """Typed version of the return of open() in binary mode."""
+3260
+3261 __slots__ = ()
+3262
+3263 @abstractmethod
+3264 def write(self, s: Union[bytes, bytearray]) -> int:
+3265 pass
+3266
+3267 @abstractmethod
+3268 def __enter__(self) -> 'BinaryIO':
+3269 pass
3270
-3271class TextIO(IO[str]):
-3272 """Typed version of the return of open() in text mode."""
-3273
-3274 __slots__ = ()
-3275
-3276 @property
-3277 @abstractmethod
-3278 def buffer(self) -> BinaryIO:
-3279 pass
-3280
-3281 @property
-3282 @abstractmethod
-3283 def encoding(self) -> str:
-3284 pass
-3285
-3286 @property
-3287 @abstractmethod
-3288 def errors(self) -> Optional[str]:
-3289 pass
-3290
-3291 @property
-3292 @abstractmethod
-3293 def line_buffering(self) -> bool:
-3294 pass
-3295
-3296 @property
-3297 @abstractmethod
-3298 def newlines(self) -> Any:
-3299 pass
-3300
-3301 @abstractmethod
-3302 def __enter__(self) -> 'TextIO':
-3303 pass
-3304
+3271
+3272class TextIO(IO[str]):
+3273 """Typed version of the return of open() in text mode."""
+3274
+3275 __slots__ = ()
+3276
+3277 @property
+3278 @abstractmethod
+3279 def buffer(self) -> BinaryIO:
+3280 pass
+3281
+3282 @property
+3283 @abstractmethod
+3284 def encoding(self) -> str:
+3285 pass
+3286
+3287 @property
+3288 @abstractmethod
+3289 def errors(self) -> Optional[str]:
+3290 pass
+3291
+3292 @property
+3293 @abstractmethod
+3294 def line_buffering(self) -> bool:
+3295 pass
+3296
+3297 @property
+3298 @abstractmethod
+3299 def newlines(self) -> Any:
+3300 pass
+3301
+3302 @abstractmethod
+3303 def __enter__(self) -> 'TextIO':
+3304 pass
3305
-3306class _DeprecatedType(type):
-3307 def __getattribute__(cls, name):
-3308 if name not in {"__dict__", "__module__", "__doc__"} and name in cls.__dict__:
-3309 warnings.warn(
-3310 f"{cls.__name__} is deprecated, import directly "
-3311 f"from typing instead. {cls.__name__} will be removed "
-3312 "in Python 3.13.",
-3313 DeprecationWarning,
-3314 stacklevel=2,
-3315 )
-3316 return super().__getattribute__(name)
-3317
+3306
+3307class _DeprecatedType(type):
+3308 def __getattribute__(cls, name):
+3309 if name not in {"__dict__", "__module__", "__doc__"} and name in cls.__dict__:
+3310 warnings.warn(
+3311 f"{cls.__name__} is deprecated, import directly "
+3312 f"from typing instead. {cls.__name__} will be removed "
+3313 "in Python 3.13.",
+3314 DeprecationWarning,
+3315 stacklevel=2,
+3316 )
+3317 return super().__getattribute__(name)
3318
-3319class io(metaclass=_DeprecatedType):
-3320 """Wrapper namespace for IO generic classes."""
-3321
-3322 __all__ = ['IO', 'TextIO', 'BinaryIO']
-3323 IO = IO
-3324 TextIO = TextIO
-3325 BinaryIO = BinaryIO
-3326
+3319
+3320class io(metaclass=_DeprecatedType):
+3321 """Wrapper namespace for IO generic classes."""
+3322
+3323 __all__ = ['IO', 'TextIO', 'BinaryIO']
+3324 IO = IO
+3325 TextIO = TextIO
+3326 BinaryIO = BinaryIO
3327
-3328io.__name__ = __name__ + '.io'
-3329sys.modules[io.__name__] = io
-3330
-3331Pattern = _alias(stdlib_re.Pattern, 1)
-3332Match = _alias(stdlib_re.Match, 1)
-3333
-3334class re(metaclass=_DeprecatedType):
-3335 """Wrapper namespace for re type aliases."""
-3336
-3337 __all__ = ['Pattern', 'Match']
-3338 Pattern = Pattern
-3339 Match = Match
-3340
+3328
+3329io.__name__ = __name__ + '.io'
+3330sys.modules[io.__name__] = io
+3331
+3332Pattern = _alias(stdlib_re.Pattern, 1)
+3333Match = _alias(stdlib_re.Match, 1)
+3334
+3335class re(metaclass=_DeprecatedType):
+3336 """Wrapper namespace for re type aliases."""
+3337
+3338 __all__ = ['Pattern', 'Match']
+3339 Pattern = Pattern
+3340 Match = Match
3341
-3342re.__name__ = __name__ + '.re'
-3343sys.modules[re.__name__] = re
-3344
+3342
+3343re.__name__ = __name__ + '.re'
+3344sys.modules[re.__name__] = re
3345
-3346def reveal_type[T](obj: T, /) -> T:
-3347 """Ask a static type checker to reveal the inferred type of an expression.
-3348
-3349 When a static type checker encounters a call to ``reveal_type()``,
-3350 it will emit the inferred type of the argument::
-3351
-3352 x: int = 1
-3353 reveal_type(x)
-3354
-3355 Running a static type checker (e.g., mypy) on this example
-3356 will produce output similar to 'Revealed type is "builtins.int"'.
-3357
-3358 At runtime, the function prints the runtime type of the
-3359 argument and returns the argument unchanged.
-3360 """
-3361 print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr)
-3362 return obj
-3363
+3346
+3347def reveal_type[T](obj: T, /) -> T:
+3348 """Ask a static type checker to reveal the inferred type of an expression.
+3349
+3350 When a static type checker encounters a call to ``reveal_type()``,
+3351 it will emit the inferred type of the argument::
+3352
+3353 x: int = 1
+3354 reveal_type(x)
+3355
+3356 Running a static type checker (e.g., mypy) on this example
+3357 will produce output similar to 'Revealed type is "builtins.int"'.
+3358
+3359 At runtime, the function prints the runtime type of the
+3360 argument and returns the argument unchanged.
+3361 """
+3362 print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr)
+3363 return obj
3364
-3365class _IdentityCallable(Protocol):
-3366 def __call__[T](self, arg: T, /) -> T:
-3367 ...
-3368
+3365
+3366class _IdentityCallable(Protocol):
+3367 def __call__[T](self, arg: T, /) -> T:
+3368 ...
3369
-3370def dataclass_transform(
-3371 *,
-3372 eq_default: bool = True,
-3373 order_default: bool = False,
-3374 kw_only_default: bool = False,
-3375 frozen_default: bool = False,
-3376 field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (),
-3377 **kwargs: Any,
-3378) -> _IdentityCallable:
-3379 """Decorator to mark an object as providing dataclass-like behaviour.
-3380
-3381 The decorator can be applied to a function, class, or metaclass.
-3382
-3383 Example usage with a decorator function::
-3384
-3385 @dataclass_transform()
-3386 def create_model[T](cls: type[T]) -> type[T]:
-3387 ...
-3388 return cls
-3389
-3390 @create_model
-3391 class CustomerModel:
-3392 id: int
-3393 name: str
-3394
-3395 On a base class::
-3396
-3397 @dataclass_transform()
-3398 class ModelBase: ...
-3399
-3400 class CustomerModel(ModelBase):
-3401 id: int
-3402 name: str
-3403
-3404 On a metaclass::
-3405
-3406 @dataclass_transform()
-3407 class ModelMeta(type): ...
-3408
-3409 class ModelBase(metaclass=ModelMeta): ...
-3410
-3411 class CustomerModel(ModelBase):
-3412 id: int
-3413 name: str
-3414
-3415 The ``CustomerModel`` classes defined above will
-3416 be treated by type checkers similarly to classes created with
-3417 ``@dataclasses.dataclass``.
-3418 For example, type checkers will assume these classes have
-3419 ``__init__`` methods that accept ``id`` and ``name``.
-3420
-3421 The arguments to this decorator can be used to customize this behavior:
-3422 - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
-3423 ``True`` or ``False`` if it is omitted by the caller.
-3424 - ``order_default`` indicates whether the ``order`` parameter is
-3425 assumed to be True or False if it is omitted by the caller.
-3426 - ``kw_only_default`` indicates whether the ``kw_only`` parameter is
-3427 assumed to be True or False if it is omitted by the caller.
-3428 - ``frozen_default`` indicates whether the ``frozen`` parameter is
-3429 assumed to be True or False if it is omitted by the caller.
-3430 - ``field_specifiers`` specifies a static list of supported classes
-3431 or functions that describe fields, similar to ``dataclasses.field()``.
-3432 - Arbitrary other keyword arguments are accepted in order to allow for
-3433 possible future extensions.
-3434
-3435 At runtime, this decorator records its arguments in the
-3436 ``__dataclass_transform__`` attribute on the decorated object.
-3437 It has no other runtime effect.
-3438
-3439 See PEP 681 for more details.
-3440 """
-3441 def decorator(cls_or_fn):
-3442 cls_or_fn.__dataclass_transform__ = {
-3443 "eq_default": eq_default,
-3444 "order_default": order_default,
-3445 "kw_only_default": kw_only_default,
-3446 "frozen_default": frozen_default,
-3447 "field_specifiers": field_specifiers,
-3448 "kwargs": kwargs,
-3449 }
-3450 return cls_or_fn
-3451 return decorator
-3452
+3370
+3371def dataclass_transform(
+3372 *,
+3373 eq_default: bool = True,
+3374 order_default: bool = False,
+3375 kw_only_default: bool = False,
+3376 frozen_default: bool = False,
+3377 field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (),
+3378 **kwargs: Any,
+3379) -> _IdentityCallable:
+3380 """Decorator to mark an object as providing dataclass-like behaviour.
+3381
+3382 The decorator can be applied to a function, class, or metaclass.
+3383
+3384 Example usage with a decorator function::
+3385
+3386 @dataclass_transform()
+3387 def create_model[T](cls: type[T]) -> type[T]:
+3388 ...
+3389 return cls
+3390
+3391 @create_model
+3392 class CustomerModel:
+3393 id: int
+3394 name: str
+3395
+3396 On a base class::
+3397
+3398 @dataclass_transform()
+3399 class ModelBase: ...
+3400
+3401 class CustomerModel(ModelBase):
+3402 id: int
+3403 name: str
+3404
+3405 On a metaclass::
+3406
+3407 @dataclass_transform()
+3408 class ModelMeta(type): ...
+3409
+3410 class ModelBase(metaclass=ModelMeta): ...
+3411
+3412 class CustomerModel(ModelBase):
+3413 id: int
+3414 name: str
+3415
+3416 The ``CustomerModel`` classes defined above will
+3417 be treated by type checkers similarly to classes created with
+3418 ``@dataclasses.dataclass``.
+3419 For example, type checkers will assume these classes have
+3420 ``__init__`` methods that accept ``id`` and ``name``.
+3421
+3422 The arguments to this decorator can be used to customize this behavior:
+3423 - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
+3424 ``True`` or ``False`` if it is omitted by the caller.
+3425 - ``order_default`` indicates whether the ``order`` parameter is
+3426 assumed to be True or False if it is omitted by the caller.
+3427 - ``kw_only_default`` indicates whether the ``kw_only`` parameter is
+3428 assumed to be True or False if it is omitted by the caller.
+3429 - ``frozen_default`` indicates whether the ``frozen`` parameter is
+3430 assumed to be True or False if it is omitted by the caller.
+3431 - ``field_specifiers`` specifies a static list of supported classes
+3432 or functions that describe fields, similar to ``dataclasses.field()``.
+3433 - Arbitrary other keyword arguments are accepted in order to allow for
+3434 possible future extensions.
+3435
+3436 At runtime, this decorator records its arguments in the
+3437 ``__dataclass_transform__`` attribute on the decorated object.
+3438 It has no other runtime effect.
+3439
+3440 See PEP 681 for more details.
+3441 """
+3442 def decorator(cls_or_fn):
+3443 cls_or_fn.__dataclass_transform__ = {
+3444 "eq_default": eq_default,
+3445 "order_default": order_default,
+3446 "kw_only_default": kw_only_default,
+3447 "frozen_default": frozen_default,
+3448 "field_specifiers": field_specifiers,
+3449 "kwargs": kwargs,
+3450 }
+3451 return cls_or_fn
+3452 return decorator
3453
-3454type _Func = Callable[..., Any]
-3455
+3454
+3455type _Func = Callable[..., Any]
3456
-3457def override[F: _Func](method: F, /) -> F:
-3458 """Indicate that a method is intended to override a method in a base class.
-3459
-3460 Usage::
-3461
-3462 class Base:
-3463 def method(self) -> None:
-3464 pass
-3465
-3466 class Child(Base):
-3467 @override
-3468 def method(self) -> None:
-3469 super().method()
-3470
-3471 When this decorator is applied to a method, the type checker will
-3472 validate that it overrides a method or attribute with the same name on a
-3473 base class. This helps prevent bugs that may occur when a base class is
-3474 changed without an equivalent change to a child class.
-3475
-3476 There is no runtime checking of this property. The decorator attempts to
-3477 set the ``__override__`` attribute to ``True`` on the decorated object to
-3478 allow runtime introspection.
-3479
-3480 See PEP 698 for details.
-3481 """
-3482 try:
-3483 method.__override__ = True
-3484 except (AttributeError, TypeError):
-3485 # Skip the attribute silently if it is not writable.
-3486 # AttributeError happens if the object has __slots__ or a
-3487 # read-only property, TypeError if it's a builtin class.
-3488 pass
-3489 return method
+3457
+3458def override[F: _Func](method: F, /) -> F:
+3459 """Indicate that a method is intended to override a method in a base class.
+3460
+3461 Usage::
+3462
+3463 class Base:
+3464 def method(self) -> None:
+3465 pass
+3466
+3467 class Child(Base):
+3468 @override
+3469 def method(self) -> None:
+3470 super().method()
+3471
+3472 When this decorator is applied to a method, the type checker will
+3473 validate that it overrides a method or attribute with the same name on a
+3474 base class. This helps prevent bugs that may occur when a base class is
+3475 changed without an equivalent change to a child class.
+3476
+3477 There is no runtime checking of this property. The decorator attempts to
+3478 set the ``__override__`` attribute to ``True`` on the decorated object to
+3479 allow runtime introspection.
+3480
+3481 See PEP 698 for details.
+3482 """
+3483 try:
+3484 method.__override__ = True
+3485 except (AttributeError, TypeError):
+3486 # Skip the attribute silently if it is not writable.
+3487 # AttributeError happens if the object has __slots__ or a
+3488 # read-only property, TypeError if it's a builtin class.
+3489 pass
+3490 return method
