mirror of https://github.com/python/cpython
2161 lines
69 KiB
Python
2161 lines
69 KiB
Python
import abc
|
|
from abc import abstractmethod, abstractproperty
|
|
import collections
|
|
import contextlib
|
|
import functools
|
|
import re as stdlib_re # Avoid confusion with the re we export.
|
|
import sys
|
|
import types
|
|
try:
|
|
import collections.abc as collections_abc
|
|
except ImportError:
|
|
import collections as collections_abc # Fallback for PY3.2.
|
|
|
|
|
|
# Please keep __all__ alphabetized within each category.
|
|
__all__ = [
|
|
# Super-special typing primitives.
|
|
'Any',
|
|
'Callable',
|
|
'ClassVar',
|
|
'Generic',
|
|
'Optional',
|
|
'Tuple',
|
|
'Type',
|
|
'TypeVar',
|
|
'Union',
|
|
|
|
# ABCs (from collections.abc).
|
|
'AbstractSet', # collections.abc.Set.
|
|
'ByteString',
|
|
'Container',
|
|
'Hashable',
|
|
'ItemsView',
|
|
'Iterable',
|
|
'Iterator',
|
|
'KeysView',
|
|
'Mapping',
|
|
'MappingView',
|
|
'MutableMapping',
|
|
'MutableSequence',
|
|
'MutableSet',
|
|
'Sequence',
|
|
'Sized',
|
|
'ValuesView',
|
|
# The following are added depending on presence
|
|
# of their non-generic counterparts in stdlib:
|
|
# Awaitable,
|
|
# AsyncIterator,
|
|
# AsyncIterable,
|
|
# Coroutine,
|
|
# Collection,
|
|
# ContextManager
|
|
|
|
# Structural checks, a.k.a. protocols.
|
|
'Reversible',
|
|
'SupportsAbs',
|
|
'SupportsFloat',
|
|
'SupportsInt',
|
|
'SupportsRound',
|
|
|
|
# Concrete collection types.
|
|
'Dict',
|
|
'DefaultDict',
|
|
'List',
|
|
'Set',
|
|
'FrozenSet',
|
|
'NamedTuple', # Not really a type.
|
|
'Generator',
|
|
|
|
# One-off things.
|
|
'AnyStr',
|
|
'cast',
|
|
'get_type_hints',
|
|
'NewType',
|
|
'no_type_check',
|
|
'no_type_check_decorator',
|
|
'overload',
|
|
'Text',
|
|
'TYPE_CHECKING',
|
|
]
|
|
|
|
# The pseudo-submodules 're' and 'io' are part of the public
|
|
# namespace, but excluded from __all__ because they might stomp on
|
|
# legitimate imports of those modules.
|
|
|
|
|
|
def _qualname(x):
|
|
if sys.version_info[:2] >= (3, 3):
|
|
return x.__qualname__
|
|
else:
|
|
# Fall back to just name.
|
|
return x.__name__
|
|
|
|
|
|
def _trim_name(nm):
|
|
if nm.startswith('_') and nm not in ('_TypeAlias',
|
|
'_ForwardRef', '_TypingBase', '_FinalTypingBase'):
|
|
nm = nm[1:]
|
|
return nm
|
|
|
|
|
|
class TypingMeta(type):
|
|
"""Metaclass for most types defined in typing module
|
|
(not a part of public API).
|
|
|
|
This overrides __new__() to require an extra keyword parameter
|
|
'_root', which serves as a guard against naive subclassing of the
|
|
typing classes. Any legitimate class defined using a metaclass
|
|
derived from TypingMeta must pass _root=True.
|
|
|
|
This also defines a dummy constructor (all the work for most typing
|
|
constructs is done in __new__) and a nicer repr().
|
|
"""
|
|
|
|
_is_protocol = False
|
|
|
|
def __new__(cls, name, bases, namespace, *, _root=False):
|
|
if not _root:
|
|
raise TypeError("Cannot subclass %s" %
|
|
(', '.join(map(_type_repr, bases)) or '()'))
|
|
return super().__new__(cls, name, bases, namespace)
|
|
|
|
def __init__(self, *args, **kwds):
|
|
pass
|
|
|
|
def _eval_type(self, globalns, localns):
|
|
"""Override this in subclasses to interpret forward references.
|
|
|
|
For example, List['C'] is internally stored as
|
|
List[_ForwardRef('C')], which should evaluate to List[C],
|
|
where C is an object found in globalns or localns (searching
|
|
localns first, of course).
|
|
"""
|
|
return self
|
|
|
|
def _get_type_vars(self, tvars):
|
|
pass
|
|
|
|
def __repr__(self):
|
|
qname = _trim_name(_qualname(self))
|
|
return '%s.%s' % (self.__module__, qname)
|
|
|
|
|
|
class _TypingBase(metaclass=TypingMeta, _root=True):
|
|
"""Internal indicator of special typing constructs."""
|
|
|
|
__slots__ = ()
|
|
|
|
def __init__(self, *args, **kwds):
|
|
pass
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
"""Constructor.
|
|
|
|
This only exists to give a better error message in case
|
|
someone tries to subclass a special typing object (not a good idea).
|
|
"""
|
|
if (len(args) == 3 and
|
|
isinstance(args[0], str) and
|
|
isinstance(args[1], tuple)):
|
|
# Close enough.
|
|
raise TypeError("Cannot subclass %r" % cls)
|
|
return super().__new__(cls)
|
|
|
|
# Things that are not classes also need these.
|
|
def _eval_type(self, globalns, localns):
|
|
return self
|
|
|
|
def _get_type_vars(self, tvars):
|
|
pass
|
|
|
|
def __repr__(self):
|
|
cls = type(self)
|
|
qname = _trim_name(_qualname(cls))
|
|
return '%s.%s' % (cls.__module__, qname)
|
|
|
|
def __call__(self, *args, **kwds):
|
|
raise TypeError("Cannot instantiate %r" % type(self))
|
|
|
|
|
|
class _FinalTypingBase(_TypingBase, _root=True):
|
|
"""Internal mix-in class to prevent instantiation.
|
|
|
|
Prevents instantiation unless _root=True is given in class call.
|
|
It is used to create pseudo-singleton instances Any, Union, Optional, etc.
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, _root=False, **kwds):
|
|
self = super().__new__(cls, *args, **kwds)
|
|
if _root is True:
|
|
return self
|
|
raise TypeError("Cannot instantiate %r" % cls)
|
|
|
|
def __reduce__(self):
|
|
return _trim_name(type(self).__name__)
|
|
|
|
|
|
class _ForwardRef(_TypingBase, _root=True):
|
|
"""Internal wrapper to hold a forward reference."""
|
|
|
|
__slots__ = ('__forward_arg__', '__forward_code__',
|
|
'__forward_evaluated__', '__forward_value__')
|
|
|
|
def __init__(self, arg):
|
|
super().__init__(arg)
|
|
if not isinstance(arg, str):
|
|
raise TypeError('Forward reference must be a string -- got %r' % (arg,))
|
|
try:
|
|
code = compile(arg, '<string>', 'eval')
|
|
except SyntaxError:
|
|
raise SyntaxError('Forward reference must be an expression -- got %r' %
|
|
(arg,))
|
|
self.__forward_arg__ = arg
|
|
self.__forward_code__ = code
|
|
self.__forward_evaluated__ = False
|
|
self.__forward_value__ = None
|
|
|
|
def _eval_type(self, globalns, localns):
|
|
if not self.__forward_evaluated__ or localns is not globalns:
|
|
if globalns is None and localns is None:
|
|
globalns = localns = {}
|
|
elif globalns is None:
|
|
globalns = localns
|
|
elif localns is None:
|
|
localns = globalns
|
|
self.__forward_value__ = _type_check(
|
|
eval(self.__forward_code__, globalns, localns),
|
|
"Forward references must evaluate to types.")
|
|
self.__forward_evaluated__ = True
|
|
return self.__forward_value__
|
|
|
|
def __eq__(self, other):
|
|
if not isinstance(other, _ForwardRef):
|
|
return NotImplemented
|
|
return (self.__forward_arg__ == other.__forward_arg__ and
|
|
self.__forward_value__ == other.__forward_value__)
|
|
|
|
def __hash__(self):
|
|
return hash((self.__forward_arg__, self.__forward_value__))
|
|
|
|
def __instancecheck__(self, obj):
|
|
raise TypeError("Forward references cannot be used with isinstance().")
|
|
|
|
def __subclasscheck__(self, cls):
|
|
raise TypeError("Forward references cannot be used with issubclass().")
|
|
|
|
def __repr__(self):
|
|
return '_ForwardRef(%r)' % (self.__forward_arg__,)
|
|
|
|
|
|
class _TypeAlias(_TypingBase, _root=True):
|
|
"""Internal helper class for defining generic variants of concrete types.
|
|
|
|
Note that this is not a type; let's call it a pseudo-type. It cannot
|
|
be used in instance and subclass checks in parameterized form, i.e.
|
|
``isinstance(42, Match[str])`` raises ``TypeError`` instead of returning
|
|
``False``.
|
|
"""
|
|
|
|
__slots__ = ('name', 'type_var', 'impl_type', 'type_checker')
|
|
|
|
def __init__(self, name, type_var, impl_type, type_checker):
|
|
"""Initializer.
|
|
|
|
Args:
|
|
name: The name, e.g. 'Pattern'.
|
|
type_var: The type parameter, e.g. AnyStr, or the
|
|
specific type, e.g. str.
|
|
impl_type: The implementation type.
|
|
type_checker: Function that takes an impl_type instance.
|
|
and returns a value that should be a type_var instance.
|
|
"""
|
|
assert isinstance(name, str), repr(name)
|
|
assert isinstance(impl_type, type), repr(impl_type)
|
|
assert not isinstance(impl_type, TypingMeta), repr(impl_type)
|
|
assert isinstance(type_var, (type, _TypingBase)), repr(type_var)
|
|
self.name = name
|
|
self.type_var = type_var
|
|
self.impl_type = impl_type
|
|
self.type_checker = type_checker
|
|
|
|
def __repr__(self):
|
|
return "%s[%s]" % (self.name, _type_repr(self.type_var))
|
|
|
|
def __getitem__(self, parameter):
|
|
if not isinstance(self.type_var, TypeVar):
|
|
raise TypeError("%s cannot be further parameterized." % self)
|
|
if self.type_var.__constraints__ and isinstance(parameter, type):
|
|
if not issubclass(parameter, self.type_var.__constraints__):
|
|
raise TypeError("%s is not a valid substitution for %s." %
|
|
(parameter, self.type_var))
|
|
if isinstance(parameter, TypeVar) and parameter is not self.type_var:
|
|
raise TypeError("%s cannot be re-parameterized." % self)
|
|
return self.__class__(self.name, parameter,
|
|
self.impl_type, self.type_checker)
|
|
|
|
def __eq__(self, other):
|
|
if not isinstance(other, _TypeAlias):
|
|
return NotImplemented
|
|
return self.name == other.name and self.type_var == other.type_var
|
|
|
|
def __hash__(self):
|
|
return hash((self.name, self.type_var))
|
|
|
|
def __instancecheck__(self, obj):
|
|
if not isinstance(self.type_var, TypeVar):
|
|
raise TypeError("Parameterized type aliases cannot be used "
|
|
"with isinstance().")
|
|
return isinstance(obj, self.impl_type)
|
|
|
|
def __subclasscheck__(self, cls):
|
|
if not isinstance(self.type_var, TypeVar):
|
|
raise TypeError("Parameterized type aliases cannot be used "
|
|
"with issubclass().")
|
|
return issubclass(cls, self.impl_type)
|
|
|
|
|
|
def _get_type_vars(types, tvars):
|
|
for t in types:
|
|
if isinstance(t, TypingMeta) or isinstance(t, _TypingBase):
|
|
t._get_type_vars(tvars)
|
|
|
|
|
|
def _type_vars(types):
|
|
tvars = []
|
|
_get_type_vars(types, tvars)
|
|
return tuple(tvars)
|
|
|
|
|
|
def _eval_type(t, globalns, localns):
|
|
if isinstance(t, TypingMeta) or isinstance(t, _TypingBase):
|
|
return t._eval_type(globalns, localns)
|
|
return t
|
|
|
|
|
|
def _type_check(arg, msg):
|
|
"""Check that the argument is a type, and return it (internal helper).
|
|
|
|
As a special case, accept None and return type(None) instead.
|
|
Also, _TypeAlias instances (e.g. Match, Pattern) are acceptable.
|
|
|
|
The msg argument is a human-readable error message, e.g.
|
|
|
|
"Union[arg, ...]: arg should be a type."
|
|
|
|
We append the repr() of the actual value (truncated to 100 chars).
|
|
"""
|
|
if arg is None:
|
|
return type(None)
|
|
if isinstance(arg, str):
|
|
arg = _ForwardRef(arg)
|
|
if (isinstance(arg, _TypingBase) and type(arg).__name__ == '_ClassVar' or
|
|
not isinstance(arg, (type, _TypingBase)) and not callable(arg)):
|
|
raise TypeError(msg + " Got %.100r." % (arg,))
|
|
# Bare Union etc. are not valid as type arguments
|
|
if (type(arg).__name__ in ('_Union', '_Optional')
|
|
and not getattr(arg, '__origin__', None)
|
|
or isinstance(arg, TypingMeta) and _gorg(arg) in (Generic, _Protocol)):
|
|
raise TypeError("Plain %s is not valid as type argument" % arg)
|
|
return arg
|
|
|
|
|
|
def _type_repr(obj):
|
|
"""Return the repr() of an object, special-casing types (internal helper).
|
|
|
|
If obj is a type, we return a shorter version than the default
|
|
type.__repr__, based on the module and qualified name, which is
|
|
typically enough to uniquely identify a type. For everything
|
|
else, we fall back on repr(obj).
|
|
"""
|
|
if isinstance(obj, type) and not isinstance(obj, TypingMeta):
|
|
if obj.__module__ == 'builtins':
|
|
return _qualname(obj)
|
|
return '%s.%s' % (obj.__module__, _qualname(obj))
|
|
if obj is ...:
|
|
return('...')
|
|
if isinstance(obj, types.FunctionType):
|
|
return obj.__name__
|
|
return repr(obj)
|
|
|
|
|
|
class _Any(_FinalTypingBase, _root=True):
|
|
"""Special type indicating an unconstrained type.
|
|
|
|
- Any is compatible with every type.
|
|
- Any assumed to have all methods.
|
|
- All values assumed to be instances of Any.
|
|
|
|
Note that all the above statements are true from the point of view of
|
|
static type checkers. At runtime, Any should not be used with instance
|
|
or class checks.
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
def __instancecheck__(self, obj):
|
|
raise TypeError("Any cannot be used with isinstance().")
|
|
|
|
def __subclasscheck__(self, cls):
|
|
raise TypeError("Any cannot be used with issubclass().")
|
|
|
|
|
|
Any = _Any(_root=True)
|
|
|
|
|
|
class TypeVar(_TypingBase, _root=True):
|
|
"""Type variable.
|
|
|
|
Usage::
|
|
|
|
T = TypeVar('T') # Can be anything
|
|
A = TypeVar('A', str, bytes) # Must be str or bytes
|
|
|
|
Type variables exist primarily for the benefit of static type
|
|
checkers. They serve as the parameters for generic types as well
|
|
as for generic function definitions. See class Generic for more
|
|
information on generic types. Generic functions work as follows:
|
|
|
|
def repeat(x: T, n: int) -> List[T]:
|
|
'''Return a list containing n references to x.'''
|
|
return [x]*n
|
|
|
|
def longest(x: A, y: A) -> A:
|
|
'''Return the longest of two strings.'''
|
|
return x if len(x) >= len(y) else y
|
|
|
|
The latter example's signature is essentially the overloading
|
|
of (str, str) -> str and (bytes, bytes) -> bytes. Also note
|
|
that if the arguments are instances of some subclass of str,
|
|
the return type is still plain str.
|
|
|
|
At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
|
|
|
|
Type variables defined with covariant=True or contravariant=True
|
|
can be used do declare covariant or contravariant generic types.
|
|
See PEP 484 for more details. By default generic types are invariant
|
|
in all type variables.
|
|
|
|
Type variables can be introspected. e.g.:
|
|
|
|
T.__name__ == 'T'
|
|
T.__constraints__ == ()
|
|
T.__covariant__ == False
|
|
T.__contravariant__ = False
|
|
A.__constraints__ == (str, bytes)
|
|
"""
|
|
|
|
__slots__ = ('__name__', '__bound__', '__constraints__',
|
|
'__covariant__', '__contravariant__')
|
|
|
|
def __init__(self, name, *constraints, bound=None,
|
|
covariant=False, contravariant=False):
|
|
super().__init__(name, *constraints, bound=bound,
|
|
covariant=covariant, contravariant=contravariant)
|
|
self.__name__ = name
|
|
if covariant and contravariant:
|
|
raise ValueError("Bivariant types are not supported.")
|
|
self.__covariant__ = bool(covariant)
|
|
self.__contravariant__ = bool(contravariant)
|
|
if constraints and bound is not None:
|
|
raise TypeError("Constraints cannot be combined with bound=...")
|
|
if constraints and len(constraints) == 1:
|
|
raise TypeError("A single constraint is not allowed")
|
|
msg = "TypeVar(name, constraint, ...): constraints must be types."
|
|
self.__constraints__ = tuple(_type_check(t, msg) for t in constraints)
|
|
if bound:
|
|
self.__bound__ = _type_check(bound, "Bound must be a type.")
|
|
else:
|
|
self.__bound__ = None
|
|
|
|
def _get_type_vars(self, tvars):
|
|
if self not in tvars:
|
|
tvars.append(self)
|
|
|
|
def __repr__(self):
|
|
if self.__covariant__:
|
|
prefix = '+'
|
|
elif self.__contravariant__:
|
|
prefix = '-'
|
|
else:
|
|
prefix = '~'
|
|
return prefix + self.__name__
|
|
|
|
def __instancecheck__(self, instance):
|
|
raise TypeError("Type variables cannot be used with isinstance().")
|
|
|
|
def __subclasscheck__(self, cls):
|
|
raise TypeError("Type variables cannot be used with issubclass().")
|
|
|
|
|
|
# Some unconstrained type variables. These are used by the container types.
|
|
# (These are not for export.)
|
|
T = TypeVar('T') # Any type.
|
|
KT = TypeVar('KT') # Key type.
|
|
VT = TypeVar('VT') # Value type.
|
|
T_co = TypeVar('T_co', covariant=True) # Any type covariant containers.
|
|
V_co = TypeVar('V_co', covariant=True) # Any type covariant containers.
|
|
VT_co = TypeVar('VT_co', covariant=True) # Value type covariant containers.
|
|
T_contra = TypeVar('T_contra', contravariant=True) # Ditto contravariant.
|
|
|
|
# A useful type variable with constraints. This represents string types.
|
|
# (This one *is* for export!)
|
|
AnyStr = TypeVar('AnyStr', bytes, str)
|
|
|
|
|
|
def _replace_arg(arg, tvars, args):
|
|
"""An internal helper function: replace arg if it is a type variable
|
|
found in tvars with corresponding substitution from args or
|
|
with corresponding substitution sub-tree if arg is a generic type.
|
|
"""
|
|
|
|
if tvars is None:
|
|
tvars = []
|
|
if hasattr(arg, '_subs_tree'):
|
|
return arg._subs_tree(tvars, args)
|
|
if isinstance(arg, TypeVar):
|
|
for i, tvar in enumerate(tvars):
|
|
if arg == tvar:
|
|
return args[i]
|
|
return arg
|
|
|
|
|
|
def _subs_tree(cls, tvars=None, args=None):
|
|
"""An internal helper function: calculate substitution tree
|
|
for generic cls after replacing its type parameters with
|
|
substitutions in tvars -> args (if any).
|
|
Repeat the same following __origin__'s.
|
|
|
|
Return a list of arguments with all possible substitutions
|
|
performed. Arguments that are generic classes themselves are represented
|
|
as tuples (so that no new classes are created by this function).
|
|
For example: _subs_tree(List[Tuple[int, T]][str]) == [(Tuple, int, str)]
|
|
"""
|
|
|
|
if cls.__origin__ is None:
|
|
return cls
|
|
# Make of chain of origins (i.e. cls -> cls.__origin__)
|
|
current = cls.__origin__
|
|
orig_chain = []
|
|
while current.__origin__ is not None:
|
|
orig_chain.append(current)
|
|
current = current.__origin__
|
|
# Replace type variables in __args__ if asked ...
|
|
tree_args = []
|
|
for arg in cls.__args__:
|
|
tree_args.append(_replace_arg(arg, tvars, args))
|
|
# ... then continue replacing down the origin chain.
|
|
for ocls in orig_chain:
|
|
new_tree_args = []
|
|
for i, arg in enumerate(ocls.__args__):
|
|
new_tree_args.append(_replace_arg(arg, ocls.__parameters__, tree_args))
|
|
tree_args = new_tree_args
|
|
return tree_args
|
|
|
|
|
|
def _remove_dups_flatten(parameters):
|
|
"""An internal helper for Union creation and substitution: flatten Union's
|
|
among parameters, then remove duplicates and strict subclasses.
|
|
"""
|
|
|
|
# Flatten out Union[Union[...], ...].
|
|
params = []
|
|
for p in parameters:
|
|
if isinstance(p, _Union) and p.__origin__ is Union:
|
|
params.extend(p.__args__)
|
|
elif isinstance(p, tuple) and len(p) > 0 and p[0] is Union:
|
|
params.extend(p[1:])
|
|
else:
|
|
params.append(p)
|
|
# Weed out strict duplicates, preserving the first of each occurrence.
|
|
all_params = set(params)
|
|
if len(all_params) < len(params):
|
|
new_params = []
|
|
for t in params:
|
|
if t in all_params:
|
|
new_params.append(t)
|
|
all_params.remove(t)
|
|
params = new_params
|
|
assert not all_params, all_params
|
|
# Weed out subclasses.
|
|
# E.g. Union[int, Employee, Manager] == Union[int, Employee].
|
|
# If object is present it will be sole survivor among proper classes.
|
|
# Never discard type variables.
|
|
# (In particular, Union[str, AnyStr] != AnyStr.)
|
|
all_params = set(params)
|
|
for t1 in params:
|
|
if not isinstance(t1, type):
|
|
continue
|
|
if any(isinstance(t2, type) and issubclass(t1, t2)
|
|
for t2 in all_params - {t1}
|
|
if not (isinstance(t2, GenericMeta) and
|
|
t2.__origin__ is not None)):
|
|
all_params.remove(t1)
|
|
return tuple(t for t in params if t in all_params)
|
|
|
|
|
|
def _check_generic(cls, parameters):
|
|
# Check correct count for parameters of a generic cls (internal helper).
|
|
if not cls.__parameters__:
|
|
raise TypeError("%s is not a generic class" % repr(cls))
|
|
alen = len(parameters)
|
|
elen = len(cls.__parameters__)
|
|
if alen != elen:
|
|
raise TypeError("Too %s parameters for %s; actual %s, expected %s" %
|
|
("many" if alen > elen else "few", repr(cls), alen, elen))
|
|
|
|
|
|
_cleanups = []
|
|
|
|
|
|
def _tp_cache(func):
|
|
"""Internal wrapper caching __getitem__ of generic types with a fallback to
|
|
original function for non-hashable arguments.
|
|
"""
|
|
|
|
cached = functools.lru_cache()(func)
|
|
_cleanups.append(cached.cache_clear)
|
|
@functools.wraps(func)
|
|
def inner(*args, **kwds):
|
|
try:
|
|
return cached(*args, **kwds)
|
|
except TypeError:
|
|
pass # All real errors (not unhashable args) are raised below.
|
|
return func(*args, **kwds)
|
|
return inner
|
|
|
|
|
|
class _Union(_FinalTypingBase, _root=True):
|
|
"""Union type; Union[X, Y] means either X or Y.
|
|
|
|
To define a union, use e.g. Union[int, str]. Details:
|
|
|
|
- The arguments must be types and there must be at least one.
|
|
|
|
- None as an argument is a special case and is replaced by
|
|
type(None).
|
|
|
|
- Unions of unions are flattened, e.g.::
|
|
|
|
Union[Union[int, str], float] == Union[int, str, float]
|
|
|
|
- Unions of a single argument vanish, e.g.::
|
|
|
|
Union[int] == int # The constructor actually returns int
|
|
|
|
- Redundant arguments are skipped, e.g.::
|
|
|
|
Union[int, str, int] == Union[int, str]
|
|
|
|
- When comparing unions, the argument order is ignored, e.g.::
|
|
|
|
Union[int, str] == Union[str, int]
|
|
|
|
- When two arguments have a subclass relationship, the least
|
|
derived argument is kept, e.g.::
|
|
|
|
class Employee: pass
|
|
class Manager(Employee): pass
|
|
Union[int, Employee, Manager] == Union[int, Employee]
|
|
Union[Manager, int, Employee] == Union[int, Employee]
|
|
Union[Employee, Manager] == Employee
|
|
|
|
- Similar for object::
|
|
|
|
Union[int, object] == object
|
|
|
|
- You cannot subclass or instantiate a union.
|
|
|
|
- You can use Optional[X] as a shorthand for Union[X, None].
|
|
"""
|
|
|
|
__slots__ = ('__parameters__', '__args__', '__origin__', '__tree_hash__')
|
|
|
|
def __new__(cls, parameters=None, origin=None, *args, _root=False):
|
|
self = super().__new__(cls, parameters, origin, *args, _root=_root)
|
|
if origin is None:
|
|
self.__parameters__ = None
|
|
self.__args__ = None
|
|
self.__origin__ = None
|
|
self.__tree_hash__ = hash(frozenset(('Union',)))
|
|
return self
|
|
if not isinstance(parameters, tuple):
|
|
raise TypeError("Expected parameters=<tuple>")
|
|
if origin is Union:
|
|
parameters = _remove_dups_flatten(parameters)
|
|
# It's not a union if there's only one type left.
|
|
if len(parameters) == 1:
|
|
return parameters[0]
|
|
self.__parameters__ = _type_vars(parameters)
|
|
self.__args__ = parameters
|
|
self.__origin__ = origin
|
|
# Pre-calculate the __hash__ on instantiation.
|
|
# This improves speed for complex substitutions.
|
|
subs_tree = self._subs_tree()
|
|
if isinstance(subs_tree, tuple):
|
|
self.__tree_hash__ = hash(frozenset(subs_tree))
|
|
else:
|
|
self.__tree_hash__ = hash(subs_tree)
|
|
return self
|
|
|
|
def _eval_type(self, globalns, localns):
|
|
if self.__args__ is None:
|
|
return self
|
|
ev_args = tuple(_eval_type(t, globalns, localns) for t in self.__args__)
|
|
ev_origin = _eval_type(self.__origin__, globalns, localns)
|
|
if ev_args == self.__args__ and ev_origin == self.__origin__:
|
|
# Everything is already evaluated.
|
|
return self
|
|
return self.__class__(ev_args, ev_origin, _root=True)
|
|
|
|
def _get_type_vars(self, tvars):
|
|
if self.__origin__ and self.__parameters__:
|
|
_get_type_vars(self.__parameters__, tvars)
|
|
|
|
def __repr__(self):
|
|
if self.__origin__ is None:
|
|
return super().__repr__()
|
|
tree = self._subs_tree()
|
|
if not isinstance(tree, tuple):
|
|
return repr(tree)
|
|
return tree[0]._tree_repr(tree)
|
|
|
|
def _tree_repr(self, tree):
|
|
arg_list = []
|
|
for arg in tree[1:]:
|
|
if not isinstance(arg, tuple):
|
|
arg_list.append(_type_repr(arg))
|
|
else:
|
|
arg_list.append(arg[0]._tree_repr(arg))
|
|
return super().__repr__() + '[%s]' % ', '.join(arg_list)
|
|
|
|
@_tp_cache
|
|
def __getitem__(self, parameters):
|
|
if parameters == ():
|
|
raise TypeError("Cannot take a Union of no types.")
|
|
if not isinstance(parameters, tuple):
|
|
parameters = (parameters,)
|
|
if self.__origin__ is None:
|
|
msg = "Union[arg, ...]: each arg must be a type."
|
|
else:
|
|
msg = "Parameters to generic types must be types."
|
|
parameters = tuple(_type_check(p, msg) for p in parameters)
|
|
if self is not Union:
|
|
_check_generic(self, parameters)
|
|
return self.__class__(parameters, origin=self, _root=True)
|
|
|
|
def _subs_tree(self, tvars=None, args=None):
|
|
if self is Union:
|
|
return Union # Nothing to substitute
|
|
tree_args = _subs_tree(self, tvars, args)
|
|
tree_args = _remove_dups_flatten(tree_args)
|
|
if len(tree_args) == 1:
|
|
return tree_args[0] # Union of a single type is that type
|
|
return (Union,) + tree_args
|
|
|
|
def __eq__(self, other):
|
|
if not isinstance(other, _Union):
|
|
return self._subs_tree() == other
|
|
return self.__tree_hash__ == other.__tree_hash__
|
|
|
|
def __hash__(self):
|
|
return self.__tree_hash__
|
|
|
|
def __instancecheck__(self, obj):
|
|
raise TypeError("Unions cannot be used with isinstance().")
|
|
|
|
def __subclasscheck__(self, cls):
|
|
raise TypeError("Unions cannot be used with issubclass().")
|
|
|
|
|
|
Union = _Union(_root=True)
|
|
|
|
|
|
class _Optional(_FinalTypingBase, _root=True):
|
|
"""Optional type.
|
|
|
|
Optional[X] is equivalent to Union[X, None].
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
@_tp_cache
|
|
def __getitem__(self, arg):
|
|
arg = _type_check(arg, "Optional[t] requires a single type.")
|
|
return Union[arg, type(None)]
|
|
|
|
|
|
Optional = _Optional(_root=True)
|
|
|
|
|
|
def _gorg(a):
|
|
"""Return the farthest origin of a generic class (internal helper)."""
|
|
assert isinstance(a, GenericMeta)
|
|
while a.__origin__ is not None:
|
|
a = a.__origin__
|
|
return a
|
|
|
|
|
|
def _geqv(a, b):
|
|
"""Return whether two generic classes are equivalent (internal helper).
|
|
|
|
The intention is to consider generic class X and any of its
|
|
parameterized forms (X[T], X[int], etc.) as equivalent.
|
|
|
|
However, X is not equivalent to a subclass of X.
|
|
|
|
The relation is reflexive, symmetric and transitive.
|
|
"""
|
|
assert isinstance(a, GenericMeta) and isinstance(b, GenericMeta)
|
|
# Reduce each to its origin.
|
|
return _gorg(a) is _gorg(b)
|
|
|
|
|
|
def _next_in_mro(cls):
|
|
"""Helper for Generic.__new__.
|
|
|
|
Returns the class after the last occurrence of Generic or
|
|
Generic[...] in cls.__mro__.
|
|
"""
|
|
next_in_mro = object
|
|
# Look for the last occurrence of Generic or Generic[...].
|
|
for i, c in enumerate(cls.__mro__[:-1]):
|
|
if isinstance(c, GenericMeta) and _gorg(c) is Generic:
|
|
next_in_mro = cls.__mro__[i+1]
|
|
return next_in_mro
|
|
|
|
|
|
def _valid_for_check(cls):
|
|
"""An internal helper to prohibit isinstance([1], List[str]) etc."""
|
|
if cls is Generic:
|
|
raise TypeError("Class %r cannot be used with class "
|
|
"or instance checks" % cls)
|
|
if (cls.__origin__ is not None and
|
|
sys._getframe(3).f_globals['__name__'] not in ['abc', 'functools']):
|
|
raise TypeError("Parameterized generics cannot be used with class "
|
|
"or instance checks")
|
|
|
|
|
|
def _make_subclasshook(cls):
|
|
"""Construct a __subclasshook__ callable that incorporates
|
|
the associated __extra__ class in subclass checks performed
|
|
against cls.
|
|
"""
|
|
if isinstance(cls.__extra__, abc.ABCMeta):
|
|
# The logic mirrors that of ABCMeta.__subclasscheck__.
|
|
# Registered classes need not be checked here because
|
|
# cls and its extra share the same _abc_registry.
|
|
def __extrahook__(subclass):
|
|
_valid_for_check(cls)
|
|
res = cls.__extra__.__subclasshook__(subclass)
|
|
if res is not NotImplemented:
|
|
return res
|
|
if cls.__extra__ in subclass.__mro__:
|
|
return True
|
|
for scls in cls.__extra__.__subclasses__():
|
|
if isinstance(scls, GenericMeta):
|
|
continue
|
|
if issubclass(subclass, scls):
|
|
return True
|
|
return NotImplemented
|
|
else:
|
|
# For non-ABC extras we'll just call issubclass().
|
|
def __extrahook__(subclass):
|
|
_valid_for_check(cls)
|
|
if cls.__extra__ and issubclass(subclass, cls.__extra__):
|
|
return True
|
|
return NotImplemented
|
|
return __extrahook__
|
|
|
|
|
|
def _no_slots_copy(dct):
|
|
"""Internal helper: copy class __dict__ and clean slots class variables.
|
|
(They will be re-created if necessary by normal class machinery.)
|
|
"""
|
|
dict_copy = dict(dct)
|
|
if '__slots__' in dict_copy:
|
|
for slot in dict_copy['__slots__']:
|
|
dict_copy.pop(slot, None)
|
|
return dict_copy
|
|
|
|
|
|
class GenericMeta(TypingMeta, abc.ABCMeta):
|
|
"""Metaclass for generic types."""
|
|
|
|
def __new__(cls, name, bases, namespace,
|
|
tvars=None, args=None, origin=None, extra=None, orig_bases=None):
|
|
if tvars is not None:
|
|
# Called from __getitem__() below.
|
|
assert origin is not None
|
|
assert all(isinstance(t, TypeVar) for t in tvars), tvars
|
|
else:
|
|
# Called from class statement.
|
|
assert tvars is None, tvars
|
|
assert args is None, args
|
|
assert origin is None, origin
|
|
|
|
# Get the full set of tvars from the bases.
|
|
tvars = _type_vars(bases)
|
|
# Look for Generic[T1, ..., Tn].
|
|
# If found, tvars must be a subset of it.
|
|
# If not found, tvars is it.
|
|
# Also check for and reject plain Generic,
|
|
# and reject multiple Generic[...].
|
|
gvars = None
|
|
for base in bases:
|
|
if base is Generic:
|
|
raise TypeError("Cannot inherit from plain Generic")
|
|
if (isinstance(base, GenericMeta) and
|
|
base.__origin__ is Generic):
|
|
if gvars is not None:
|
|
raise TypeError(
|
|
"Cannot inherit from Generic[...] multiple types.")
|
|
gvars = base.__parameters__
|
|
if gvars is None:
|
|
gvars = tvars
|
|
else:
|
|
tvarset = set(tvars)
|
|
gvarset = set(gvars)
|
|
if not tvarset <= gvarset:
|
|
raise TypeError(
|
|
"Some type variables (%s) "
|
|
"are not listed in Generic[%s]" %
|
|
(", ".join(str(t) for t in tvars if t not in gvarset),
|
|
", ".join(str(g) for g in gvars)))
|
|
tvars = gvars
|
|
|
|
initial_bases = bases
|
|
if extra is not None and type(extra) is abc.ABCMeta and extra not in bases:
|
|
bases = (extra,) + bases
|
|
bases = tuple(_gorg(b) if isinstance(b, GenericMeta) else b for b in bases)
|
|
|
|
# remove bare Generic from bases if there are other generic bases
|
|
if any(isinstance(b, GenericMeta) and b is not Generic for b in bases):
|
|
bases = tuple(b for b in bases if b is not Generic)
|
|
self = super().__new__(cls, name, bases, namespace, _root=True)
|
|
|
|
self.__parameters__ = tvars
|
|
# Be prepared that GenericMeta will be subclassed by TupleMeta
|
|
# and CallableMeta, those two allow ..., (), or [] in __args___.
|
|
self.__args__ = tuple(... if a is _TypingEllipsis else
|
|
() if a is _TypingEmpty else
|
|
a for a in args) if args else None
|
|
self.__origin__ = origin
|
|
self.__extra__ = extra
|
|
# Speed hack (https://github.com/python/typing/issues/196).
|
|
self.__next_in_mro__ = _next_in_mro(self)
|
|
# Preserve base classes on subclassing (__bases__ are type erased now).
|
|
if orig_bases is None:
|
|
self.__orig_bases__ = initial_bases
|
|
|
|
# This allows unparameterized generic collections to be used
|
|
# with issubclass() and isinstance() in the same way as their
|
|
# collections.abc counterparts (e.g., isinstance([], Iterable)).
|
|
if ('__subclasshook__' not in namespace and extra # allow overriding
|
|
or hasattr(self.__subclasshook__, '__name__') and
|
|
self.__subclasshook__.__name__ == '__extrahook__'):
|
|
self.__subclasshook__ = _make_subclasshook(self)
|
|
if isinstance(extra, abc.ABCMeta):
|
|
self._abc_registry = extra._abc_registry
|
|
|
|
if origin and hasattr(origin, '__qualname__'): # Fix for Python 3.2.
|
|
self.__qualname__ = origin.__qualname__
|
|
self.__tree_hash__ = hash(self._subs_tree()) if origin else hash((self.__name__,))
|
|
return self
|
|
|
|
def _get_type_vars(self, tvars):
|
|
if self.__origin__ and self.__parameters__:
|
|
_get_type_vars(self.__parameters__, tvars)
|
|
|
|
def _eval_type(self, globalns, localns):
|
|
ev_origin = (self.__origin__._eval_type(globalns, localns)
|
|
if self.__origin__ else None)
|
|
ev_args = tuple(_eval_type(a, globalns, localns) for a
|
|
in self.__args__) if self.__args__ else None
|
|
if ev_origin == self.__origin__ and ev_args == self.__args__:
|
|
return self
|
|
return self.__class__(self.__name__,
|
|
self.__bases__,
|
|
_no_slots_copy(self.__dict__),
|
|
tvars=_type_vars(ev_args) if ev_args else None,
|
|
args=ev_args,
|
|
origin=ev_origin,
|
|
extra=self.__extra__,
|
|
orig_bases=self.__orig_bases__)
|
|
|
|
def __repr__(self):
|
|
if self.__origin__ is None:
|
|
return super().__repr__()
|
|
return self._tree_repr(self._subs_tree())
|
|
|
|
def _tree_repr(self, tree):
|
|
arg_list = []
|
|
for arg in tree[1:]:
|
|
if arg == ():
|
|
arg_list.append('()')
|
|
elif not isinstance(arg, tuple):
|
|
arg_list.append(_type_repr(arg))
|
|
else:
|
|
arg_list.append(arg[0]._tree_repr(arg))
|
|
return super().__repr__() + '[%s]' % ', '.join(arg_list)
|
|
|
|
def _subs_tree(self, tvars=None, args=None):
|
|
if self.__origin__ is None:
|
|
return self
|
|
tree_args = _subs_tree(self, tvars, args)
|
|
return (_gorg(self),) + tuple(tree_args)
|
|
|
|
def __eq__(self, other):
|
|
if not isinstance(other, GenericMeta):
|
|
return NotImplemented
|
|
if self.__origin__ is None or other.__origin__ is None:
|
|
return self is other
|
|
return self.__tree_hash__ == other.__tree_hash__
|
|
|
|
def __hash__(self):
|
|
return self.__tree_hash__
|
|
|
|
@_tp_cache
|
|
def __getitem__(self, params):
|
|
if not isinstance(params, tuple):
|
|
params = (params,)
|
|
if not params and not _gorg(self) is Tuple:
|
|
raise TypeError(
|
|
"Parameter list to %s[...] cannot be empty" % _qualname(self))
|
|
msg = "Parameters to generic types must be types."
|
|
params = tuple(_type_check(p, msg) for p in params)
|
|
if self is Generic:
|
|
# Generic can only be subscripted with unique type variables.
|
|
if not all(isinstance(p, TypeVar) for p in params):
|
|
raise TypeError(
|
|
"Parameters to Generic[...] must all be type variables")
|
|
if len(set(params)) != len(params):
|
|
raise TypeError(
|
|
"Parameters to Generic[...] must all be unique")
|
|
tvars = params
|
|
args = params
|
|
elif self in (Tuple, Callable):
|
|
tvars = _type_vars(params)
|
|
args = params
|
|
elif self is _Protocol:
|
|
# _Protocol is internal, don't check anything.
|
|
tvars = params
|
|
args = params
|
|
elif self.__origin__ in (Generic, _Protocol):
|
|
# Can't subscript Generic[...] or _Protocol[...].
|
|
raise TypeError("Cannot subscript already-subscripted %s" %
|
|
repr(self))
|
|
else:
|
|
# Subscripting a regular Generic subclass.
|
|
_check_generic(self, params)
|
|
tvars = _type_vars(params)
|
|
args = params
|
|
return self.__class__(self.__name__,
|
|
self.__bases__,
|
|
_no_slots_copy(self.__dict__),
|
|
tvars=tvars,
|
|
args=args,
|
|
origin=self,
|
|
extra=self.__extra__,
|
|
orig_bases=self.__orig_bases__)
|
|
|
|
def __instancecheck__(self, instance):
|
|
# Since we extend ABC.__subclasscheck__ and
|
|
# ABC.__instancecheck__ inlines the cache checking done by the
|
|
# latter, we must extend __instancecheck__ too. For simplicity
|
|
# we just skip the cache check -- instance checks for generic
|
|
# classes are supposed to be rare anyways.
|
|
return issubclass(instance.__class__, self)
|
|
|
|
def __copy__(self):
|
|
return self.__class__(self.__name__, self.__bases__,
|
|
_no_slots_copy(self.__dict__),
|
|
self.__parameters__, self.__args__, self.__origin__,
|
|
self.__extra__, self.__orig_bases__)
|
|
|
|
|
|
# Prevent checks for Generic to crash when defining Generic.
|
|
Generic = None
|
|
|
|
|
|
def _generic_new(base_cls, cls, *args, **kwds):
|
|
# Assure type is erased on instantiation,
|
|
# but attempt to store it in __orig_class__
|
|
if cls.__origin__ is None:
|
|
return base_cls.__new__(cls)
|
|
else:
|
|
origin = _gorg(cls)
|
|
obj = base_cls.__new__(origin)
|
|
try:
|
|
obj.__orig_class__ = cls
|
|
except AttributeError:
|
|
pass
|
|
obj.__init__(*args, **kwds)
|
|
return obj
|
|
|
|
|
|
class Generic(metaclass=GenericMeta):
|
|
"""Abstract base class for generic types.
|
|
|
|
A generic type is typically declared by inheriting from
|
|
this class parameterized with one or more type variables.
|
|
For example, a generic mapping type might be defined as::
|
|
|
|
class Mapping(Generic[KT, VT]):
|
|
def __getitem__(self, key: KT) -> VT:
|
|
...
|
|
# Etc.
|
|
|
|
This class can then be used as follows::
|
|
|
|
def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
|
|
try:
|
|
return mapping[key]
|
|
except KeyError:
|
|
return default
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, Generic):
|
|
raise TypeError("Type Generic cannot be instantiated; "
|
|
"it can be used only as a base class")
|
|
return _generic_new(cls.__next_in_mro__, cls, *args, **kwds)
|
|
|
|
|
|
class _TypingEmpty:
|
|
"""Internal placeholder for () or []. Used by TupleMeta and CallableMeta
|
|
to allow empty list/tuple in specific places, without allowing them
|
|
to sneak in where prohibited.
|
|
"""
|
|
|
|
|
|
class _TypingEllipsis:
|
|
"""Internal placeholder for ... (ellipsis)."""
|
|
|
|
|
|
class TupleMeta(GenericMeta):
|
|
"""Metaclass for Tuple (internal)."""
|
|
|
|
@_tp_cache
|
|
def __getitem__(self, parameters):
|
|
if self.__origin__ is not None or not _geqv(self, Tuple):
|
|
# Normal generic rules apply if this is not the first subscription
|
|
# or a subscription of a subclass.
|
|
return super().__getitem__(parameters)
|
|
if parameters == ():
|
|
return super().__getitem__((_TypingEmpty,))
|
|
if not isinstance(parameters, tuple):
|
|
parameters = (parameters,)
|
|
if len(parameters) == 2 and parameters[1] is ...:
|
|
msg = "Tuple[t, ...]: t must be a type."
|
|
p = _type_check(parameters[0], msg)
|
|
return super().__getitem__((p, _TypingEllipsis))
|
|
msg = "Tuple[t0, t1, ...]: each t must be a type."
|
|
parameters = tuple(_type_check(p, msg) for p in parameters)
|
|
return super().__getitem__(parameters)
|
|
|
|
def __instancecheck__(self, obj):
|
|
if self.__args__ == None:
|
|
return isinstance(obj, tuple)
|
|
raise TypeError("Parameterized Tuple cannot be used "
|
|
"with isinstance().")
|
|
|
|
def __subclasscheck__(self, cls):
|
|
if self.__args__ == None:
|
|
return issubclass(cls, tuple)
|
|
raise TypeError("Parameterized Tuple cannot be used "
|
|
"with issubclass().")
|
|
|
|
|
|
class Tuple(tuple, extra=tuple, metaclass=TupleMeta):
|
|
"""Tuple type; Tuple[X, Y] is the cross-product type of X and Y.
|
|
|
|
Example: Tuple[T1, T2] is a tuple of two elements corresponding
|
|
to type variables T1 and T2. Tuple[int, float, str] is a tuple
|
|
of an int, a float and a string.
|
|
|
|
To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, Tuple):
|
|
raise TypeError("Type Tuple cannot be instantiated; "
|
|
"use tuple() instead")
|
|
return _generic_new(tuple, cls, *args, **kwds)
|
|
|
|
|
|
class CallableMeta(GenericMeta):
|
|
"""Metaclass for Callable (internal)."""
|
|
|
|
def __repr__(self):
|
|
if self.__origin__ is None:
|
|
return super().__repr__()
|
|
return self._tree_repr(self._subs_tree())
|
|
|
|
def _tree_repr(self, tree):
|
|
if _gorg(self) is not Callable:
|
|
return super()._tree_repr(tree)
|
|
# For actual Callable (not its subclass) we override
|
|
# super()._tree_repr() for nice formatting.
|
|
arg_list = []
|
|
for arg in tree[1:]:
|
|
if not isinstance(arg, tuple):
|
|
arg_list.append(_type_repr(arg))
|
|
else:
|
|
arg_list.append(arg[0]._tree_repr(arg))
|
|
if arg_list[0] == '...':
|
|
return repr(tree[0]) + '[..., %s]' % arg_list[1]
|
|
return (repr(tree[0]) +
|
|
'[[%s], %s]' % (', '.join(arg_list[:-1]), arg_list[-1]))
|
|
|
|
def __getitem__(self, parameters):
|
|
"""A thin wrapper around __getitem_inner__ to provide the latter
|
|
with hashable arguments to improve speed.
|
|
"""
|
|
|
|
if self.__origin__ is not None or not _geqv(self, Callable):
|
|
return super().__getitem__(parameters)
|
|
if not isinstance(parameters, tuple) or len(parameters) != 2:
|
|
raise TypeError("Callable must be used as "
|
|
"Callable[[arg, ...], result].")
|
|
args, result = parameters
|
|
if args is Ellipsis:
|
|
parameters = (Ellipsis, result)
|
|
else:
|
|
if not isinstance(args, list):
|
|
raise TypeError("Callable[args, result]: args must be a list."
|
|
" Got %.100r." % (args,))
|
|
parameters = (tuple(args), result)
|
|
return self.__getitem_inner__(parameters)
|
|
|
|
@_tp_cache
|
|
def __getitem_inner__(self, parameters):
|
|
args, result = parameters
|
|
msg = "Callable[args, result]: result must be a type."
|
|
result = _type_check(result, msg)
|
|
if args is Ellipsis:
|
|
return super().__getitem__((_TypingEllipsis, result))
|
|
msg = "Callable[[arg, ...], result]: each arg must be a type."
|
|
args = tuple(_type_check(arg, msg) for arg in args)
|
|
parameters = args + (result,)
|
|
return super().__getitem__(parameters)
|
|
|
|
|
|
class Callable(extra=collections_abc.Callable, metaclass = CallableMeta):
|
|
"""Callable type; Callable[[int], str] is a function of (int) -> str.
|
|
|
|
The subscription syntax must always be used with exactly two
|
|
values: the argument list and the return type. The argument list
|
|
must be a list of types or ellipsis; the return type must be a single type.
|
|
|
|
There is no syntax to indicate optional or keyword arguments,
|
|
such function types are rarely used as callback types.
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, Callable):
|
|
raise TypeError("Type Callable cannot be instantiated; "
|
|
"use a non-abstract subclass instead")
|
|
return _generic_new(cls.__next_in_mro__, cls, *args, **kwds)
|
|
|
|
|
|
class _ClassVar(_FinalTypingBase, _root=True):
|
|
"""Special type construct to mark class variables.
|
|
|
|
An annotation wrapped in ClassVar indicates that a given
|
|
attribute is intended to be used as a class variable and
|
|
should not be set on instances of that class. Usage::
|
|
|
|
class Starship:
|
|
stats: ClassVar[Dict[str, int]] = {} # class variable
|
|
damage: int = 10 # instance variable
|
|
|
|
ClassVar accepts only types and cannot be further subscribed.
|
|
|
|
Note that ClassVar is not a class itself, and should not
|
|
be used with isinstance() or issubclass().
|
|
"""
|
|
|
|
__slots__ = ('__type__',)
|
|
|
|
def __init__(self, tp=None, **kwds):
|
|
self.__type__ = tp
|
|
|
|
def __getitem__(self, item):
|
|
cls = type(self)
|
|
if self.__type__ is None:
|
|
return cls(_type_check(item,
|
|
'{} accepts only single type.'.format(cls.__name__[1:])),
|
|
_root=True)
|
|
raise TypeError('{} cannot be further subscripted'
|
|
.format(cls.__name__[1:]))
|
|
|
|
def _eval_type(self, globalns, localns):
|
|
new_tp = _eval_type(self.__type__, globalns, localns)
|
|
if new_tp == self.__type__:
|
|
return self
|
|
return type(self)(new_tp, _root=True)
|
|
|
|
def __repr__(self):
|
|
r = super().__repr__()
|
|
if self.__type__ is not None:
|
|
r += '[{}]'.format(_type_repr(self.__type__))
|
|
return r
|
|
|
|
def __hash__(self):
|
|
return hash((type(self).__name__, self.__type__))
|
|
|
|
def __eq__(self, other):
|
|
if not isinstance(other, _ClassVar):
|
|
return NotImplemented
|
|
if self.__type__ is not None:
|
|
return self.__type__ == other.__type__
|
|
return self is other
|
|
|
|
|
|
ClassVar = _ClassVar(_root=True)
|
|
|
|
|
|
def cast(typ, val):
|
|
"""Cast a value to a type.
|
|
|
|
This returns the value unchanged. To the type checker this
|
|
signals that the return value has the designated type, but at
|
|
runtime we intentionally don't check anything (we want this
|
|
to be as fast as possible).
|
|
"""
|
|
return val
|
|
|
|
|
|
def _get_defaults(func):
|
|
"""Internal helper to extract the default arguments, by name."""
|
|
try:
|
|
code = func.__code__
|
|
except AttributeError:
|
|
# Some built-in functions don't have __code__, __defaults__, etc.
|
|
return {}
|
|
pos_count = code.co_argcount
|
|
arg_names = code.co_varnames
|
|
arg_names = arg_names[:pos_count]
|
|
defaults = func.__defaults__ or ()
|
|
kwdefaults = func.__kwdefaults__
|
|
res = dict(kwdefaults) if kwdefaults else {}
|
|
pos_offset = pos_count - len(defaults)
|
|
for name, value in zip(arg_names[pos_offset:], defaults):
|
|
assert name not in res
|
|
res[name] = value
|
|
return res
|
|
|
|
|
|
def get_type_hints(obj, globalns=None, localns=None):
|
|
"""Return type hints for an object.
|
|
|
|
This is often the same as obj.__annotations__, but it handles
|
|
forward references encoded as string literals, and if necessary
|
|
adds Optional[t] if a default value equal to None is set.
|
|
|
|
The argument may be a module, class, method, or function. The annotations
|
|
are returned as a dictionary. For classes, annotations include also
|
|
inherited members.
|
|
|
|
TypeError is raised if the argument is not of a type that can contain
|
|
annotations, and an empty dictionary is returned if no annotations are
|
|
present.
|
|
|
|
BEWARE -- the behavior of globalns and localns is counterintuitive
|
|
(unless you are familiar with how eval() and exec() work). The
|
|
search order is locals first, then globals.
|
|
|
|
- If no dict arguments are passed, an attempt is made to use the
|
|
globals from obj, and these are also used as the locals. If the
|
|
object does not appear to have globals, an exception is raised.
|
|
|
|
- If one dict argument is passed, it is used for both globals and
|
|
locals.
|
|
|
|
- If two dict arguments are passed, they specify globals and
|
|
locals, respectively.
|
|
"""
|
|
|
|
if getattr(obj, '__no_type_check__', None):
|
|
return {}
|
|
if globalns is None:
|
|
globalns = getattr(obj, '__globals__', {})
|
|
if localns is None:
|
|
localns = globalns
|
|
elif localns is None:
|
|
localns = globalns
|
|
# Classes require a special treatment.
|
|
if isinstance(obj, type):
|
|
hints = {}
|
|
for base in reversed(obj.__mro__):
|
|
ann = base.__dict__.get('__annotations__', {})
|
|
for name, value in ann.items():
|
|
if value is None:
|
|
value = type(None)
|
|
if isinstance(value, str):
|
|
value = _ForwardRef(value)
|
|
value = _eval_type(value, globalns, localns)
|
|
hints[name] = value
|
|
return hints
|
|
hints = getattr(obj, '__annotations__', None)
|
|
if hints is None:
|
|
# Return empty annotations for something that _could_ have them.
|
|
if (isinstance(obj, types.FunctionType) or
|
|
isinstance(obj, types.BuiltinFunctionType) or
|
|
isinstance(obj, types.MethodType) or
|
|
isinstance(obj, types.ModuleType)):
|
|
return {}
|
|
else:
|
|
raise TypeError('{!r} is not a module, class, method, '
|
|
'or function.'.format(obj))
|
|
defaults = _get_defaults(obj)
|
|
hints = dict(hints)
|
|
for name, value in hints.items():
|
|
if value is None:
|
|
value = type(None)
|
|
if isinstance(value, str):
|
|
value = _ForwardRef(value)
|
|
value = _eval_type(value, globalns, localns)
|
|
if name in defaults and defaults[name] is None:
|
|
value = Optional[value]
|
|
hints[name] = value
|
|
return hints
|
|
|
|
|
|
def no_type_check(arg):
|
|
"""Decorator to indicate that annotations are not type hints.
|
|
|
|
The argument must be a class or function; if it is a class, it
|
|
applies recursively to all methods and classes defined in that class
|
|
(but not to methods defined in its superclasses or subclasses).
|
|
|
|
This mutates the function(s) or class(es) in place.
|
|
"""
|
|
if isinstance(arg, type):
|
|
arg_attrs = arg.__dict__.copy()
|
|
for attr, val in arg.__dict__.items():
|
|
if val in arg.__bases__:
|
|
arg_attrs.pop(attr)
|
|
for obj in arg_attrs.values():
|
|
if isinstance(obj, types.FunctionType):
|
|
obj.__no_type_check__ = True
|
|
if isinstance(obj, type):
|
|
no_type_check(obj)
|
|
try:
|
|
arg.__no_type_check__ = True
|
|
except TypeError: # built-in classes
|
|
pass
|
|
return arg
|
|
|
|
|
|
def no_type_check_decorator(decorator):
|
|
"""Decorator to give another decorator the @no_type_check effect.
|
|
|
|
This wraps the decorator with something that wraps the decorated
|
|
function in @no_type_check.
|
|
"""
|
|
|
|
@functools.wraps(decorator)
|
|
def wrapped_decorator(*args, **kwds):
|
|
func = decorator(*args, **kwds)
|
|
func = no_type_check(func)
|
|
return func
|
|
|
|
return wrapped_decorator
|
|
|
|
|
|
def _overload_dummy(*args, **kwds):
|
|
"""Helper for @overload to raise when called."""
|
|
raise NotImplementedError(
|
|
"You should not call an overloaded function. "
|
|
"A series of @overload-decorated functions "
|
|
"outside a stub module should always be followed "
|
|
"by an implementation that is not @overload-ed.")
|
|
|
|
|
|
def overload(func):
|
|
"""Decorator for overloaded functions/methods.
|
|
|
|
In a stub file, place two or more stub definitions for the same
|
|
function in a row, each decorated with @overload. For example:
|
|
|
|
@overload
|
|
def utf8(value: None) -> None: ...
|
|
@overload
|
|
def utf8(value: bytes) -> bytes: ...
|
|
@overload
|
|
def utf8(value: str) -> bytes: ...
|
|
|
|
In a non-stub file (i.e. a regular .py file), do the same but
|
|
follow it with an implementation. The implementation should *not*
|
|
be decorated with @overload. For example:
|
|
|
|
@overload
|
|
def utf8(value: None) -> None: ...
|
|
@overload
|
|
def utf8(value: bytes) -> bytes: ...
|
|
@overload
|
|
def utf8(value: str) -> bytes: ...
|
|
def utf8(value):
|
|
# implementation goes here
|
|
"""
|
|
return _overload_dummy
|
|
|
|
|
|
class _ProtocolMeta(GenericMeta):
|
|
"""Internal metaclass for _Protocol.
|
|
|
|
This exists so _Protocol classes can be generic without deriving
|
|
from Generic.
|
|
"""
|
|
|
|
def __instancecheck__(self, obj):
|
|
if _Protocol not in self.__bases__:
|
|
return super().__instancecheck__(obj)
|
|
raise TypeError("Protocols cannot be used with isinstance().")
|
|
|
|
def __subclasscheck__(self, cls):
|
|
if not self._is_protocol:
|
|
# No structural checks since this isn't a protocol.
|
|
return NotImplemented
|
|
|
|
if self is _Protocol:
|
|
# Every class is a subclass of the empty protocol.
|
|
return True
|
|
|
|
# Find all attributes defined in the protocol.
|
|
attrs = self._get_protocol_attrs()
|
|
|
|
for attr in attrs:
|
|
if not any(attr in d.__dict__ for d in cls.__mro__):
|
|
return False
|
|
return True
|
|
|
|
def _get_protocol_attrs(self):
|
|
# Get all Protocol base classes.
|
|
protocol_bases = []
|
|
for c in self.__mro__:
|
|
if getattr(c, '_is_protocol', False) and c.__name__ != '_Protocol':
|
|
protocol_bases.append(c)
|
|
|
|
# Get attributes included in protocol.
|
|
attrs = set()
|
|
for base in protocol_bases:
|
|
for attr in base.__dict__.keys():
|
|
# Include attributes not defined in any non-protocol bases.
|
|
for c in self.__mro__:
|
|
if (c is not base and attr in c.__dict__ and
|
|
not getattr(c, '_is_protocol', False)):
|
|
break
|
|
else:
|
|
if (not attr.startswith('_abc_') and
|
|
attr != '__abstractmethods__' and
|
|
attr != '__annotations__' and
|
|
attr != '__weakref__' and
|
|
attr != '_is_protocol' and
|
|
attr != '__dict__' and
|
|
attr != '__args__' and
|
|
attr != '__slots__' and
|
|
attr != '_get_protocol_attrs' and
|
|
attr != '__next_in_mro__' and
|
|
attr != '__parameters__' and
|
|
attr != '__origin__' and
|
|
attr != '__orig_bases__' and
|
|
attr != '__extra__' and
|
|
attr != '__tree_hash__' and
|
|
attr != '__module__'):
|
|
attrs.add(attr)
|
|
|
|
return attrs
|
|
|
|
|
|
class _Protocol(metaclass=_ProtocolMeta):
|
|
"""Internal base class for protocol classes.
|
|
|
|
This implements a simple-minded structural issubclass check
|
|
(similar but more general than the one-offs in collections.abc
|
|
such as Hashable).
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
_is_protocol = True
|
|
|
|
|
|
# Various ABCs mimicking those in collections.abc.
|
|
# A few are simply re-exported for completeness.
|
|
|
|
Hashable = collections_abc.Hashable # Not generic.
|
|
|
|
|
|
if hasattr(collections_abc, 'Awaitable'):
|
|
class Awaitable(Generic[T_co], extra=collections_abc.Awaitable):
|
|
__slots__ = ()
|
|
|
|
__all__.append('Awaitable')
|
|
|
|
|
|
if hasattr(collections_abc, 'Coroutine'):
|
|
class Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co],
|
|
extra=collections_abc.Coroutine):
|
|
__slots__ = ()
|
|
|
|
__all__.append('Coroutine')
|
|
|
|
|
|
if hasattr(collections_abc, 'AsyncIterable'):
|
|
|
|
class AsyncIterable(Generic[T_co], extra=collections_abc.AsyncIterable):
|
|
__slots__ = ()
|
|
|
|
class AsyncIterator(AsyncIterable[T_co],
|
|
extra=collections_abc.AsyncIterator):
|
|
__slots__ = ()
|
|
|
|
__all__.append('AsyncIterable')
|
|
__all__.append('AsyncIterator')
|
|
|
|
|
|
class Iterable(Generic[T_co], extra=collections_abc.Iterable):
|
|
__slots__ = ()
|
|
|
|
|
|
class Iterator(Iterable[T_co], extra=collections_abc.Iterator):
|
|
__slots__ = ()
|
|
|
|
|
|
class SupportsInt(_Protocol):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __int__(self) -> int:
|
|
pass
|
|
|
|
|
|
class SupportsFloat(_Protocol):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __float__(self) -> float:
|
|
pass
|
|
|
|
|
|
class SupportsComplex(_Protocol):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __complex__(self) -> complex:
|
|
pass
|
|
|
|
|
|
class SupportsBytes(_Protocol):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __bytes__(self) -> bytes:
|
|
pass
|
|
|
|
|
|
class SupportsAbs(_Protocol[T_co]):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __abs__(self) -> T_co:
|
|
pass
|
|
|
|
|
|
class SupportsRound(_Protocol[T_co]):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __round__(self, ndigits: int = 0) -> T_co:
|
|
pass
|
|
|
|
|
|
if hasattr(collections_abc, 'Reversible'):
|
|
class Reversible(Iterable[T_co], extra=collections_abc.Reversible):
|
|
__slots__ = ()
|
|
else:
|
|
class Reversible(_Protocol[T_co]):
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def __reversed__(self) -> 'Iterator[T_co]':
|
|
pass
|
|
|
|
|
|
Sized = collections_abc.Sized # Not generic.
|
|
|
|
|
|
class Container(Generic[T_co], extra=collections_abc.Container):
|
|
__slots__ = ()
|
|
|
|
|
|
if hasattr(collections_abc, 'Collection'):
|
|
class Collection(Sized, Iterable[T_co], Container[T_co],
|
|
extra=collections_abc.Collection):
|
|
__slots__ = ()
|
|
|
|
__all__.append('Collection')
|
|
|
|
|
|
# Callable was defined earlier.
|
|
|
|
if hasattr(collections_abc, 'Collection'):
|
|
class AbstractSet(Collection[T_co],
|
|
extra=collections_abc.Set):
|
|
__slots__ = ()
|
|
else:
|
|
class AbstractSet(Sized, Iterable[T_co], Container[T_co],
|
|
extra=collections_abc.Set):
|
|
__slots__ = ()
|
|
|
|
|
|
class MutableSet(AbstractSet[T], extra=collections_abc.MutableSet):
|
|
__slots__ = ()
|
|
|
|
|
|
# NOTE: It is only covariant in the value type.
|
|
if hasattr(collections_abc, 'Collection'):
|
|
class Mapping(Collection[KT], Generic[KT, VT_co],
|
|
extra=collections_abc.Mapping):
|
|
__slots__ = ()
|
|
else:
|
|
class Mapping(Sized, Iterable[KT], Container[KT], Generic[KT, VT_co],
|
|
extra=collections_abc.Mapping):
|
|
__slots__ = ()
|
|
|
|
|
|
class MutableMapping(Mapping[KT, VT], extra=collections_abc.MutableMapping):
|
|
__slots__ = ()
|
|
|
|
if hasattr(collections_abc, 'Reversible'):
|
|
if hasattr(collections_abc, 'Collection'):
|
|
class Sequence(Reversible[T_co], Collection[T_co],
|
|
extra=collections_abc.Sequence):
|
|
__slots__ = ()
|
|
else:
|
|
class Sequence(Sized, Reversible[T_co], Container[T_co],
|
|
extra=collections_abc.Sequence):
|
|
__slots__ = ()
|
|
else:
|
|
class Sequence(Sized, Iterable[T_co], Container[T_co],
|
|
extra=collections_abc.Sequence):
|
|
__slots__ = ()
|
|
|
|
|
|
class MutableSequence(Sequence[T], extra=collections_abc.MutableSequence):
|
|
__slots__ = ()
|
|
|
|
|
|
class ByteString(Sequence[int], extra=collections_abc.ByteString):
|
|
__slots__ = ()
|
|
|
|
|
|
class List(list, MutableSequence[T], extra=list):
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, List):
|
|
raise TypeError("Type List cannot be instantiated; "
|
|
"use list() instead")
|
|
return _generic_new(list, cls, *args, **kwds)
|
|
|
|
|
|
class Set(set, MutableSet[T], extra=set):
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, Set):
|
|
raise TypeError("Type Set cannot be instantiated; "
|
|
"use set() instead")
|
|
return _generic_new(set, cls, *args, **kwds)
|
|
|
|
|
|
class FrozenSet(frozenset, AbstractSet[T_co], extra=frozenset):
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, FrozenSet):
|
|
raise TypeError("Type FrozenSet cannot be instantiated; "
|
|
"use frozenset() instead")
|
|
return _generic_new(frozenset, cls, *args, **kwds)
|
|
|
|
|
|
class MappingView(Sized, Iterable[T_co], extra=collections_abc.MappingView):
|
|
__slots__ = ()
|
|
|
|
|
|
class KeysView(MappingView[KT], AbstractSet[KT],
|
|
extra=collections_abc.KeysView):
|
|
__slots__ = ()
|
|
|
|
|
|
class ItemsView(MappingView[Tuple[KT, VT_co]],
|
|
AbstractSet[Tuple[KT, VT_co]],
|
|
Generic[KT, VT_co],
|
|
extra=collections_abc.ItemsView):
|
|
__slots__ = ()
|
|
|
|
|
|
class ValuesView(MappingView[VT_co], extra=collections_abc.ValuesView):
|
|
__slots__ = ()
|
|
|
|
|
|
if hasattr(contextlib, 'AbstractContextManager'):
|
|
class ContextManager(Generic[T_co], extra=contextlib.AbstractContextManager):
|
|
__slots__ = ()
|
|
__all__.append('ContextManager')
|
|
|
|
|
|
class Dict(dict, MutableMapping[KT, VT], extra=dict):
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, Dict):
|
|
raise TypeError("Type Dict cannot be instantiated; "
|
|
"use dict() instead")
|
|
return _generic_new(dict, cls, *args, **kwds)
|
|
|
|
class DefaultDict(collections.defaultdict, MutableMapping[KT, VT],
|
|
extra=collections.defaultdict):
|
|
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, DefaultDict):
|
|
raise TypeError("Type DefaultDict cannot be instantiated; "
|
|
"use collections.defaultdict() instead")
|
|
return _generic_new(collections.defaultdict, cls, *args, **kwds)
|
|
|
|
# Determine what base class to use for Generator.
|
|
if hasattr(collections_abc, 'Generator'):
|
|
# Sufficiently recent versions of 3.5 have a Generator ABC.
|
|
_G_base = collections_abc.Generator
|
|
else:
|
|
# Fall back on the exact type.
|
|
_G_base = types.GeneratorType
|
|
|
|
|
|
class Generator(Iterator[T_co], Generic[T_co, T_contra, V_co],
|
|
extra=_G_base):
|
|
__slots__ = ()
|
|
|
|
def __new__(cls, *args, **kwds):
|
|
if _geqv(cls, Generator):
|
|
raise TypeError("Type Generator cannot be instantiated; "
|
|
"create a subclass instead")
|
|
return _generic_new(_G_base, cls, *args, **kwds)
|
|
|
|
|
|
# Internal type variable used for Type[].
|
|
CT_co = TypeVar('CT_co', covariant=True, bound=type)
|
|
|
|
|
|
# This is not a real generic class. Don't use outside annotations.
|
|
class Type(Generic[CT_co], extra=type):
|
|
"""A special construct usable to annotate class objects.
|
|
|
|
For example, suppose we have the following classes::
|
|
|
|
class User: ... # Abstract base for User classes
|
|
class BasicUser(User): ...
|
|
class ProUser(User): ...
|
|
class TeamUser(User): ...
|
|
|
|
And a function that takes a class argument that's a subclass of
|
|
User and returns an instance of the corresponding class::
|
|
|
|
U = TypeVar('U', bound=User)
|
|
def new_user(user_class: Type[U]) -> U:
|
|
user = user_class()
|
|
# (Here we could write the user object to a database)
|
|
return user
|
|
|
|
joe = new_user(BasicUser)
|
|
|
|
At this point the type checker knows that joe has type BasicUser.
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
|
|
def _make_nmtuple(name, types):
|
|
msg = "NamedTuple('Name', [(f0, t0), (f1, t1), ...]); each t must be a type"
|
|
types = [(n, _type_check(t, msg)) for n, t in types]
|
|
nm_tpl = collections.namedtuple(name, [n for n, t in types])
|
|
nm_tpl._field_types = dict(types)
|
|
try:
|
|
nm_tpl.__module__ = sys._getframe(2).f_globals.get('__name__', '__main__')
|
|
except (AttributeError, ValueError):
|
|
pass
|
|
return nm_tpl
|
|
|
|
|
|
_PY36 = sys.version_info[:2] >= (3, 6)
|
|
|
|
|
|
class NamedTupleMeta(type):
|
|
|
|
def __new__(cls, typename, bases, ns):
|
|
if ns.get('_root', False):
|
|
return super().__new__(cls, typename, bases, ns)
|
|
if not _PY36:
|
|
raise TypeError("Class syntax for NamedTuple is only supported"
|
|
" in Python 3.6+")
|
|
types = ns.get('__annotations__', {})
|
|
return _make_nmtuple(typename, types.items())
|
|
|
|
class NamedTuple(metaclass=NamedTupleMeta):
|
|
"""Typed version of namedtuple.
|
|
|
|
Usage in Python versions >= 3.6::
|
|
|
|
class Employee(NamedTuple):
|
|
name: str
|
|
id: int
|
|
|
|
This is equivalent to::
|
|
|
|
Employee = collections.namedtuple('Employee', ['name', 'id'])
|
|
|
|
The resulting class has one extra attribute: _field_types,
|
|
giving a dict mapping field names to types. (The field names
|
|
are in the _fields attribute, which is part of the namedtuple
|
|
API.) Alternative equivalent keyword syntax is also accepted::
|
|
|
|
Employee = NamedTuple('Employee', name=str, id=int)
|
|
|
|
In Python versions <= 3.5 use::
|
|
|
|
Employee = NamedTuple('Employee', [('name', str), ('id', int)])
|
|
"""
|
|
_root = True
|
|
|
|
def __new__(self, typename, fields=None, **kwargs):
|
|
if kwargs and not _PY36:
|
|
raise TypeError("Keyword syntax for NamedTuple is only supported"
|
|
" in Python 3.6+")
|
|
if fields is None:
|
|
fields = kwargs.items()
|
|
elif kwargs:
|
|
raise TypeError("Either list of fields or keywords"
|
|
" can be provided to NamedTuple, not both")
|
|
return _make_nmtuple(typename, fields)
|
|
|
|
|
|
def NewType(name, tp):
|
|
"""NewType creates simple unique types with almost zero
|
|
runtime overhead. NewType(name, tp) is considered a subtype of tp
|
|
by static type checkers. At runtime, NewType(name, tp) returns
|
|
a dummy function that simply returns its argument. Usage::
|
|
|
|
UserId = NewType('UserId', int)
|
|
|
|
def name_by_id(user_id: UserId) -> str:
|
|
...
|
|
|
|
UserId('user') # Fails type check
|
|
|
|
name_by_id(42) # Fails type check
|
|
name_by_id(UserId(42)) # OK
|
|
|
|
num = UserId(5) + 1 # type: int
|
|
"""
|
|
|
|
def new_type(x):
|
|
return x
|
|
|
|
new_type.__name__ = name
|
|
new_type.__supertype__ = tp
|
|
return new_type
|
|
|
|
|
|
# Python-version-specific alias (Python 2: unicode; Python 3: str)
|
|
Text = str
|
|
|
|
|
|
# Constant that's True when type checking, but False here.
|
|
TYPE_CHECKING = False
|
|
|
|
|
|
class IO(Generic[AnyStr]):
|
|
"""Generic base class for TextIO and BinaryIO.
|
|
|
|
This is an abstract, generic version of the return of open().
|
|
|
|
NOTE: This does not distinguish between the different possible
|
|
classes (text vs. binary, read vs. write vs. read/write,
|
|
append-only, unbuffered). The TextIO and BinaryIO subclasses
|
|
below capture the distinctions between text vs. binary, which is
|
|
pervasive in the interface; however we currently do not offer a
|
|
way to track the other distinctions in the type system.
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
@abstractproperty
|
|
def mode(self) -> str:
|
|
pass
|
|
|
|
@abstractproperty
|
|
def name(self) -> str:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def close(self) -> None:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def closed(self) -> bool:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def fileno(self) -> int:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def flush(self) -> None:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def isatty(self) -> bool:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def read(self, n: int = -1) -> AnyStr:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def readable(self) -> bool:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def readline(self, limit: int = -1) -> AnyStr:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def readlines(self, hint: int = -1) -> List[AnyStr]:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def seek(self, offset: int, whence: int = 0) -> int:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def seekable(self) -> bool:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def tell(self) -> int:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def truncate(self, size: int = None) -> int:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def writable(self) -> bool:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def write(self, s: AnyStr) -> int:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def writelines(self, lines: List[AnyStr]) -> None:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def __enter__(self) -> 'IO[AnyStr]':
|
|
pass
|
|
|
|
@abstractmethod
|
|
def __exit__(self, type, value, traceback) -> None:
|
|
pass
|
|
|
|
|
|
class BinaryIO(IO[bytes]):
|
|
"""Typed version of the return of open() in binary mode."""
|
|
|
|
__slots__ = ()
|
|
|
|
@abstractmethod
|
|
def write(self, s: Union[bytes, bytearray]) -> int:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def __enter__(self) -> 'BinaryIO':
|
|
pass
|
|
|
|
|
|
class TextIO(IO[str]):
|
|
"""Typed version of the return of open() in text mode."""
|
|
|
|
__slots__ = ()
|
|
|
|
@abstractproperty
|
|
def buffer(self) -> BinaryIO:
|
|
pass
|
|
|
|
@abstractproperty
|
|
def encoding(self) -> str:
|
|
pass
|
|
|
|
@abstractproperty
|
|
def errors(self) -> Optional[str]:
|
|
pass
|
|
|
|
@abstractproperty
|
|
def line_buffering(self) -> bool:
|
|
pass
|
|
|
|
@abstractproperty
|
|
def newlines(self) -> Any:
|
|
pass
|
|
|
|
@abstractmethod
|
|
def __enter__(self) -> 'TextIO':
|
|
pass
|
|
|
|
|
|
class io:
|
|
"""Wrapper namespace for IO generic classes."""
|
|
|
|
__all__ = ['IO', 'TextIO', 'BinaryIO']
|
|
IO = IO
|
|
TextIO = TextIO
|
|
BinaryIO = BinaryIO
|
|
|
|
io.__name__ = __name__ + '.io'
|
|
sys.modules[io.__name__] = io
|
|
|
|
|
|
Pattern = _TypeAlias('Pattern', AnyStr, type(stdlib_re.compile('')),
|
|
lambda p: p.pattern)
|
|
Match = _TypeAlias('Match', AnyStr, type(stdlib_re.match('', '')),
|
|
lambda m: m.re.pattern)
|
|
|
|
|
|
class re:
|
|
"""Wrapper namespace for re type aliases."""
|
|
|
|
__all__ = ['Pattern', 'Match']
|
|
Pattern = Pattern
|
|
Match = Match
|
|
|
|
re.__name__ = __name__ + '.re'
|
|
sys.modules[re.__name__] = re
|