Issue 24180: Documentation for PEP 492 changes.

4 files changed, 105 insertions, 3 deletions

diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 8a71259..28ba430 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -33,9 +33,9 @@ The collections module offers the following :term:`ABCs <abstract base class>`:
 
 .. tabularcolumns:: |l|L|L|L|
 
-=========================  =====================  ======================  ====================================================
+========================== ====================== ======================= ====================================================
 ABC                        Inherits from          Abstract Methods        Mixin Methods
-=========================  =====================  ======================  ====================================================
+========================== ====================== ======================= ====================================================
 :class:`Container`                                ``__contains__``
 :class:`Hashable`                                 ``__hash__``
 :class:`Iterable`                                 ``__iter__``
@@ -81,7 +81,11 @@ ABC                        Inherits from          Abstract Methods        Mixin
 :class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
                            :class:`Set`                                   ``__iter__``
 :class:`ValuesView`        :class:`MappingView`                           ``__contains__``, ``__iter__``
-=========================  =====================  ======================  ====================================================
+:class:`Awaitable`                                ``__await__``
+:class:`Coroutine`                                ``send``, ``throw``     ``close``
+:class:`AsyncIterable`                            ``__aiter__``
+:class:`AsyncIterator`     :class:`AsyncIterable` ``__anext__``           ``__aiter__``
+========================== ====================== ======================= ====================================================
 
 
 .. class:: Container
@@ -134,6 +138,41 @@ ABC                        Inherits from          Abstract Methods        Mixin
 
    ABCs for mapping, items, keys, and values :term:`views <view>`.
 
+.. class:: Awaitable
+
+   ABC for classes that provide ``__await__`` method.  Instances
+   of such classes can be used in ``await`` expression.
+
+   :term:`coroutine` objects and instances of
+   :class:`~collections.abc.Coroutine` are too instances of this ABC.
+
+   .. versionadded:: 3.5
+
+.. class:: Coroutine
+
+   ABC for coroutine compatible classes that implement a subset of
+   generator methods defined in :pep:`342`, namely:
+   :meth:`~generator.send`, :meth:`~generator.throw` and
+   :meth:`~generator.close` methods.  All :class:`Coroutine` instances
+   are also instances of :class:`Awaitable`.  See also the definition
+   of :term:`coroutine`.
+
+   .. versionadded:: 3.5
+
+.. class:: AsyncIterable
+
+   ABC for classes that provide ``__aiter__`` method.  See also the
+   definition of :term:`asynchronous iterable`.
+
+   .. versionadded:: 3.5
+
+.. class:: AsyncIterator
+
+   ABC for classes that provide ``__aiter__`` and ``__anext__``
+   methods.  See also the definition of :term:`asynchronous iterator`.
+
+   .. versionadded:: 3.5
+
 
 These ABCs allow us to ask classes or instances if they provide
 particular functionality, for example::
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index e7768be..6162068 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -322,6 +322,14 @@ The following exceptions are the exceptions that are usually raised.
    .. versionchanged:: 3.5
       Introduced the RuntimeError transformation.
 
+.. exception:: StopAsyncIteration
+
+   Must be raised by :meth:`__anext__` method of an
+   :term:`asynchronous iterator` object to stop the iteration.
+
+   .. versionadded:: 3.5
+      See also :pep:`492`.
+
 .. exception:: SyntaxError
 
    Raised when the parser encounters a syntax error.  This may occur in an
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index d3cd1a8..b3b4dd8 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -266,6 +266,47 @@ attributes:
    Return true if the object is a generator.
 
 
+.. function:: iscoroutinefunction(object)
+
+   Return true if the object is a coroutine function.
+
+   Coroutine functions are defined with an ``async def`` syntax,
+   or are generators decorated with :func:`types.coroutine`
+   or :func:`asyncio.coroutine`.
+
+   The function will return false for plain python generator
+   functions.
+
+   See also :pep:`492`.
+
+   .. versionadded:: 3.5
+
+
+.. function:: iscoroutine(object)
+
+   Return true if the object is a coroutine.
+
+   Coroutines are results of calls of coroutine functions or
+   generator functions decorated with :func:`types.coroutine`
+   or :func:`asyncio.coroutine`.
+
+   The function will return false for plain python generators.
+
+   See also :class:`collections.abc.Coroutine` and :pep:`492`.
+
+   .. versionadded:: 3.5
+
+
+.. function:: isawaitable(object)
+
+   Return true if the object can be used in :keyword:`await`
+   expression.
+
+   See also :class:`collections.abc.Awaitable` and :pep:`492`.
+
+   .. versionadded:: 3.5
+
+
 .. function:: istraceback(object)
 
    Return true if the object is a traceback.
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 34fffe6..3fb0c9c 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -271,3 +271,17 @@ Additional Utility Classes and Functions
    attributes on the class with the same name (see Enum for an example).
 
    .. versionadded:: 3.4
+
+
+Coroutines Utility Functions
+----------------------------
+
+.. function:: coroutine(gen_func)
+
+   The function transforms a generator function to a :term:`coroutine function`,
+   so that it returns a :term:`coroutine` object.
+
+   *gen_func* is modified in-place, hence the function can be used as a
+   decorator.
+
+   .. versionadded:: 3.5