python-peps/pep-0492.txt

PEP: 492
Title: Coroutines with async and await syntax
Version: $Revision$
Last-Modified: $Date$
Author: Yury Selivanov <yselivanov@sprymix.com>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 09-Apr-2015
Python-Version: 3.5
Post-History: 17-Apr-2015, 21-Apr-2015


Abstract
========

This PEP introduces new syntax for coroutines, asynchronous ``with``
statements and ``for`` loops.  The main motivation behind this proposal
is to streamline writing and maintaining asynchronous code, as well as
to simplify previously hard to implement code patterns.


Rationale and Goals
===================

Current Python supports implementing coroutines via generators (PEP
342), further enhanced by the ``yield from`` syntax introduced in PEP
380. This approach has a number of shortcomings:

* it is easy to confuse coroutines with regular generators, since they
  share the same syntax; async libraries often attempt to alleviate
  this by using decorators (e.g. ``@asyncio.coroutine`` [1]_);

* it is not possible to natively define a coroutine which has no
  ``yield`` or  ``yield from`` statements, again requiring the use of
  decorators to fix potential refactoring issues;

* support for asynchronous calls is limited to expressions where
  ``yield`` is allowed syntactically, limiting the usefulness of
  syntactic features, such as ``with`` and ``for`` statements.

This proposal makes coroutines a native Python language feature, and
clearly separates them from generators.  This removes
generator/coroutine ambiguity, and makes it possible to reliably define
coroutines without reliance on a specific library.  This also enables
linters and IDEs to improve static code analysis and refactoring.

Native coroutines and the associated new syntax features make it
possible to define context manager and iteration protocols in
asynchronous terms. As shown later in this proposal, the new ``async
with`` statement lets Python programs perform asynchronous calls when
entering and exiting a runtime context, and the new ``async for``
statement makes it possible to perform asynchronous calls in iterators.


Specification
=============

This proposal introduces new syntax and semantics to enhance coroutine
support in Python, it does not change the internal implementation of
coroutines, which are still based on generators.

It is strongly suggested that the reader understands how coroutines are
implemented in Python (PEP 342 and PEP 380).  It is also recommended to
read PEP 3156 (asyncio framework) and PEP 3152 (Cofunctions).

From this point in this document we use the word *coroutine* to refer
to functions declared using the new syntax.  *generator-based
coroutine* is used where necessary to refer to coroutines that are
based on generator syntax.


New Coroutine Declaration Syntax
--------------------------------

The following new syntax is used to declare a coroutine::

    async def read_data(db):
        pass

Key properties of coroutines:

* ``async def`` functions are always coroutines, even if they do not
  contain ``await`` expressions.

* It is a ``SyntaxError`` to have ``yield`` or ``yield from``
  expressions in an ``async`` function.

* Internally, a new code object flag - ``CO_COROUTINE`` - is introduced
  to enable runtime detection of coroutines (and migrating existing
  code). All coroutines have both ``CO_COROUTINE`` and ``CO_GENERATOR``
  flags set.

* Regular generators, when called, return a *generator object*;
  similarly, coroutines return a *coroutine object*.

* ``StopIteration`` exceptions are not propagated out of coroutines,
  and are replaced with a ``RuntimeError``.  For regular generators
  such behavior requires a future import (see PEP 479).


types.coroutine()
-----------------

A new function ``coroutine(gen)`` is added to the ``types`` module.  It
applies ``CO_COROUTINE`` flag to the passed generator-function's code
object, making it to return a *coroutine object* when called.

This feature enables an easy upgrade path for existing libraries.


Await Expression
----------------

The following new ``await`` expression is used to obtain a result of
coroutine execution::

    async def read_data(db):
        data = await db.fetch('SELECT ...')
        ...

``await``, similarly to ``yield from``, suspends execution of
``read_data`` coroutine until ``db.fetch`` *awaitable* completes and
returns the result data.

It uses the ``yield from`` implementation with an extra step of
validating its argument.  ``await`` only accepts an *awaitable*, which
can be one of:

* A *coroutine object* returned from a *coroutine* or a generator
  decorated with ``types.coroutine()``.

