summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/glossary.rst7
-rw-r--r--Doc/reference/compound_stmts.rst2
-rw-r--r--Doc/reference/datamodel.rst48
-rw-r--r--Doc/whatsnew/3.5.rst13
4 files changed, 63 insertions, 7 deletions
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 75b380b..e7bcb6a 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -76,13 +76,12 @@ Glossary
asynchronous iterable
An object, that can be used in an :keyword:`async for` statement.
- Must return an :term:`awaitable` from its :meth:`__aiter__` method,
- which should in turn be resolved in an :term:`asynchronous iterator`
- object. Introduced by :pep:`492`.
+ Must return an :term:`asyncronous iterator` from its
+ :meth:`__aiter__` method. Introduced by :pep:`492`.
asynchronous iterator
An object that implements :meth:`__aiter__` and :meth:`__anext__`
- methods, that must return :term:`awaitable` objects.
+ methods. ``__anext__`` must return an :term:`awaitable` object.
:keyword:`async for` resolves awaitable returned from asynchronous
iterator's :meth:`__anext__` method until it raises
:exc:`StopAsyncIteration` exception. Introduced by :pep:`492`.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 8047673..2469422 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -726,7 +726,7 @@ The following code::
Is semantically equivalent to::
iter = (ITER)
- iter = await type(iter).__aiter__(iter)
+ iter = type(iter).__aiter__(iter)
running = True
while running:
try:
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 3ddbd62..493acaa 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2359,6 +2359,7 @@ generators, coroutines do not directly support iteration.
Coroutine objects are automatically closed using the above process when
they are about to be destroyed.
+.. _async-iterators:
Asynchronous Iterators
----------------------
@@ -2371,7 +2372,7 @@ Asynchronous iterators can be used in an :keyword:`async for` statement.
.. method:: object.__aiter__(self)
- Must return an *awaitable* resulting in an *asynchronous iterator* object.
+ Must return an *asynchronous iterator* object.
.. method:: object.__anext__(self)
@@ -2384,7 +2385,7 @@ An example of an asynchronous iterable object::
async def readline(self):
...
- async def __aiter__(self):
+ def __aiter__(self):
return self
async def __anext__(self):
@@ -2395,6 +2396,49 @@ An example of an asynchronous iterable object::
.. versionadded:: 3.5
+.. note::
+
+ .. versionchanged:: 3.5.2
+ Starting with CPython 3.5.2, ``__aiter__`` can directly return
+ :term:`asynchronous iterators <asynchronous iterator>`. Returning
+ an :term:`awaitable` object will result in a
+ :exc:`PendingDeprecationWarning`.
+
+ The recommended way of writing backwards compatible code in
+ CPython 3.5.x is to continue returning awaitables from
+ ``__aiter__``. If you want to avoid the PendingDeprecationWarning
+ and keep the code backwards compatible, the following decorator
+ can be used::
+
+ import functools
+ import sys
+
+ if sys.version_info < (3, 5, 2):
+ def aiter_compat(func):
+ @functools.wraps(func)
+ async def wrapper(self):
+ return func(self)
+ return wrapper
+ else:
+ def aiter_compat(func):
+ return func
+
+ Example::
+
+ class AsyncIterator:
+
+ @aiter_compat
+ def __aiter__(self):
+ return self
+
+ async def __anext__(self):
+ ...
+
+ Starting with CPython 3.6, the :exc:`PendingDeprecationWarning`
+ will be replaced with the :exc:`DeprecationWarning`.
+ In CPython 3.7, returning an awaitable from ``__aiter__`` will
+ result in a :exc:`RuntimeError`.
+
Asynchronous Context Managers
-----------------------------
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index 83d5ce6..2d7f8a4 100644
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -247,6 +247,19 @@ be used inside a coroutine function declared with :keyword:`async def`.
Coroutine functions are intended to be run inside a compatible event loop,
such as the :ref:`asyncio loop <asyncio-event-loop>`.
+
+.. note::
+
+ .. versionchanged:: 3.5.2
+ Starting with CPython 3.5.2, ``__aiter__`` can directly return
+ :term:`asynchronous iterators <asynchronous iterator>`. Returning
+ an :term:`awaitable` object will result in a
+ :exc:`PendingDeprecationWarning`.
+
+ See more details in the :ref:`async-iterators` documentation
+ section.
+
+
.. seealso::
:pep:`492` -- Coroutines with async and await syntax