Guido van Rossum | 17 Apr 23:58 2015

PEP 484 (Type Hints) -- the next draft is here

The PEP 484 authors (Jukka, Łukasz and I) have a new draft ready. This time we're posting to python-dev.

While we don't have all details totally sorted out, it's a lot closer. We have a BDFL-Delegate (Mark Shannon), and we've worked out a variety of issues at PyCon. Our hope remains that we'll get the typing.py module added to CPython 3.5 before beta 1 goes out (May 24).

Below is a list of key changes since the draft posted to python-dev on March 20 (for more details see https://github.com/ambv/typehinting/commits/master/pep-0484.txt) and the full text of the PEP. The new draft is also in the peps repo (https://hg.python.org/peps/file/tip/pep-0484.txt) and will soon be on python.org (https://www.python.org/dev/peps/pep-0484/ -- give it 10-30 minutes).

As always, between draft postings the PEP text is updated frequently by the authors in a dedicated GitHub repo (https://github.com/ambv/typehinting), and many detailed discussions are found in the issue tracker there (https://github.com/ambv/typehinting/issues). The typing.py module also lives in that repo (https://github.com/ambv/typehinting/tree/master/prototyping).

Key changes since 20-Mar-2015 draft
--------------------------------------------------

Generics:
- Properly specify generics and type variables.
- Add covariant/contravariant flags to TypeVar().

Type specifications:
- Define type aliases.
- Kill Undefined.
- Better specification of `# type:` comments.

Specifics:
- Add Generator (a generic type describing generator objects)
- Document get_type_hints().

Stubs:
- Only .pyi is a valid extension for stub files.
- Add discussion of third-party stubs (see issue #84).

Process:
- Mark Shannon is now BDFL-Delegate.
- Add section on PEP Development Process, with github links.

Other:
- Mention the __future__ proposal (a separate PEP to be developed).
- Lots of editing; remove some sections that didn't specify anything.

Full PEP text
------------------

PEP: 484
Title: Type Hints
Version: $Revision$
Last-Modified: $Date$
Author: Guido van Rossum <guido <at> python.org>, Jukka Lehtosalo <jukka.lehtosalo <at> iki.fi>, Łukasz Langa <lukasz <at> langa.pl>
BDFL-delegate: Mark Shannon
Discussions-To: Python-Dev <python-dev <at> python.org>
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
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::

  def greeting(name: str) -> str:
      return 'Hello ' + name

While these annotations are available at runtime through the usual
``__annotations__`` attribute, *no type checking happens at runtime*.
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.

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.

The type system supports unions, generic types, and a special type
named ``Any`` which is consistent with (i.e. assignable to and from) all
types.  This latter feature is taken from the idea of gradual typing.
Gradual typing and the full type system are explained in PEP 483.

Other approaches from which we have borrowed or to which ours can be
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.

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.

Of these goals, static analysis is the most important.  This includes
support for off-line type checkers such as mypy, as well as providing
a standard notation that can be used by IDEs for code completion and
refactoring.

Non-goals
---------

While the proposed typing module will contain some building blocks for
runtime type checking -- in particular a useful ``isinstance()``
implementation -- third party packages would have to be developed to
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
typed language, and the authors have no desire to ever make type hints
mandatory, even by convention.


What is checked?
================

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 `` <at> no_type_check`` decorator or a
``# type: ignore`` comment (see below).

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``.

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.

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 should understand decorators; this may require
annotations on decorator definitions.  In particular, a type checker
should understand the built-in decorators `` <at> property``,
`` <at> staticmethod`` and `` <at> classmethod``.  The first argument of a class
method should not be annotated; it is assumed to be a subclass of the
defining class.


Type Definition Syntax
======================

The syntax leverages PEP 3107-style annotations with a number of
extensions described in sections below.  In its basic form, type
hinting is used by filling function annotation slots with classes::

  def greeting(name: str) -> str:
      return 'Hello ' + name

This states that the expected type of the ``name`` argument is
``str``.  Analogically, the expected return type is ``str``.

Expressions whose type is a subtype of a specific argument type are
also accepted for that argument.


Acceptable type hints
---------------------

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).

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
intentionally somewhat vague requirement, specific inclusions and
exclusions may be added to future versions of this PEP as warranted by
the discussion.)

In addition to the above, the following special constructs defined
below may be used: ``None``, ``Any``, ``Union``, ``Tuple``,
``Callable``, all ABCs and stand-ins for concrete classes exported
from ``typing`` (e.g. ``Sequence`` and ``Dict``), type variables, and
type aliases.

All newly introducedw names used to support features described in
following sections (such as ``Any`` and ``Union``) are available in
the ``typing`` module.


Using None
----------

When used in a type hint, the expression ``None`` is considered
equivalent to ``type(None)``.


Type aliases
------------

Type aliases are defined by simple variable assignments::

  Url = str

  def retry(url: Url, retry_count: int) -> None: ...

Note that we recommend capitalizing alias names, since they represent
user-defined types, which (like user-defined classes) are typically
spelled that way.

Type aliases may be as complex as type hints in annotations --
anything that is acceptable as a type hint is acceptable in a type
alias::

    from typing import TypeVar, Iterable, Tuple

    T = TypeVar('T', int, float, complex)
    Vector = Iterable[Tuple[T, T]]

    def inproduct(v: Vector) -> T:
        return sum(x*y for x, y in v)

This is equivalent to::

    from typing import TypeVar, Iterable, Tuple

    T = TypeVar('T', int, float, complex)

    def inproduct(v: Iterable[Tuple[T, T]]) -> T:
        return sum(x*y for x, y in v)


Callable
--------

Frameworks expecting callback functions of specific signatures might be
type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``.
Examples::

  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
(three dots) for the list of arguments::

  def partial(func: Callable[..., str], *args) -> Callable[..., str]:
      # Body

Note that there are no square brackets around the ellipsis.  The
arguments of the callback are completely unconstrained in this case
(and keyword arguments are acceptable).

Since using callbacks with keyword arguments is not perceived as a
common use case, there is currently no support for specifying keyword
arguments with ``Callable``.  Similarly, there is no support for
specifying callback signatures with a variable number of argument of a
specific type.


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.  Example::

  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``.  Example::

  from typing import Sequence, TypeVar

  T = TypeVar('T')      # Declare type variable

  def first(l: Sequence[T]) -> T:   # Generic function
      return l[0]

In this case the contract is that the returned value is consistent with
the elements held by the collection.

``TypeVar`` supports constraining parametric types to a fixed set of
possible types.  For example, we can define a type variable that ranges
over just ``str`` and ``bytes``.  By default, a type variable ranges
over all possible types.  Example of constraining a type variable::

  from typing import TypeVar

  AnyStr = TypeVar('AnyStr', str, bytes)

  def concat(x: AnyStr, y: AnyStr) -> AnyStr:
      return x + y

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
as their respective explicitly listed base types in the context of the
type variable.  Consider this example::

  class MyStr(str): ...

  x = concat(MyStr('apple'), MyStr('pie'))

The call is valid but the type variable ``AnyStr`` will be set to
``str`` and not ``MyStr``. In effect, the inferred type of the return
value assigned to ``x`` will also be ``str``.

Additionally, ``Any`` is a valid value for every type variable.
Consider the following::

  def count_truthy(elements: List[Any]) -> int:
      return sum(1 for elem in elements if element)

This is equivalent to omitting the generic notation and just saying
``elements: List``.


User-defined generic types
--------------------------

You can include a ``Generic`` base class to define a user-defined class
as generic.  Example::

  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. This is valid::

  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]):
      ...


Arbitrary generic types as base classes
---------------------------------------

``Generic[T]`` is only valid as a base class -- it's not a proper type.
However, user-defined generic types such as ``LinkedList[T]`` from the
above example and built-in generic types and ABCs such as ``List[T]``
and ``Iterable[T]`` are valid both as types and as base classes. For
example, we can define a subclass of ``Dict`` that specializes type
arguments::

  from typing import Dict, List, Optional

  class Node:
      ...

  class SymbolTable(Dict[str, List[Node]]):
      def push(self, name: str, node: Node) -> None:
          self.setdefault(name, []).append(node)

      def pop(self, name: str) -> Node:
          return self[name].pop()

      def lookup(self, name: str) -> Optional[Node]:
          nodes = self.get(name)
          if nodes:
              return nodes[-1]
          return None

``SymbolTable`` is a subclass of ``dict`` and a subtype of ``Dict[str,
List[Node]]``.

If a generic base class has a type variable as a type argument, this
makes the defined class generic. For example, we can define a generic
``LinkedList`` class that is iterable and a container::

  from typing import TypeVar, Iterable, Container

  T = TypeVar('T')

  class LinkedList(Iterable[T], Container[T]):
      ...

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[...]``.


Abstract generic types
----------------------

The metaclass used by ``Generic`` is a subclass of ``abc.ABCMeta``.
A generic class can be an ABC by including abstract methods
or properties, and generic classes can also have ABCs as base
classes without a metaclass conflict.


Forward references
------------------

When a type hint contains names that have not been defined yet, that
definition may be expressed as a string literal, to be resolved later.

A situation where this occurs commonly is the definition of a
container class, where the class being defined occurs in the signature
of some of the methods.  For example, the following code (the start of
a simple binary tree implementation) does not work::

  class Tree:
      def __init__(self, left: Tree, right: Tree):
          self.left = left
          self.right = right

To address this, we write::

  class Tree:
      def __init__(self, left: 'Tree', right: 'Tree'):
          self.left = left
          self.right = right

The string literal should contain a valid Python expression (i.e.,
``compile(lit, '', 'expr')`` should be a valid code object) and it
should evaluate without errors once the module has been fully loaded.
The local and global namespace in which it is evaluated should be the
same namespaces in which default arguments to the same function would
be evaluated.

Moreover, the expression should be parseable as a valid type hint, i.e.,
it is constrained by the rules from the section `Acceptable type hints`_
above.

It is allowable to use string literals as *part* of a type hint, for
example::

    class Tree:
        ...
        def leaves(self) -> List['Tree']:
            ...


Union types
-----------

Since accepting a small, limited set of expected types for a single
argument is common, there is a new special factory called ``Union``.
Example::

  from typing import Union

  def handle_employees(e: Union[Employee, Sequence[Employee]]) -> None:
      if isinstance(e, Employee):
          e = [e]
      ...

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.

One common case of union types are *optional* types.  By default,
``None`` is an invalid value for any type, unless a default value of
``None`` has been provided in the function definition.  Examples::

  def handle_employee(e: Union[Employee, None]) -> None: ...

As a shorthand for ``Union[T1, None]`` you can write ``Optional[T1]``;
for example, the above is equivalent to::

  from typing import Optional

  def handle_employee(e: Optional[Employee]) -> None: ...

An optional type is also automatically assumed when the default value is
``None``, for example::

  def handle_employee(e: Employee = None): ...

This is equivalent to::

  def handle_employee(e: Optional[Employee] = None) -> None: ...

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``.
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.


Predefined constants
--------------------

Some predefined Boolean constants are defined in the ``typing``
module to enable platform-specific type definitions and such::

  from typing import PY2, PY3, WINDOWS, POSIX

  if PY2:
      text = unicode
  else:
      text = str

  def f() -> text: ...

  if WINDOWS:
      loop = ProactorEventLoop
  else:
      loop = UnixSelectorEventLoop

It is up to the type checker implementation to define their values, as
long as ``PY2 == not PY3`` and ``WINDOWS == not POSIX``.  When the
program is being executed these always reflect the current platform,
and this is also the suggested default when the program is being
type-checked.


Compatibility with other uses of function annotations
=====================================================

A number of existing or potential use cases for function annotations
exist, which are incompatible with type hinting.  These may confuse
a static type checker.  However, since type hinting annotations have no
runtime behavior (other than evaluation of the annotation expression and
storing annotations in the ``__annotations__`` attribute of the function
object), this does not make the program incorrect -- it just may cause
a type checker to emit spurious warnings or errors.

To mark portions of the program that should not be covered by type
hinting, you can use one or more of the following:

* a ``# type: ignore`` comment;

* a `` <at> no_type_check`` decorator on a class or function;

* a custom class or function decorator marked with
  `` <at> no_type_check_decorator``.

For more details see later sections.

In order for maximal compatibility with offline type checking it may
eventually be a good idea to change interfaces that rely on annotations
to switch to a different mechanism, for example a decorator.  In Python
3.5 there is no pressure to do this, however.  See also the longer
discussion under `Rejected alternatives`_ below.


Type comments
=============

No first-class syntax support for explicitly marking variables as being
of a specific type is added by this PEP.  To help with type inference in
complex cases, a comment of the following format may be used::

  x = []   # type: List[Employee]
  x, y, z = [], [], []  # type: List[int], List[int], List[str]
  x, y, z = [], [], []  # type: (List[int], List[int], List[str])
  x = [
     1,
     2,
  ]  # type: List[int]

Type comments should be put on the last line of the statement that
contains the variable definition. They can also be placed on
``with`` statements and ``for`` statements, right after the colon.

Examples of type comments on ``with`` and ``for`` statements::

  with frobnicate() as foo:  # type: int
      # Here foo is an int
      ...

  for x, y in points:  # type: float, float
      # Here x and y are floats
      ...

The ``# type: ignore`` comment should be put on the line that the
error refers to::

  import http.client
  errors = {
      'not_found': http.client.NOT_FOUND  # type: ignore
  }

A ``# type: ignore`` comment on a line by itself disables all type
checking for the rest of the file.

If type hinting proves useful in general, a syntax for typing variables
may be provided in a future Python version.

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::

  from typing import List, cast

  def find_first_str(a: List[object]) -> str:
      index = next(i for i, x in enumerate(a) if isinstance(x, str))
      # 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
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
expression unchanged -- it does not check the type, and it does not
convert or coerce the value.

Casts differ from type comments (see the previous section).  When using
a type comment, the type checker should still verify that the inferred
type is consistent with the stated type.  When using a cast, the type
checker should blindly believe the programmer.  Also, casts can be used
in expressions, while type comments only apply to assignments.


Stub Files
==========

Stub files are files containing type hints that are only for use by
the type checker, not at runtime.  There are several use cases for
stub files:

* Extension modules

* Third-party modules whose authors have not yet added type hints

* Standard library modules for which type hints have not yet been
  written

* Modules that must be compatible with Python 2 and 3

* Modules that use annotations for other purposes

Stub files have the same syntax as regular Python modules.  There is one
feature of the ``typing`` module that may only be used in stub files:
the `` <at> 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.

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
corresponding "real" module.

While stub files are syntactically valid Python modules, they use the
``.pyi`` extension to make it possible to maintain stub files in the
same directory as the corresponding real module.  This also reinforces
the notion that no runtime behavior should be expected of stub files.

Function overloading
--------------------

The `` <at> overload`` decorator allows describing functions that support
multiple different combinations of argument types.  This pattern is
used frequently in builtin modules and types.  For example, the
``__getitem__()`` method of the ``bytes`` type can be described as
follows::

  from typing import overload

  class bytes:
    ...
    <at> overload
    def __getitem__(self, i: int) -> int: pass
    <at> overload
    def __getitem__(self, s: slice) -> bytes: pass

This description is more precise than would be possible using unions
(which cannot express the relationship between the argument and return
types)::

  from typing import Union
  class bytes:
    ...
    def __getitem__(self, a: Union[int, slice]) -> Union[int, bytes]: pass

Another example where `` <at> overload`` comes in handy is the type of the
builtin ``map()`` function, which takes a different number of
arguments depending on the type of the callable::

  from typing import Callable, Iterable, Iterator, Tuple, TypeVar, overload

  T1 = TypeVar('T1')
  T2 = TypeVar('T2)
  S = TypeVar('S')

  <at> overload
  def map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]: pass
  <at> overload
  def map(func: Callable[[T1, T2], S],
          iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]: pass
  # ... and we could add more items to support more than two iterables

Note that we could also easily add items to support ``map(None, ...)``::

  <at> overload
  def map(func: None, iter1: Iterable[T1]) -> Iterable[T1]: pass
  <at> overload
  def map(func: None,
          iter1: Iterable[T1],
          iter2: Iterable[T2]) -> Iterable[Tuple[T1, T2]]: pass

The `` <at> overload`` decorator may only be used in stub files.  While it
would be possible to provide a multiple dispatch implementation using
this syntax, its implementation would require using
``sys._getframe()``, which is frowned upon.  Also, designing and
implementing an efficient multiple dispatch mechanism is hard, which
is why previous attempts were abandoned in favor of
``functools.singledispatch()``.  (See PEP 443, especially its section
"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.

Storing and distributing stub files
-----------------------------------

The easiest form of stub file storage and distribution is to put them
alongside Python modules in the same directory.  This makes them easy to
find by both programmers and the tools.  However, since package
maintainers are free not to add type hinting to their packages,
third-party stubs installable by ``pip`` from PyPI are also supported.
In this case we have to consider three issues: naming, versioning,
installation path.

This PEP does not provide a recommendation on a naming scheme that
should be used for third-party stub file packages.  Discoverability will
hopefully be based on package popularity, like with Django packages for
example.

Third-party stubs have to be versioned using the lowest version of the
source package that is compatible.  Example: FooPackage has versions
1.0, 1.1, 1.2, 1.3, 2.0, 2.1, 2.2.  There are API changes in versions
1.1, 2.0 and 2.2.  The stub file package maintainer is free to release
stubs for all versions but at least 1.0, 1.1, 2.0 and 2.2 are needed
to enable the end user type check all versions.  This is because the
user knows that the closest *lower or equal* version of stubs is
compatible.  In the provided example, for FooPackage 1.3 the user would
choose stubs version 1.1.

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
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
under that directory (just like bare directory installs by ``pip`` in
site-packages).  Stub file package authors might use the following
snippet in ``setup.py``::

  ...
  data_files=[
      (
          'shared/typehints/python{}.{}'.format(*sys.version_info[:2]),
          pathlib.Path(SRC_PATH).glob('**/*.pyi'),
      ),
  ],
  ...


Exceptions
==========

No syntax for listing explicitly raised exceptions is proposed.
Currently the only known use case for this feature is documentational,
in which case the recommendation is to put this information in a
docstring.


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:

* Dict, used as ``Dict[key_type, value_type]``

* List, used as ``List[element_type]``

* Set, used as ``Set[element_type]``. See remark for ``AbstractSet``
  below.

* 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.)

