bpo-31861: Provide aiter and anext builtins

Doc/glossary.rst

@@ -88,6 +88,11 @@ Glossary
       :ref:`the difference between arguments and parameters
       <faq-argument-vs-parameter>`, and :pep:`362`.
 
+   asynchronous callable
+      Any callable that returns an :term:`awaitable`. Examples include
+      :term:`coroutine functions <coroutine function>` and the built-in
+      :func:`anext` function.
+
    asynchronous context manager
       An object which controls the environment seen in an
       :keyword:`async with` statement by defining :meth:`__aenter__` and

Doc/library/functions.rst

@@ -12,31 +12,31 @@ are always available.  They are listed here in alphabetical order.
 +=========================+=======================+=======================+=========================+
 | |  **A**                | |  **E**              | |  **L**              | |  **R**                |
 | |  :func:`abs`          | |  :func:`enumerate`  | |  :func:`len`        | |  |func-range|_        |
-| |  :func:`all`          | |  :func:`eval`       | |  |func-list|_       | |  :func:`repr`         |
-| |  :func:`any`          | |  :func:`exec`       | |  :func:`locals`     | |  :func:`reversed`     |
-| |  :func:`ascii`        | |                     | |                     | |  :func:`round`        |
-| |                       | |  **F**              | |  **M**              | |                       |
-| |  **B**                | |  :func:`filter`     | |  :func:`map`        | |  **S**                |
-| |  :func:`bin`          | |  :func:`float`      | |  :func:`max`        | |  |func-set|_          |
-| |  :func:`bool`         | |  :func:`format`     | |  |func-memoryview|_ | |  :func:`setattr`      |
-| |  :func:`breakpoint`   | |  |func-frozenset|_  | |  :func:`min`        | |  :func:`slice`        |
-| |  |func-bytearray|_    | |                     | |                     | |  :func:`sorted`       |
-| |  |func-bytes|_        | |  **G**              | |  **N**              | |  :func:`staticmethod` |
-| |                       | |  :func:`getattr`    | |  :func:`next`       | |  |func-str|_          |
-| |  **C**                | |  :func:`globals`    | |                     | |  :func:`sum`          |
-| |  :func:`callable`     | |                     | |  **O**              | |  :func:`super`        |
-| |  :func:`chr`          | |  **H**              | |  :func:`object`     | |                       |
-| |  :func:`classmethod`  | |  :func:`hasattr`    | |  :func:`oct`        | |  **T**                |
-| |  :func:`compile`      | |  :func:`hash`       | |  :func:`open`       | |  |func-tuple|_        |
-| |  :func:`complex`      | |  :func:`help`       | |  :func:`ord`        | |  :func:`type`         |
-| |                       | |  :func:`hex`        | |                     | |                       |
-| |  **D**                | |                     | |  **P**              | |  **V**                |
-| |  :func:`delattr`      | |  **I**              | |  :func:`pow`        | |  :func:`vars`         |
-| |  |func-dict|_         | |  :func:`id`         | |  :func:`print`      | |                       |
-| |  :func:`dir`          | |  :func:`input`      | |  :func:`property`   | |  **Z**                |
-| |  :func:`divmod`       | |  :func:`int`        | |                     | |  :func:`zip`          |
-| |                       | |  :func:`isinstance` | |                     | |                       |
-| |                       | |  :func:`issubclass` | |                     | |  **_**                |
+| |  :func:`aiter`        | |  :func:`eval`       | |  |func-list|_       | |  :func:`repr`         |
+| |  :func:`all`          | |  :func:`exec`       | |  :func:`locals`     | |  :func:`reversed`     |
+| |  :func:`any`          | |                     | |                     | |  :func:`round`        |
+| |  :func:`anext`        | |  **F**              | |  **M**              | |                       |
+| |  :func:`ascii`        | |  :func:`filter`     | |  :func:`map`        | |  **S**                |
+| |                       | |  :func:`float`      | |  :func:`max`        | |  |func-set|_          |
+| |  **B**                | |  :func:`format`     | |  |func-memoryview|_ | |  :func:`setattr`      |
+| |  :func:`bin`          | |  |func-frozenset|_  | |  :func:`min`        | |  :func:`slice`        |
+| |  :func:`bool`         | |                     | |                     | |  :func:`sorted`       |
+| |  :func:`breakpoint`   | |  **G**              | |  **N**              | |  :func:`staticmethod` |
+| |  |func-bytearray|_    | |  :func:`getattr`    | |  :func:`next`       | |  |func-str|_          |
+| |  |func-bytes|_        | |  :func:`globals`    | |                     | |  :func:`sum`          |
+| |                       | |                     | |  **O**              | |  :func:`super`        |
+| |  **C**                | |  **H**              | |  :func:`object`     | |                       |
+| |  :func:`callable`     | |  :func:`hasattr`    | |  :func:`oct`        | |  **T**                |
+| |  :func:`chr`          | |  :func:`hash`       | |  :func:`open`       | |  |func-tuple|_        |
+| |  :func:`classmethod`  | |  :func:`help`       | |  :func:`ord`        | |  :func:`type`         |
+| |  :func:`compile`      | |  :func:`hex`        | |                     | |                       |
+| |  :func:`complex`      | |                     | |  **P**              | |  **V**                |
+| |                       | |  **I**              | |  :func:`pow`        | |  :func:`vars`         |
+| |  **D**                | |  :func:`id`         | |  :func:`print`      | |                       |
+| |  :func:`delattr`      | |  :func:`input`      | |  :func:`property`   | |  **Z**                |
+| |  |func-dict|_         | |  :func:`int`        | |                     | |  :func:`zip`          |
+| |  :func:`dir`          | |  :func:`isinstance` | |                     | |                       |
+| |  :func:`divmod`       | |  :func:`issubclass` | |                     | |  **_**                |
 | |                       | |  :func:`iter`       | |                     | |  :func:`__import__`   |
 +-------------------------+-----------------------+-----------------------+-------------------------+
 
