diff -r 2df7c958974e Doc/library/typing.rst --- a/Doc/library/typing.rst Sat May 23 18:08:55 2015 -0700 +++ b/Doc/library/typing.rst Sun May 24 22:22:56 2015 -0500 @@ -13,3 +13,479 @@ :class:`Tuple`, :class:`Callable`, :class:`TypeVar`, and :class:`Generic`. For full specification please see :pep:`484`. For a simplified introduction to type hints see :pep:`483`. + + +The function below takes and returns a string and is annotated as follows:: + + def greeting(name: str) -> str: + return 'Hello ' + name + +In the function `greeting`, the argument `name` is expected to by of type `str` +and the return type `str`. Subtypes are accepted as arguments. + +Type aliases +------------ + +A type alias is defined by assigning the type to the alias:: + + Url = str + +Callable +-------- + +Frameworks expecting callback functions of specific signatures might be +type hinted using `Callable[[Arg1Type, Arg2Type], ReturnType]`. + +For example:: + + from typing import Callable + + def feeder(get_next_item: Callable[[], str]) -> None: + # Body + + def async_query(on_success: Callable[[int], None], + on_error: Callable[[int, Exception], None]) -> None: + # Body + +Generics +-------- + +Since type information about objects kept in containers cannot be statically +inferred in a generic way, abstract base classes have been extended to support +subscription to denote expected types for container elements. + +.. code-block:: python + + from typing import Mapping, Set + + def notify_by_email(employees: Set[Employee], + overrides: Mapping[str, str]) -> None: ... + +Generics can be parametrized by using a new factory available in typing +called TypeVar. + +.. code-block:: python + + from typing import Sequence, TypeVar + + T = TypeVar('T') # Declare type variable + + def first(l: Sequence[T]) -> T: # Generic function + return l[0] + + +User-defined generic types +-------------------------- + +A user-defined class can be defined as a generic. + +.. code-block:: python + + from typing import TypeVar, Generic + + T = TypeVar('T') + + class LoggedVar(Generic[T]): + def __init__(self, value: T, name: str, logger: Logger) -> None: + self.name = name + self.logger = logger + self.value = value + + def set(self, new: T) -> None: + self.log('Set ' + repr(self.value)) + self.value = new + + def get(self) -> T: + self.log('Get ' + repr(self.value)) + return self.value + + def log(self, message: str) -> None: + self.logger.info('{}: {}'.format(self.name message)) + +`Generic[T]` as a base class defines that the class `LoggedVar` takes a single +type parameter `T` . This also makes `T` valid as a type within the class body. + +The `Generic` base class uses a metaclass that defines `__getitem__` so that +`LoggedVar[t]` is valid as a type:: + + from typing import Iterable + + def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None: + for var in vars: + var.set(0) + +A generic type can have any number of type variables, and type variables may +be constrained:: + + from typing import TypeVar, Generic + ... + + T = TypeVar('T') + S = TypeVar('S') + + class Pair(Generic[T, S]): + ... + +Each type variable argument to `Generic` must be distinct. +This is thus invalid:: + + from typing import TypeVar, Generic + ... + + T = TypeVar('T') + + class Pair(Generic[T, T]): # INVALID + ... + +You can use multiple inheritance with `Generic`:: + + from typing import TypeVar, Generic, Sized + + T = TypeVar('T') + + class LinkedList(Sized, Generic[T]): + ... + +Subclassing a generic class without specifying type parameters assumes `Any` +for each position. In the following example, `MyIterable` is not generic but +implicitly inherits from `Iterable[Any]`:: + + from typing import Iterable + + class MyIterable(Iterable): # Same as Iterable[Any] + +Generic metaclasses are not supported. + +The `Any` type +-------------- + +A special kind of type is `Any`. Every type is a subtype of `Any`. +This is also true for the builtin type object. However, to the static type +checker these are completely different. + +When the type of a value is object, the type checker will reject almost all +operations on it, and assigning it to a variable (or using it as a return value) +of a more specialized type is a type error. On the other hand, when a value has +type `Any`, the type checker will allow all operations on it, and a value of +type `Any` can be assigned to a variable (or used as a return value) of a more +constrained type. + +Version and platform checking +----------------------------- + +Type checkers are expected to understand simple version and platform checks, +e.g.:: + + import sys + + if sys.version_info[0] >= 3: + # Python 3 specific definitions + else: + # Python 2 specific definitions + + if sys.platform == 'win32': + # Windows specific definitions + else: + # Posix specific definitions + +Default argument values +----------------------- + +Use a literal ellipsis `...` to declare an argument as having a default value:: + + def foo(x: AnyStr, y: AnyStr = ...) -> AnyStr: ... + + +Classes, functions, and decorators +---------------------------------- + +The module defines the following classes, functions and decorators: + +.. class:: Any(Final, metaclass=AnyMeta, _root=True) + + Special type indicating an unconstrained type. + + * Any object is an instance of Any. + * Any class is a subclass of Any. + * As a special case, Any and object are subclasses of each other. + +.. class:: TypeVar(TypingMeta, metaclass=TypingMeta, _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: + + .. code-block:: python + + def repeat(x: T, n: int) -> Sequence[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) 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. + + Type variables may be marked covariant or contravariant by passing + covariant=True or contravariant=True. See PEP 484 for more + details. By default type variables are invariant. + + Type variables can be introspected. e.g.:: + + T.__name__ == 'T' + T.__constraints__ == () + T.__covariant__ == False + T.__contravariant__ = False + A.__constraints__ == (str, bytes) + +.. class:: Union(Final, metaclass=UnionMeta, _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 + + * Corollary: if Any is present it is the sole survivor, e.g.:: + + Union[int, Any] == Any + + * Similar for object:: + + Union[int, object] == object + + * To cut a tie: `Union[object, Any] == Union[Any, object] == Any`. + + * You cannot subclass or instantiate a union. + + * You cannot write `Union[X][Y]` + + * You can use `Optional[X]` as a shorthand for `Union[X, None]`. + +.. class:: Optional(Final, metaclass=OptionalMeta, _root=True) + + Optional type. + + `Optional[X]` is equivalent to `Union[X, type(None)]`. + +.. class:: Tuple(Final, metaclass=TupleMeta, _root=True) + + 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 `Sequence[T]`. + +.. class:: Callable(Final, metaclass=CallableMeta, _root=True) + + 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; 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:: 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. + 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, key: KT, default: VT) -> VT: + try: + return mapping[key] + except KeyError: + return default + + For clarity the type variables may be redefined, e.g.:: + + X = TypeVar('X') + Y = TypeVar('Y') + def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y: + # Same body as above. + +.. class:: Iterable(Generic[T_co], extra=collections_abc.Iterable) + +.. class:: Iterator(Iterable[T_co], extra=collections_abc.Iterator) + +.. class:: SupportsInt(_Protocol) + +.. class:: SupportsFloat(_Protocol) + +.. class:: SupportsAbs(_Protocol[T]) + +.. class:: SupportsRound(_Protocol[T]) + +.. class:: Reversible(_Protocol[T]) + +.. class:: Container(Generic[T_co], extra=collections_abc.Container) + +.. class:: AbstractSet(Sized, Iterable[T_co], Container[T_co], extra=collections_abc.Set) + +.. class:: MutableSet(AbstractSet[T], extra=collections_abc.MutableSet) + +.. class:: Mapping(Sized, Iterable[KT_co], Container[KT_co], Generic[KT_co, VT_co], extra=collections_abc.Mapping) + +.. class:: MutableMapping(Mapping[KT, VT], extra=collections_abc.MutableMapping) + +.. class:: Sequence(Sized, Iterable[T_co], Container[T_co], extra=collections_abc.Sequence) + +.. class:: MutableSequence(Sequence[T], extra=collections_abc.MutableSequence) + +.. class:: ByteString(Sequence[int], extra=collections_abc.ByteString) + +.. class:: List(list, MutableSequence[T], metaclass=_ListMeta) + +.. class:: Set(set, MutableSet[T], metaclass=_SetMeta) + +.. class:: MappingView(Sized, Iterable[T_co], extra=collections_abc.MappingView) + +.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co], extra=collections_abc.KeysView) + +.. class:: ItemsView(MappingView, Generic[KT_co, VT_co], extra=collections_abc.ItemsView) + +.. class:: ValuesView(MappingView[VT_co], extra=collections_abc.ValuesView) + +.. class:: Dict(dict, MutableMapping[KT, VT], metaclass=_DictMeta) + +.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co], extra=_G_base) + +.. class:: io + + Wrapper namespace for IO generic classes. + +.. class:: re + + Wrapper namespace for re type classes. + +.. function:: NamedTuple(typename, fields) + + Typed version of namedtuple. + + Usage:: + + Employee = typing.NamedTuple('Employee', [('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.) + +.. function:: 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). + +.. function:: get_type_hints(obj, globalns=None, localns=None) + + Return type hints for a function or method 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. + + .. warning:: + + 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. + +.. function:: overload(func) + + .. note:: + + Overloading is only supported in library stubs + + +.. decorator:: 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 defined in that class (but not + to methods defined in its superclasses or subclasses). + + This mutates the function(s) in place. + +.. decorator:: 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.