* 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:

* ByteString

* Callable (see above)

* Container

* Hashable (not generic, but present for completeness)

* ItemsView

* Iterable

* Iterator

* KeysView

* Mapping

* MappingView

* MutableMapping

* MutableSequence

* MutableSet

* Sequence

* Set, renamed to ``AbstractSet``. This name change was required
  because ``Set`` in the ``typing`` module means ``set()`` with
  generics.

* Sized (not generic, but present for completeness)

* ValuesView

A few one-off types are defined that test for single special methods
(similar to ``Hashable`` or ``Sized``):

* Reversible, to test for ``__reversed__``

* SupportsAbs, to test for ``__abs__``

* SupportsFloat, to test for ``__float__``

* SupportsInt, to test for ``__int__``

* SupportsRound, to test for ``__round__``

The library includes literals for platform-specific type hinting:

* PY2

* PY3, equivalent to ``not PY2``

* WINDOWS

* POSIX, equivalent to ``not WINDOWS``

The following conveniece functions and decorators are exported:

* 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
  with the same meaning as `` <at> no_type_check`` (see below)

* overload, described earlier

* 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:

* IO (generic over ``AnyStr``)

* BinaryIO (a simple subclass of ``IO[bytes]``)

* TextIO (a simple subclass of ``IO[str]``)

The following types are provided by the ``typing.re`` module:

* 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
=====================

During discussion of earlier drafts of this PEP, various objections
were raised and alternatives were proposed.  We discuss some of these
here and explain why we reject them.

Several main objections were raised.

Which brackets for generic type parameters?
-------------------------------------------

Most people are familiar with the use of angular brackets
(e.g. ``List<int>``) in languages like C++, Java, C# and Swift to
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
positions, where general expressions aren't allowed.  (And also by
using very powerful parsing techniques that can backtrack over an
arbitrary section of code.)

But in Python, we'd like type expressions to be (syntactically) the
same as other expressions, so that we can use e.g. variable assignment
to create type aliases.  Consider this simple type expression::

    List<int>

From the Python parser's perspective, the expression begins with the
same four tokens (NAME, LESS, NAME, GREATER) as a chained comparison::

    a < b > c  # I.e., (a < b) and (b > c)

We can even make up an example that could be parsed both ways::

    a < b > [ c ]

Assuming we had angular brackets in the language, this could be
interpreted as either of the following two::

    (a<b>)[c]      # I.e., (a<b>).__getitem__(c)
    a < b > ([c])  # I.e., (a < b) and (b > [c])

It would surely be possible to come up with a rule to disambiguate
such cases, but to most users the rules would feel arbitrary and
complex.  It would also require us to dramatically change the CPython
parser (and every other parser for Python).  It should be noted that
Python's current parser is intentionally "dumb" -- a simple grammar is
easier for users to reason about.

For all these reasons, square brackets (e.g. ``List[int]``) are (and
have long been) the preferred syntax for generic type parameters.
They can be implemented by defining the ``__getitem__()`` method on
the metaclass, and no new syntax is required at all.  This option
works in all recent versions of Python (starting with Python 2.2).
Python is not alone in this syntactic choice -- generic classes in
Scala also use square brackets.

What about existing uses of annotations?
----------------------------------------

One line of argument points out that PEP 3107 explicitly supports
the use of arbitrary expressions in function annotations.  The new
proposal is then considered incompatible with the specification of PEP
3107.

Our response to this is that, first of all, the current proposal does
not introduce any direct incompatibilities, so programs using
annotations in Python 3.4 will still work correctly and without
prejudice in Python 3.5.

We do hope that type hints will eventually become the sole use for
annotations, but this will require additional discussion and a
deprecation period after the initial roll-out of the typing module
with Python 3.5.  The current PEP will have provisional status (see
PEP 411) until Python 3.6 is released.  The fastest conceivable scheme
would introduce silent deprecation of non-type-hint annotations in
3.6, full deprecation in 3.7, and declare type hints as the only
allowed use of annotations in Python 3.8.  This should give authors of
packages that use annotations plenty of time to devise another
approach, even if type hints become an overnight success.

Another possible outcome would be that type hints will eventually
become the default meaning for annotations, but that there will always
remain an option to disable them.  For this purpose the current
proposal defines a decorator `` <at> no_type_check`` which disables the
default interpretation of annotations as type hints in a given class
or function.  It also defines a meta-decorator
`` <at> no_type_check_decorator`` which can be used to decorate a decorator
(!), causing annotations in any function or class decorated with the
latter to be ignored by the type checker.

There are also ``# type: ignore`` comments, and static checkers should
support configuration options to disable type checking in selected
packages.

Despite all these options, proposals have been circulated to allow
type hints and other forms of annotations to coexist for individual
arguments.  One proposal suggests that if an annotation for a given
argument is a dictionary literal, each key represents a different form
of annotation, and the key ``'type'`` would be use for type hints.
The problem with this idea and its variants is that the notation
becomes very "noisy" and hard to read.  Also, in most cases where
existing libraries use annotations, there would be little need to
combine them with type hints.  So the simpler approach of selectively
disabling type hints appears sufficient.

The problem of forward declarations
-----------------------------------

The current proposal is admittedly sub-optimal when type hints must
contain forward references.  Python requires all names to be defined
by the time they are used.  Apart from circular imports this is rarely
a problem: "use" here means "look up at runtime", and with most
"forward" references there is no problem in ensuring that a name is
defined before the function using it is called.

The problem with type hints is that annotations (per PEP 3107, and
similar to default values) are evaluated at the time a function is
defined, and thus any names used in an annotation must be already
defined when the function is being defined.  A common scenario is a
class definition whose methods need to reference the class itself in
their annotations.  (More general, it can also occur with mutually
recursive classes.)  This is natural for container types, for
example::

  class Node:
      """Binary tree node."""

      def __init__(self, left: Node, right: None):
          self.left = left
          self.right = right

As written this will not work, because of the peculiarity in Python
that class names become defined once the entire body of the class has
been executed.  Our solution, which isn't particularly elegant, but
gets the job done, is to allow using string literals in annotations.
Most of the time you won't have to use this though -- most *uses* of
type hints are expected to reference builtin types or types defined in
other modules.

A counterproposal would change the semantics of type hints so they
aren't evaluated at runtime at all (after all, type checking happens
off-line, so why would type hints need to be evaluated at runtime at
all).  This of course would run afoul of backwards compatibility,
since the Python interpreter doesn't actually know whether a
particular annotation is meant to be a type hint or something else.

A compromise is possible where a ``__future__`` import could enable
turning *all* annotations in a given module into string literals, as
follows::

  from __future__ import annotations

  class ImSet:
      def add(self, a: ImSet) -> List[ImSet]: ...

  assert ImSet.add.__annotations__ == {'a': 'ImSet', 'return': 'List[ImSet]'}

Such a ``__future__`` import statement will be proposed in a separate
PEP.


The double colon
----------------

A few creative souls have tried to invent solutions for this problem.
For example, it was proposed to use a double colon (``::``) for type
hints, solving two problems at once: disambiguating between type hints
and other annotations, and changing the semantics to preclude runtime
evaluation.  There are several things wrong with this idea, however.

* It's ugly.  The single colon in Python has many uses, and all of
  them look familiar because they resemble the use of the colon in
  English text.  This is a general rule of thumb by which Python
  abides for most forms of punctuation; the exceptions are typically
  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
  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.

* What would you do for return type annotations?

* It's actually a feature that type hints are evaluated at runtime.

  * Making type hints available at runtime allows runtime type
    checkers to be built on top of type hints.

  * It catches mistakes even when the type checker is not run.  Since
    it is a separate program, users may choose not to run it (or even
    install it), but might still want to use type hints as a concise
    form of documentation.  Broken type hints are no use even for
    documentation.

* Because it's new syntax, using the double colon for type hints would
  limit them to code that works with Python 3.5 only.  By using
  existing syntax, the current proposal can easily work for older
  versions of Python 3.  (And in fact mypy supports Python 3.2 and
  newer.)

* If type hints become successful we may well decide to add new syntax
  in the future to declare the type for variables, for example
  ``var age: int = 42``.  If we were to use a double colon for
  argument type hints, for consistency we'd have to use the same
  convention for future syntax, perpetuating the ugliness.

Other forms of new syntax
-------------------------

A few other forms of alternative syntax have been proposed, e.g. the
introduction of a ``where`` keyword [roberge]_, and Cobra-inspired
``requires`` clauses.  But these all share a problem with the double
colon: they won't work for earlier versions of Python 3.  The same
would apply to a new ``__future__`` import.

Other backwards compatible conventions
--------------------------------------

The ideas put forward include:

* A decorator, e.g. `` <at> typehints(name=str, returns=str)``.  This could
  work, but it's pretty verbose (an extra line, and the argument names
  must be repeated), and a far cry in elegance from the PEP 3107
  notation.

* Stub files.  We do want stub files, but they are primarily useful
  for adding type hints to existing code that doesn't lend itself to
  adding type hints, e.g. 3rd party packages, code that needs to
  support both Python 2 and Python 3, and especially extension
  modules.  For most situations, having the annotations in line with
  the function definitions makes them much more useful.

* Docstrings.  There is an existing convention for docstrings, based
  on the Sphinx notation (``:type arg1: description``).  This is
  pretty verbose (an extra line per parameter), and not very elegant.
  We could also make up something new, but the annotation syntax is
  hard to beat (because it was designed for this very purpose).

It's also been proposed to simply wait another release.  But what
problem would that solve?  It would just be procrastination.


PEP Development Process
=======================

A live draft for this PEP lives on GitHub [github]_.  There is also an
issue tracker [issues]_, where much of the technical discussion takes
place.

The draft on GitHub is updated regularly in small increments.  The
official PEPS repo [peps_] is (usually) only updated when a new draft
is posted to python-dev.


Acknowledgements
================

This document could not be completed without valuable input,
encouragement and advice from Jim Baker, Jeremy Siek, Michael Matson
Vitousek, Andrey Vlasovskikh, Radomir Dopieralski, Peter Ludemann,
and the BDFL-Delegate, Mark Shannon.

Influences include existing languages, libraries and frameworks
mentioned in PEP 482.  Many thanks to their creators, in alphabetical
order: Stefan Behnel, William Edwards, Greg Ewing, Larry Hastings,
Anders Hejlsberg, Alok Menghrajani, Travis E. Oliphant, Joe Pamer,
Raoul-Gabriel Urma, and Julien Verlaguet.


References
==========

.. [mypy]
   http://mypy-lang.org