@@ -61,6 +61,22 @@ are always available.  They are listed here in alphabetical order.
    If the argument is a complex number, its magnitude is returned.
 
 
+.. function:: aiter(object, [sentinel])
+
+   Return an :term:`asynchronous iterator` object. This is the async variant
+   of the :func:`iter` builtin, and behaves similarly.
+
+   If sentinel is omitted, then *object* must be an
+   :term:`asynchronous iterable` object, and :func:`aiter` returns an iterator
+   for it.
+
+   Otherwise, *object* must be an :term:`asynchronous callable`. When the
+   resulting async iterator is async iterated, the passed callable is
+   called and awaited and the values returned become the values produced
+   by the iterator. When the awaited return value is equal to sentinel,
+   the async iterator terminates with :exc:`StopAsyncIteration`.
+
+
 .. function:: all(iterable)
 
    Return ``True`` if all elements of the *iterable* are true (or if the iterable
@@ -73,6 +89,20 @@ are always available.  They are listed here in alphabetical order.
           return True
 
 
+.. awaitablefunction:: anext(async_iterator[, default])
+
+   When awaited, return the next item from the given :term:`asynchronous
+   iterator`, or *default* if given and the iterator is exhausted.
+
+   This is the async variant of the :func:`next` builtin, and behaves
+   similarly.
+
+   Immediately, call the :meth:`~object.__anext__` method of *async_iterator*,
+   then return an :term:`awaitable`. Awaiting this returns the next value of the
+   iterator. If *default* is given, it is returned if the iterator is exhausted,
+   otherwise :exc:`StopAsyncIteration` is raised.
+
+
 .. function:: any(iterable)
 
    Return ``True`` if any element of the *iterable* is true.  If the iterable

Include/abstract.h

@@ -324,6 +324,11 @@ PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj,
    returns itself. */
 PyAPI_FUNC(PyObject *) PyObject_GetIter(PyObject *);
 
+/* Takes an object and returns an async iterator for it.
+   This is typically a new iterator but if the argument is an async iterator,
+   this returns itself. */
+PyAPI_FUNC(PyObject *) PyObject_GetAiter(PyObject *);
+
 /* Returns 1 if the object 'obj' provides iterator protocols, and 0 otherwise.
 
    This function always succeeds. */

Include/cpython/abstract.h

@@ -331,6 +331,13 @@ PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
     (Py_TYPE(obj)->tp_iternext != NULL && \
      Py_TYPE(obj)->tp_iternext != &_PyObject_NextNotImplemented)
 
+#define PyAiter_Check(obj) \
+    (Py_TYPE(obj)->tp_as_async != NULL && \
+     Py_TYPE(obj)->tp_as_async->am_aiter != NULL && \
+     Py_TYPE(obj)->tp_as_async->am_aiter != &_PyObject_NextNotImplemented && \
+     Py_TYPE(obj)->tp_as_async->am_anext != NULL && \
+     Py_TYPE(obj)->tp_as_async->am_anext != &_PyObject_NextNotImplemented)
+
 /* === Sequence protocol ================================================ */
 
 /* Assume tp_as_sequence and sq_item exist and that 'i' does not

Include/iterobject.h

@@ -7,6 +7,9 @@ extern "C" {
 
 PyAPI_DATA(PyTypeObject) PySeqIter_Type;
 PyAPI_DATA(PyTypeObject) PyCallIter_Type;
+PyAPI_DATA(PyTypeObject) PyCallAsyncIter_Type;
+PyAPI_DATA(PyTypeObject) PyAsyncCallAwaitable_Type;
+PyAPI_DATA(PyTypeObject) PyAnextAwaitable_Type;
 
 #define PySeqIter_Check(op) Py_IS_TYPE(op, &PySeqIter_Type)
 
@@ -16,6 +19,8 @@ PyAPI_FUNC(PyObject *) PySeqIter_New(PyObject *);
 #define PyCallIter_Check(op) Py_IS_TYPE(op, &PyCallIter_Type)
 
 PyAPI_FUNC(PyObject *) PyCallIter_New(PyObject *, PyObject *);
+PyAPI_FUNC(PyObject *) PyCallAsyncIter_New(PyObject *, PyObject *);
+PyAPI_FUNC(PyObject *) PyAnextAwaitable_New(PyObject *, PyObject *);
 
 #ifdef __cplusplus
 }

Lib/test/test_asyncgen.py

@@ -372,6 +372,97 @@ def tearDown(self):
         self.loop = None
         asyncio.set_event_loop_policy(None)
 
+    def test_async_gen_anext(self):
+        async def gen():
+            yield 1
+            yield 2
+        g = gen()
+        async def consume():
+            results = []
+            results.append(await anext(g))
+            results.append(await anext(g))
+            results.append(await anext(g, 'buckle my shoe'))
+            return results
+        res = self.loop.run_until_complete(consume())
+        self.assertEqual(res, [1, 2, 'buckle my shoe'])
+        with self.assertRaises(StopAsyncIteration):
+            self.loop.run_until_complete(consume())
+
+    def test_async_gen_aiter(self):
+        async def gen():
+            yield 1
+            yield 2
+        g = gen()
+        async def consume():
+            return [i async for i in aiter(g)]
+        res = self.loop.run_until_complete(consume())
+        self.assertEqual(res, [1, 2])
+
+    def test_async_gen_aiter_class(self):
+        results = []
+        loop = self.loop
+        class Gen:
+            async def __aiter__(self):
+                yield 1
+                await asyncio.sleep(0.01)
+                yield 2
+        g = Gen()
+        async def consume():
+            ait = aiter(g)
+            while True:
+                try:
+                    results.append(await anext(ait))
+                except StopAsyncIteration:
+                    break
+        self.loop.run_until_complete(consume())
+        self.assertEqual(results, [1, 2])
+
+    def test_async_gen_aiter_2_arg(self):
+        async def gen():
+            yield 1
+            yield 2
+            yield 3
+        g = gen()
+        async def foo():
+            return await anext(g)
+        async def consume():
+            return [i async for i in aiter(foo, 3)]
+        res = self.loop.run_until_complete(consume())
+        self.assertEqual(res, [1, 2])
+
+    def test_async_aiter_callable(self):
+        v = 0
+        async def foo():
+            nonlocal v
+            v += 1
+            return v
+        async def consume():
+            return [i async for i in aiter(foo, 3)]
+        res = self.loop.run_until_complete(consume())
+        self.assertEqual(res, [1, 2])
+
+    def test_anext_bad_args(self):
+        self._test_bad_args(anext)
+
+    def test_aiter_bad_args(self):
+        self._test_bad_args(aiter)
+
+    def _test_bad_args(self, afn):
+        async def gen():
+            yield 1
+        async def call_with_no_args():
+            await afn()
+        async def call_with_3_args():
+            await afn(gen(), 1, 2)
+        async def call_with_bad_args():
+            await afn(1, gen())
+        with self.assertRaises(TypeError):
+            self.loop.run_until_complete(call_with_no_args())
+        with self.assertRaises(TypeError):
+            self.loop.run_until_complete(call_with_3_args())
+        with self.assertRaises(TypeError):
+            self.loop.run_until_complete(call_with_bad_args())
+
     async def to_list(self, gen):
         res = []
         async for i in gen:

Lib/test/test_inspect.py

@@ -3812,7 +3812,7 @@ def test_builtins_have_signatures(self):
         no_signature = set()
         # These need PEP 457 groups
         needs_groups = {"range", "slice", "dir", "getattr",
-                        "next", "iter", "vars"}
+                        "next", "iter", "anext", "aiter", "vars"}
         no_signature |= needs_groups
         # These need PEP 457 groups or a signature change to accept None
         needs_semantic_update = {"round"}

Lib/test/test_posix.py

@@ -1929,7 +1929,7 @@ def test_posix_spawnp(self):
 class TestPosixWeaklinking(unittest.TestCase):
     # These test cases verify that weak linking support on macOS works
     # as expected. These cases only test new behaviour introduced by weak linking,
-    # regular behaviour is tested by the normal test cases. 
+    # regular behaviour is tested by the normal test cases.
     #
     # See the section on Weak Linking in Mac/README.txt for more information.
     def setUp(self):

Misc/NEWS.d/next/Library/2018-08-24-01-08-09.bpo-31861.-q9RKJ.rst

@@ -0,0 +1,2 @@
+Add builtins.aiter and builtins.anext.
+Patch by Daniel Pope (@lordmauve), Joshua Bronson (@jab), and Justin Wang (@justin39).

Objects/abstract.c

@@ -2638,6 +2638,30 @@ PyObject_GetIter(PyObject *o)
     }
 }
 
+
+PyObject *
+PyObject_GetAiter(PyObject *o) {
+    PyTypeObject *t = Py_TYPE(o);
+    unaryfunc f;
+
+    f = t->tp_as_async->am_aiter;
+    if (f == NULL) {
+        return type_error("'%.200s' object is not async iterable", o);
+    }
+    else {
+        PyObject *it = (*f)(o);
+        if (it != NULL && !PyAiter_Check(it)) {
+            PyErr_Format(PyExc_TypeError,
+                         "aiter() returned non-async-iterator "
+                         "of type '%.100s'",
+                         Py_TYPE(it)->tp_name);
+            Py_DECREF(it);
+            it = NULL;
+        }
+        return it;
+    }
+}
+
 #undef PyIter_Check
 
 int PyIter_Check(PyObject *obj)