Issue 24180: Documentation for PEP 492 changes.
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 @@
.. 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 @@
: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 @@
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 @@
.. 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 @@
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 @@
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