.. [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

.. [github]
   https://github.com/ambv/typehinting

.. [issues]
   https://github.com/ambv/typehinting/issues

.. [peps]
   https://hg.python.org/peps/file/tip/pep-0484.txt


Copyright
=========

This document has been placed in the public domain.



..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   coding: utf-8
   End:


--
--Guido van Rossum (python.org/~guido)
<div><div dir="ltr">
<div>
<div>
<div>The PEP 484 authors (Jukka, &#321;ukasz and I) have a new draft ready. This time we're posting to python-dev.<br><br>While we don't have all details totally sorted out, it's a lot closer. We have a BDFL-Delegate (Mark Shannon), and we've worked out a variety of issues at PyCon. Our hope remains that we'll get the typing.py module added to CPython 3.5 before beta 1 goes out (May 24).<br><br>Below is a list of key changes since the draft posted to python-dev on March 20 (for more details see <a href="https://github.com/ambv/typehinting/commits/master/pep-0484.txt">https://github.com/ambv/typehinting/commits/master/pep-0484.txt</a>) and the full text of the PEP. The new draft is also in the peps repo (<a href="https://hg.python.org/peps/file/tip/pep-0484.txt">https://hg.python.org/peps/file/tip/pep-0484.txt</a>) and will soon be on <a href="http://python.org">python.org</a> (<a href="https://www.python.org/dev/peps/pep-0484/">https://www.python.org/dev/peps/pep-0484/</a> -- give it 10-30 minutes).<br><br>As always, between draft postings the PEP text is updated frequently by the authors in a dedicated GitHub repo (<a href="https://github.com/ambv/typehinting">https://github.com/ambv/typehinting</a>), and many detailed discussions are found in the issue tracker there (<a href="https://github.com/ambv/typehinting/issues">https://github.com/ambv/typehinting/issues</a>). The typing.py module also lives in that repo (<a href="https://github.com/ambv/typehinting/tree/master/prototyping">https://github.com/ambv/typehinting/tree/master/prototyping</a>).<br><br>
</div>Key changes since 20-Mar-2015 draft<br>--------------------------------------------------<br><br>Generics:<br>- Properly specify generics and type variables.<br>- Add covariant/contravariant flags to TypeVar().<br><br>Type specifications:<br>- Define type aliases.<br>- Kill Undefined.<br>- Better specification of `# type:` comments.<br><br>Specifics:<br>- Add Generator (a generic type describing generator objects)<br>- Document get_type_hints().<br><br>Stubs:<br>- Only .pyi is a valid extension for stub files.<br>- Add discussion of third-party stubs (see issue #84).<br><br>Process:<br>- Mark Shannon is now BDFL-Delegate.<br>- Add section on PEP Development Process, with github links.<br><br>Other:<br>- Mention the __future__ proposal (a separate PEP to be developed).<br>- Lots of editing; remove some sections that didn't specify anything.<br><br>
</div>Full PEP text<br>------------------<br><br>
</div>PEP: 484<br>Title: Type Hints<br>Version: $Revision$<br>Last-Modified: $Date$<br>Author: Guido van Rossum &lt;<a href="mailto:guido <at> python.org">guido <at> python.org</a>&gt;, Jukka Lehtosalo &lt;<a href="mailto:jukka.lehtosalo <at> iki.fi">jukka.lehtosalo <at> iki.fi</a>&gt;, &#321;ukasz Langa &lt;<a href="mailto:lukasz <at> langa.pl">lukasz <at> langa.pl</a>&gt;<br>BDFL-delegate: Mark Shannon<br>Discussions-To: Python-Dev &lt;<a href="mailto:python-dev <at> python.org">python-dev <at> python.org</a>&gt;<br>Status: Draft<br>Type: Standards Track<br>Content-Type: text/x-rst<br>Created: 29-Sep-2014<br>Post-History: 16-Jan-2015,20-Mar-2015,17-Apr-2015<br>Resolution:<br><br><br>Abstract<br>========<br><br>This PEP introduces a standard syntax for type hints using annotations<br>(PEP 3107) on function definitions.&nbsp; For example, here is a simple<br>function whose argument and return type are declared in the<br>annotations::<br><br>&nbsp; def greeting(name: str) -&gt; str:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return 'Hello ' + name<br><br>While these annotations are available at runtime through the usual<br>``__annotations__`` attribute, *no type checking happens at runtime*.<br>Instead, the proposal assumes the existence of a separate off-line<br>type checker which users can run over their source code voluntarily.<br>Essentially, such a type checker acts as a very powerful linter.<br><br>The proposal is strongly inspired by mypy [mypy]_.&nbsp; For example, the<br>type "sequence of integers" can be written as ``Sequence[int]``.&nbsp; The<br>square brackets mean that no new syntax needs to be added to the<br>language.&nbsp; The example here uses a custom class ``Sequence``, imported<br>from a pure-Python module ``typing``.&nbsp; The ``Sequence[int]``<br>notation works by implementing ``__getitem__()`` in the metaclass.<br><br>The type system supports unions, generic types, and a special type<br>named ``Any`` which is consistent with (i.e. assignable to and from) all<br>types.&nbsp; This latter feature is taken from the idea of gradual typing.<br>Gradual typing and the full type system are explained in PEP 483.<br><br>Other approaches from which we have borrowed or to which ours can be<br>compared and contrasted are described in PEP 482.<br><br><br>Rationale and Goals<br>===================<br><br>PEP 3107 added support for arbitrary annotations on parts of a function<br>definition.&nbsp; Although no meaning was assigned to annotations then, there<br>has always been an implicit goal to use them for type hinting, which is<br>listed as the first possible use case in said PEP.<br><br>This PEP aims to provide a standard syntax for type annotations, opening<br>up Python code to easier static analysis and refactoring, potential<br>runtime type checking, and performance optimizations utilizing type<br>information.<br><br>Of these goals, static analysis is the most important.&nbsp; This includes<br>support for off-line type checkers such as mypy, as well as providing<br>a standard notation that can be used by IDEs for code completion and<br>refactoring.<br><br>Non-goals<br>---------<br><br>While the proposed typing module will contain some building blocks for<br>runtime type checking -- in particular a useful ``isinstance()``<br>implementation -- third party packages would have to be developed to<br>implement specific runtime type checking functionality, for example<br>using decorators or metaclasses.&nbsp; Using type hints for performance<br>optimizations is left as an exercise for the reader.<br><br>It should also be emphasized that Python will remain a dynamically<br>typed language, and the authors have no desire to ever make type hints<br>mandatory, even by convention.<br><br><br>What is checked?<br>================<br><br>Any function (or method -- for brevity we won't be repeating this)<br>with at least one argument or return annotation is checked, unless<br>type checking is disabled by the `` <at> no_type_check`` decorator or a<br>``# type: ignore`` comment (see below).<br><br>A checked function should have annotations for all its arguments and<br>its return type, with the exception that the ``self`` argument of a<br>method should not be annotated; it is assumed to have the type of the<br>containing class.&nbsp; Notably, the return type of ``__init__`` should be<br>annotated with ``-&gt; None``.<br><br>The body of a checked function is checked for consistency with the<br>given annotations.&nbsp; The annotations are also used to check correctness<br>of calls appearing in other checked functions.<br><br>Functions without any annotations (or whose checking is disabled) are<br>assumed to have type ``Any`` when they are referenced in checked<br>functions, and this should completely silence complaints from the<br>checker regarding those references (although a checker may still<br>request that a type be specified using a cast or a ``# type:`` comment<br>if a more specific type than ``Any`` is needed for analysis of<br>subsequent code).<br><br>A type checker should understand decorators; this may require<br>annotations on decorator definitions.&nbsp; In particular, a type checker<br>should understand the built-in decorators `` <at> property``,<br>`` <at> staticmethod`` and `` <at> classmethod``.&nbsp; The first argument of a class<br>method should not be annotated; it is assumed to be a subclass of the<br>defining class.<br><br><br>Type Definition Syntax<br>======================<br><br>The syntax leverages PEP 3107-style annotations with a number of<br>extensions described in sections below.&nbsp; In its basic form, type<br>hinting is used by filling function annotation slots with classes::<br><br>&nbsp; def greeting(name: str) -&gt; str:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return 'Hello ' + name<br><br>This states that the expected type of the ``name`` argument is<br>``str``.&nbsp; Analogically, the expected return type is ``str``.<br><br>Expressions whose type is a subtype of a specific argument type are<br>also accepted for that argument.<br><br><br>Acceptable type hints<br>---------------------<br><br>Type hints may be built-in classes (including those defined in<br>standard library or third-party extension modules), abstract base<br>classes, types available in the ``types`` module, and user-defined<br>classes (including those defined in the standard library or<br>third-party modules).&nbsp; Annotations for built-in classes (and other<br>classes at the discretion of the developer) may be placed in stub<br>files (see below).<br><br>Annotations must be valid expressions that evaluate without raising<br>exceptions at the time the function is defined (but see below for<br>forward references).<br><br>The needs of static analysis require that annotations must be simple<br>enough to be interpreted by static analysis tools.&nbsp; In particular,<br>dynamically computed types are not acceptable.&nbsp; (This is an<br>intentionally somewhat vague requirement, specific inclusions and<br>exclusions may be added to future versions of this PEP as warranted by<br>the discussion.)<br><br>In addition to the above, the following special constructs defined<br>below may be used: ``None``, ``Any``, ``Union``, ``Tuple``,<br>``Callable``, all ABCs and stand-ins for concrete classes exported<br>from ``typing`` (e.g. ``Sequence`` and ``Dict``), type variables, and<br>type aliases.<br><br>All newly introducedw names used to support features described in<br>following sections (such as ``Any`` and ``Union``) are available in<br>the ``typing`` module.<br><br><br>Using None<br>----------<br><br>When used in a type hint, the expression ``None`` is considered<br>equivalent to ``type(None)``.<br><br><br>Type aliases<br>------------<br><br>Type aliases are defined by simple variable assignments::<br><br>&nbsp; Url = str<br><br>&nbsp; def retry(url: Url, retry_count: int) -&gt; None: ...<br><br>Note that we recommend capitalizing alias names, since they represent<br>user-defined types, which (like user-defined classes) are typically<br>spelled that way.<br><br>Type aliases may be as complex as type hints in annotations --<br>anything that is acceptable as a type hint is acceptable in a type<br>alias::<br><br>&nbsp;&nbsp;&nbsp; from typing import TypeVar, Iterable, Tuple<br><br>&nbsp;&nbsp;&nbsp; T = TypeVar('T', int, float, complex)<br>&nbsp;&nbsp;&nbsp; Vector = Iterable[Tuple[T, T]]<br><br>&nbsp;&nbsp;&nbsp; def inproduct(v: Vector) -&gt; T:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return sum(x*y for x, y in v)<br><br>This is equivalent to::<br><br>&nbsp;&nbsp;&nbsp; from typing import TypeVar, Iterable, Tuple<br><br>&nbsp;&nbsp;&nbsp; T = TypeVar('T', int, float, complex)<br><br>&nbsp;&nbsp;&nbsp; def inproduct(v: Iterable[Tuple[T, T]]) -&gt; T:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return sum(x*y for x, y in v)<br><br><br>Callable<br>--------<br><br>Frameworks expecting callback functions of specific signatures might be<br>type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``.<br>Examples::<br><br>&nbsp; from typing import Callable<br><br>&nbsp; def feeder(get_next_item: Callable[[], str]) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # Body<br><br>&nbsp; def async_query(on_success: Callable[[int], None],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; on_error: Callable[[int, Exception], None]) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # Body<br><br>It is possible to declare the return type of a callable without<br>specifying the call signature by substituting a literal ellipsis<br>(three dots) for the list of arguments::<br><br>&nbsp; def partial(func: Callable[..., str], *args) -&gt; Callable[..., str]:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # Body<br><br>Note that there are no square brackets around the ellipsis.&nbsp; The<br>arguments of the callback are completely unconstrained in this case<br>(and keyword arguments are acceptable).<br><br>Since using callbacks with keyword arguments is not perceived as a<br>common use case, there is currently no support for specifying keyword<br>arguments with ``Callable``.&nbsp; Similarly, there is no support for<br>specifying callback signatures with a variable number of argument of a<br>specific type.<br><br><br>Generics<br>--------<br><br>Since type information about objects kept in containers cannot be<br>statically inferred in a generic way, abstract base classes have been<br>extended to support subscription to denote expected types for container<br>elements.&nbsp; Example::<br><br>&nbsp; from typing import Mapping, Set<br><br>&nbsp; def notify_by_email(employees: Set[Employee], overrides: Mapping[str, str]) -&gt; None: ...<br><br>Generics can be parametrized by using a new factory available in<br>``typing`` called ``TypeVar``.&nbsp; Example::<br><br>&nbsp; from typing import Sequence, TypeVar<br><br>&nbsp; T = TypeVar('T')&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # Declare type variable<br><br>&nbsp; def first(l: Sequence[T]) -&gt; T:&nbsp;&nbsp; # Generic function<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return l[0]<br><br>In this case the contract is that the returned value is consistent with<br>the elements held by the collection.<br><br>``TypeVar`` supports constraining parametric types to a fixed set of<br>possible types.&nbsp; For example, we can define a type variable that ranges<br>over just ``str`` and ``bytes``.&nbsp; By default, a type variable ranges<br>over all possible types.&nbsp; Example of constraining a type variable::<br><br>&nbsp; from typing import TypeVar<br><br>&nbsp; AnyStr = TypeVar('AnyStr', str, bytes)<br><br>&nbsp; def concat(x: AnyStr, y: AnyStr) -&gt; AnyStr:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return x + y<br><br>The function ``concat`` can be called with either two ``str`` arguments<br>or two ``bytes`` arguments, but not with a mix of ``str`` and ``bytes``<br>arguments.<br><br>Note that subtypes of types constrained by a type variable are treated<br>as their respective explicitly listed base types in the context of the<br>type variable.&nbsp; Consider this example::<br><br>&nbsp; class MyStr(str): ...<br><br>&nbsp; x = concat(MyStr('apple'), MyStr('pie'))<br><br>The call is valid but the type variable ``AnyStr`` will be set to<br>``str`` and not ``MyStr``. In effect, the inferred type of the return<br>value assigned to ``x`` will also be ``str``.<br><br>Additionally, ``Any`` is a valid value for every type variable.<br>Consider the following::<br><br>&nbsp; def count_truthy(elements: List[Any]) -&gt; int:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return sum(1 for elem in elements if element)<br><br>This is equivalent to omitting the generic notation and just saying<br>``elements: List``.<br><br><br>User-defined generic types<br>--------------------------<br><br>You can include a ``Generic`` base class to define a user-defined class<br>as generic.&nbsp; Example::<br><br>&nbsp; from typing import TypeVar, Generic<br><br>&nbsp; T = TypeVar('T')<br><br>&nbsp; class LoggedVar(Generic[T]):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def __init__(self, value: T, name: str, logger: Logger) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://self.name">self.name</a> = name<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.logger = logger<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.value = value<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def set(self, new: T) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.log('Set ' + repr(self.value))<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.value = new<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def get(self) -&gt; T:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.log('Get ' + repr(self.value))<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return self.value<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def log(self, message: str) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <a href="http://self.logger.info">self.logger.info</a>('{}: {}'.format(<a href="http://self.name">self.name</a> message))<br><br>``Generic[T]`` as a base class defines that the class ``LoggedVar``<br>takes a single type parameter ``T``. This also makes ``T`` valid as<br>a type within the class body.<br><br>The ``Generic`` base class uses a metaclass that defines ``__getitem__``<br>so that ``LoggedVar[t]`` is valid as a type::<br><br>&nbsp; from typing import Iterable<br><br>&nbsp; def zero_all_vars(vars: Iterable[LoggedVar[int]]) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; for var in vars:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var.set(0)<br><br>A generic type can have any number of type variables, and type variables<br>may be constrained. This is valid::<br><br>&nbsp; from typing import TypeVar, Generic<br>&nbsp; ...<br><br>&nbsp; T = TypeVar('T')<br>&nbsp; S = TypeVar('S')<br><br>&nbsp; class Pair(Generic[T, S]):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>Each type variable argument to ``Generic`` must be distinct. This is<br>thus invalid::<br><br>&nbsp; from typing import TypeVar, Generic<br>&nbsp; ...<br><br>&nbsp; T = TypeVar('T')<br><br>&nbsp; class Pair(Generic[T, T]):&nbsp;&nbsp; # INVALID<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>You can use multiple inheritance with ``Generic``::<br><br>&nbsp; from typing import TypeVar, Generic, Sized<br><br>&nbsp; T = TypeVar('T')<br><br>&nbsp; class LinkedList(Sized, Generic[T]):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br><br>Arbitrary generic types as base classes<br>---------------------------------------<br><br>``Generic[T]`` is only valid as a base class -- it's not a proper type.<br>However, user-defined generic types such as ``LinkedList[T]`` from the<br>above example and built-in generic types and ABCs such as ``List[T]``<br>and ``Iterable[T]`` are valid both as types and as base classes. For<br>example, we can define a subclass of ``Dict`` that specializes type<br>arguments::<br><br>&nbsp; from typing import Dict, List, Optional<br><br>&nbsp; class Node:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>&nbsp; class SymbolTable(Dict[str, List[Node]]):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def push(self, name: str, node: Node) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.setdefault(name, []).append(node)<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def pop(self, name: str) -&gt; Node:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return self[name].pop()<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def lookup(self, name: str) -&gt; Optional[Node]:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; nodes = self.get(name)<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if nodes:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return nodes[-1]<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return None<br><br>``SymbolTable`` is a subclass of ``dict`` and a subtype of ``Dict[str,<br>List[Node]]``.<br><br>If a generic base class has a type variable as a type argument, this<br>makes the defined class generic. For example, we can define a generic<br>``LinkedList`` class that is iterable and a container::<br><br>&nbsp; from typing import TypeVar, Iterable, Container<br><br>&nbsp; T = TypeVar('T')<br><br>&nbsp; class LinkedList(Iterable[T], Container[T]):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>Now ``LinkedList[int]`` is a valid type. Note that we can use ``T``<br>multiple times in the base class list, as long as we don't use the<br>same type variable ``T`` multiple times within ``Generic[...]``.<br><br><br>Abstract generic types<br>----------------------<br><br>The metaclass used by ``Generic`` is a subclass of ``abc.ABCMeta``.<br>A generic class can be an ABC by including abstract methods<br>or properties, and generic classes can also have ABCs as base<br>classes without a metaclass conflict.<br><br><br>Forward references<br>------------------<br><br>When a type hint contains names that have not been defined yet, that<br>definition may be expressed as a string literal, to be resolved later.<br><br>A situation where this occurs commonly is the definition of a<br>container class, where the class being defined occurs in the signature<br>of some of the methods.&nbsp; For example, the following code (the start of<br>a simple binary tree implementation) does not work::<br><br>&nbsp; class Tree:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def __init__(self, left: Tree, right: Tree):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.left = left<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.right = right<br><br>To address this, we write::<br><br>&nbsp; class Tree:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def __init__(self, left: 'Tree', right: 'Tree'):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.left = left<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.right = right<br><br>The string literal should contain a valid Python expression (i.e.,<br>``compile(lit, '', 'expr')`` should be a valid code object) and it<br>should evaluate without errors once the module has been fully loaded.<br>The local and global namespace in which it is evaluated should be the<br>same namespaces in which default arguments to the same function would<br>be evaluated.<br><br>Moreover, the expression should be parseable as a valid type hint, i.e.,<br>it is constrained by the rules from the section `Acceptable type hints`_<br>above.<br><br>It is allowable to use string literals as *part* of a type hint, for<br>example::<br><br>&nbsp;&nbsp;&nbsp; class Tree:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def leaves(self) -&gt; List['Tree']:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br><br>Union types<br>-----------<br><br>Since accepting a small, limited set of expected types for a single<br>argument is common, there is a new special factory called ``Union``.<br>Example::<br><br>&nbsp; from typing import Union<br><br>&nbsp; def handle_employees(e: Union[Employee, Sequence[Employee]]) -&gt; None:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if isinstance(e, Employee):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; e = [e]<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>A type factored by ``Union[T1, T2, ...]`` responds ``True`` to<br>``issubclass`` checks for ``T1`` and any of its subclasses, ``T2`` and<br>any of its subclasses, and so on.<br><br>One common case of union types are *optional* types.&nbsp; By default,<br>``None`` is an invalid value for any type, unless a default value of<br>``None`` has been provided in the function definition.&nbsp; Examples::<br><br>&nbsp; def handle_employee(e: Union[Employee, None]) -&gt; None: ...<br><br>As a shorthand for ``Union[T1, None]`` you can write ``Optional[T1]``;<br>for example, the above is equivalent to::<br><br>&nbsp; from typing import Optional<br><br>&nbsp; def handle_employee(e: Optional[Employee]) -&gt; None: ...<br><br>An optional type is also automatically assumed when the default value is<br>``None``, for example::<br><br>&nbsp; def handle_employee(e: Employee = None): ...<br><br>This is equivalent to::<br><br>&nbsp; def handle_employee(e: Optional[Employee] = None) -&gt; None: ...<br><br>The ``Any`` type<br>----------------<br><br>A special kind of type is ``Any``.&nbsp; Every class is a subclass of<br>``Any``.&nbsp; This is also true for the builtin class ``object``.<br>However, to the static type checker these are completely different.<br><br>When the type of a value is ``object``, the type checker will reject<br>almost all operations on it, and assigning it to a variable (or using<br>it as a return value) of a more specialized type is a type error.&nbsp; On<br>the other hand, when a value has type ``Any``, the type checker will<br>allow all operations on it, and a value of type ``Any`` can be assigned<br>to a variable (or used as a return value) of a more constrained type.<br><br><br>Predefined constants<br>--------------------<br><br>Some predefined Boolean constants are defined in the ``typing``<br>module to enable platform-specific type definitions and such::<br><br>&nbsp; from typing import PY2, PY3, WINDOWS, POSIX<br><br>&nbsp; if PY2:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; text = unicode<br>&nbsp; else:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; text = str<br><br>&nbsp; def f() -&gt; text: ...<br><br>&nbsp; if WINDOWS:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; loop = ProactorEventLoop<br>&nbsp; else:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; loop = UnixSelectorEventLoop<br><br>It is up to the type checker implementation to define their values, as<br>long as ``PY2 == not PY3`` and ``WINDOWS == not POSIX``.&nbsp; When the<br>program is being executed these always reflect the current platform,<br>and this is also the suggested default when the program is being<br>type-checked.<br><br><br>Compatibility with other uses of function annotations<br>=====================================================<br><br>A number of existing or potential use cases for function annotations<br>exist, which are incompatible with type hinting.&nbsp; These may confuse<br>a static type checker.&nbsp; However, since type hinting annotations have no<br>runtime behavior (other than evaluation of the annotation expression and<br>storing annotations in the ``__annotations__`` attribute of the function<br>object), this does not make the program incorrect -- it just may cause<br>a type checker to emit spurious warnings or errors.<br><br>To mark portions of the program that should not be covered by type<br>hinting, you can use one or more of the following:<br><br>* a ``# type: ignore`` comment;<br><br>* a `` <at> no_type_check`` decorator on a class or function;<br><br>* a custom class or function decorator marked with<br>&nbsp; `` <at> no_type_check_decorator``.<br><br>For more details see later sections.<br><br>In order for maximal compatibility with offline type checking it may<br>eventually be a good idea to change interfaces that rely on annotations<br>to switch to a different mechanism, for example a decorator.&nbsp; In Python<br>3.5 there is no pressure to do this, however.&nbsp; See also the longer<br>discussion under `Rejected alternatives`_ below.<br><br><br>Type comments<br>=============<br><br>No first-class syntax support for explicitly marking variables as being<br>of a specific type is added by this PEP.&nbsp; To help with type inference in<br>complex cases, a comment of the following format may be used::<br><br>&nbsp; x = []&nbsp;&nbsp; # type: List[Employee]<br>&nbsp; x, y, z = [], [], []&nbsp; # type: List[int], List[int], List[str]<br>&nbsp; x, y, z = [], [], []&nbsp; # type: (List[int], List[int], List[str])<br>&nbsp; x = [<br>&nbsp;&nbsp;&nbsp;&nbsp; 1,<br>&nbsp;&nbsp;&nbsp;&nbsp; 2,<br>&nbsp; ]&nbsp; # type: List[int]<br><br>Type comments should be put on the last line of the statement that<br>contains the variable definition. They can also be placed on<br>``with`` statements and ``for`` statements, right after the colon.<br><br>Examples of type comments on ``with`` and ``for`` statements::<br><br>&nbsp; with frobnicate() as foo:&nbsp; # type: int<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # Here foo is an int<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>&nbsp; for x, y in points:&nbsp; # type: float, float<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # Here x and y are floats<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ...<br><br>The ``# type: ignore`` comment should be put on the line that the<br>error refers to::<br><br>&nbsp; import http.client<br>&nbsp; errors = {<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 'not_found': http.client.NOT_FOUND&nbsp; # type: ignore<br>&nbsp; }<br><br>A ``# type: ignore`` comment on a line by itself disables all type<br>checking for the rest of the file.<br><br>If type hinting proves useful in general, a syntax for typing variables<br>may be provided in a future Python version.<br><br>Casts<br>=====<br><br>Occasionally the type checker may need a different kind of hint: the<br>programmer may know that an expression is of a more constrained type<br>than the type checker infers.&nbsp; For example::<br><br>&nbsp; from typing import List, cast<br><br>&nbsp; def find_first_str(a: List[object]) -&gt; str:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; index = next(i for i, x in enumerate(a) if isinstance(x, str))<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # We only get here if there's at least one string in a<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return cast(str, a[index])<br><br>The type checker infers the type ``object`` for ``a[index]``, but we<br>know that (if the code gets to that point) it must be a string.&nbsp; The<br>``cast(t, x)`` call tells the type checker that we are confident that<br>the type of ``x`` is ``t``.&nbsp; At runtime a cast always returns the<br>expression unchanged -- it does not check the type, and it does not<br>convert or coerce the value.<br><br>Casts differ from type comments (see the previous section).&nbsp; When using<br>a type comment, the type checker should still verify that the inferred<br>type is consistent with the stated type.&nbsp; When using a cast, the type<br>checker should blindly believe the programmer.&nbsp; Also, casts can be used<br>in expressions, while type comments only apply to assignments.<br><br><br>Stub Files<br>==========<br><br>Stub files are files containing type hints that are only for use by<br>the type checker, not at runtime.&nbsp; There are several use cases for<br>stub files:<br><br>* Extension modules<br><br>* Third-party modules whose authors have not yet added type hints<br><br>* Standard library modules for which type hints have not yet been<br>&nbsp; written<br><br>* Modules that must be compatible with Python 2 and 3<br><br>* Modules that use annotations for other purposes<br><br>Stub files have the same syntax as regular Python modules.&nbsp; There is one<br>feature of the ``typing`` module that may only be used in stub files:<br>the `` <at> overload`` decorator described below.<br><br>The type checker should only check function signatures in stub files;<br>function bodies in stub files should just be a single ``pass``<br>statement.<br><br>The type checker should have a configurable search path for stub files.<br>If a stub file is found the type checker should not read the<br>corresponding "real" module.<br><br>While stub files are syntactically valid Python modules, they use the<br>``.pyi`` extension to make it possible to maintain stub files in the<br>same directory as the corresponding real module.&nbsp; This also reinforces<br>the notion that no runtime behavior should be expected of stub files.<br><br>Function overloading<br>--------------------<br><br>The `` <at> overload`` decorator allows describing functions that support<br>multiple different combinations of argument types.&nbsp; This pattern is<br>used frequently in builtin modules and types.&nbsp; For example, the<br>``__getitem__()`` method of the ``bytes`` type can be described as<br>follows::<br><br>&nbsp; from typing import overload<br><br>&nbsp; class bytes:<br>&nbsp;&nbsp;&nbsp; ...<br>&nbsp;&nbsp;&nbsp;  <at> overload<br>&nbsp;&nbsp;&nbsp; def __getitem__(self, i: int) -&gt; int: pass<br>&nbsp;&nbsp;&nbsp;  <at> overload<br>&nbsp;&nbsp;&nbsp; def __getitem__(self, s: slice) -&gt; bytes: pass<br><br>This description is more precise than would be possible using unions<br>(which cannot express the relationship between the argument and return<br>types)::<br><br>&nbsp; from typing import Union<br>&nbsp; class bytes:<br>&nbsp;&nbsp;&nbsp; ...<br>&nbsp;&nbsp;&nbsp; def __getitem__(self, a: Union[int, slice]) -&gt; Union[int, bytes]: pass<br><br>Another example where `` <at> overload`` comes in handy is the type of the<br>builtin ``map()`` function, which takes a different number of<br>arguments depending on the type of the callable::<br><br>&nbsp; from typing import Callable, Iterable, Iterator, Tuple, TypeVar, overload<br><br>&nbsp; T1 = TypeVar('T1')<br>&nbsp; T2 = TypeVar('T2)<br>&nbsp; S = TypeVar('S')<br><br>&nbsp;  <at> overload<br>&nbsp; def map(func: Callable[[T1], S], iter1: Iterable[T1]) -&gt; Iterator[S]: pass<br>&nbsp;  <at> overload<br>&nbsp; def map(func: Callable[[T1, T2], S],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; iter1: Iterable[T1], iter2: Iterable[T2]) -&gt; Iterator[S]: pass<br>&nbsp; # ... and we could add more items to support more than two iterables<br><br>Note that we could also easily add items to support ``map(None, ...)``::<br><br>&nbsp;  <at> overload<br>&nbsp; def map(func: None, iter1: Iterable[T1]) -&gt; Iterable[T1]: pass<br>&nbsp;  <at> overload<br>&nbsp; def map(func: None,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; iter1: Iterable[T1],<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; iter2: Iterable[T2]) -&gt; Iterable[Tuple[T1, T2]]: pass<br><br>The `` <at> overload`` decorator may only be used in stub files.&nbsp; While it<br>would be possible to provide a multiple dispatch implementation using<br>this syntax, its implementation would require using<br>``sys._getframe()``, which is frowned upon.&nbsp; Also, designing and<br>implementing an efficient multiple dispatch mechanism is hard, which<br>is why previous attempts were abandoned in favor of<br>``functools.singledispatch()``.&nbsp; (See PEP 443, especially its section<br>"Alternative approaches".)&nbsp; In the future we may come up with a<br>satisfactory multiple dispatch design, but we don't want such a design<br>to be constrained by the overloading syntax defined for type hints in<br>stub files.<br><br>Storing and distributing stub files<br>-----------------------------------<br><br>The easiest form of stub file storage and distribution is to put them<br>alongside Python modules in the same directory.&nbsp; This makes them easy to<br>find by both programmers and the tools.&nbsp; However, since package<br>maintainers are free not to add type hinting to their packages,<br>third-party stubs installable by ``pip`` from PyPI are also supported.<br>In this case we have to consider three issues: naming, versioning,<br>installation path.<br><br>This PEP does not provide a recommendation on a naming scheme that<br>should be used for third-party stub file packages.&nbsp; Discoverability will<br>hopefully be based on package popularity, like with Django packages for<br>example.<br><br>Third-party stubs have to be versioned using the lowest version of the<br>source package that is compatible.&nbsp; Example: FooPackage has versions<br>1.0, 1.1, 1.2, 1.3, 2.0, 2.1, 2.2.&nbsp; There are API changes in versions<br>1.1, 2.0 and 2.2.&nbsp; The stub file package maintainer is free to release<br>stubs for all versions but at least 1.0, 1.1, 2.0 and 2.2 are needed<br>to enable the end user type check all versions.&nbsp; This is because the<br>user knows that the closest *lower or equal* version of stubs is<br>compatible.&nbsp; In the provided example, for FooPackage 1.3 the user would<br>choose stubs version 1.1.<br><br>Note that if the user decides to use the "latest" available source<br>package, using the "latest" stub files should generally also work if<br>they're updated often.<br><br>Third-party stub packages can use any location for stub storage.&nbsp; The<br>type checker will search for them using PYTHONPATH.&nbsp; A default fallback<br>directory that is always checked is ``shared/typehints/python3.5/`` (or<br>3.6, etc.).&nbsp; Since there can only be one package installed for a given<br>Python version per environment, no additional versioning is performed<br>under that directory (just like bare directory installs by ``pip`` in<br>site-packages).&nbsp; Stub file package authors might use the following<br>snippet in ``setup.py``::<br><br>&nbsp; ...<br>&nbsp; data_files=[<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 'shared/typehints/python{}.{}'.format(*sys.version_info[:2]),<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pathlib.Path(SRC_PATH).glob('**/*.pyi'),<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ),<br>&nbsp; ],<br>&nbsp; ...<br><br><br>Exceptions<br>==========<br><br>No syntax for listing explicitly raised exceptions is proposed.<br>Currently the only known use case for this feature is documentational,<br>in which case the recommendation is to put this information in a<br>docstring.<br><br><br>The ``typing`` Module<br>=====================<br><br>To open the usage of static type checking to Python 3.5 as well as older<br>versions, a uniform namespace is required.&nbsp; For this purpose, a new<br>module in the standard library is introduced called ``typing``.&nbsp; It<br>holds a set of classes representing builtin types with generics, namely:<br><br>* Dict, used as ``Dict[key_type, value_type]``<br><br>* List, used as ``List[element_type]``<br><br>* Set, used as ``Set[element_type]``. See remark for ``AbstractSet``<br>&nbsp; below.<br><br>* FrozenSet, used as ``FrozenSet[element_type]``<br><br>* Tuple, used by listing the element types, for example<br>&nbsp; ``Tuple[int, int, str]``.<br>&nbsp; Arbitrary-length homogeneous tuples can be expressed<br>&nbsp; using one type and ellipsis, for example ``Tuple[int, ...]``.<br>&nbsp; (The ``...`` here are part of the syntax.)<br><br>* NamedTuple, used as<br>&nbsp; ``NamedTuple(type_name, [(field_name, field_type), ...])``<br>&nbsp; and equivalent to<br>&nbsp; ``collections.namedtuple(type_name, [field_name, ...])``.<br><br>The generic versions of concrete collection types (``Dict``, ``List``,<br>``Set``, ``FrozenSet``, and homogeneous arbitrary-length ``Tuple``)<br>are mainly useful for annotating return values.&nbsp; For arguments, prefer<br>the abstract collection types defined below, e.g.&nbsp; ``Mapping``,<br>``Sequence`` or ``AbstractSet``.<br><br>The ``typing`` module defines the ``Generator`` type for return values<br>of generator functions. It is a subtype of ``Iterable`` and it has<br>additional type variables for the type accepted by the ``send()``<br>method and the return type of the generator:<br><br>* Generator, used as ``Generator[yield_type, send_type, return_type]``<br><br>It also introduces factories and helper members needed to express<br>generics and union types:<br><br>* Any, used as ``def get(key: str) -&gt; Any: ...``<br><br>* Union, used as ``Union[Type1, Type2, Type3]``<br><br>* TypeVar, used as ``X = TypeVar('X', Type1, Type2, Type3)`` or simply<br>&nbsp; ``Y = TypeVar('Y')``<br><br>* Callable, used as ``Callable[[Arg1Type, Arg2Type], ReturnType]``<br><br>* AnyStr, defined as ``TypeVar('AnyStr', str, bytes)``<br><br>All abstract base classes available in ``collections.abc`` are<br>importable from the ``typing`` module, with added generics support:<br><br>* ByteString<br><br>* Callable (see above)<br><br>* Container<br><br>* Hashable (not generic, but present for completeness)<br><br>* ItemsView<br><br>* Iterable<br><br>* Iterator<br><br>* KeysView<br><br>* Mapping<br><br>* MappingView<br><br>* MutableMapping<br><br>* MutableSequence<br><br>* MutableSet<br><br>* Sequence<br><br>* Set, renamed to ``AbstractSet``. This name change was required<br>&nbsp; because ``Set`` in the ``typing`` module means ``set()`` with<br>&nbsp; generics.<br><br>* Sized (not generic, but present for completeness)<br><br>* ValuesView<br><br>A few one-off types are defined that test for single special methods<br>(similar to ``Hashable`` or ``Sized``):<br><br>* Reversible, to test for ``__reversed__``<br><br>* SupportsAbs, to test for ``__abs__``<br><br>* SupportsFloat, to test for ``__float__``<br><br>* SupportsInt, to test for ``__int__``<br><br>* SupportsRound, to test for ``__round__``<br><br>The library includes literals for platform-specific type hinting:<br><br>* PY2<br><br>* PY3, equivalent to ``not PY2``<br><br>* WINDOWS<br><br>* POSIX, equivalent to ``not WINDOWS``<br><br>The following conveniece functions and decorators are exported:<br><br>* cast, described earlier<br><br>* no_type_check, a decorator to disable type checking per class or<br>&nbsp; function (see below)<br><br>* no_type_check_decorator, a decorator to create your own decorators<br>&nbsp; with the same meaning as `` <at> no_type_check`` (see below)<br><br>* overload, described earlier<br><br>* get_type_hints, a utility function to retrieve the type hints from a<br>&nbsp; function or method.&nbsp; Given a function or method object, it returns<br>&nbsp; a dict with the same format as ``__annotations__``, but evaluating<br>&nbsp; forward references (which are given as string literals) as expressions<br>&nbsp; in the context of the original function or method definition.<br><br>The following types are available in the ``<a href="http://typing.io">typing.io</a>`` module:<br><br>* IO (generic over ``AnyStr``)<br><br>* BinaryIO (a simple subclass of ``IO[bytes]``)<br><br>* TextIO (a simple subclass of ``IO[str]``)<br><br>The following types are provided by the ``<a href="http://typing.re">typing.re</a>`` module:<br><br>* Match and Pattern, types of ``re.match()`` and ``re.compile()``<br>&nbsp; results (generic over ``AnyStr``)<br><br>As a convenience measure, types from ``<a href="http://typing.io">typing.io</a>`` and ``<a href="http://typing.re">typing.re</a>`` are<br>also available in ``typing`` (quoting Guido, "There's a reason those<br>modules have two-letter names.").<br><br><br>Rejected Alternatives<br>=====================<br><br>During discussion of earlier drafts of this PEP, various objections<br>were raised and alternatives were proposed.&nbsp; We discuss some of these<br>here and explain why we reject them.<br><br>Several main objections were raised.<br><br>Which brackets for generic type parameters?<br>-------------------------------------------<br><br>Most people are familiar with the use of angular brackets<br>(e.g. ``List&lt;int&gt;``) in languages like C++, Java, C# and Swift to<br>express the parametrization of generic types.&nbsp; The problem with these<br>is that they are really hard to parse, especially for a simple-minded<br>parser like Python.&nbsp; In most languages the ambiguities are usually<br>dealy with by only allowing angular brackets in specific syntactic<br>positions, where general expressions aren't allowed.&nbsp; (And also by<br>using very powerful parsing techniques that can backtrack over an<br>arbitrary section of code.)<br><br>But in Python, we'd like type expressions to be (syntactically) the<br>same as other expressions, so that we can use e.g. variable assignment<br>to create type aliases.&nbsp; Consider this simple type expression::<br><br>&nbsp;&nbsp;&nbsp; List&lt;int&gt;<br><br>From the Python parser's perspective, the expression begins with the<br>same four tokens (NAME, LESS, NAME, GREATER) as a chained comparison::<br><br>&nbsp;&nbsp;&nbsp; a &lt; b &gt; c&nbsp; # I.e., (a &lt; b) and (b &gt; c)<br><br>We can even make up an example that could be parsed both ways::<br><br>&nbsp;&nbsp;&nbsp; a &lt; b &gt; [ c ]<br><br>Assuming we had angular brackets in the language, this could be<br>interpreted as either of the following two::<br><br>&nbsp;&nbsp;&nbsp; (a&lt;b&gt;)[c]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # I.e., (a&lt;b&gt;).__getitem__(c)<br>&nbsp;&nbsp;&nbsp; a &lt; b &gt; ([c])&nbsp; # I.e., (a &lt; b) and (b &gt; [c])<br><br>It would surely be possible to come up with a rule to disambiguate<br>such cases, but to most users the rules would feel arbitrary and<br>complex.&nbsp; It would also require us to dramatically change the CPython<br>parser (and every other parser for Python).&nbsp; It should be noted that<br>Python's current parser is intentionally "dumb" -- a simple grammar is<br>easier for users to reason about.<br><br>For all these reasons, square brackets (e.g. ``List[int]``) are (and<br>have long been) the preferred syntax for generic type parameters.<br>They can be implemented by defining the ``__getitem__()`` method on<br>the metaclass, and no new syntax is required at all.&nbsp; This option<br>works in all recent versions of Python (starting with Python 2.2).<br>Python is not alone in this syntactic choice -- generic classes in<br>Scala also use square brackets.<br><br>What about existing uses of annotations?<br>----------------------------------------<br><br>One line of argument points out that PEP 3107 explicitly supports<br>the use of arbitrary expressions in function annotations.&nbsp; The new<br>proposal is then considered incompatible with the specification of PEP<br>3107.<br><br>Our response to this is that, first of all, the current proposal does<br>not introduce any direct incompatibilities, so programs using<br>annotations in Python 3.4 will still work correctly and without<br>prejudice in Python 3.5.<br><br>We do hope that type hints will eventually become the sole use for<br>annotations, but this will require additional discussion and a<br>deprecation period after the initial roll-out of the typing module<br>with Python 3.5.&nbsp; The current PEP will have provisional status (see<br>PEP 411) until Python 3.6 is released.&nbsp; The fastest conceivable scheme<br>would introduce silent deprecation of non-type-hint annotations in<br>3.6, full deprecation in 3.7, and declare type hints as the only<br>allowed use of annotations in Python 3.8.&nbsp; This should give authors of<br>packages that use annotations plenty of time to devise another<br>approach, even if type hints become an overnight success.<br><br>Another possible outcome would be that type hints will eventually<br>become the default meaning for annotations, but that there will always<br>remain an option to disable them.&nbsp; For this purpose the current<br>proposal defines a decorator `` <at> no_type_check`` which disables the<br>default interpretation of annotations as type hints in a given class<br>or function.&nbsp; It also defines a meta-decorator<br>`` <at> no_type_check_decorator`` which can be used to decorate a decorator<br>(!), causing annotations in any function or class decorated with the<br>latter to be ignored by the type checker.<br><br>There are also ``# type: ignore`` comments, and static checkers should<br>support configuration options to disable type checking in selected<br>packages.<br><br>Despite all these options, proposals have been circulated to allow<br>type hints and other forms of annotations to coexist for individual<br>arguments.&nbsp; One proposal suggests that if an annotation for a given<br>argument is a dictionary literal, each key represents a different form<br>of annotation, and the key ``'type'`` would be use for type hints.<br>The problem with this idea and its variants is that the notation<br>becomes very "noisy" and hard to read.&nbsp; Also, in most cases where<br>existing libraries use annotations, there would be little need to<br>combine them with type hints.&nbsp; So the simpler approach of selectively<br>disabling type hints appears sufficient.<br><br>The problem of forward declarations<br>-----------------------------------<br><br>The current proposal is admittedly sub-optimal when type hints must<br>contain forward references.&nbsp; Python requires all names to be defined<br>by the time they are used.&nbsp; Apart from circular imports this is rarely<br>a problem: "use" here means "look up at runtime", and with most<br>"forward" references there is no problem in ensuring that a name is<br>defined before the function using it is called.<br><br>The problem with type hints is that annotations (per PEP 3107, and<br>similar to default values) are evaluated at the time a function is<br>defined, and thus any names used in an annotation must be already<br>defined when the function is being defined.&nbsp; A common scenario is a<br>class definition whose methods need to reference the class itself in<br>their annotations.&nbsp; (More general, it can also occur with mutually<br>recursive classes.)&nbsp; This is natural for container types, for<br>example::<br><br>&nbsp; class Node:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; """Binary tree node."""<br><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def __init__(self, left: Node, right: None):<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.left = left<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.right = right<br><br>As written this will not work, because of the peculiarity in Python<br>that class names become defined once the entire body of the class has<br>been executed.&nbsp; Our solution, which isn't particularly elegant, but<br>gets the job done, is to allow using string literals in annotations.<br>Most of the time you won't have to use this though -- most *uses* of<br>type hints are expected to reference builtin types or types defined in<br>other modules.<br><br>A counterproposal would change the semantics of type hints so they<br>aren't evaluated at runtime at all (after all, type checking happens<br>off-line, so why would type hints need to be evaluated at runtime at<br>all).&nbsp; This of course would run afoul of backwards compatibility,<br>since the Python interpreter doesn't actually know whether a<br>particular annotation is meant to be a type hint or something else.<br><br>A compromise is possible where a ``__future__`` import could enable<br>turning *all* annotations in a given module into string literals, as<br>follows::<br><br>&nbsp; from __future__ import annotations<br><br>&nbsp; class ImSet:<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; def add(self, a: ImSet) -&gt; List[ImSet]: ...<br><br>&nbsp; assert ImSet.add.__annotations__ == {'a': 'ImSet', 'return': 'List[ImSet]'}<br><br>Such a ``__future__`` import statement will be proposed in a separate<br>PEP.<br><br><br>The double colon<br>----------------<br><br>A few creative souls have tried to invent solutions for this problem.<br>For example, it was proposed to use a double colon (``::``) for type<br>hints, solving two problems at once: disambiguating between type hints<br>and other annotations, and changing the semantics to preclude runtime<br>evaluation.&nbsp; There are several things wrong with this idea, however.<br><br>* It's ugly.&nbsp; The single colon in Python has many uses, and all of<br>&nbsp; them look familiar because they resemble the use of the colon in<br>&nbsp; English text.&nbsp; This is a general rule of thumb by which Python<br>&nbsp; abides for most forms of punctuation; the exceptions are typically<br>&nbsp; well known from other programming languages.&nbsp; But this use of ``::``<br>&nbsp; is unheard of in English, and in other languages (e.g. C++) it is<br>&nbsp; used as a scoping operator, which is a very different beast.&nbsp; In<br>&nbsp; contrast, the single colon for type hints reads natural -- and no<br>&nbsp; wonder, since it was carefully designed for this purpose (the idea<br>&nbsp; long predates PEP 3107 [gvr-artima]_).&nbsp; It is also used in the same<br>&nbsp; fashion in other languages from Pascal to Swift.<br><br>* What would you do for return type annotations?<br><br>* It's actually a feature that type hints are evaluated at runtime.<br><br>&nbsp; * Making type hints available at runtime allows runtime type<br>&nbsp;&nbsp;&nbsp; checkers to be built on top of type hints.<br><br>&nbsp; * It catches mistakes even when the type checker is not run.&nbsp; Since<br>&nbsp;&nbsp;&nbsp; it is a separate program, users may choose not to run it (or even<br>&nbsp;&nbsp;&nbsp; install it), but might still want to use type hints as a concise<br>&nbsp;&nbsp;&nbsp; form of documentation.&nbsp; Broken type hints are no use even for<br>&nbsp;&nbsp;&nbsp; documentation.<br><br>* Because it's new syntax, using the double colon for type hints would<br>&nbsp; limit them to code that works with Python 3.5 only.&nbsp; By using<br>&nbsp; existing syntax, the current proposal can easily work for older<br>&nbsp; versions of Python 3.&nbsp; (And in fact mypy supports Python 3.2 and<br>&nbsp; newer.)<br><br>* If type hints become successful we may well decide to add new syntax<br>&nbsp; in the future to declare the type for variables, for example<br>&nbsp; ``var age: int = 42``.&nbsp; If we were to use a double colon for<br>&nbsp; argument type hints, for consistency we'd have to use the same<br>&nbsp; convention for future syntax, perpetuating the ugliness.<br><br>Other forms of new syntax<br>-------------------------<br><br>A few other forms of alternative syntax have been proposed, e.g. the<br>introduction of a ``where`` keyword [roberge]_, and Cobra-inspired<br>``requires`` clauses.&nbsp; But these all share a problem with the double<br>colon: they won't work for earlier versions of Python 3.&nbsp; The same<br>would apply to a new ``__future__`` import.<br><br>Other backwards compatible conventions<br>--------------------------------------<br><br>The ideas put forward include:<br><br>* A decorator, e.g. `` <at> typehints(name=str, returns=str)``.&nbsp; This could<br>&nbsp; work, but it's pretty verbose (an extra line, and the argument names<br>&nbsp; must be repeated), and a far cry in elegance from the PEP 3107<br>&nbsp; notation.<br><br>* Stub files.&nbsp; We do want stub files, but they are primarily useful<br>&nbsp; for adding type hints to existing code that doesn't lend itself to<br>&nbsp; adding type hints, e.g. 3rd party packages, code that needs to<br>&nbsp; support both Python 2 and Python 3, and especially extension<br>&nbsp; modules.&nbsp; For most situations, having the annotations in line with<br>&nbsp; the function definitions makes them much more useful.<br><br>* Docstrings.&nbsp; There is an existing convention for docstrings, based<br>&nbsp; on the Sphinx notation (``:type arg1: description``).&nbsp; This is<br>&nbsp; pretty verbose (an extra line per parameter), and not very elegant.<br>&nbsp; We could also make up something new, but the annotation syntax is<br>&nbsp; hard to beat (because it was designed for this very purpose).<br><br>It's also been proposed to simply wait another release.&nbsp; But what<br>problem would that solve?&nbsp; It would just be procrastination.<br><br><br>PEP Development Process<br>=======================<br><br>A live draft for this PEP lives on GitHub [github]_.&nbsp; There is also an<br>issue tracker [issues]_, where much of the technical discussion takes<br>place.<br><br>The draft on GitHub is updated regularly in small increments.&nbsp; The<br>official PEPS repo [peps_] is (usually) only updated when a new draft<br>is posted to python-dev.<br><br><br>Acknowledgements<br>================<br><br>This document could not be completed without valuable input,<br>encouragement and advice from Jim Baker, Jeremy Siek, Michael Matson<br>Vitousek, Andrey Vlasovskikh, Radomir Dopieralski, Peter Ludemann,<br>and the BDFL-Delegate, Mark Shannon.<br><br>Influences include existing languages, libraries and frameworks<br>mentioned in PEP 482.&nbsp; Many thanks to their creators, in alphabetical<br>order: Stefan Behnel, William Edwards, Greg Ewing, Larry Hastings,<br>Anders Hejlsberg, Alok Menghrajani, Travis E. Oliphant, Joe Pamer,<br>Raoul-Gabriel Urma, and Julien Verlaguet.<br><br><br>References<br>==========<br><br>.. [mypy]<br>&nbsp;&nbsp; <a href="http://mypy-lang.org">http://mypy-lang.org</a><br><br>.. [pyflakes]<br>&nbsp;&nbsp; <a href="https://github.com/pyflakes/pyflakes/">https://github.com/pyflakes/pyflakes/</a><br><br>.. [pylint]<br>&nbsp;&nbsp; <a href="http://www.pylint.org">http://www.pylint.org</a><br><br>.. [gvr-artima]<br>&nbsp;&nbsp; <a href="http://www.artima.com/weblogs/viewpost.jsp?thread=85551">http://www.artima.com/weblogs/viewpost.jsp?thread=85551</a><br><br>.. [roberge]<br>&nbsp;&nbsp; <a href="http://aroberge.blogspot.com/2015/01/type-hinting-in-python-focus-on.html">http://aroberge.blogspot.com/2015/01/type-hinting-in-python-focus-on.html</a><br><br>.. [github]<br>&nbsp;&nbsp; <a href="https://github.com/ambv/typehinting">https://github.com/ambv/typehinting</a><br><br>.. [issues]<br>&nbsp;&nbsp; <a href="https://github.com/ambv/typehinting/issues">https://github.com/ambv/typehinting/issues</a><br><br>.. [peps]<br>&nbsp;&nbsp; <a href="https://hg.python.org/peps/file/tip/pep-0484.txt">https://hg.python.org/peps/file/tip/pep-0484.txt</a><br><br><br>Copyright<br>=========<br><br>This document has been placed in the public domain.<br><br><br><br>..<br>&nbsp;&nbsp; Local Variables:<br>&nbsp;&nbsp; mode: indented-text<br>&nbsp;&nbsp; indent-tabs-mode: nil<br>&nbsp;&nbsp; sentence-end-double-space: t<br>&nbsp;&nbsp; fill-column: 70<br>&nbsp;&nbsp; coding: utf-8<br>&nbsp;&nbsp; End:<br><br clear="all"><div><div><div><div>
<br>-- <br><div class="gmail_signature">--Guido van Rossum (<a href="http://python.org/~guido" target="_blank">python.org/~guido</a>)</div>
</div></div></div></div>
</div></div>
Yury Selivanov | 17 Apr 21:12 2015
Picon

async/await PEP

Hello,

I've just posted a new PEP about adding async/await to python-ideas.
Maybe I should have posted it here instead..

Anyways, please take a look.

Thanks,
Yury
Python tracker | 17 Apr 18:08 2015

Summary of Python tracker Issues


ACTIVITY SUMMARY (2015-04-10 - 2015-04-17)
Python tracker at http://bugs.python.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open    4792 (-31)
  closed 30957 (+113)
  total  35749 (+82)

Open issues with patches: 2240 

Issues opened (60)
==================

#22980: C extension naming doesn't take bitness into account
http://bugs.python.org/issue22980  reopened by lemburg

#23908: Check path arguments of os functions for null character
http://bugs.python.org/issue23908  opened by serhiy.storchaka

#23910: C implementation  of namedtuple (WIP)
http://bugs.python.org/issue23910  opened by llllllllll

#23911: Move path-based bootstrap code to a separate frozen file.
http://bugs.python.org/issue23911  opened by eric.snow

#23914: pickle fails with SystemError
http://bugs.python.org/issue23914  opened by alex

#23915: traceback set with BaseException.with_traceback() overwritten 
http://bugs.python.org/issue23915  opened by abathur

#23917: please fall back to sequential compilation when concurrent doe
http://bugs.python.org/issue23917  opened by doko

#23919: [Windows] test_os fails several C-level assertions
http://bugs.python.org/issue23919  opened by zach.ware

#23920: Should Clinic have "nullable" or types=NoneType?
http://bugs.python.org/issue23920  opened by larry

#23921: Standardize documentation whitespace, formatting
http://bugs.python.org/issue23921  opened by jedwards

#23922: turtle.py and turtledemo use the default tkinter icon
http://bugs.python.org/issue23922  opened by Al.Sweigart

#23926: skipitem() in getargs.c still supports 'w' and 'w#', and shoul
http://bugs.python.org/issue23926  opened by larry

#23927: getargs.c skipitem() doesn't skip 'w*'
http://bugs.python.org/issue23927  opened by larry

#23930: SimpleCookie doesn't  parse comma-only separated cookies corre
http://bugs.python.org/issue23930  opened by riklaunim

#23931: Update DevGuide link in Quickstart Step 1
http://bugs.python.org/issue23931  opened by willingc

#23933: Struct module should acept arrays
http://bugs.python.org/issue23933  opened by gamaanderson

#23934: inspect.signature reporting "()" for all builtin & extension t
http://bugs.python.org/issue23934  opened by ncoghlan

#23936: Wrong references to deprecated find_module instead of find_spe
http://bugs.python.org/issue23936  opened by raulcd

#23937: IDLE start maximized
http://bugs.python.org/issue23937  opened by zektron42

#23942: Explain naming of the patch files in the bug tracker
http://bugs.python.org/issue23942  opened by maciej.szulik

#23946: Invalid timestamps reported by os.stat() when Windows FILETIME
http://bugs.python.org/issue23946  opened by CristiFati

#23947: Add mechanism to import stdlib package bypassing user packages
http://bugs.python.org/issue23947  opened by steve.dower

#23948: Deprecate os.kill() on Windows
http://bugs.python.org/issue23948  opened by jpe

#23949: Number of elements display in error message is wrong while unp
http://bugs.python.org/issue23949  opened by ulaganathanm123 <at> gmail.com

#23950: Odd behavior with "file" and "filename" attributes in cgi.Fiel
http://bugs.python.org/issue23950  opened by deadpixi

#23951: Update devguide style to use a similar theme as Docs
http://bugs.python.org/issue23951  opened by willingc

#23952: Document the 'maxlen' member of the cgi module
http://bugs.python.org/issue23952  opened by deadpixi

#23953: test_mmap uses cruel and unusual amounts of disk space
http://bugs.python.org/issue23953  opened by larry

#23954: Pressing enter/return or clicking IDLE's autocomplete does not
http://bugs.python.org/issue23954  opened by Al.Sweigart

#23955: Add python.ini file for embedded/applocal installs
http://bugs.python.org/issue23955  opened by steve.dower

#23958: compile warnings in libffi
http://bugs.python.org/issue23958  opened by steveha

#23959: Update imaplib to support RFC3501
http://bugs.python.org/issue23959  opened by maciej.szulik

#23960: PyErr_SetImportError doesn't clean up on some errors
http://bugs.python.org/issue23960  opened by blackfawn

#23961: IDLE autocomplete window does not automatically close when sel
http://bugs.python.org/issue23961  opened by Al.Sweigart

#23962: Incorrect TimeoutError referenced in concurrent.futures docume
http://bugs.python.org/issue23962  opened by ryder.lewis

#23963: Windows build error using original openssl source
http://bugs.python.org/issue23963  opened by anselm.kruis

#23964: Update README documentation for IDLE tests.
http://bugs.python.org/issue23964  opened by Al.Sweigart

#23965: test_ssl failure on Fedora 22
http://bugs.python.org/issue23965  opened by kushal.das

#23966: More clearly expose/explain native and cross-build target info
http://bugs.python.org/issue23966  opened by ncoghlan

#23967: Make inspect.signature expression evaluation more powerful
http://bugs.python.org/issue23967  opened by larry

#23968: rename the platform directory from plat-$(MACHDEP) to plat-$(P
http://bugs.python.org/issue23968  opened by doko

#23969: please set a SOABI for MacOSX
http://bugs.python.org/issue23969  opened by doko

#23970: Update distutils.msvccompiler for VC14
http://bugs.python.org/issue23970  opened by steve.dower

#23971: dict(list) and dict.fromkeys() doesn't account for 2/3 fill ra
http://bugs.python.org/issue23971  opened by larry

#23972: Asyncio reuseport
http://bugs.python.org/issue23972  opened by Boris.FELD

#23973: PEP 484 implementation
http://bugs.python.org/issue23973  opened by gvanrossum

#23974: random.randrange() biased output
http://bugs.python.org/issue23974  opened by gurnec

#23975: numbers.Rational implements __float__ incorrectly
http://bugs.python.org/issue23975  opened by wolma

#23976: ZipFile.writestr implies non-regular files
http://bugs.python.org/issue23976  opened by dalphus

#23977: Enhancing IDLE's test_delegator.py unit test
http://bugs.python.org/issue23977  opened by Al.Sweigart

#23978: ttk.Style.element_create using incorrect tk.call syntax
http://bugs.python.org/issue23978  opened by jmorgensen

#23979: Multiprocessing Pool.map pickles arguments passed to workers
http://bugs.python.org/issue23979  opened by kieleth

#23980: Documentation for format units starting with 'e' is inconsiste
http://bugs.python.org/issue23980  opened by larry

#23981: Update test_unicodedata.py to use script_helpers
http://bugs.python.org/issue23981  opened by bobcatfish

#23982: Tkinter in Python 3.4 for Windows incorrectly renders certain 
http://bugs.python.org/issue23982  opened by MartyMacGyver

#23983: Update example in the pty documentation
http://bugs.python.org/issue23983  opened by berker.peksag

#23984: Documentation error: Descriptors
http://bugs.python.org/issue23984  opened by bjonnh

#23985: Crash when deleting slices from duplicated bytearray
http://bugs.python.org/issue23985  opened by johan

#23986: Inaccuracy about "in" keyword for list and tuple
http://bugs.python.org/issue23986  opened by wim.glenn

#23987: docs about containers membership testing wrong for broken obje
http://bugs.python.org/issue23987  opened by ethan.furman

Most recent 15 issues with no replies (15)
==========================================

#23986: Inaccuracy about "in" keyword for list and tuple
http://bugs.python.org/issue23986

#23984: Documentation error: Descriptors
http://bugs.python.org/issue23984

#23983: Update example in the pty documentation
http://bugs.python.org/issue23983

#23982: Tkinter in Python 3.4 for Windows incorrectly renders certain 
http://bugs.python.org/issue23982

#23978: ttk.Style.element_create using incorrect tk.call syntax
http://bugs.python.org/issue23978

#23977: Enhancing IDLE's test_delegator.py unit test
http://bugs.python.org/issue23977

#23976: ZipFile.writestr implies non-regular files
http://bugs.python.org/issue23976

#23975: numbers.Rational implements __float__ incorrectly
http://bugs.python.org/issue23975

#23973: PEP 484 implementation
http://bugs.python.org/issue23973

#23968: rename the platform directory from plat-$(MACHDEP) to plat-$(P
http://bugs.python.org/issue23968

#23963: Windows build error using original openssl source
http://bugs.python.org/issue23963

#23960: PyErr_SetImportError doesn't clean up on some errors
http://bugs.python.org/issue23960

#23955: Add python.ini file for embedded/applocal installs
http://bugs.python.org/issue23955

#23954: Pressing enter/return or clicking IDLE's autocomplete does not
http://bugs.python.org/issue23954

#23952: Document the 'maxlen' member of the cgi module
http://bugs.python.org/issue23952

Most recent 15 issues waiting for review (15)
=============================================

#23983: Update example in the pty documentation
http://bugs.python.org/issue23983

#23981: Update test_unicodedata.py to use script_helpers
http://bugs.python.org/issue23981

#23977: Enhancing IDLE's test_delegator.py unit test
http://bugs.python.org/issue23977

#23971: dict(list) and dict.fromkeys() doesn't account for 2/3 fill ra
http://bugs.python.org/issue23971

#23970: Update distutils.msvccompiler for VC14
http://bugs.python.org/issue23970

#23968: rename the platform directory from plat-$(MACHDEP) to plat-$(P
http://bugs.python.org/issue23968

#23967: Make inspect.signature expression evaluation more powerful
http://bugs.python.org/issue23967

#23964: Update README documentation for IDLE tests.
http://bugs.python.org/issue23964

#23963: Windows build error using original openssl source
http://bugs.python.org/issue23963

#23962: Incorrect TimeoutError referenced in concurrent.futures docume
http://bugs.python.org/issue23962

#23960: PyErr_SetImportError doesn't clean up on some errors
http://bugs.python.org/issue23960

#23949: Number of elements display in error message is wrong while unp
http://bugs.python.org/issue23949

#23946: Invalid timestamps reported by os.stat() when Windows FILETIME
http://bugs.python.org/issue23946

#23936: Wrong references to deprecated find_module instead of find_spe
http://bugs.python.org/issue23936

#23934: inspect.signature reporting "()" for all builtin & extension t
http://bugs.python.org/issue23934

Top 10 most discussed issues (10)
=================================

#22980: C extension naming doesn't take bitness into account
http://bugs.python.org/issue22980  34 msgs

#9517: Make test.script_helper more comprehensive, and use it in the 
http://bugs.python.org/issue9517  22 msgs

#5438: test_bigmem.test_from_2G_generator uses more memory than expec
http://bugs.python.org/issue5438  15 msgs

#23949: Number of elements display in error message is wrong while unp
http://bugs.python.org/issue23949  11 msgs

#23970: Update distutils.msvccompiler for VC14
http://bugs.python.org/issue23970  11 msgs

#17445: Handle bytes comparisons in difflib.Differ
http://bugs.python.org/issue17445  10 msgs

#23910: C implementation  of namedtuple (WIP)
http://bugs.python.org/issue23910  10 msgs

#4254: _cursesmodule.c callable update_lines_cols()
http://bugs.python.org/issue4254   9 msgs

#19050: [Python 2, Windows] fflush called on pointer to potentially cl
http://bugs.python.org/issue19050   9 msgs

#21327: socket.type value changes after using settimeout()
http://bugs.python.org/issue21327   9 msgs

Issues closed (104)
===================

#6006: ffi.c compile failures on AIX 5.3 with xlc
http://bugs.python.org/issue6006  closed by akuchling

#6983: Add specific get_platform() for freebsd
http://bugs.python.org/issue6983  closed by akuchling

#8882: socketmodule.c`getsockaddrarg() should not check the	length of
http://bugs.python.org/issue8882  closed by akuchling

#9014: Incorrect documentation of the PyObject_HEAD macro
http://bugs.python.org/issue9014  closed by gregory.p.smith

#9859: Add tests to verify API match of modules with 2 implementation
http://bugs.python.org/issue9859  closed by gregory.p.smith

#11754: Check calculated constants in test_string.py
http://bugs.python.org/issue11754  closed by r.david.murray

#12275: urllib.request.HTTPRedirectHandler won't redirect to a URL wit
http://bugs.python.org/issue12275  closed by vadmium

#12327: in HTTPConnection the are len(body) and TypeError catch except
http://bugs.python.org/issue12327  closed by r.david.murray

#12652: Keep test.support docs out of the global docs index
http://bugs.python.org/issue12652  closed by willingc

#12955: urllib.request example should use "with ... as:"
http://bugs.python.org/issue12955  closed by berker.peksag

#13164: importing rlcompleter module writes a control sequence in stdo
http://bugs.python.org/issue13164  closed by r.david.murray

#13472: devguide doesn’t list all build dependencies
http://bugs.python.org/issue13472  closed by willingc

#14374: Compiling Python 2.7.2 on HP11i PA-RISC ends with segmentation
http://bugs.python.org/issue14374  closed by akuchling

#14458: Non-admin installation fails
http://bugs.python.org/issue14458  closed by zach.ware

#14767: urllib.request.HTTPRedirectHandler raises HTTPError when Locat
http://bugs.python.org/issue14767  closed by vadmium

#15625: Support u and w codes in memoryview
http://bugs.python.org/issue15625  closed by steve.dower

#16050: ctypes: callback from C++ to Python fails with Illegal Instruc
http://bugs.python.org/issue16050  closed by r.david.murray

#16222: some terms not found by devguide's search box
http://bugs.python.org/issue16222  closed by willingc

#16229: Demo *redemo.py* lacking in Windows installation
http://bugs.python.org/issue16229  closed by zach.ware

#16405: Explain how to set up the whitespace commit hook locally
http://bugs.python.org/issue16405  closed by ned.deily

#16501: deprecate RISCOS "support"
http://bugs.python.org/issue16501  closed by akuchling

#16914: timestamping in smtplib.py to help troubleshoot server timeout
http://bugs.python.org/issue16914  closed by r.david.murray

#17202: Add .bat line to .hgeol
http://bugs.python.org/issue17202  closed by python-dev

#17284: create mercurial section in devguide's committing.rst
http://bugs.python.org/issue17284  closed by willingc

#17380: initproc return value is unclear
http://bugs.python.org/issue17380  closed by r.david.murray

#17630: Create a pure Python zipfile/tarfile importer
http://bugs.python.org/issue17630  closed by gregory.p.smith

#17751: ctypes/test/test_macholib.py fails when run from the installed
http://bugs.python.org/issue17751  closed by zach.ware

#17800: Add gc.needs_finalizing() to check if an object needs finalisi
http://bugs.python.org/issue17800  closed by benjamin.peterson

#17831: urllib.URLopener.open breaks ActiveDirectory user
http://bugs.python.org/issue17831  closed by r.david.murray

#17898: gettext bug while parsing plural-forms metadata
http://bugs.python.org/issue17898  closed by akuchling

#18128: pygettext: non-standard timestamp format in POT-Creation-Date
http://bugs.python.org/issue18128  closed by r.david.murray

#18166: 'value' attribute for ValueError
http://bugs.python.org/issue18166  closed by pitrou

#18402: Finding perl64
http://bugs.python.org/issue18402  closed by python-dev

#19121: Documentation guidelines enhancements
http://bugs.python.org/issue19121  closed by willingc

#19292: Make SSLContext.set_default_verify_paths() work on Windows
http://bugs.python.org/issue19292  closed by pitrou

#19933: Round default argument for "ndigits"
http://bugs.python.org/issue19933  closed by steve.dower

#20309: Not all method descriptors are callable
http://bugs.python.org/issue20309  closed by ncoghlan

#20586: Argument Clinic: functions with valid sig but no docstring hav
http://bugs.python.org/issue20586  closed by zach.ware

#21013: server-specific SSL context configuration
http://bugs.python.org/issue21013  closed by pitrou

#21116: Failure to create multiprocessing shared arrays larger than 50
http://bugs.python.org/issue21116  closed by pitrou

#21146: update gzip usage examples in docs
http://bugs.python.org/issue21146  closed by akuchling

#21217: inspect.getsourcelines finds wrong lines when lambda used argu
http://bugs.python.org/issue21217  closed by pitrou

#21400: Code coverage documentation is out-of-date.
http://bugs.python.org/issue21400  closed by ned.deily

#21416: argparse should accept bytes arguments as originally passed
http://bugs.python.org/issue21416  closed by zach.ware

#21511: Thinko in Lib/quopri.py, decoding b"==" to b"="
http://bugs.python.org/issue21511  closed by r.david.murray

#21741: Convert most of the test suite to using unittest.main()
http://bugs.python.org/issue21741  closed by zach.ware

#22046: ZipFile.read() should mention that it might throw NotImplement
http://bugs.python.org/issue22046  closed by gregory.p.smith

#22248: urllib.request.urlopen raises exception when 30X-redirect url 
http://bugs.python.org/issue22248  closed by vadmium

#22411: Embedding Python on Windows
http://bugs.python.org/issue22411  closed by steve.dower

#22631: Feature Request CAN_RAW_FD_FRAMES
http://bugs.python.org/issue22631  closed by larry

#22982: BOM incorrectly inserted before writing, after seeking in text
http://bugs.python.org/issue22982  closed by pitrou

#23193: Please support "numeric_owner" in tarfile
http://bugs.python.org/issue23193  closed by eric.smith

#23309: Hang on interpreter shutdown if daemon thread prints to stdout
http://bugs.python.org/issue23309  closed by pitrou

#23310: MagicMock initializer fails for magic methods
http://bugs.python.org/issue23310  closed by lukasz.langa

#23452: Build errors using VS Express 2013 in win32 mode
http://bugs.python.org/issue23452  closed by tim.golden

#23464: Remove or deprecate JoinableQueue in asyncio docs
http://bugs.python.org/issue23464  closed by r.david.murray

#23528: Limit decompressed data when reading from GzipFile
http://bugs.python.org/issue23528  closed by pitrou

#23529: Limit decompressed data when reading from LZMAFile and BZ2File
http://bugs.python.org/issue23529  closed by pitrou

#23612: 3.5.0a2 Windows installer does not remove 3.5.0a1
http://bugs.python.org/issue23612  closed by zach.ware

#23686: Update Windows and OS X installer OpenSSL to 1.0.2a
http://bugs.python.org/issue23686  closed by python-dev

#23703: urljoin() with no directory segments duplicates filename
http://bugs.python.org/issue23703  closed by berker.peksag

#23726: Don't enable GC for classes that don't add new fields
http://bugs.python.org/issue23726  closed by pitrou

#23727: rfc2231 line continuations result in an additional newline
http://bugs.python.org/issue23727  closed by r.david.murray

#23730: Document return value for ZipFile.extract()
http://bugs.python.org/issue23730  closed by python-dev

#23731: Implement PEP 488
http://bugs.python.org/issue23731  closed by brett.cannon

#23732: Update porting HOWTO about new -b semantics
http://bugs.python.org/issue23732  closed by brett.cannon

#23733: Update porting HOWTO for bytes interpolation
http://bugs.python.org/issue23733  closed by brett.cannon

#23761: test_socket fails on Mac OSX 10.9.5
http://bugs.python.org/issue23761  closed by willingc

#23811: Python py_compile error message inconsistent and missing newli
http://bugs.python.org/issue23811  closed by berker.peksag

#23817: Consider FreeBSD like any other OS in SOVERSION
http://bugs.python.org/issue23817  closed by haypo

#23820: test_importlib fails under -O
http://bugs.python.org/issue23820  closed by brett.cannon

#23822: test_py_compile fails under -O
http://bugs.python.org/issue23822  closed by brett.cannon

#23826: test_enum fails under -OO
http://bugs.python.org/issue23826  closed by ethan.furman

#23865: Fix possible leaks in close methods
http://bugs.python.org/issue23865  closed by serhiy.storchaka

#23900: Add a default docstring to Enum subclasses
http://bugs.python.org/issue23900  closed by python-dev

#23904: pathlib.PurePath does not accept bytes components
http://bugs.python.org/issue23904  closed by python-dev

#23907: Python
http://bugs.python.org/issue23907  closed by r.david.murray

#23909: highlight query string does not work on docs.python.org/2
http://bugs.python.org/issue23909  closed by python-dev

#23912: Inconsistent whitespace/formatting in docs/reference/datamodel
http://bugs.python.org/issue23912  closed by berker.peksag

#23913: error in some byte sizes of docs in array module
http://bugs.python.org/issue23913  closed by r.david.murray

#23916: module importing performance regression
http://bugs.python.org/issue23916  closed by pitrou

#23918: symbols namespace pollution
http://bugs.python.org/issue23918  closed by python-dev

#23923: Integer operations (// or %) on negative numbers product wrong
http://bugs.python.org/issue23923  closed by eric.smith

#23924: Add OS X to Dev Guide Quickstart build step
http://bugs.python.org/issue23924  closed by ned.deily

#23925: test_cmd_line failing on PYTHONSTARTUP
http://bugs.python.org/issue23925  closed by r.david.murray

#23928: SSL wiki page, host name matching, CN and SAN
http://bugs.python.org/issue23928  closed by pitrou

#23929: Minor typo (way vs. away) in os.renames docstring
http://bugs.python.org/issue23929  closed by python-dev

#23932: Tutorial section on function annotations is out of date re: PE
http://bugs.python.org/issue23932  closed by python-dev

#23935: Clean up Clinic's type expressions of buffers
http://bugs.python.org/issue23935  closed by larry

#23938: Deprecation of windows xp support missing from whats new
http://bugs.python.org/issue23938  closed by python-dev

#23939: test_get_platform_osx failure on Python 3.5.0a0 osx 10.6
http://bugs.python.org/issue23939  closed by ned.deily

#23940: test__supports_universal_builds failure on Python 3.5.0a0 osx 
http://bugs.python.org/issue23940  closed by ned.deily

#23941: Google Login not working
http://bugs.python.org/issue23941  closed by ned.deily

#23943: Misspellings in a few files
http://bugs.python.org/issue23943  closed by berker.peksag

#23944: Argument Clinic: wrap impl's declaration if it's too long
http://bugs.python.org/issue23944  closed by larry

#23945: webbrowser.open opens twice on Windows if BROWSER is set
http://bugs.python.org/issue23945  closed by andig2

#23956: Compatibility misspelled in Lib/imp.py
http://bugs.python.org/issue23956  closed by python-dev

#23957: Additional misspelled in documentation
http://bugs.python.org/issue23957  closed by r.david.murray

#23988: keyworded argument count is wrong
http://bugs.python.org/issue23988  closed by benjamin.peterson

#1481347: parse_makefile doesn't handle $$  correctly
http://bugs.python.org/issue1481347  closed by ned.deily

#1745108: 2.5.1 curses panel segfault in new_panel on aix 5.3
http://bugs.python.org/issue1745108  closed by akuchling

#1475523: gettext breaks on plural-forms header
http://bugs.python.org/issue1475523  closed by akuchling

#1648890: HP-UX: ld -Wl,+b...
http://bugs.python.org/issue1648890  closed by akuchling

#1284316: Win32: Security problem with default installation directory
http://bugs.python.org/issue1284316  closed by steve.dower

ACTIVITY SUMMARY (2015-04-10 - 2015-04-17)
Python tracker at http://bugs.python.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open    4792 (-31)
  closed 30957 (+113)
  total  35749 (+82)

Open issues with patches: 2240 

Issues opened (60)
==================

#22980: C extension naming doesn't take bitness into account
http://bugs.python.org/issue22980  reopened by lemburg

#23908: Check path arguments of os functions for null character
http://bugs.python.org/issue23908  opened by serhiy.storchaka

#23910: C implementation  of namedtuple (WIP)
http://bugs.python.org/issue23910  opened by llllllllll

#23911: Move path-based bootstrap code to a separate frozen file.
http://bugs.python.org/issue23911  opened by eric.snow

#23914: pickle fails with SystemError
http://bugs.python.org/issue23914  opened by alex

#23915: traceback set with BaseException.with_traceback() overwritten 
http://bugs.python.org/issue23915  opened by abathur

#23917: please fall back to sequential compilation when concurrent doe
http://bugs.python.org/issue23917  opened by doko

#23919: [Windows] test_os fails several C-level assertions
http://bugs.python.org/issue23919  opened by zach.ware

#23920: Should Clinic have "nullable" or types=NoneType?
http://bugs.python.org/issue23920  opened by larry

#23921: Standardize documentation whitespace, formatting
http://bugs.python.org/issue23921  opened by jedwards

#23922: turtle.py and turtledemo use the default tkinter icon
http://bugs.python.org/issue23922  opened by Al.Sweigart

#23926: skipitem() in getargs.c still supports 'w' and 'w#', and shoul
http://bugs.python.org/issue23926  opened by larry

#23927: getargs.c skipitem() doesn't skip 'w*'
http://bugs.python.org/issue23927  opened by larry

#23930: SimpleCookie doesn't  parse comma-only separated cookies corre
http://bugs.python.org/issue23930  opened by riklaunim

#23931: Update DevGuide link in Quickstart Step 1
http://bugs.python.org/issue23931  opened by willingc

#23933: Struct module should acept arrays
http://bugs.python.org/issue23933  opened by gamaanderson

#23934: inspect.signature reporting "()" for all builtin & extension t
http://bugs.python.org/issue23934  opened by ncoghlan

#23936: Wrong references to deprecated find_module instead of find_spe
http://bugs.python.org/issue23936  opened by raulcd

#23937: IDLE start maximized
http://bugs.python.org/issue23937  opened by zektron42

#23942: Explain naming of the patch files in the bug tracker
http://bugs.python.org/issue23942  opened by maciej.szulik

#23946: Invalid timestamps reported by os.stat() when Windows FILETIME
http://bugs.python.org/issue23946  opened by CristiFati

#23947: Add mechanism to import stdlib package bypassing user packages
http://bugs.python.org/issue23947  opened by steve.dower

#23948: Deprecate os.kill() on Windows
http://bugs.python.org/issue23948  opened by jpe

#23949: Number of elements display in error message is wrong while unp
http://bugs.python.org/issue23949  opened by ulaganathanm123 <at> gmail.com

#23950: Odd behavior with "file" and "filename" attributes in cgi.Fiel
http://bugs.python.org/issue23950  opened by deadpixi

#23951: Update devguide style to use a similar theme as Docs
http://bugs.python.org/issue23951  opened by willingc

#23952: Document the 'maxlen' member of the cgi module
http://bugs.python.org/issue23952  opened by deadpixi

#23953: test_mmap uses cruel and unusual amounts of disk space
http://bugs.python.org/issue23953  opened by larry

#23954: Pressing enter/return or clicking IDLE's autocomplete does not
http://bugs.python.org/issue23954  opened by Al.Sweigart

#23955: Add python.ini file for embedded/applocal installs
http://bugs.python.org/issue23955  opened by steve.dower

#23958: compile warnings in libffi
http://bugs.python.org/issue23958  opened by steveha

#23959: Update imaplib to support RFC3501
http://bugs.python.org/issue23959  opened by maciej.szulik

#23960: PyErr_SetImportError doesn't clean up on some errors
http://bugs.python.org/issue23960  opened by blackfawn

#23961: IDLE autocomplete window does not automatically close when sel
http://bugs.python.org/issue23961  opened by Al.Sweigart

#23962: Incorrect TimeoutError referenced in concurrent.futures docume
http://bugs.python.org/issue23962  opened by ryder.lewis

#23963: Windows build error using original openssl source
http://bugs.python.org/issue23963  opened by anselm.kruis

#23964: Update README documentation for IDLE tests.
http://bugs.python.org/issue23964  opened by Al.Sweigart

#23965: test_ssl failure on Fedora 22
http://bugs.python.org/issue23965  opened by kushal.das

#23966: More clearly expose/explain native and cross-build target info
http://bugs.python.org/issue23966  opened by ncoghlan

#23967: Make inspect.signature expression evaluation more powerful
http://bugs.python.org/issue23967  opened by larry

#23968: rename the platform directory from plat-$(MACHDEP) to plat-$(P
http://bugs.python.org/issue23968  opened by doko

#23969: please set a SOABI for MacOSX
http://bugs.python.org/issue23969  opened by doko

#23970: Update distutils.msvccompiler for VC14
http://bugs.python.org/issue23970  opened by steve.dower

#23971: dict(list) and dict.fromkeys() doesn't account for 2/3 fill ra
http://bugs.python.org/issue23971  opened by larry

#23972: Asyncio reuseport
http://bugs.python.org/issue23972  opened by Boris.FELD

#23973: PEP 484 implementation
http://bugs.python.org/issue23973  opened by gvanrossum

#23974: random.randrange() biased output
http://bugs.python.org/issue23974  opened by gurnec

#23975: numbers.Rational implements __float__ incorrectly
http://bugs.python.org/issue23975  opened by wolma

#23976: ZipFile.writestr implies non-regular files
http://bugs.python.org/issue23976  opened by dalphus

#23977: Enhancing IDLE's test_delegator.py unit test
http://bugs.python.org/issue23977  opened by Al.Sweigart

#23978: ttk.Style.element_create using incorrect tk.call syntax
http://bugs.python.org/issue23978  opened by jmorgensen

#23979: Multiprocessing Pool.map pickles arguments passed to workers
http://bugs.python.org/issue23979  opened by kieleth

#23980: Documentation for format units starting with 'e' is inconsiste
http://bugs.python.org/issue23980  opened by larry

#23981: Update test_unicodedata.py to use script_helpers
http://bugs.python.org/issue23981  opened by bobcatfish

#23982: Tkinter in Python 3.4 for Windows incorrectly renders certain 
http://bugs.python.org/issue23982  opened by MartyMacGyver

#23983: Update example in the pty documentation
http://bugs.python.org/issue23983  opened by berker.peksag

#23984: Documentation error: Descriptors
http://bugs.python.org/issue23984  opened by bjonnh

#23985: Crash when deleting slices from duplicated bytearray
http://bugs.python.org/issue23985  opened by johan

#23986: Inaccuracy about "in" keyword for list and tuple
http://bugs.python.org/issue23986  opened by wim.glenn

#23987: docs about containers membership testing wrong for broken obje
http://bugs.python.org/issue23987  opened by ethan.furman

Most recent 15 issues with no replies (15)
==========================================

#23986: Inaccuracy about "in" keyword for list and tuple
http://bugs.python.org/issue23986

#23984: Documentation error: Descriptors
http://bugs.python.org/issue23984

#23983: Update example in the pty documentation
http://bugs.python.org/issue23983

#23982: Tkinter in Python 3.4 for Windows incorrectly renders certain 
http://bugs.python.org/issue23982

#23978: ttk.Style.element_create using incorrect tk.call syntax
http://bugs.python.org/issue23978

#23977: Enhancing IDLE's test_delegator.py unit test
http://bugs.python.org/issue23977

#23976: ZipFile.writestr implies non-regular files
http://bugs.python.org/issue23976

#23975: numbers.Rational implements __float__ incorrectly
http://bugs.python.org/issue23975

#23973: PEP 484 implementation
http://bugs.python.org/issue23973

#23968: rename the platform directory from plat-$(MACHDEP) to plat-$(P
http://bugs.python.org/issue23968

#23963: Windows build error using original openssl source
http://bugs.python.org/issue23963

#23960: PyErr_SetImportError doesn't clean up on some errors
http://bugs.python.org/issue23960

#23955: Add python.ini file for embedded/applocal installs
http://bugs.python.org/issue23955

#23954: Pressing enter/return or clicking IDLE's autocomplete does not
http://bugs.python.org/issue23954

#23952: Document the 'maxlen' member of the cgi module
http://bugs.python.org/issue23952

Most recent 15 issues waiting for review (15)
=============================================

#23983: Update example in the pty documentation
http://bugs.python.org/issue23983

#23981: Update test_unicodedata.py to use script_helpers
http://bugs.python.org/issue23981

#23977: Enhancing IDLE's test_delegator.py unit test
http://bugs.python.org/issue23977

#23971: dict(list) and dict.fromkeys() doesn't account for 2/3 fill ra
http://bugs.python.org/issue23971

#23970: Update distutils.msvccompiler for VC14
http://bugs.python.org/issue23970

#23968: rename the platform directory from plat-$(MACHDEP) to plat-$(P
http://bugs.python.org/issue23968

#23967: Make inspect.signature expression evaluation more powerful
http://bugs.python.org/issue23967

#23964: Update README documentation for IDLE tests.
http://bugs.python.org/issue23964

#23963: Windows build error using original openssl source
http://bugs.python.org/issue23963

#23962: Incorrect TimeoutError referenced in concurrent.futures docume
http://bugs.python.org/issue23962

#23960: PyErr_SetImportError doesn't clean up on some errors
http://bugs.python.org/issue23960

#23949: Number of elements display in error message is wrong while unp
http://bugs.python.org/issue23949

#23946: Invalid timestamps reported by os.stat() when Windows FILETIME
http://bugs.python.org/issue23946

#23936: Wrong references to deprecated find_module instead of find_spe
http://bugs.python.org/issue23936

#23934: inspect.signature reporting "()" for all builtin & extension t
http://bugs.python.org/issue23934

Top 10 most discussed issues (10)
=================================

#22980: C extension naming doesn't take bitness into account
http://bugs.python.org/issue22980  34 msgs

#9517: Make test.script_helper more comprehensive, and use it in the 
http://bugs.python.org/issue9517  22 msgs

#5438: test_bigmem.test_from_2G_generator uses more memory than expec
http://bugs.python.org/issue5438  15 msgs

#23949: Number of elements display in error message is wrong while unp
http://bugs.python.org/issue23949  11 msgs

#23970: Update distutils.msvccompiler for VC14
http://bugs.python.org/issue23970  11 msgs

#17445: Handle bytes comparisons in difflib.Differ
http://bugs.python.org/issue17445  10 msgs

#23910: C implementation  of namedtuple (WIP)
http://bugs.python.org/issue23910  10 msgs

#4254: _cursesmodule.c callable update_lines_cols()
http://bugs.python.org/issue4254   9 msgs

#19050: [Python 2, Windows] fflush called on pointer to potentially cl
http://bugs.python.org/issue19050   9 msgs

#21327: socket.type value changes after using settimeout()
http://bugs.python.org/issue21327   9 msgs

Issues closed (104)
===================

#6006: ffi.c compile failures on AIX 5.3 with xlc
http://bugs.python.org/issue6006  closed by akuchling

#6983: Add specific get_platform() for freebsd
http://bugs.python.org/issue6983  closed by akuchling

#8882: socketmodule.c`getsockaddrarg() should not check the	length of
http://bugs.python.org/issue8882  closed by akuchling

#9014: Incorrect documentation of the PyObject_HEAD macro
http://bugs.python.org/issue9014  closed by gregory.p.smith

#9859: Add tests to verify API match of modules with 2 implementation
http://bugs.python.org/issue9859  closed by gregory.p.smith

#11754: Check calculated constants in test_string.py
http://bugs.python.org/issue11754  closed by r.david.murray

#12275: urllib.request.HTTPRedirectHandler won't redirect to a URL wit
http://bugs.python.org/issue12275  closed by vadmium

#12327: in HTTPConnection the are len(body) and TypeError catch except
http://bugs.python.org/issue12327  closed by r.david.murray

#12652: Keep test.support docs out of the global docs index
http://bugs.python.org/issue12652  closed by willingc

#12955: urllib.request example should use "with ... as:"
http://bugs.python.org/issue12955  closed by berker.peksag

#13164: importing rlcompleter module writes a control sequence in stdo
http://bugs.python.org/issue13164  closed by r.david.murray

#13472: devguide doesn’t list all build dependencies
http://bugs.python.org/issue13472  closed by willingc

#14374: Compiling Python 2.7.2 on HP11i PA-RISC ends with segmentation
http://bugs.python.org/issue14374  closed by akuchling

#14458: Non-admin installation fails
http://bugs.python.org/issue14458  closed by zach.ware

#14767: urllib.request.HTTPRedirectHandler raises HTTPError when Locat
http://bugs.python.org/issue14767  closed by vadmium

#15625: Support u and w codes in memoryview
http://bugs.python.org/issue15625  closed by steve.dower

#16050: ctypes: callback from C++ to Python fails with Illegal Instruc
http://bugs.python.org/issue16050  closed by r.david.murray

#16222: some terms not found by devguide's search box
http://bugs.python.org/issue16222  closed by willingc

#16229: Demo *redemo.py* lacking in Windows installation
http://bugs.python.org/issue16229  closed by zach.ware

#16405: Explain how to set up the whitespace commit hook locally
http://bugs.python.org/issue16405  closed by ned.deily

#16501: deprecate RISCOS "support"
http://bugs.python.org/issue16501  closed by akuchling

#16914: timestamping in smtplib.py to help troubleshoot server timeout
http://bugs.python.org/issue16914  closed by r.david.murray

#17202: Add .bat line to .hgeol
http://bugs.python.org/issue17202  closed by python-dev

#17284: create mercurial section in devguide's committing.rst
http://bugs.python.org/issue17284  closed by willingc

#17380: initproc return value is unclear
http://bugs.python.org/issue17380  closed by r.david.murray

#17630: Create a pure Python zipfile/tarfile importer
http://bugs.python.org/issue17630  closed by gregory.p.smith

#17751: ctypes/test/test_macholib.py fails when run from the installed
http://bugs.python.org/issue17751  closed by zach.ware

#17800: Add gc.needs_finalizing() to check if an object needs finalisi
http://bugs.python.org/issue17800  closed by benjamin.peterson

#17831: urllib.URLopener.open breaks ActiveDirectory user
http://bugs.python.org/issue17831  closed by r.david.murray

#17898: gettext bug while parsing plural-forms metadata
http://bugs.python.org/issue17898  closed by akuchling

#18128: pygettext: non-standard timestamp format in POT-Creation-Date
http://bugs.python.org/issue18128  closed by r.david.murray

#18166: 'value' attribute for ValueError
http://bugs.python.org/issue18166  closed by pitrou

#18402: Finding perl64
http://bugs.python.org/issue18402  closed by python-dev

#19121: Documentation guidelines enhancements
http://bugs.python.org/issue19121  closed by willingc

#19292: Make SSLContext.set_default_verify_paths() work on Windows
http://bugs.python.org/issue19292  closed by pitrou

#19933: Round default argument for "ndigits"
http://bugs.python.org/issue19933  closed by steve.dower

#20309: Not all method descriptors are callable
http://bugs.python.org/issue20309  closed by ncoghlan

#20586: Argument Clinic: functions with valid sig but no docstring hav
http://bugs.python.org/issue20586  closed by zach.ware

#21013: server-specific SSL context configuration
http://bugs.python.org/issue21013  closed by pitrou

#21116: Failure to create multiprocessing shared arrays larger than 50
http://bugs.python.org/issue21116  closed by pitrou

#21146: update gzip usage examples in docs
http://bugs.python.org/issue21146  closed by akuchling

#21217: inspect.getsourcelines finds wrong lines when lambda used argu
http://bugs.python.org/issue21217  closed by pitrou

#21400: Code coverage documentation is out-of-date.
http://bugs.python.org/issue21400  closed by ned.deily

#21416: argparse should accept bytes arguments as originally passed
http://bugs.python.org/issue21416  closed by zach.ware

#21511: Thinko in Lib/quopri.py, decoding b"==" to b"="
http://bugs.python.org/issue21511  closed by r.david.murray

#21741: Convert most of the test suite to using unittest.main()
http://bugs.python.org/issue21741  closed by zach.ware

#22046: ZipFile.read() should mention that it might throw NotImplement
http://bugs.python.org/issue22046  closed by gregory.p.smith

#22248: urllib.request.urlopen raises exception when 30X-redirect url 
http://bugs.python.org/issue22248  closed by vadmium

#22411: Embedding Python on Windows
http://bugs.python.org/issue22411  closed by steve.dower

#22631: Feature Request CAN_RAW_FD_FRAMES
http://bugs.python.org/issue22631  closed by larry

#22982: BOM incorrectly inserted before writing, after seeking in text
http://bugs.python.org/issue22982  closed by pitrou

#23193: Please support "numeric_owner" in tarfile
http://bugs.python.org/issue23193  closed by eric.smith

#23309: Hang on interpreter shutdown if daemon thread prints to stdout
http://bugs.python.org/issue23309  closed by pitrou

#23310: MagicMock initializer fails for magic methods
http://bugs.python.org/issue23310  closed by lukasz.langa

#23452: Build errors using VS Express 2013 in win32 mode
http://bugs.python.org/issue23452  closed by tim.golden

#23464: Remove or deprecate JoinableQueue in asyncio docs
http://bugs.python.org/issue23464  closed by r.david.murray

#23528: Limit decompressed data when reading from GzipFile
http://bugs.python.org/issue23528  closed by pitrou

#23529: Limit decompressed data when reading from LZMAFile and BZ2File
http://bugs.python.org/issue23529  closed by pitrou

#23612: 3.5.0a2 Windows installer does not remove 3.5.0a1
http://bugs.python.org/issue23612  closed by zach.ware

#23686: Update Windows and OS X installer OpenSSL to 1.0.2a
http://bugs.python.org/issue23686  closed by python-dev

#23703: urljoin() with no directory segments duplicates filename
http://bugs.python.org/issue23703  closed by berker.peksag

#23726: Don't enable GC for classes that don't add new fields
http://bugs.python.org/issue23726  closed by pitrou

#23727: rfc2231 line continuations result in an additional newline
http://bugs.python.org/issue23727  closed by r.david.murray

#23730: Document return value for ZipFile.extract()
http://bugs.python.org/issue23730  closed by python-dev

#23731: Implement PEP 488
http://bugs.python.org/issue23731  closed by brett.cannon

#23732: Update porting HOWTO about new -b semantics
http://bugs.python.org/issue23732  closed by brett.cannon

#23733: Update porting HOWTO for bytes interpolation
http://bugs.python.org/issue23733  closed by brett.cannon

#23761: test_socket fails on Mac OSX 10.9.5
http://bugs.python.org/issue23761  closed by willingc

#23811: Python py_compile error message inconsistent and missing newli
http://bugs.python.org/issue23811  closed by berker.peksag

#23817: Consider FreeBSD like any other OS in SOVERSION
http://bugs.python.org/issue23817  closed by haypo

#23820: test_importlib fails under -O
http://bugs.python.org/issue23820  closed by brett.cannon

#23822: test_py_compile fails under -O
http://bugs.python.org/issue23822  closed by brett.cannon

#23826: test_enum fails under -OO
http://bugs.python.org/issue23826  closed by ethan.furman

#23865: Fix possible leaks in close methods
http://bugs.python.org/issue23865  closed by serhiy.storchaka

#23900: Add a default docstring to Enum subclasses
http://bugs.python.org/issue23900  closed by python-dev

#23904: pathlib.PurePath does not accept bytes components
http://bugs.python.org/issue23904  closed by python-dev

#23907: Python
http://bugs.python.org/issue23907  closed by r.david.murray

#23909: highlight query string does not work on docs.python.org/2
http://bugs.python.org/issue23909  closed by python-dev

#23912: Inconsistent whitespace/formatting in docs/reference/datamodel
http://bugs.python.org/issue23912  closed by berker.peksag

#23913: error in some byte sizes of docs in array module
http://bugs.python.org/issue23913  closed by r.david.murray

#23916: module importing performance regression
http://bugs.python.org/issue23916  closed by pitrou

#23918: symbols namespace pollution
http://bugs.python.org/issue23918  closed by python-dev

#23923: Integer operations (// or %) on negative numbers product wrong
http://bugs.python.org/issue23923  closed by eric.smith

#23924: Add OS X to Dev Guide Quickstart build step
http://bugs.python.org/issue23924  closed by ned.deily

#23925: test_cmd_line failing on PYTHONSTARTUP
http://bugs.python.org/issue23925  closed by r.david.murray

#23928: SSL wiki page, host name matching, CN and SAN
http://bugs.python.org/issue23928  closed by pitrou

#23929: Minor typo (way vs. away) in os.renames docstring
http://bugs.python.org/issue23929  closed by python-dev

#23932: Tutorial section on function annotations is out of date re: PE
http://bugs.python.org/issue23932  closed by python-dev

#23935: Clean up Clinic's type expressions of buffers
http://bugs.python.org/issue23935  closed by larry

#23938: Deprecation of windows xp support missing from whats new
http://bugs.python.org/issue23938  closed by python-dev

#23939: test_get_platform_osx failure on Python 3.5.0a0 osx 10.6
http://bugs.python.org/issue23939  closed by ned.deily

#23940: test__supports_universal_builds failure on Python 3.5.0a0 osx 
http://bugs.python.org/issue23940  closed by ned.deily

#23941: Google Login not working
http://bugs.python.org/issue23941  closed by ned.deily

#23943: Misspellings in a few files
http://bugs.python.org/issue23943  closed by berker.peksag

#23944: Argument Clinic: wrap impl's declaration if it's too long
http://bugs.python.org/issue23944  closed by larry

#23945: webbrowser.open opens twice on Windows if BROWSER is set
http://bugs.python.org/issue23945  closed by andig2

#23956: Compatibility misspelled in Lib/imp.py
http://bugs.python.org/issue23956  closed by python-dev

#23957: Additional misspelled in documentation
http://bugs.python.org/issue23957  closed by r.david.murray

#23988: keyworded argument count is wrong
http://bugs.python.org/issue23988  closed by benjamin.peterson

#1481347: parse_makefile doesn't handle $$  correctly
http://bugs.python.org/issue1481347  closed by ned.deily

#1745108: 2.5.1 curses panel segfault in new_panel on aix 5.3
http://bugs.python.org/issue1745108  closed by akuchling

#1475523: gettext breaks on plural-forms header
http://bugs.python.org/issue1475523  closed by akuchling

#1648890: HP-UX: ld -Wl,+b...
http://bugs.python.org/issue1648890  closed by akuchling

#1284316: Win32: Security problem with default installation directory
http://bugs.python.org/issue1284316  closed by steve.dower
Petr Viktorin | 17 Apr 15:52 2015
Picon

Changing PyModuleDef.m_reload to m_slots

Hello,

PEP 489, Redesigning extension module loading [0], is currently 
discussed on import-sig, but one question calls for a wider audience.

As a background, the PyModuleDef structure [1] is currently:

     struct PyModuleDef{
       PyModuleDef_Base m_base;
       const char* m_name;
       const char* m_doc;
       Py_ssize_t m_size;
       PyMethodDef *m_methods;
       inquiry m_reload;
       traverseproc m_traverse;
       inquiry m_clear;
       freefunc m_free;
     };

... where the m_reload pointer is unused, and must be NULL.
My proposal is to repurpose this pointer to hold an array of slots, in 
the style of PEP 384's PyType_Spec [2], which would allow adding 
extensions -- both those needed for PEP 489 and future ones.

The result would be:

     typedef struct {
         int slot;
         void *value;
     } PyModuleDesc_Slot;

     typedef struct PyModuleDef {
         PyModuleDef_Base m_base;
         const char* m_name;
         const char* m_doc;
         Py_ssize_t m_size;
         PyMethodDef *m_methods;
         PyModuleDesc_Slot* m_slots;  /* <-- change here */
         traverseproc m_traverse;
         inquiry m_clear;
         freefunc m_free;
     } PyModuleDef;

The alternative is defining another struct for module definitions, with 
a parallel versions of functions to operate on it, and duplication on 
the lower level (e.g. a variant of PyModule_GetDef, variants for 
PyState_FindModule &c with the supporting registry, extra storage in 
module objects, two places to look in for GC/deallocation hooks).

The downside is that, strictly speaking, this would break API/ABI, 
though in pedantic details.

The field name could conceivably be used to get the NULL or in C99-style 
designated initializers, but since NULL is the only valid value, I don't 
see a reason for that. It could also be used for zeroing the structure 
after allocating a PyModuleDef dynamically.

ABI-wise, this changes a function pointer to a data pointer. To my 
knowledge, Python doesn't support a platform where this would matter, 
but I admit my knowledge is not complete.

Please share any concerns you might have about this change.

[0] https://www.python.org/dev/peps/pep-0489/
[1] https://docs.python.org/3/c-api/module.html#c.PyModuleDef
[2] https://www.python.org/dev/peps/pep-0384/#type-objects
Alex Shkop | 17 Apr 09:40 2015
Picon

unittest test discovery and namespace packages

Hello!

There's an issue considering test discovery in unittest module. Basically it is about unittest module that doesn't find tests in namespace packages. For more info see issue http://bugs.python.org/issue23882.

I'm willing to make a patch for this bug. But I need help to formulate how test discovery should work.

Documentation states that all importable modules that match pattern will be loaded. This means that test modules inside namespace packages should be loaded too. But enabling this would change things drastically. For example now, running

python -m unittest

inside cpython source root does nothing. If we will enable test discovery inside namespace packages then this command will start running the whole python test suite in Lib/test/.

So I'm looking for someone's help to clarify how test discovery should work.
 
Thanks,
Alex
--
Issue in bugtracker - http://bugs.python.org/issue23882 
Documentation for discover() method - https://docs.python.org/3.4/library/unittest.html#unittest.TestLoader.discover
<div><div dir="ltr">Hello!<br><br>There's an issue&nbsp;considering test discovery in unittest module. Basically it is about unittest module that doesn't find tests in namespace packages. For more info see issue <a href="http://bugs.python.org/issue23882">http://bugs.python.org/issue23882</a>.<br><br>I'm willing to make a patch for this bug. But I need help to formulate how test discovery should work.<br><br>Documentation states that all importable modules that match pattern will be loaded. This means that test modules inside namespace packages should be loaded too. But enabling this would change things drastically. For example now, running<br><br>python -m unittest<br><br>inside cpython source root does nothing. If we will enable test discovery inside namespace packages then this command will start running the whole python test suite in Lib/test/.<br><br>So I'm looking for someone's help to clarify how test discovery should work.<br>&nbsp;<br>Thanks,<br>Alex<br>--<br>Issue in bugtracker - <a href="http://bugs.python.org/issue23882">http://bugs.python.org/issue23882</a>&nbsp;<br>Documentation for discover() method -&nbsp;<a href="https://docs.python.org/3.4/library/unittest.html#unittest.TestLoader.discover">https://docs.python.org/3.4/library/unittest.html#unittest.TestLoader.discover</a>
</div></div>
Facundo Batista | 17 Apr 03:32 2015
Picon

How to behave regarding commiting

Hola!

I'm asking this because quite some time passed since I was active in
the development of our beloved language.

I'm trying to not break any new rule not known by me.

I opened a bug recently [0], somebody else proposed a patch that I
like. However, that patch has no test. I will do a test for that code,
but then what?

Shall I just commit and push? Or the whole branch should be proposed
for further reviewing?

Thank you!!

[0] http://bugs.python.org/issue23887

--

-- 
.    Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
Twitter:  <at> facundobatista
Facundo Batista | 16 Apr 23:09 2015
Picon

Not being able to compile: "make: *** [Programs/_freeze_importlib] Error 1"

Hello!

It's been a while since I compiled python and run the test suite.

Now that I'm starting to work in a patch, wanted to do that as a
sanity check, and even "./configure" finishing ok, "make" fails :/
(I'm on Ubuntu Trusty, all packages updated, all dependencies
theorically installed).

Full trace here:

  http://linkode.org/TgkzZw90JUaoodvYzU7zX6

Before going into a deep debug, I thought about sending a mail to see
if anybode else hit this issue, if it's a common problem, if there's a
known workaround.

Thanks!!

--

-- 
.    Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
Twitter:  <at> facundobatista
Isaac Schwabacher | 16 Apr 00:36 2015
Picon

Re: Status on PEP-431 Timezones

On 15-04-15, Akira Li <4kir4.1i <at> gmail.com> wrote:
> Isaac Schwabacher <ischwabacher <at> wisc.edu> writes:
> 
> > On 15-04-15, Akira Li <4kir4.1i <at> gmail.com> wrote:
> >> Isaac Schwabacher <ischwabacher <at> wisc.edu> writes:
> >> > ...
> >> >
> >> > I know that you can do datetime.now(tz), and you can do datetime(2013,
> >> > 11, 3, 1, 30, tzinfo=zoneinfo('America/Chicago')), but not being able
> >> > to add a time zone to an existing naive datetime is painful (and
> >> > strptime doesn't even let you pass in a time zone). 
> >> 
> >> `.now(tz)` is correct. `datetime(..., tzinfo=tz)`) is wrong: if tz is a
> >> pytz timezone then you may get a wrong tzinfo (LMT), you should use
> >> `tz.localize(naive_dt, is_dst=False|True|None)` instead.
> >
> > The whole point of this thread is to finalize PEP 431, which fixes the
> > problem for which `localize()` and `normalize()` are workarounds. When
> > this is done, `datetime(..., tzinfo=tz)` will be correct.
> >
> > ijs
> 
> The input time is ambiguous. Even if we assume PEP 431 is implemented in
> some form, your code is still missing isdst parameter (or the
> analog). PEP 431 won't fix it; it can't resolve the ambiguity by
> itself. Notice is_dst paramter in the `tz.localize()` call (current
> API).

...yeah, I forgot to throw that in there. It was supposed to be there all along. Nothing to see here, move along.

> .now(tz) works even during end-of-DST transitions (current API) when the
> local time is ambiguous.

I know that. That's what I was complaining about-- I was trying to talk about how astimezone() was going to be
inadequate even after the PEP was implemented because it couldn't turn naive datetimes into aware ones,
and people were giving examples that started with aware datetimes generated by now(tz), which
completely went around the point I was trying to make. But it looks like astimezone() is going to grow an
is_dst parameter, and everything will be OK.

ijs
Isaac Schwabacher | 15 Apr 22:35 2015
Picon

Re: Status on PEP-431 Timezones

On 15-04-15, Akira Li <4kir4.1i <at> gmail.com> wrote:
> Isaac Schwabacher <ischwabacher <at> wisc.edu> writes:
> > ...
> >
> > I know that you can do datetime.now(tz), and you can do datetime(2013,
> > 11, 3, 1, 30, tzinfo=zoneinfo('America/Chicago')), but not being able
> > to add a time zone to an existing naive datetime is painful (and
> > strptime doesn't even let you pass in a time zone). 
> 
> `.now(tz)` is correct. `datetime(..., tzinfo=tz)`) is wrong: if tz is a
> pytz timezone then you may get a wrong tzinfo (LMT), you should use
> `tz.localize(naive_dt, is_dst=False|True|None)` instead.

The whole point of this thread is to finalize PEP 431, which fixes the problem for which `localize()` and
`normalize()` are workarounds. When this is done, `datetime(..., tzinfo=tz)` will be correct.

ijs
Isaac Schwabacher | 15 Apr 19:33 2015
Picon

Re: Status on PEP-431 Timezones

On 15-04-15, Lennart Regebro  wrote:
> On Wed, Apr 15, 2015 at 12:40 PM, Isaac Schwabacher
> <ischwabacher <at> wisc.edu> wrote:
> > I am on the fence about EPOCH + offset as an internal representation. On the one hand, it is conceptually
cleaner than the horrible byte-packing that exists today, but on the other hand, it has implications for
future implementations of leap-second-awareness. For instance, offset measures the difference
between the local time and UTC. But is it honest-to-goodness leap-second aware UTC, or is it really Unix
time? This could be solved by giving each tzinfo a pointer to the UTC from which it is offset, but that sounds
like a can of worms we don't want to open. But if don't and we store EPOCH + offset, we can't add leap second
awareness to UTC without corrupting all persisted aware datetimes.
> 
> 
> That's true, with separate values like there is now we can easily
> allow 23:59:60 as a timestamp during leap seconds. I'm not entirely
> sure it makes a big difference though, I don't think we ever wants to
> deal with leap seconds by default.
> 
> I don't think we ever want the standard arithmetic deal with leap
> seconds anyway.
> 
> datetime(2012, 6, 30, 23, 30) + timedelta(seconds=3600) returning
> datetime(2012, 7, 1, 0, 29, 59)
> 
> 
> I guess leap second implementations should rather have special
> functions for arithmethics that deal with this.

You need relative timedeltas to mitigate the pain of leap seconds, yes. But as soon as you have timedeltas
that are capable of representing "this number of seconds into the next minute" ("one minute") as opposed
to "sixty seconds", this isn't so much of a problem. Though of course subtraction will (and should!)
continue to yield timedelta(seconds=3601).

From my perspective, the issue is more that the stdlib shouldn't rule out leap seconds. It's reasonable
enough to expect users who actually want them to write appropriate tzinfo and timedelta classes, but we
don't want to make that impossible the way the old tzinfo interface made DST-aware time zones impossible
by insisting that implementers implement a function that wasn't mathematically a function.

I need to think about this more before I can get a real rant going.

ijs
Isaac Schwabacher | 15 Apr 18:40 2015
Picon

Re: Status on PEP-431 Timezones

On 15-04-15, Lennart Regebro  wrote:
> On Wed, Apr 15, 2015 at 11:10 AM, Chris Angelico <rosuav <at> gmail.com> wrote:
> > Bikeshed: Would arithmetic be based on UTC time or Unix time? It'd be
> > more logical to describe it as "adding six hours means adding six
> > hours to the UTC time", but it'd look extremely odd when there's a
> > leap second.
> 
> It would ignore leap seconds. If you want to call that unix time or
> not is a matter of opinion. Hm. I guess the internal representation
> *could* be EPOCH + offset, and local times could be calculated
> properties, which could be cached (or possibly calculated at
> creation).

I am on the fence about EPOCH + offset as an internal representation. On the one hand, it is conceptually
cleaner than the horrible byte-packing that exists today, but on the other hand, it has implications for
future implementations of leap-second-awareness. For instance, offset measures the difference
between the local time and UTC. But is it honest-to-goodness leap-second aware UTC, or is it really Unix
time? This could be solved by giving each tzinfo a pointer to the UTC from which it is offset, but that sounds
like a can of worms we don't want to open. But if don't and we store EPOCH + offset, we can't add leap second
awareness to UTC without corrupting all persisted aware datetimes.

Also, I didn't mention this before because I figured people were getting sick of my dumb idea, but another
advantage of always caching the offset is that you can detect future datetimes that have been corrupted by
zoneinfo changes. You need both absolute time and offset to be able to do this.

ijs

Gmane