gh-157361: Implement anext() in Python instead of C

Include/internal/pycore_pylifecycle.h

@@ -26,6 +26,7 @@ extern int _Py_IsLocaleCoercionTarget(const char *ctype_loc);
 extern void _Py_InitVersion(void);
 extern PyStatus _PyFaulthandler_Init(int enable);
 extern PyObject * _PyBuiltin_Init(PyInterpreterState *interp);
+extern int _PyBuiltin_InitPythonFunctions(PyObject *dict);
 extern PyStatus _PySys_Create(
     PyThreadState *tstate,
     PyObject **sysmod_p);

Lib/_pybuiltins.py

@@ -0,0 +1,42 @@
+"""Builtins implemented in Python.
+
+This module is frozen into the interpreter and imported during startup,
+before the import system exists.  The names listed in ``__all__`` are
+copied into the ``builtins`` module.
+"""
+
+__all__ = ['anext']
+
+_NOT_GIVEN = sentinel("_NOT_GIVEN")
+
+
+def anext(async_iterator, default=_NOT_GIVEN, /):
+    """Return the next item from the async iterator.
+
+    If default is given and the async iterator is exhausted,
+    it is returned instead of raising StopAsyncIteration.
+    """
+    cls = type(async_iterator)
+    try:
+        # Looked up on the type, like the C slot am_anext.
+        anext_method = cls.__anext__
+    except AttributeError:
+        raise TypeError(
+            f"'{cls.__name__}' object is not an async iterator"
+        ) from None
+    awaitable = anext_method(async_iterator)
+    if default is _NOT_GIVEN:
+        return awaitable
+    return _anext_with_default(awaitable, default)
+
+
+async def _anext_with_default(awaitable, default):
+    try:
+        return await awaitable
+    except StopAsyncIteration:
+        return default
+
+
+for _name in __all__:
+    globals()[_name].__module__ = 'builtins'
+del _name

Lib/test/test_asyncgen.py

@@ -2,6 +2,7 @@
 import types
 import unittest
 import contextlib
+import warnings
 
 from test.support.import_helper import import_module
 from test.support import gc_collect, requires_working_socket
@@ -709,7 +710,16 @@ def test_send():
         async def test_throw():
             p = ait_class()
             obj = anext(p, "completed")
-            self.assertRaises(SyntaxError, obj.throw, SyntaxError)
+            with warnings.catch_warnings():
+                # Throwing into the unstarted anext() coroutine leaves the
+                # inner __anext__() awaitable never awaited.
+                warnings.simplefilter("ignore", RuntimeWarning)
+                self.assertRaises(SyntaxError, obj.throw, SyntaxError)
+            if isinstance(p, types.AsyncGeneratorType):
+                # The never-run asend() already registered the async
+                # generator with the loop's finalizer; close it explicitly
+                # so no aclose() task is left pending at loop close.
+                await p.aclose()
             return "completed"
 
         result = self.loop.run_until_complete(test_throw())
@@ -1132,9 +1142,13 @@ async def agenfn():
                 yield 'aaa'
 
             agen = agenfn()
-            with contextlib.closing(anext(agen, "default").__await__()) as g:
-                with self.assertRaises(MyError):
-                    g.throw(MyError())
+            with warnings.catch_warnings():
+                # Throwing into the unstarted anext() coroutine leaves the
+                # inner asend() awaitable never awaited.
+                warnings.simplefilter("ignore", RuntimeWarning)
+                with contextlib.closing(anext(agen, "default").__await__()) as g:
+                    with self.assertRaises(MyError):
+                        g.throw(MyError())
 
         def run_test(test):
             with self.subTest('pure-Python anext()'):

Lib/test/test_asyncio/test_graph.py

@@ -148,6 +148,46 @@ async def main():
             'async generator CallStackTestBase.test_stack_async_gen.<locals>.gen()',
             stack_for_gen_nested_call[1])
 
+    async def test_stack_anext_default(self):
+        # anext() with a default wraps the awaitable in a coroutine, so the
+        # call graph of a suspended task sees through it into __anext__().
+
+        loop = asyncio.get_running_loop()
+        blocker = loop.create_future()
+
+        async def inner():
+            await blocker
+
+        class AIter:
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                await inner()
+                return 1
+
+        async def main():
+            await anext(AIter(), None)
+
+        task = asyncio.create_task(main(), name='anext task')
+        await asyncio.sleep(0)
+        try:
+            stack = capture_test_stack(fut=task)
+        finally:
+            blocker.set_result(None)
+            await task
+
+        self.assertEqual(stack[0], [
+            'T<anext task>',
+            [
+                'a inner',
+                'a __anext__',
+                'a _anext_with_default',
+                'a main',
+            ],
+            []
+        ])
+
     def test_ag_frame_used_for_async_generator(self):
         # Regression test for gh-148736: the ag_await branch of
         # _build_graph_for_future must read ag_frame, not cr_frame.