* An object with an ``__await__`` method returning an iterator.

  Any ``yield from`` chain of calls ends with a ``yield``.  This is a
  fundamental mechanism of how *Futures* are implemented.  Since,
  internally, coroutines are a special kind of generators, every
  ``await`` is suspended by a ``yield`` somewhere down the chain of
  ``await`` calls (please refer to PEP 3156 for a detailed
  explanation.)

  To enable this behavior for coroutines, a new magic method called
  ``__await__`` is added.  In asyncio, for instance, to enable Future
  objects in ``await`` statements, the only change is to add
  ``__await__ = __iter__`` line to ``asyncio.Future`` class.

  Objects with ``__await__`` method are called *Future-like* objects in
  the rest of this PEP.

  Also, please note that ``__aiter__`` method (see its definition
  below) cannot be used for this purpose.  It is a different protocol,
  and would be like using ``__iter__`` instead of ``__call__`` for
  regular callables.

It is a ``SyntaxError`` to use ``await`` outside of a coroutine.


Asynchronous Context Managers and "async with"
----------------------------------------------

An *asynchronous context manager* is a context manager that is able to
suspend execution in its *enter* and *exit* methods.

To make this possible, a new protocol for asynchronous context managers
is proposed.  Two new magic methods are added: ``__aenter__`` and
``__aexit__``. Both must return an *awaitable*.

An example of an asynchronous context manager::

    class AsyncContextManager:
        async def __aenter__(self):
            await log('entering context')

        async def __aexit__(self, exc_type, exc, tb):
            await log('exiting context')


New Syntax
''''''''''

A new statement for asynchronous context managers is proposed::

    async with EXPR as VAR:
        BLOCK


which is semantically equivalent to::

    mgr = (EXPR)
    aexit = type(mgr).__aexit__
    aenter = type(mgr).__aenter__(mgr)
    exc = True

    try:
        try:
            VAR = await aenter
            BLOCK
        except:
            exc = False
            exit_res = await aexit(mgr, *sys.exc_info())
            if not exit_res:
                raise

    finally:
        if exc:
            await aexit(mgr, None, None, None)


As with regular ``with`` statements, it is possible to specify multiple
context managers in a single ``async with`` statement.

It is an error to pass a regular context manager without ``__aenter__``
and ``__aexit__`` methods to ``async with``.  It is a ``SyntaxError``
to use ``async with`` outside of a coroutine.


Example
'''''''

With asynchronous context managers it is easy to implement proper
database transaction managers for coroutines::

    async def commit(session, data):
        ...

        async with session.transaction():
            ...
            await session.update(data)
            ...

Code that needs locking also looks lighter::

    async with lock:
        ...

instead of::

    with (yield from lock):
        ...


Asynchronous Iterators and "async for"
--------------------------------------

An *asynchronous iterable* is able to call asynchronous code in its
*iter* implementation, and *asynchronous iterator* can call
asynchronous code in its *next* method.  To support asynchronous
iteration:

1. An object must implement an  ``__aiter__`` method returning an
   *awaitable* resulting in an *asynchronous iterator object*.

2. An *asynchronous iterator object* must implement an ``__anext__``
   method returning an *awaitable*.

3. To stop iteration ``__anext__`` must raise a ``StopAsyncIteration``
   exception.

An example of asynchronous iterable::

    class AsyncIterable:
        async def __aiter__(self):
            return self

        async def __anext__(self):
            data = await self.fetch_data()
            if data:
                return data
            else:
                raise StopAsyncIteration

        async def fetch_data(self):
            ...


New Syntax
''''''''''

A new statement for iterating through asynchronous iterators is
proposed::

    async for TARGET in ITER:
        BLOCK
    else:
        BLOCK2

which is semantically equivalent to::

    iter = (ITER)
    iter = await type(iter).__aiter__(iter)
    running = True
    while running:
        try:
            TARGET = await type(iter).__anext__(iter)
        except StopAsyncIteration:
            running = False
        else:
            BLOCK
    else:
        BLOCK2


