class TypingMeta(type):
- """Metaclass for every type defined below.
+ """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 (including internal subclasses created by
- e.g. Union[X, Y]) must pass _root=True.
+ derived from TypingMeta must pass _root=True.
- This also defines a dummy constructor (all the work is done in
- __new__) and a nicer repr().
+ 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 _eval_type(self, globalns, localns):
"""Override this in subclasses to interpret forward references.
- For example, Union['C'] is internally stored as
- Union[_ForwardRef('C')], which should evaluate to _Union[C],
+ 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).
"""
class _TypingBase(metaclass=TypingMeta, _root=True):
- """Indicator of special typing constructs."""
+ """Internal indicator of special typing constructs."""
__slots__ = ()
class _FinalTypingBase(_TypingBase, _root=True):
- """Mix-in class to prevent instantiation.
+ """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, Tuple, etc.
+ It is used to create pseudo-singleton instances Any, Union, Optional, etc.
"""
__slots__ = ()
class _ForwardRef(_TypingBase, _root=True):
- """Wrapper to hold a forward reference."""
+ """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('ForwardRef must be a string -- got %r' % (arg,))
+ raise TypeError('Forward reference must be a string -- got %r' % (arg,))
try:
code = compile(arg, '<string>', 'eval')
except SyntaxError:
- raise SyntaxError('ForwardRef must be an expression -- got %r' %
+ raise SyntaxError('Forward reference must be an expression -- got %r' %
(arg,))
self.__forward_arg__ = arg
self.__forward_code__ = code
def _type_check(arg, msg):
- """Check that the argument is a type, and return it.
+ """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.
def _type_repr(obj):
- """Return the repr() of an object, special-casing types.
+ """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
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) -> Sequence[T]:
+ def repeat(x: T, n: int) -> List[T]:
'''Return a list containing n references to x.'''
return [x]*n
that if the arguments are instances of some subclass of str,
the return type is still plain str.
- At runtime, isinstance(x, T) will raise TypeError. However,
- issubclass(C, T) is true for any class C, and issubclass(str, A)
- and issubclass(bytes, A) are true, and issubclass(int, A) is
- false. (TODO: Why is this needed? This may change. See #136.)
+ 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.
def _replace_arg(arg, tvars, args):
- """ A helper fuunction: replace arg if it is a type variable
+ """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.
"""
def _subs_tree(cls, tvars=None, args=None):
- """ Calculate substitution tree for generic cls after
- replacing its type parameters with substitutions in tvars -> args (if any).
- Repeat the same cyclicaly following __origin__'s.
+ """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:
def _remove_dups_flatten(parameters):
- """ A helper for Union creation and substitution: flatten Union's
+ """An internal helper for Union creation and substitution: flatten Union's
among parameters, then remove duplicates and strict subclasses.
"""
def _check_generic(cls, parameters):
- # Check correct count for parameters of a generic cls.
+ # 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)
def _tp_cache(func):
- """ Caching for __getitem__ of generic types with a fallback to
+ """Internal wrapper caching __getitem__ of generic types with a fallback to
original function for non-hashable arguments.
"""
def _gorg(a):
- """Return the farthest origin of a generic class."""
+ """Return the farthest origin of a generic class (internal helper)."""
assert isinstance(a, GenericMeta)
while a.__origin__ is not None:
a = a.__origin__
def _geqv(a, b):
- """Return whether two generic classes are equivalent.
+ """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.
+ parameterized forms (X[T], X[int], etc.) as equivalent.
However, X is not equivalent to a subclass of X.
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)
class Generic(metaclass=GenericMeta):
"""Abstract base class for generic types.
- A generic type is typically declared by inheriting from an
- instantiation of this class with one or more type variables.
+ 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]):
class _TypingEmpty:
- """Placeholder for () or []. Used by TupleMeta and CallableMeta
- to allow empy list/tuple in specific places, without allowing them
+ """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:
- """Ditto for ..."""
+ """Internal placeholder for ... (ellipsis)."""
class TupleMeta(GenericMeta):
- """Metaclass for Tuple"""
+ """Metaclass for Tuple (internal)."""
@_tp_cache
def __getitem__(self, parameters):
class CallableMeta(GenericMeta):
- """ Metaclass for Callable."""
+ """Metaclass for Callable (internal)."""
def __repr__(self):
if self.__origin__ is None:
'[[%s], %s]' % (', '.join(arg_list[:-1]), arg_list[-1]))
def __getitem__(self, parameters):
- """ A thin wrapper around __getitem_inner__ to provide the latter
+ """A thin wrapper around __getitem_inner__ to provide the latter
with hashable arguments to improve speed.
"""
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; the return type must be a single type.
+ 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.
class _Protocol(metaclass=_ProtocolMeta):
"""Internal base class for protocol classes.
- This implements a simple-minded structural isinstance check
+ This implements a simple-minded structural issubclass check
(similar but more general than the one-offs in collections.abc
such as Hashable).
"""
projects / python / commitdiff