diff options
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/glossary.rst | 7 | ||||
-rw-r--r-- | Doc/reference/compound_stmts.rst | 2 | ||||
-rw-r--r-- | Doc/reference/datamodel.rst | 48 | ||||
-rw-r--r-- | Doc/whatsnew/3.5.rst | 13 |
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 |