It is an error to pass a regular iterable without ``__aiter__`` method
to ``async for``.  It is a ``SyntaxError`` to use ``async for`` outside
of a coroutine.

As for with regular ``for`` statement, ``async for`` has an optional
``else`` clause.


Example 1
'''''''''

With asynchronous iteration protocol it is possible to asynchronously
buffer data during iteration::

    async for data in cursor:
        ...

Where ``cursor`` is an asynchronous iterator that prefetches ``N`` rows
of data from a database after every ``N`` iterations.

The following code illustrates new asynchronous iteration protocol::

    class Cursor:
        def __init__(self):
            self.buffer = collections.deque()

        def _prefetch(self):
            ...

        async def __aiter__(self):
            return self

        async def __anext__(self):
            if not self.buffer:
                self.buffer = await self._prefetch()
                if not self.buffer:
                    raise StopAsyncIteration
            return self.buffer.popleft()

then the ``Cursor`` class can be used as follows::

    async for row in Cursor():
        print(row)

which would be equivalent to the following code::

    i = await Cursor().__aiter__()
    while True:
        try:
            row = await i.__anext__()
        except StopAsyncIteration:
            break
        else:
            print(row)


Example 2
'''''''''

The following is a utility class that transforms a regular iterable to
an asynchronous one.  While this is not a very useful thing to do, the
code illustrates the relationship between regular and asynchronous
iterators.

::

    class AsyncIteratorWrapper:
        def __init__(self, obj):
            self._it = iter(obj)

        async def __aiter__(self):
            return self

        async def __anext__(self):
            try:
                value = next(self._it)
            except StopIteration:
                raise StopAsyncIteration
            return value

    async for item in AsyncIteratorWrapper("abc"):
        print(item)


