iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated version of PEP 484.

This commit is contained in:
Guido van Rossum 2015-05-20 08:26:09 -07:00
parent c087f9657f
commit cc952ce033
1 changed files with 424 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

557
pep-0484.txt
View File

@ -9,17 +9,29 @@ Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 29-Sep-2014
Post-History: 16-Jan-2015,20-Mar-2015,17-Apr-2015
Post-History: 16-Jan-2015,20-Mar-2015,17-Apr-2015,20-May-2015
Resolution:
Abstract
========
This PEP introduces a standard syntax for type hints using annotations
(PEP 3107) on function definitions. For example, here is a simple
function whose argument and return type are declared in the
annotations::
PEP 3107 introduced syntax for function annotations, but the semantics
were deliberately left undefined. There has now been enough 3rd party
usage for static type analysis that the community would benefit from
a standard vocabulary and baseline tools within the standard library.
This PEP introduces a provisional module to provide these standard
definitions and tools, along with some conventions for situations
where annotations are not available.
Note that this PEP still explicitly does NOT prevent other uses of
annotations, nor does it require (or forbid) any particular processing
of annotations, even when they conform to this specification. It
simply enables better coordination, as PEP 333 did for web frameworks.
For example, here is a simple function whose argument and return type
are declared in the annotations::
def greeting(name: str) -> str:
return 'Hello ' + name
@ -29,13 +41,17 @@ While these annotations are available at runtime through the usual
Instead, the proposal assumes the existence of a separate off-line
type checker which users can run over their source code voluntarily.
Essentially, such a type checker acts as a very powerful linter.
(While it would of course be possible for individual users to employ
a similar checker at run time for Design By Contract enforcement or
JIT optimization, those tools are not yet as mature.)
The proposal is strongly inspired by mypy [mypy]_. For example, the
type "sequence of integers" can be written as ``Sequence[int]``. The
square brackets mean that no new syntax needs to be added to the
language. The example here uses a custom class ``Sequence``, imported
from a pure-Python module ``typing``. The ``Sequence[int]``
notation works by implementing ``__getitem__()`` in the metaclass.
language. The example here uses a custom type ``Sequence``, imported
from a pure-Python module ``typing``. The ``Sequence[int]`` notation
works at runtime by implementing ``__getitem__()`` in the metaclass
(but its significance is primarily to an offline type checker).
The type system supports unions, generic types, and a special type
named ``Any`` which is consistent with (i.e. assignable to and from) all
@ -49,15 +65,16 @@ compared and contrasted are described in PEP 482.
Rationale and Goals
===================
PEP 3107 added support for arbitrary annotations on parts of a function
definition. Although no meaning was assigned to annotations then, there
has always been an implicit goal to use them for type hinting, which is
listed as the first possible use case in said PEP.
PEP 3107 added support for arbitrary annotations on parts of a
function definition. Although no meaning was assigned to annotations
then, there has always been an implicit goal to use them for type
hinting [gvr-artima]_, which is listed as the first possible use case
in said PEP.
This PEP aims to provide a standard syntax for type annotations, opening
up Python code to easier static analysis and refactoring, potential
runtime type checking, and performance optimizations utilizing type
information.
This PEP aims to provide a standard syntax for type annotations,
opening up Python code to easier static analysis and refactoring,
potential runtime type checking, and (perhaps, in some contexts)
code generation utilizing type information.
Of these goals, static analysis is the most important. This includes
support for off-line type checkers such as mypy, as well as providing
@ -74,43 +91,43 @@ implement specific runtime type checking functionality, for example
using decorators or metaclasses. Using type hints for performance
optimizations is left as an exercise for the reader.
It should also be emphasized that Python will remain a dynamically
It should also be emphasized that **Python will remain a dynamically
typed language, and the authors have no desire to ever make type hints
mandatory, even by convention.
mandatory, even by convention.**
What is checked?
================
The meaning of annotations
==========================
Any function (or method -- for brevity we won't be repeating this)
with at least one argument or return annotation is checked, unless
type checking is disabled by the ``@no_type_check`` decorator or a
``# type: ignore`` comment (see below).
Any function without annotations should be treated as having the most
general type possible, or ignored, by any type checker. Functions
with the ``@no_type_check`` decorator or with a ``# type: ignore``
comment should be treated as having no annotations.
A checked function should have annotations for all its arguments and
its return type, with the exception that the ``self`` argument of a
method should not be annotated; it is assumed to have the type of the
containing class. Notably, the return type of ``__init__`` should be
annotated with ``-> None``.
It is recommended but not required that checked functions have
annotations for all arguments and the return type. For a checked
function, the default annotation for arguments and for the return type
is ``Any``. An exception is that the first argument of instance and
class methods does not need to be annotated; it is assumed to have the
type of the containing class for instance methods, and ``type`` for
class methods.
The body of a checked function is checked for consistency with the
given annotations. The annotations are also used to check correctness
of calls appearing in other checked functions.
(Note that the return type of ``__init__`` ought to be annotated with
``-> None``. The reason for this is subtle. If ``__init__`` assumed
a return annotation of ``-> None``, would that mean that an
argument-less, un-annotated ``__init__`` method should still be
type-checked? Rather than leaving this ambiguous or introducing an
exception to the exception, we simply say that ``__init__`` ought to
have a return annotation; the default behavior is thus the same as for
other methods.)
Functions without any annotations (or whose checking is disabled) are
assumed to have type ``Any`` when they are referenced in checked
functions, and this should completely silence complaints from the
checker regarding those references (although a checker may still
request that a type be specified using a cast or a ``# type:`` comment
if a more specific type than ``Any`` is needed for analysis of
subsequent code).
A type checker is expected to check the body of a checked function for
consistency with the given annotations. The annotations may also used
to check correctness of calls appearing in other checked functions.
A type checker should understand decorators; this may require
annotations on decorator definitions. In particular, a type checker
should understand the built-in decorators ``@property``,
``@staticmethod`` and ``@classmethod``. The first argument of a class
method should not be annotated; it is assumed to be a subclass of the
defining class.
Type checkers are expected to attempt to infer as much information as
necessary. The minimum requirement is to handle the builtin
decorators ``@property``, ``@staticmethod`` and ``@classmethod``.
Type Definition Syntax
@ -137,17 +154,20 @@ Type hints may be built-in classes (including those defined in
standard library or third-party extension modules), abstract base
classes, types available in the ``types`` module, and user-defined
classes (including those defined in the standard library or
third-party modules). Annotations for built-in classes (and other
classes at the discretion of the developer) may be placed in stub
files (see below).
third-party modules).
While annotations are normally the best format for type hints,
there are times when it is more appropriate to represent them
by a special comment, or in a separately distributed interface
file. (See below for examples.)
Annotations must be valid expressions that evaluate without raising
exceptions at the time the function is defined (but see below for
forward references).
The needs of static analysis require that annotations must be simple
enough to be interpreted by static analysis tools. In particular,
dynamically computed types are not acceptable. (This is an
Annotations should be kept simple or static analysis tools may not be
able to interpret the values. For example, dynamically computed types
are unlikely to be understood. (This is an
intentionally somewhat vague requirement, specific inclusions and
exclusions may be added to future versions of this PEP as warranted by
the discussion.)
@ -158,7 +178,7 @@ below may be used: ``None``, ``Any``, ``Union``, ``Tuple``,
from ``typing`` (e.g. ``Sequence`` and ``Dict``), type variables, and
type aliases.
All newly introducedw names used to support features described in
All newly introduced names used to support features described in
following sections (such as ``Any`` and ``Union``) are available in
the ``typing`` module.
@ -280,7 +300,10 @@ The function ``concat`` can be called with either two ``str`` arguments
or two ``bytes`` arguments, but not with a mix of ``str`` and ``bytes``
arguments.
Note that subtypes of types constrained by a type variable are treated
There should be at least two constraints, if any; specifying a single
constraint is disallowed.
Subtypes of types constrained by a type variable should be treated
as their respective explicitly listed base types in the context of the
type variable. Consider this example::
@ -374,6 +397,35 @@ You can use multiple inheritance with ``Generic``::
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]
...
Instantiating generic classes and type erasure
----------------------------------------------
Generic types like ``List`` or ``Sequence`` cannot be instantiated.
However, user-defined classes derived from them can be instantiated.
Given a generic class ``Node[T]`` there are three forms of
instantiation:
* ``x = Node()`` -- the type of x is ``Node[Any]``.
* ``x = Node[T]()`` -- the type of x is ``Node[T]``.
* ``x = Node[int]()`` -- the type of x is ``Node[int]``.
At runtime the type is not preserved, and the observable type of x is
just ``Node``. This is type erasure and common practice in languages
with generics (e.g. Java, Typescript).
Arbitrary generic types as base classes
---------------------------------------
@ -421,6 +473,17 @@ Now ``LinkedList[int]`` is a valid type. Note that we can use ``T``
multiple times in the base class list, as long as we don't use the
same type variable ``T`` multiple times within ``Generic[...]``.
Also consider the following example::
from typing import TypeVar, Mapping
T = TypeVar('T')
class MyDict(Mapping[str, T]):
...
In this case MyDict has a single parameter, T.
Abstract generic types
----------------------
@ -431,6 +494,164 @@ or properties, and generic classes can also have ABCs as base
classes without a metaclass conflict.
Type variables with an upper bound
----------------------------------
A type variable may specify an upper bound using ``bound=<type>``.
This means that an actual type substituted (explicitly or implictly)
for the type variable must be a subclass of the boundary type. A
common example is the definition of a Comparable type that works well
enough to catch the most common errors::
from typing import TypeVar
class Comparable(metaclass=ABCMeta):
@abstractmethod
def __lt__(self, other: Any) -> bool: ...
... # __gt__ etc. as well
CT = TypeVar('CT', bound=Comparable)
def min(x: CT, y: CT) -> CT:
if x < y:
return x
else:
return y
min(1, 2) # ok, return type int
min('x', 'y') # ok, return type str
(Note that this is not ideal -- for example ``min('x', 1)`` is invalid
at runtime but a type checker would simply infer the return type
``Comparable``. Unfortunately, addressing this would require
introducing a much more powerful and also much more complicated
concept, F-bounded polymorphism. We may revisit this in the future.)
An upper bound cannot be combined with type constraints (as in used
``AnyStr``, see the example earlier); type constraints cause the
inferred type to be _exactly_ one of the constraint types, while an
upper bound just requires that the actual type is a subclass of the
boundary type.
Covariance and contravariance
-----------------------------
Consider a class ``Employee`` with a subclass ``Manager``. Now
suppose we have a function with an argument annotated with
``List[Employee]``. Should we be allowed to call this function with a
variable of type ``List[Manager]`` as its argument? Many people would
answer "yes, of course" without even considering the consequences.
But unless we know more about the function, a type checker should
reject such a call: the function might append an ``Employee`` instance
to the list, which would violate the variable's type in the caller.
It turns out such an argument acts _contravariantly_, whereas the
intuitive answer (which is correct in case the function doesn't mutate
its argument!) requires the argument to act _covariantly_. A longer
introduction to these concepts can be found on Wikipedia
[wiki-variance]_; here we just show how to control a type checker's
behavior.
By default type variables are considered _invariant_, which means that
arguments for arguments annotated with types like ``List[Employee]``
must exactly match the type annotation -- no subclasses or
superclasses of the type parameter (in this example ``Employee``) are
allowed.
To facilitate the declaration of container types where covariant type
checking is acceptable, a type variable can be declared using
``covariant=True``. For the (rare) case where contravariant behavior
is desirable, pass ``contravariant=True``. At most one of these may
be passed.
A typical example involves defining an immutable container class::
from typing import TypeVar
T = TypeVar('T', covariant=True)
class ImmutableList(Generic[T]):
def append(self, T): ...
...
class Employee: ...
class Manager(Employee): ...
def dump_employees(emps: ImmutableList[Employee]) -> None: ...
mgrs = ... # type: ImmutableList[Mananger]
mgrs.append(Manager())
dump_employees(mgrs) # OK
The immutable collection classes in ``typing`` are all defined using a
covariant type variable (e.g. ``Mapping`` and ``Sequence``). The
mutable collection classes (e.g. ``MutableMapping`` and
``MutableSequence``) are defined using regular invariant type
variables. The one example of a contravariant type variable is the
``Generator`` type, which is contravariant in the ``send()`` argument
type (see below).
Note: variance affects type parameters for generic types -- it does
not affect regular parameters. For example, the following example is
fine::
from typing import TypeVar
class Employee: ...
class Manager(Employee): ...
E = TypeVar('E', bound=Employee) # Invariant
def dump_employee(e: E) -> None: ...
dump_employee(Manager()) # OK
The numeric tower
-----------------
PEP 3141 defines Python's numeric tower, and the stdlib module
``numbers`` implements the corresponding ABCs (``Number``,
``Complex``, ``Real``, ``Rational`` and ``Integral``). There are some
issues with these ABCs, but the built-in concrete numeric classes
``complex``, ``float`` and ``int`` are ubiquitous (especially the
latter two :-).
Rather than requiring that users write ``import numbers`` and then use
``numbers.Float`` etc., this PEP proposes a straightforward shortcut
that is almost as effective: when an argument is annotated as having
type ``float``, an argument of type ``int`` is acceptable; similar,
for an argument annotated as having type ``complex``, arguments of
type ``float`` or ``int`` are acceptable. This does not handle
classes implementing the corresponding ABCs or the
``fractions.Fraction`` class, but we believe those use cases are
exceedingly rare.
The bytes types
---------------
There are three different builtin classes used for arrays of bytes
(not counting the classes available in the ``array`` module):
``bytes``, ``bytearray`` and ``memoryview``. Of these, ``bytes`` and
``bytearray`` have many behaviors in common (though not all --
``bytearray`` is mutable).
While there is an ABC ``ByteString`` defined in ``collections.abc``
and a corresponding type in ``typing``, functions accepting bytes (of
some form) are so common that it would be cumbersome to have to write
``typing.ByteString`` everywhere. So, as a shortcut similar to that
for the builtin numeric classes, when an argument is annotated as
having type ``bytes``, arguments of type ``bytearray`` or
``memoryview`` are acceptable. (Again, there are situations where
this isn't sound, but we believe those are exceedingly rare in
practice.)
Forward references
------------------
@ -529,8 +750,8 @@ Example::
...
A type factored by ``Union[T1, T2, ...]`` responds ``True`` to
``issubclass`` checks for ``T1`` and any of its subclasses, ``T2`` and
any of its subclasses, and so on.
``issubclass`` checks for ``T1`` and any of its subtypes, ``T2`` and
any of its subtypes, and so on.
One common case of union types are *optional* types. By default,
``None`` is an invalid value for any type, unless a default value of
@ -557,8 +778,8 @@ This is equivalent to::
The ``Any`` type
----------------
A special kind of type is ``Any``. Every class is a subclass of
``Any``. This is also true for the builtin class ``object``.
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
@ -596,6 +817,22 @@ and this is also the suggested default when the program is being
type-checked.
Default argument values
-----------------------
In stubs it may be useful to declare an argument as having a default
without specifying the actual default value. For example::
def foo(x: AnyStr, y: AnyStr = ...) -> AnyStr: ...
What should the default value look like? Any of the options ``""``,
``b""`` or ``None`` fails to satisfy the type constraint (actually,
``None`` will *modify* the type to become ``Optional[AnyStr]``).
In such cases the default value may be specified as a literal
ellipsis, i.e. the above example is literally what you would write.
Compatibility with other uses of function annotations
=====================================================
@ -655,6 +892,28 @@ Examples of type comments on ``with`` and ``for`` statements::
# Here x and y are floats
...
In stubs it may be useful to declare the existence of a variable
without giving it an initial value. This can be done using a literal
ellipsis::
from typing import IO
stream = ... # type: IO[str]
In non-stub code, there is a similar special case:
from typing import IO
stream = None # type: IO[str]
Type checkers should not complain about this (despite the value
``None`` not matching the given type), nor should they change the
inferred type to ``Optional[...]`` (despite the rule that does this
for annotated arguments with a default value of ``None``). The
assumption here is that other code will ensure that the variable is
given a value of the proper type, and all uses can assume that the
variable has the given type.
The ``# type: ignore`` comment should be put on the line that the
error refers to::
@ -674,7 +933,7 @@ Casts
Occasionally the type checker may need a different kind of hint: the
programmer may know that an expression is of a more constrained type
than the type checker infers. For example::
than a type checker may be able to infer. For example::
from typing import List, cast
@ -683,7 +942,8 @@ than the type checker infers. For example::
# We only get here if there's at least one string in a
return cast(str, a[index])
The type checker infers the type ``object`` for ``a[index]``, but we
Some type checkers may not be able to infers that the type of
``a[index]`` is ``str`` and only infer ``object`` or ``Any``", but we
know that (if the code gets to that point) it must be a string. The
``cast(t, x)`` call tells the type checker that we are confident that
the type of ``x`` is ``t``. At runtime a cast always returns the
@ -720,8 +980,8 @@ feature of the ``typing`` module that may only be used in stub files:
the ``@overload`` decorator described below.
The type checker should only check function signatures in stub files;
function bodies in stub files should just be a single ``pass``
statement.
It is recommended that function bodies in stub files just be a single
ellipsis (``...``).
The type checker should have a configurable search path for stub files.
If a stub file is found the type checker should not read the
@ -732,6 +992,12 @@ While stub files are syntactically valid Python modules, they use the
same directory as the corresponding real module. This also reinforces
the notion that no runtime behavior should be expected of stub files.
Additional notes on stub files:
* Modules and variables imported into the stub are not considered
exported from the stub unless the import uses the ``import ... as
...`` form.
Function overloading
--------------------
@ -746,9 +1012,9 @@ follows::
class bytes:
...
@overload
def __getitem__(self, i: int) -> int: pass
def __getitem__(self, i: int) -> int: ...
@overload
def __getitem__(self, s: slice) -> bytes: pass
def __getitem__(self, s: slice) -> bytes: ...
This description is more precise than would be possible using unions
(which cannot express the relationship between the argument and return
@ -757,7 +1023,7 @@ types)::
from typing import Union
class bytes:
...
def __getitem__(self, a: Union[int, slice]) -> Union[int, bytes]: pass
def __getitem__(self, a: Union[int, slice]) -> Union[int, bytes]: ...
Another example where ``@overload`` comes in handy is the type of the
builtin ``map()`` function, which takes a different number of
@ -770,20 +1036,20 @@ arguments depending on the type of the callable::
S = TypeVar('S')
@overload
def map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]: pass
def map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]: ...
@overload
def map(func: Callable[[T1, T2], S],
iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]: pass
iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]: ...
# ... and we could add more items to support more than two iterables
Note that we could also easily add items to support ``map(None, ...)``::
@overload
def map(func: None, iter1: Iterable[T1]) -> Iterable[T1]: pass
def map(func: None, iter1: Iterable[T1]) -> Iterable[T1]: ...
@overload
def map(func: None,
iter1: Iterable[T1],
iter2: Iterable[T2]) -> Iterable[Tuple[T1, T2]]: pass
iter2: Iterable[T2]) -> Iterable[Tuple[T1, T2]]: ...
The ``@overload`` decorator may only be used in stub files. While it
would be possible to provide a multiple dispatch implementation using
@ -795,7 +1061,8 @@ is why previous attempts were abandoned in favor of
"Alternative approaches".) In the future we may come up with a
satisfactory multiple dispatch design, but we don't want such a design
to be constrained by the overloading syntax defined for type hints in
stub files.
stub files. In the meantime, using the ``@overload`` decorator or
calling ``overload()`` directly raises ``RuntimeError``.
Storing and distributing stub files
-----------------------------------
@ -827,8 +1094,8 @@ Note that if the user decides to use the "latest" available source
package, using the "latest" stub files should generally also work if
they're updated often.
Third-party stub packages can use any location for stub storage. The
type checker will search for them using PYTHONPATH. A default fallback
Third-party stub packages can use any location for stub storage. Type
checkers should search for them using PYTHONPATH. A default fallback
directory that is always checked is ``shared/typehints/python3.5/`` (or
3.6, etc.). Since there can only be one package installed for a given
Python version per environment, no additional versioning is performed
@ -845,6 +1112,16 @@ snippet in ``setup.py``::
],
...
The Typeshed Repo
-----------------
There is a shared repository where useful stubs are being collected
[typeshed]_. Note that stubs for a given package will not be included
here without the explicit consent of the package owner. Further
policies regarding the stubs collected here will be decided at a later
time, after discussion on python-dev, and reported in the typeshed
repo's README.
Exceptions
==========
@ -860,8 +1137,32 @@ The ``typing`` Module
To open the usage of static type checking to Python 3.5 as well as older
versions, a uniform namespace is required. For this purpose, a new
module in the standard library is introduced called ``typing``. It
holds a set of classes representing builtin types with generics, namely:
module in the standard library is introduced called ``typing``.
It defines the fundamental building blocks for constructing types
(e.g. ``Any``), types representing generic variants of builtin
collections (e.g. ``List``), types representing generic
collection ABCs (e.g. ``Sequence``), and a small collection of
convenience definitions.
Fundamental building blocks:
* Any, used as ``def get(key: str) -> Any: ...``
* Union, used as ``Union[Type1, Type2, Type3]``
* Callable, used as ``Callable[[Arg1Type, Arg2Type], ReturnType]``
* Tuple, used by listing the element types, for example
``Tuple[int, int, str]``.
Arbitrary-length homogeneous tuples can be expressed
using one type and ellipsis, for example ``Tuple[int, ...]``.
(The ``...`` here are part of the syntax, a literal ellipsis.)
* TypeVar, used as ``X = TypeVar('X', Type1, Type2, Type3)`` or simply
``Y = TypeVar('Y')`` (see above for more details)
Generic variants of builtin collections:
* Dict, used as ``Dict[key_type, value_type]``
@ -872,53 +1173,28 @@ holds a set of classes representing builtin types with generics, namely:
* FrozenSet, used as ``FrozenSet[element_type]``
* Tuple, used by listing the element types, for example
``Tuple[int, int, str]``.
Arbitrary-length homogeneous tuples can be expressed
using one type and ellipsis, for example ``Tuple[int, ...]``.
(The ``...`` here are part of the syntax.)
Note: ``Dict``, ``List``, ``Set`` and ``FrozenSet`` are mainly useful
for annotating return values. For arguments, prefer the abstract
collection types defined below, e.g. ``Mapping``, ``Sequence`` or
``AbstractSet``.
* NamedTuple, used as
``NamedTuple(type_name, [(field_name, field_type), ...])``
and equivalent to
``collections.namedtuple(type_name, [field_name, ...])``.
The generic versions of concrete collection types (``Dict``, ``List``,
``Set``, ``FrozenSet``, and homogeneous arbitrary-length ``Tuple``)
are mainly useful for annotating return values. For arguments, prefer
the abstract collection types defined below, e.g. ``Mapping``,
``Sequence`` or ``AbstractSet``.
The ``typing`` module defines the ``Generator`` type for return values
of generator functions. It is a subtype of ``Iterable`` and it has
additional type variables for the type accepted by the ``send()``
method and the return type of the generator:
* Generator, used as ``Generator[yield_type, send_type, return_type]``
It also introduces factories and helper members needed to express
generics and union types:
* Any, used as ``def get(key: str) -> Any: ...``
* Union, used as ``Union[Type1, Type2, Type3]``
* TypeVar, used as ``X = TypeVar('X', Type1, Type2, Type3)`` or simply
``Y = TypeVar('Y')``
* Callable, used as ``Callable[[Arg1Type, Arg2Type], ReturnType]``
* AnyStr, defined as ``TypeVar('AnyStr', str, bytes)``
All abstract base classes available in ``collections.abc`` are
importable from the ``typing`` module, with added generics support:
Generic variants of container ABCs (and a few non-containers):
* ByteString
* Callable (see above)
* Callable (see above, listed here for completeness)
* Container
* Generator, used as ``Generator[yield_type, send_type,
return_type]``. This represents the return value of generator
functions. It is a subtype of ``Iterable`` and it has additional
type variables for the type accepted by the ``send()`` method (which
is contravariant -- a generator that accepts sending it ``Employee``
instance is valid in a context where a generator is required that
accepts sending it ``Manager`` instances) and the return type of the
generator.
* Hashable (not generic, but present for completeness)
* ItemsView
@ -956,13 +1232,17 @@ A few one-off types are defined that test for single special methods
* SupportsAbs, to test for ``__abs__``
* SupportsComplex, to test for ``__complex__``
* SupportsFloat, to test for ``__float__``
* SupportsInt, to test for ``__int__``
* SupportsRound, to test for ``__round__``
The library includes literals for platform-specific type hinting:
* SupportsBytes, to test for ``__bytes__``
Constants for platform-specific type hinting:
* PY2
@ -972,41 +1252,46 @@ The library includes literals for platform-specific type hinting:
* POSIX, equivalent to ``not WINDOWS``
The following conveniece functions and decorators are exported:
Convenience definitions:
* cast, described earlier
* AnyStr, defined as ``TypeVar('AnyStr', str, bytes)``
* no_type_check, a decorator to disable type checking per class or
* NamedTuple, used as
``NamedTuple(type_name, [(field_name, field_type), ...])``
and equivalent to
``collections.namedtuple(type_name, [field_name, ...])``.
This is useful to declare the types of the fields of a a named tuple
type.
* cast(), described earlier
* @no_type_check, a decorator to disable type checking per class or
function (see below)
* no_type_check_decorator, a decorator to create your own decorators
* @no_type_check_decorator, a decorator to create your own decorators
with the same meaning as ``@no_type_check`` (see below)
* overload, described earlier
* @overload, described earlier
* get_type_hints, a utility function to retrieve the type hints from a
* get_type_hints(), a utility function to retrieve the type hints from a
function or method. Given a function or method object, it returns
a dict with the same format as ``__annotations__``, but evaluating
forward references (which are given as string literals) as expressions
in the context of the original function or method definition.
The following types are available in the ``typing.io`` module:
Types available in the ``typing.io`` submodule:
* IO (generic over ``AnyStr``)
* BinaryIO (a simple subclass of ``IO[bytes]``)
* BinaryIO (a simple subtype of ``IO[bytes]``)
* TextIO (a simple subclass of ``IO[str]``)
* TextIO (a simple subtype of ``IO[str]``)
The following types are provided by the ``typing.re`` module:
Types available in the ``typing.re`` submodule:
* Match and Pattern, types of ``re.match()`` and ``re.compile()``
results (generic over ``AnyStr``)
As a convenience measure, types from ``typing.io`` and ``typing.re`` are
also available in ``typing`` (quoting Guido, "There's a reason those
modules have two-letter names.").
Rejected Alternatives
=====================
@ -1025,7 +1310,7 @@ Most people are familiar with the use of angular brackets
express the parametrization of generic types. The problem with these
is that they are really hard to parse, especially for a simple-minded
parser like Python. In most languages the ambiguities are usually
dealy with by only allowing angular brackets in specific syntactic
dealt with by only allowing angular brackets in specific syntactic
positions, where general expressions aren't allowed. (And also by
using very powerful parsing techniques that can backtrack over an
arbitrary section of code.)
@ -1187,7 +1472,7 @@ evaluation. There are several things wrong with this idea, however.
well known from other programming languages. But this use of ``::``
is unheard of in English, and in other languages (e.g. C++) it is
used as a scoping operator, which is a very different beast. In
contrast, the single colon for type hints reads natural -- and no
contrast, the single colon for type hints reads naturally -- and no
wonder, since it was carefully designed for this purpose (the idea
long predates PEP 3107 [gvr-artima]_). It is also used in the same
fashion in other languages from Pascal to Swift.
@ -1286,15 +1571,21 @@ References
.. [mypy]
http://mypy-lang.org
.. [gvr-artima]
http://www.artima.com/weblogs/viewpost.jsp?thread=85551
.. [wiki-variance]
http://en.wikipedia.org/wiki/Covariance_and_contravariance_%28computer_science%29
.. [typeshed]
https://github.com/JukkaL/typeshed/
.. [pyflakes]
https://github.com/pyflakes/pyflakes/
.. [pylint]
http://www.pylint.org
.. [gvr-artima]
http://www.artima.com/weblogs/viewpost.jsp?thread=85551
.. [roberge]
http://aroberge.blogspot.com/2015/01/type-hinting-in-python-focus-on.html