diff -r 1d44d4addc17 Doc/library/typing.rst --- a/Doc/library/typing.rst Sun Aug 02 10:25:06 2015 -0400 +++ b/Doc/library/typing.rst Sun Aug 02 22:50:25 2015 +0200 @@ -13,3 +13,418 @@ :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:: + + Vector = List[float] + +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 + +It is possible to declare the return type of a callable without specifying +the call signature by substituting a literal ellipsis +for the list of arguments in the type hint: `Callable[..., ReturnType]`. +`None` as a type hint is a special case and is replaced by `type(None)`. + +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, Sequence + + def notify_by_email(employees: Sequence[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 class. + +.. code-block:: python + + from typing import TypeVar, Generic + from logging import Logger + + 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', int, str) + + class StrangePair(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. + +Default argument values +----------------------- + +Use a literal ellipsis `...` to declare an argument as having a default value:: + + from typing import AnyStr + + def foo(x: AnyStr, y: AnyStr = ...) -> AnyStr: ... + + +Classes, functions, and decorators +---------------------------------- + +The module defines the following classes, functions and decorators: + +.. class:: Any + + 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 + + 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`. In general, + `isinstance` and `issublass` should not be used with types. + + 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. + +.. class:: Union + + 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. + + * 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] + + * If `Any` is present it is the sole survivor, e.g.:: + + Union[int, Any] == 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 + + Optional type. + + `Optional[X]` is equivalent to `Union[X, type(None)]`. + +.. class:: Tuple + + Tuple type; `Tuple[X, Y]` is the is the type of a tuple of two items + with the first item of type X and the second of type 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 literal ellipsis, e.g. `Tuple[int, ...]`. + +.. class:: Callable + + 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. + `Callable[..., ReturnType]` could be used to type hint a callable + taking any number of arguments and returning `ReturnType`. + A plain `Callable` is equivalent to `Callable[..., Any]`. + +.. class:: Generic + + 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:: + + X = TypeVar('X') + Y = TypeVar('Y') + def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y: + try: + return mapping[key] + except KeyError: + return default + +.. class:: Iterable(Generic[T_co]) + +.. class:: Iterator(Iterable[T_co]) + +.. class:: SupportsInt + +.. class:: SupportsFloat + +.. class:: SupportsAbs + +.. class:: SupportsRound + +.. class:: Reversible + +.. class:: Container(Generic[T_co]) + +.. class:: AbstractSet(Sized, Iterable[T_co], Container[T_co]) + +.. class:: MutableSet(AbstractSet[T]) + +.. class:: Mapping(Sized, Iterable[KT_co], Container[KT_co], Generic[KT_co, VT_co]) + +.. class:: MutableMapping(Mapping[KT, VT]) + +.. class:: Sequence(Sized, Iterable[T_co], Container[T_co]) + +.. class:: MutableSequence(Sequence[T]) + +.. class:: ByteString(Sequence[int]) + +.. class:: List(list, MutableSequence[T]) + +.. class:: Set(set, MutableSet[T]) + +.. class:: MappingView(Sized, Iterable[T_co]) + +.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co]) + +.. class:: ItemsView(MappingView, Generic[KT_co, VT_co]) + +.. class:: ValuesView(MappingView[VT_co]) + +.. class:: Dict(dict, MutableMapping[KT, VT]) + +.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co]) + +.. 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) + + 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. + +.. 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.