Lib/test/test_coroutines.py

@@ -1312,8 +1312,12 @@ async def __anext__(self):
             def __aiter__(self):
                 return self
 
-        with contextlib.closing(anext(A(), "a").__await__()) as anext_awaitable:
-            self.assertRaises(TypeError, anext_awaitable.close, 1)
+        with warnings.catch_warnings():
+            # Closing the unstarted anext() coroutine leaves the inner
+            # __anext__() coroutine never awaited.
+            warnings.simplefilter("ignore", RuntimeWarning)
+            with contextlib.closing(anext(A(), "a").__await__()) as anext_awaitable:
+                self.assertRaises(TypeError, anext_awaitable.close, 1)
 
     def test_with_1(self):
         class Manager:

Lib/test/test_importlib/util.py

@@ -69,7 +69,8 @@ def import_importlib(module_name):
     fresh = ('importlib',) if '.' in module_name else ()
     frozen = import_helper.import_fresh_module(module_name)
     source = import_helper.import_fresh_module(module_name, fresh=fresh,
-                                         blocked=('_frozen_importlib', '_frozen_importlib_external'))
+                                         blocked=('_frozen_importlib', '_frozen_importlib_external',
+                                                  '_pybuiltins'))
     return {'Frozen': frozen, 'Source': source}
 
 

Lib/test/test_inspect/test_inspect.py

@@ -6174,7 +6174,7 @@ def test_builtins_have_signatures(self):
                         "next", "vars"}
         no_signature |= needs_groups
         # These have unrepresentable parameter default values of NULL
-        unsupported_signature = {"anext", "aiter", "iter"}
+        unsupported_signature = {"aiter", "iter"}
         # These need *args support in Argument Clinic
         needs_varargs = {"min", "max", "__build_class__"}
         no_signature |= needs_varargs

Makefile.pre.in

@@ -1623,7 +1623,8 @@ Programs/_testembed: Programs/_testembed.o $(LINK_PYTHON_DEPS)
 BOOTSTRAP_HEADERS = \
 	Python/frozen_modules/importlib._bootstrap.h \
 	Python/frozen_modules/importlib._bootstrap_external.h \
-	Python/frozen_modules/zipimport.h
+	Python/frozen_modules/zipimport.h \
+	Python/frozen_modules/_pybuiltins.h
 
 Programs/_bootstrap_python.o: Programs/_bootstrap_python.c $(BOOTSTRAP_HEADERS) $(PYTHON_HEADERS)
 
@@ -1664,6 +1665,7 @@ FROZEN_FILES_IN = \
 		Lib/importlib/_bootstrap.py \
 		Lib/importlib/_bootstrap_external.py \
 		Lib/zipimport.py \
+		Lib/_pybuiltins.py \
 		Lib/abc.py \
 		Lib/codecs.py \
 		Lib/io.py \
@@ -1690,6 +1692,7 @@ FROZEN_FILES_OUT = \
 		Python/frozen_modules/importlib._bootstrap.h \
 		Python/frozen_modules/importlib._bootstrap_external.h \
 		Python/frozen_modules/zipimport.h \
+		Python/frozen_modules/_pybuiltins.h \
 		Python/frozen_modules/abc.h \
 		Python/frozen_modules/codecs.h \
 		Python/frozen_modules/io.h \
@@ -1735,6 +1738,9 @@ Python/frozen_modules/importlib._bootstrap_external.h: Lib/importlib/_bootstrap_
 Python/frozen_modules/zipimport.h: Lib/zipimport.py $(FREEZE_MODULE_BOOTSTRAP_DEPS)
 	$(FREEZE_MODULE_BOOTSTRAP) zipimport $(srcdir)/Lib/zipimport.py Python/frozen_modules/zipimport.h
 
+Python/frozen_modules/_pybuiltins.h: Lib/_pybuiltins.py $(FREEZE_MODULE_BOOTSTRAP_DEPS)
+	$(FREEZE_MODULE_BOOTSTRAP) _pybuiltins $(srcdir)/Lib/_pybuiltins.py Python/frozen_modules/_pybuiltins.h
+
 Python/frozen_modules/abc.h: Lib/abc.py $(FREEZE_MODULE_DEPS)
 	$(FREEZE_MODULE) abc $(srcdir)/Lib/abc.py Python/frozen_modules/abc.h
 

Misc/NEWS.d/next/Core_and_Builtins/2026-09-12-16-40-00.gh-issue-157361.anextpy.rst

@@ -0,0 +1,4 @@
+Implement :func:`anext` in Python instead of C, in a frozen ``_pybuiltins``
+module. The awaitable returned by ``anext(it, default)`` is now a plain
+coroutine, so introspection tools such as :func:`asyncio.print_call_graph`
+can see through it into :meth:`~object.__anext__`.