gh-143055: address review (fix throw() arity crash, doc precision)

- async_gen_unpack_throw: validate arity with _PyArg_CheckPositional so that
  calling throw() with no arguments on the internal wrapper (reachable via
  ag_await while suspended at the delegation) raises TypeError instead of
  crashing the interpreter via gen_set_exception(NULL, ...).
- Correct the whatsnew/NEWS/reference wording: an async generator
  expression's aclose() throws GeneratorExit into the sub-iterator via its
  throw(), rather than calling close().
- Add a regression test for the throw() arity check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: graingert

Doc/reference/expressions.rst

@@ -895,9 +895,10 @@ In a generator expression, a starred expression is delegated to using
 :keyword:`yield from <yield>` semantics: values sent into the generator with
 :meth:`~generator.send` and exceptions thrown in with :meth:`~generator.throw`
 are forwarded to the sub-iterator currently being unpacked.  The same applies
-to asynchronous generator expressions, where :meth:`~agen.asend`,
-:meth:`~agen.athrow` and :meth:`~agen.aclose` are forwarded to the
-(synchronous) sub-iterator.
+to asynchronous generator expressions, where :meth:`~agen.asend` is forwarded
+to the (synchronous) sub-iterator's :meth:`~generator.send`, and
+:meth:`~agen.athrow` and :meth:`~agen.aclose` to its :meth:`~generator.throw`
+(:meth:`~agen.aclose` throwing :exc:`GeneratorExit`).
 
 .. versionadded:: 3.15
 

Doc/whatsnew/3.16.rst

@@ -80,11 +80,11 @@ Other language changes
   :keyword:`yield from <yield>` semantics.  Values sent with
   :meth:`~generator.send` and exceptions thrown with
   :meth:`~generator.throw` are forwarded to the sub-iterator, and the same
-  applies to asynchronous generator expressions, where
-  :meth:`~agen.asend`, :meth:`~agen.athrow` and :meth:`~agen.aclose`
-  are forwarded to the (synchronous) sub-iterator's
-  :meth:`~generator.send`, :meth:`~generator.throw` and
-  :meth:`~generator.close`.
+  applies to asynchronous generator expressions: :meth:`~agen.asend` is
+  forwarded to the (synchronous) sub-iterator's :meth:`~generator.send`,
+  while :meth:`~agen.athrow` and :meth:`~agen.aclose` are forwarded to its
+  :meth:`~generator.throw` (:meth:`~agen.aclose` throwing
+  :exc:`GeneratorExit`, as :meth:`generator.close` does).
   (Contributed in :gh:`143055`.)
 
 

Lib/test/test_unpack_ex.py

@@ -901,6 +901,20 @@ def sub():
         self._run(agen.aclose())
         self.assertEqual(closed, [True])
 
+    def test_unpack_helper_throw_requires_argument(self):
+        # The internal sync-iterable wrapper is reachable via ag_await while
+        # suspended at the delegation; throw() must validate its arity rather
+        # than crash (gh-143055).
+        agen = (*[1, 2, 3] async for _ in self._aiter([0]))
+        self._run(agen.asend(None))
+        wrapper = agen.ag_await
+        self.assertIsNotNone(wrapper)
+        with self.assertRaises(TypeError):
+            wrapper.throw()
+        # A valid exception is still accepted and propagates out.
+        with self.assertRaises(ValueError):
+            wrapper.throw(ValueError('boom'))
+
     def test_unpacking_async_iterable_is_a_type_error(self):
         # ``*`` unpacking is synchronous; async iterables cannot be unpacked.
         async def agen_fn():

Misc/NEWS.d/next/Core_and_Builtins/2026-06-29-12-00-00.gh-issue-143055.Yd8fG2.rst

@@ -3,7 +3,7 @@ now delegates to the sub-iterable using :keyword:`yield from <yield>`
 semantics, so that values sent with :meth:`~generator.send` and exceptions
 thrown with :meth:`~generator.throw` are forwarded to the sub-iterator.  This
 also works in asynchronous generator expressions, where
-:meth:`~agen.asend`, :meth:`~agen.athrow` and :meth:`~agen.aclose`
-are forwarded to the (synchronous) sub-iterator's
-:meth:`~generator.send`, :meth:`~generator.throw` and
-:meth:`~generator.close`.
+:meth:`~agen.asend` is forwarded to the (synchronous) sub-iterator's
+:meth:`~generator.send`, and :meth:`~agen.athrow` and :meth:`~agen.aclose`
+are forwarded to its :meth:`~generator.throw` (:meth:`~agen.aclose` throwing
+:exc:`GeneratorExit`).

Objects/genobject.c

@@ -2351,6 +2351,9 @@ async_gen_unpack_am_send(PyObject *op, PyObject *arg, PyObject **presult)
 static PyObject *
 async_gen_unpack_throw(PyObject *op, PyObject *const *args, Py_ssize_t nargs)
 {
+    if (!_PyArg_CheckPositional("throw", nargs, 1, 3)) {
+        return NULL;
+    }
     PyAsyncGenUnpack *o = _PyAsyncGenUnpack_CAST(op);
     PyObject *meth;
     if (PyObject_GetOptionalAttr(o->agu_iterator, &_Py_ID(throw), &meth) < 0) {
@@ -2361,7 +2364,7 @@ async_gen_unpack_throw(PyObject *op, PyObject *const *args, Py_ssize_t nargs)
            it here.  This mirrors how `yield from` behaves when throwing into
            a subiterator that does not define throw(): the exception
            propagates out of the delegation. */
-        PyObject *typ = nargs >= 1 ? args[0] : NULL;
+        PyObject *typ = args[0];
         PyObject *val = nargs >= 2 ? args[1] : NULL;
         PyObject *tb = nargs >= 3 ? args[2] : NULL;
         gen_set_exception(typ, val, tb);