Why StopAsyncIteration?
'''''''''''''''''''''''

Coroutines are still based on generators internally.  So, before PEP
479, there was no fundamental difference between

::

    def g1():
        yield from fut
        return 'spam'

and

::

    def g2():
        yield from fut
        raise StopIteration('spam')

And since PEP 479 is accepted and enabled by default for coroutines,
the following example will have its ``StopIteration`` wrapped into a
``RuntimeError``

::

    async def a1():
        await fut
        raise StopIteration('spam')

The only way to tell the outside code that the iteration has ended is
to raise something other than ``StopIteration``.  Therefore, a new
built-in exception class ``StopAsyncIteration`` was added.

Moreover, with semantics from PEP 479, all ``StopIteration`` exceptions
raised in coroutines are wrapped in ``RuntimeError``.


Debugging Features
------------------

One of the most frequent mistakes that people make when using
generators as coroutines is forgetting to use ``yield from``::

    @asyncio.coroutine
    def useful():
        asyncio.sleep(1) # this will do noting without 'yield from'

For debugging this kind of mistakes there is a special debug mode in
asyncio, in which ``@coroutine`` decorator wraps all functions with a
special object with a destructor logging a warning.  Whenever a wrapped
generator gets garbage collected, a detailed logging message is
generated with information about where exactly the decorator function
was defined, stack trace of where it was collected, etc.  Wrapper
object also provides a convenient ``__repr__`` function with detailed
information about the generator.

The only problem is how to enable these debug capabilities.  Since
debug facilities should be a no-op in production mode, ``@coroutine``
decorator makes the decision of whether to wrap or not to wrap based on
an OS environment variable ``PYTHONASYNCIODEBUG``.  This way it is
possible to run asyncio programs with asyncio's own functions
instrumented.  ``EventLoop.set_debug``, a different debug facility, has
no impact on ``@coroutine`` decorator's behavior.

With this proposal, coroutines is a native, distinct from generators,
concept. New methods ``set_coroutine_wrapper`` and
``get_coroutine_wrapper`` are added to the ``sys`` module, with which
frameworks can provide advanced debugging facilities.

It is also important to make coroutines as fast and efficient as
possible, therefore there are no debug features enabled by default.

Example::

    async def debug_me():
        await asyncio.sleep(1)

    def async_debug_wrap(generator):
        return asyncio.AsyncDebugWrapper(generator)

    sys.set_coroutine_wrapper(async_debug_wrap)

    debug_me()  # <- this line will likely GC the coroutine object and
                # trigger AsyncDebugWrapper's code.

    assert isinstance(debug_me(), AsyncDebugWrapper)

    sys.set_coroutine_wrapper(None) # <- this unsets any
                                    #    previously set wrapper
    assert not isinstance(debug_me(), AsyncDebugWrapper)

If ``sys.set_coroutine_wrapper()`` is called twice, the new wrapper
replaces the previous wrapper.  ``sys.set_coroutine_wrapper(None)``
unsets the wrapper.


Glossary
========

:Coroutine:
    A coroutine function, or just "coroutine", is declared with ``async
    def``. It uses ``await`` and ``return value``; see `New Coroutine
    Declaration Syntax`_ for details.

:Coroutine object:
    Returned from a coroutine function. See `Await Expression`_ for
    details.

:Future-like object:
    An object with an ``__await__`` method.  Can be consumed by an
    ``await`` expression in a coroutine. A coroutine waiting for a
    Future-like object is suspended until the Future-like object's
    ``__await__`` completes, and returns the result.  See `Await
    Expression`_ for details.

:Awaitable:
    A *Future-like* object or a *coroutine object*.  See `Await
    Expression`_ for details.

:Generator-based coroutine:
    Coroutines based in generator syntax.  Most common example is
    ``@asyncio.coroutine``.

:Asynchronous context manager:
   An asynchronous context manager has ``__aenter__`` and ``__aexit__``
   methods and can be used with ``async with``.  See `Asynchronous
   Context Managers and "async with"`_ for details.

:Asynchronous iterable:
    An object with an ``__aiter__`` method, which must return an
    *asynchronous iterator* object.  Can be used with ``async for``.
    See `Asynchronous Iterators and "async for"`_ for details.

:Asynchronous iterator:
    An asynchronous iterator has an ``__anext__`` method.  See
    `Asynchronous Iterators and "async for"`_ for details.


List of functions and methods
=============================

================= =================================== =================
Method            Can contain                         Can't contain
================= =================================== =================
async def func    await, return value                 yield, yield from
async def __a*__  await, return value                 yield, yield from
def __a*__        return awaitable                    await
def __await__     yield, yield from, return iterable  await
generator         yield, yield from, return value     await
================= =================================== =================

Where:

* "async def func": coroutine;

* "async def __a*__": ``__aiter__``, ``__anext__``, ``__aenter__``,
  ``__aexit__`` defined with the ``async`` keyword;

* "def __a*__": ``__aiter__``, ``__anext__``, ``__aenter__``,
  ``__aexit__`` defined without the ``async`` keyword, must return an
  *awaitable*;

* "def __await__": ``__await__`` method to implement *Future-like*
  objects;

* generator: a "regular" generator, function defined with ``def`` and
  which contains a least one ``yield`` or ``yield from`` expression.


Transition Plan
===============

To avoid backwards compatibility issues with ``async`` and ``await``
keywords, it was decided to modify ``tokenizer.c`` in such a way, that
it:

* recognizes ``async def`` name tokens combination (start of a
  coroutine);

* keeps track of regular functions and coroutines;

* replaces ``'async'`` token with ``ASYNC`` and ``'await'`` token with
  ``AWAIT`` when in the process of yielding tokens for coroutines.

This approach allows for seamless combination of new syntax features
(all of them available only in ``async`` functions) with any existing
code.

An example of having "async def" and "async" attribute in one piece of
code::

    class Spam:
        async = 42

    async def ham():
        print(getattr(Spam, 'async'))

    # The coroutine can be executed and will print '42'


Backwards Compatibility
-----------------------

This proposal preserves 100% backwards compatibility.


Grammar Updates
---------------

Grammar changes are also fairly minimal::

    await_expr: AWAIT test
    await_stmt: await_expr

    decorated: decorators (classdef | funcdef | async_funcdef)
    async_funcdef: ASYNC funcdef

    async_stmt: ASYNC (funcdef | with_stmt | for_stmt)

    compound_stmt: (if_stmt | while_stmt | for_stmt | try_stmt |
                    with_stmt | funcdef | classdef | decorated |
                    async_stmt)

    flow_stmt: (break_stmt | continue_stmt | return_stmt |
                raise_stmt | yield_stmt | await_stmt)

    atom: ('(' [yield_expr|await_expr|testlist_comp] ')' |
          '[' [testlist_comp] ']' |
          '{' [dictorsetmaker] '}' |
          NAME | NUMBER | STRING+ | '...' | 'None' | 'True' | 'False’)

    expr_stmt: testlist_star_expr
                    (augassign (yield_expr|await_expr|testlist) |
                    ('=' (yield_expr|await_expr|testlist_star_expr))*)


Transition Period Shortcomings
------------------------------

There is just one.

Until ``async`` and ``await`` are not proper keywords, it is not
possible (or at least very hard) to fix ``tokenizer.c`` to recognize
them on the **same line** with ``def`` keyword::

    # async and await will always be parsed as variables

    async def outer():                             # 1
        def nested(a=(await fut)):
            pass

    async def foo(): return (await fut)            # 2

Since ``await`` and ``async`` in such cases are parsed as ``NAME``
tokens, a ``SyntaxError`` will be raised.

To workaround these issues, the above examples can be easily rewritten
to a more readable form::

    async def outer():                             # 1
        a_default = await fut
        def nested(a=a_default):
            pass

    async def foo():                               # 2
        return (await fut)

This limitation will go away as soon as ``async`` and ``await`` ate
proper keywords.  Or if it's decided to use a future import for this
PEP.


Deprecation Plans
-----------------

``async`` and ``await`` names will be softly deprecated in CPython 3.5
and 3.6. In 3.7 we will transform them to proper keywords.  Making
``async`` and ``await`` proper keywords before 3.7 might make it harder
for people to port their code to Python 3.


asyncio
-------

``asyncio`` module was adapted and tested to work with coroutines and
new statements.  Backwards compatibility is 100% preserved.

The required changes are mainly:

1. Modify ``@asyncio.coroutine`` decorator to use new
   ``types.coroutine()`` function.

2. Add ``__await__ = __iter__`` line to ``asyncio.Future`` class.

3. Add ``ensure_task()`` as an alias for ``async()`` function.
   Deprecate ``async()`` function.


Design Considerations
=====================

PEP 3152
--------

PEP 3152 by Gregory Ewing proposes a different mechanism for coroutines
(called "cofunctions").  Some key points:

1. A new keyword ``codef`` to declare a *cofunction*.  *Cofunction* is
   always a generator, even if there is no ``cocall`` expressions
   inside it.  Maps to ``async def`` in this proposal.

2. A new keyword ``cocall`` to call a *cofunction*.  Can only be used
   inside a *cofunction*.  Maps to ``await`` in this proposal (with
   some differences, see below.)

3. It is not possible to call a *cofunction* without a ``cocall``
   keyword.

4. ``cocall`` grammatically requires parentheses after it::

    atom: cocall | <existing alternatives for atom>
    cocall: 'cocall' atom cotrailer* '(' [arglist] ')'
    cotrailer: '[' subscriptlist ']' | '.' NAME

5. ``cocall f(*args, **kwds)`` is semantically equivalent to
   ``yield from f.__cocall__(*args, **kwds)``.

Differences from this proposal:

1. There is no equivalent of ``__cocall__`` in this PEP, which is
   called and its result is passed to ``yield from`` in the ``cocall``
   expression. ``await`` keyword expects an *awaitable* object,
   validates the type, and executes ``yield from`` on it.  Although,
   ``__await__`` method is similar to ``__cocall__``, but is only used
   to define *Future-like* objects.

2. ``await`` is defined in almost the same way as ``yield from`` in the
   grammar (it is later enforced that ``await`` can only be inside
   ``async def``).  It is possible to simply write ``await future``,
   whereas ``cocall`` always requires parentheses.

3. To make asyncio work with PEP 3152 it would be required to modify
   ``@asyncio.coroutine`` decorator to wrap all functions in an object
   with a ``__cocall__`` method.  To call *cofunctions* from existing
   generator-based coroutines it would be required to use ``costart``
   built-in.  In this proposal ``@asyncio.coroutine`` simply sets
   ``CO_COROUTINE`` on the wrapped function's code object and
   everything works automatically.

4. Since it is impossible to call a *cofunction* without a ``cocall``
   keyword, it automatically prevents the common mistake of forgetting
   to use ``yield from`` on generator-based coroutines.  This proposal
   addresses this problem with a different approach, see `Debugging
   Features`_.

5. A shortcoming of requiring a ``cocall`` keyword to call a coroutine
   is that if is decided to implement coroutine-generators --
   coroutines with ``yield`` or ``async yield`` expressions -- we
   wouldn't need a ``cocall`` keyword to call them.  So we'll end up
   having ``__cocall__`` and no ``__call__`` for regular coroutines,
   and having ``__call__`` and no ``__cocall__`` for coroutine-
   generators.

6. Requiring parentheses grammatically also introduces a whole lot
   of new problems.

   Code like the following::

       await fut
       await function_returning_future()
       await asyncio.gather(coro1(arg1, arg2), coro2(arg1, arg2))

    would look like::

       cocall fut()  # or cocall costart(fut)
       cocall (function_returning_future())()
       cocall asyncio.gather(costart(coro1, arg1, arg2),
                             costart(coro2, arg1, arg2))

7. There are no equivalents of ``async for`` and ``async with`` in PEP
   3152.


Coroutine-generators
--------------------

With ``async for`` keyword it is desirable to have a concept of a
*coroutine-generator* -- a coroutine with ``yield`` and ``yield from``
expressions.  To avoid any ambiguity with regular generators, we would
likely require to have an ``async`` keyword before ``yield``, and
``async yield from`` would raise a ``StopAsyncIteration`` exception.

While it is possible to implement coroutine-generators, we believe that
they are out of scope of this proposal.  It is an advanced concept that
should be carefully considered and balanced, with a non-trivial changes
in the implementation of current generator objects.  This is a matter
for a separate PEP.


No implicit wrapping in Futures
-------------------------------

There is a proposal to add similar mechanism to ECMAScript 7 [2]_.  A
key difference is that JavaScript "async functions" always return a
Promise. While this approach has some advantages, it also implies that
a new Promise object is created on each "async function" invocation.

We could implement a similar functionality in Python, by wrapping all
coroutines in a Future object, but this has the following
disadvantages:

1. Performance.  A new Future object would be instantiated on each
   coroutine call.  Moreover, this makes implementation of ``await``
   expressions slower (disabling optimizations of ``yield from``).

2. A new built-in ``Future`` object would need to be added.

3. Coming up with a generic ``Future`` interface that is usable for any
   use case in any framework is a very hard to solve problem.

4. It is not a feature that is used frequently, when most of the code
   is coroutines.


Why "async" and "await" keywords
--------------------------------

async/await is not a new concept in programming languages:

* C# has it since long time ago [5]_;

* proposal to add async/await in ECMAScript 7 [2]_;
  see also Traceur project [9]_;

* Facebook's Hack/HHVM [6]_;

* Google's Dart language [7]_;

* Scala [8]_;

* proposal to add async/await to C++ [10]_;

* and many other less popular languages.

This is a huge benefit, as some users already have experience with
async/await, and because it makes working with many languages in one
project easier (Python with ECMAScript 7 for instance).


Why "__aiter__" is a coroutine
------------------------------

In principle, ``__aiter__`` could be a regular function.  There are
several good reasons to make it a coroutine:

* as most of the ``__anext__``, ``__aenter__``, and ``__aexit__``
  methods are coroutines, users would often make a mistake defining it
  as ``async`` anyways;

* there might be a need to run some asynchronous operations in
  ``__aiter__``, for instance to prepare DB queries or do some file
  operation.


Importance of "async" keyword
-----------------------------

While it is possible to just implement ``await`` expression and treat
all functions with at least one ``await`` as coroutines, this approach
makes APIs design, code refactoring and its long time support harder.

Let's pretend that Python only has ``await`` keyword::

    def useful():
        ...
        await log(...)
        ...

    def important():
        await useful()

If ``useful()`` function is refactored and someone removes all
``await`` expressions from it, it would become a regular python
function, and all code that depends on it, including ``important()``
would be broken.  To mitigate this issue a decorator similar to
``@asyncio.coroutine`` has to be introduced.


Why "async def"
---------------

For some people bare ``async name(): pass`` syntax might look more
appealing than ``async def name(): pass``.  It is certainly easier to
type.  But on the other hand, it breaks the symmetry between ``async
def``, ``async with`` and ``async for``, where ``async`` is a modifier,
stating that the statement is asynchronous.  It is also more consistent
with the existing grammar.


Why "async def" and not "def async"
-----------------------------------

``async`` keyword is a *statement qualifier*.  A good analogy to it are
"static", "public", "unsafe" keywords from other languages.  "async
for" is an asynchronous "for" statement, "async with" is an
asynchronous "with" statement, "async def" is an asynchronous function.

Having "async" after the main statement keyword might introduce some
confusion, like "for async item in iterator" can be read as "for each
asynchronous item in iterator".

Having ``async`` keyword before ``def``, ``with`` and ``for`` also
makes the language grammar simpler.  And "async def" better separates
coroutines from regular functions visually.


Why not a __future__ import
---------------------------

``__future__`` imports are inconvenient and easy to forget to add.
Also, they are enabled for the whole source file.  Consider that there
is a big project with a popular module named "async.py".  With future
imports it is required to either import it using ``__import__()`` or
``importlib.import_module()`` calls, or to rename the module.  The
proposed approach makes it possible to continue using old code and
modules without a hassle, while coming up with a migration plan for
future python versions.


Why magic methods start with "a"
--------------------------------

New asynchronous magic methods ``__aiter__``, ``__anext__``,
``__aenter__``, and ``__aexit__`` all start with the same prefix "a".
An alternative proposal is to use "async" prefix, so that ``__aiter__``
becomes ``__async_iter__``. However, to align new magic methods with
the existing ones, such as ``__radd__`` and ``__iadd__`` it was decided
to use a shorter version.


Why not reuse existing magic names
----------------------------------

An alternative idea about new asynchronous iterators and context
managers was to reuse existing magic methods, by adding an ``async``
keyword to their declarations::

    class CM:
        async def __enter__(self): # instead of __aenter__
            ...

This approach has the following downsides:

* it would not be possible to create an object that works in both
  ``with`` and ``async with`` statements;

* it would look confusing and would require some implicit magic behind
  the scenes in the interpreter;

* one of the main points of this proposal is to make coroutines as
  simple and foolproof as possible.


Comprehensions
--------------

For the sake of restricting the broadness of this PEP there is no new
syntax for asynchronous comprehensions.  This should be considered in a
separate PEP, if there is a strong demand for this feature.


Async lambdas
-------------

Lambda coroutines are not part of this proposal.  In this proposal they
would look like ``async lambda(parameters): expression``.  Unless there
is a strong demand to have them as part of this proposal, it is
recommended to consider them later in a separate PEP.


Performance
===========

Overall Impact
--------------

This proposal introduces no observable performance impact.  Here is an
output of python's official set of benchmarks [4]_:

::

    python perf.py -r -b default ../cpython/python.exe ../cpython-aw/python.exe

    [skipped]

    Report on Darwin ysmac 14.3.0 Darwin Kernel Version 14.3.0:
    Mon Mar 23 11:59:05 PDT 2015; root:xnu-2782.20.48~5/RELEASE_X86_64
    x86_64 i386

    Total CPU cores: 8

    ### etree_iterparse ###
    Min: 0.365359 -> 0.349168: 1.05x faster
    Avg: 0.396924 -> 0.379735: 1.05x faster
    Significant (t=9.71)
    Stddev: 0.01225 -> 0.01277: 1.0423x larger

    The following not significant results are hidden, use -v to show them:
    django_v2, 2to3, etree_generate, etree_parse, etree_process, fastpickle,
    fastunpickle, json_dump_v2, json_load, nbody, regex_v8, tornado_http.


Tokenizer modifications
-----------------------

There is no observable slowdown of parsing python files with the
modified tokenizer: parsing of one 12Mb file
(``Lib/test/test_binop.py`` repeated 1000 times) takes the same amount
of time.


async/await
-----------

The following micro-benchmark was used to determine performance
difference between "async" functions and generators::

    import sys
    import time

    def binary(n):
        if n <= 0:
            return 1
        l = yield from binary(n - 1)
        r = yield from binary(n - 1)
        return l + 1 + r

    async def abinary(n):
        if n <= 0:
            return 1
        l = await abinary(n - 1)
        r = await abinary(n - 1)
        return l + 1 + r

    def timeit(gen, depth, repeat):
        t0 = time.time()
        for _ in range(repeat):
            list(gen(depth))
        t1 = time.time()
        print('{}({}) * {}: total {:.3f}s'.format(
            gen.__name__, depth, repeat, t1-t0))

The result is that there is no observable performance difference.
Minimum timing of 3 runs

::

    abinary(19) * 30: total 12.985s
    binary(19) * 30: total 12.953s

Note that depth of 19 means 1,048,575 calls.


Reference Implementation
========================

The reference implementation can be found here: [3]_.

List of high-level changes and new protocols
--------------------------------------------

1. New syntax for defining coroutines: ``async def`` and new ``await``
   keyword.

2. New ``__await__`` method for Future-like objects.

3. New syntax for asynchronous context managers: ``async with``.  And
   associated protocol with ``__aenter__`` and ``__aexit__`` methods.

4. New syntax for asynchronous iteration: ``async for``.  And
   associated protocol with ``__aiter__``, ``__aexit__`` and new built-
   in exception ``StopAsyncIteration``.

5. New AST nodes: ``AsyncFunctionDef``, ``AsyncFor``, ``AsyncWith``,
   ``Await``.

6. New functions: ``sys.set_coroutine_wrapper(callback)``,
   ``sys.get_coroutine_wrapper()``, and ``types.coroutine(gen)``.

7. New ``CO_COROUTINE`` bit flag for code objects.

While the list of changes and new things is not short, it is important
to understand, that most users will not use these features directly.
It is intended to be used in frameworks and libraries to provide users
with convenient to use and unambiguous APIs with ``async def``,
``await``, ``async for`` and ``async with`` syntax.


Working example
---------------

All concepts proposed in this PEP are implemented [3]_ and can be
tested.

::

    import asyncio

    async def echo_server():
        print('Serving on localhost:8000')
        await asyncio.start_server(handle_connection,
                                   'localhost', 8000)

    async def handle_connection(reader, writer):
        print('New connection...')

        while True:
            data = await reader.read(8192)

            if not data:
                break

            print('Sending {:.10}... back'.format(repr(data)))
            writer.write(data)

    loop = asyncio.get_event_loop()
    loop.run_until_complete(echo_server())
    try:
        loop.run_forever()
    finally:
        loop.close()


References
==========

.. [1] https://docs.python.org/3/library/asyncio-task.html#asyncio.coroutine

.. [2] http://wiki.ecmascript.org/doku.php?id=strawman:async_functions

.. [3] https://github.com/1st1/cpython/tree/await

.. [4] https://hg.python.org/benchmarks

.. [5] https://msdn.microsoft.com/en-us/library/hh191443.aspx

.. [6] http://docs.hhvm.com/manual/en/hack.async.php

.. [7] https://www.dartlang.org/articles/await-async/

.. [8] http://docs.scala-lang.org/sips/pending/async.html

.. [9] https://github.com/google/traceur-compiler/wiki/LanguageFeatures#async-functions-experimental

.. [10] http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3722.pdf (PDF)


Acknowledgments
===============

I thank Guido van Rossum, Victor Stinner, Elvis Pranskevichus, Andrew
Svetlov, and Łukasz Langa for their initial feedback.


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: