Address review comments

Reword the aiter() documentation like the iter() one, avoid using the name
"queue" for two different things in the example, describe every field of
the iterator structs separately, add calliter_exhaust() for symmetry with
acalliter_exhaust(), use bool and designated initializers in new code.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/functions.rst

@@ -68,8 +68,12 @@ are always available.  They are listed here in alphabetical order.
               aiter(callable, /, stop_value, *, stop_exception=StopAsyncIteration)
               aiter(callable, /, *, stop_exception)
 
-   Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
-   Equivalent to calling ``x.__aiter__()``.
+   Return an :term:`asynchronous iterator` object.
+   The first argument is interpreted very differently
+   depending on the presence of the other arguments.
+   Without other arguments,
+   the single argument must be an :term:`asynchronous iterable`,
+   and the result is equivalent to calling ``x.__aiter__()``.
 
    If *stop_value* or *stop_exception* is given,
    then the first argument must be a callable object.
@@ -86,8 +90,9 @@ are always available.  They are listed here in alphabetical order.
    *stop_exception* is an exception class or a tuple of exception classes.
    If *stop_value* is not specified,
    the iteration stops only when the callable raises an exception.
-   If the callable raises :exc:`StopAsyncIteration` which does not match
-   *stop_exception*, it is replaced with a :exc:`RuntimeError`,
+   If the callable raises :exc:`StopAsyncIteration`
+   which does not match *stop_exception*,
+   it is replaced with a :exc:`RuntimeError`,
    as for asynchronous generators (see :pep:`525`).
 
    For example, reading fixed-size chunks from an asynchronous stream
@@ -1195,13 +1200,15 @@ are always available.  They are listed here in alphabetical order.
    will call *callable* with no arguments for each call to its
    :meth:`~iterator.__next__` method; if the value returned is equal to
    *stop_value*, or if the call raises an exception matching *stop_exception*,
-   :exc:`StopIteration` will be raised, otherwise the value will be returned.
+   :exc:`StopIteration` will be raised, otherwise the value will
+   be returned.
 
    *stop_exception* is an exception class or a tuple of exception classes.
    If *stop_value* is not specified,
    the iteration stops only when the callable raises an exception.
-   If the callable raises :exc:`StopIteration` which does not match
-   *stop_exception*, it is replaced with a :exc:`RuntimeError`,
+   If the callable raises :exc:`StopIteration`
+   which does not match *stop_exception*,
+   it is replaced with a :exc:`RuntimeError`,
    as for generators (see :pep:`479`).
 
    See also :ref:`typeiter`.
@@ -1215,16 +1222,18 @@ are always available.  They are listed here in alphabetical order.
           for block in iter(partial(f.read, 64), b''):
               process_block(block)
 
-   *stop_exception* is useful for callables which report exhaustion by raising an
-   exception instead of returning a special value.
+   *stop_exception* is useful for callables
+   which report exhaustion by raising an exception
+   instead of returning a special value.
    For example, draining a queue::
 
-      from queue import Empty
-      for item in iter(queue.get_nowait, stop_exception=Empty):
+      import queue
+      for item in iter(input_queue.get_nowait, stop_exception=queue.Empty):
           process_item(item)
 
    .. versionchanged:: next
-      Added the *stop_exception* parameter and allowed passing *stop_value* by keyword.
+      Added the *stop_exception* parameter
+      and allowed passing *stop_value* by keyword.
 
 
 .. function:: len(object, /)

Lib/test/test_iter.py

@@ -93,7 +93,7 @@ def __call__(self):
         i = self.i
         self.i = i + 1
         if i > 100:
-            raise IndexError # Emergency stop
+            raise IndexError  # stops the iteration
         return i
 
 class EmptyIterClass:

Objects/iterobject.c

@@ -188,9 +188,8 @@ PyTypeObject PySeqIter_Type = {
 
 typedef struct {
     PyObject_HEAD
-    /* Both are set to NULL when the iterator is exhausted */
-    PyObject *it_callable;
-    PyObject *it_sentinel;  /* can be NULL */
+    PyObject *it_callable;  /* set to NULL when the iterator is exhausted */
+    PyObject *it_sentinel;  /* can be NULL, and is when exhausted */
     PyObject *it_stop_exc;  /* never NULL */
 } calliterobject;
 
@@ -220,6 +219,13 @@ PyCallIter_New(PyObject *callable, PyObject *sentinel)
     return _PyCallIter_NewEx(callable, sentinel, NULL);
 }
 
+static void
+calliter_exhaust(calliterobject *it)
+{
+    Py_CLEAR(it->it_callable);
+    Py_CLEAR(it->it_sentinel);
+}
+
 static void
 calliter_dealloc(PyObject *op)
 {
@@ -263,14 +269,12 @@ calliter_iternext(PyObject *op)
         }
 
         if (ok > 0) {
-            Py_CLEAR(it->it_callable);
-            Py_CLEAR(it->it_sentinel);
+            calliter_exhaust(it);
         }
     }
     else if (PyErr_ExceptionMatches(it->it_stop_exc)) {
         PyErr_Clear();
-        Py_CLEAR(it->it_callable);
-        Py_CLEAR(it->it_sentinel);
+        calliter_exhaust(it);
     }
     else if (PyErr_ExceptionMatches(PyExc_StopIteration)) {
         /* It would be mistaken for the end of the iteration (see PEP 479). */
@@ -620,9 +624,8 @@ PyAnextAwaitable_New(PyObject *awaitable, PyObject *default_value)
 
 typedef struct {
     PyObject_HEAD
-    /* Both are set to NULL when the iterator is exhausted */
-    PyObject *it_callable;
-    PyObject *it_sentinel;  /* can be NULL */
+    PyObject *it_callable;  /* set to NULL when the iterator is exhausted */
+    PyObject *it_sentinel;  /* can be NULL, and is when exhausted */
     PyObject *it_stop_exc;  /* never NULL */
 } acalliterobject;
 
@@ -634,7 +637,7 @@ typedef struct {
     PyObject_HEAD
     PyObject *aw_iterator; /* the iterator which created this object */
     PyObject *aw_wrapped;  /* the awaitable returned by the callable */
-    char aw_closed;
+    bool aw_closed;
 } acallawaitableobject;
 
 #define acallawaitableobject_CAST(op)   ((acallawaitableobject *)(op))
@@ -704,28 +707,13 @@ static PyAsyncMethods acalliter_as_async = {
 
 PyTypeObject _PyACallIter_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
-    "async_callable_iterator",                  /* tp_name */
-    sizeof(acalliterobject),                    /* tp_basicsize */
-    0,                                          /* tp_itemsize */
-    /* methods */
-    acalliter_dealloc,                          /* tp_dealloc */
-    0,                                          /* tp_vectorcall_offset */
-    0,                                          /* tp_getattr */
-    0,                                          /* tp_setattr */
-    &acalliter_as_async,                        /* tp_as_async */
-    0,                                          /* tp_repr */
-    0,                                          /* tp_as_number */
-    0,                                          /* tp_as_sequence */
-    0,                                          /* tp_as_mapping */
-    0,                                          /* tp_hash */
-    0,                                          /* tp_call */
-    0,                                          /* tp_str */
-    PyObject_GenericGetAttr,                    /* tp_getattro */
-    0,                                          /* tp_setattro */
-    0,                                          /* tp_as_buffer */
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,    /* tp_flags */
-    0,                                          /* tp_doc */
-    acalliter_traverse,                         /* tp_traverse */
+    .tp_name = "async_callable_iterator",
+    .tp_basicsize = sizeof(acalliterobject),
+    .tp_dealloc = acalliter_dealloc,
+    .tp_as_async = &acalliter_as_async,
+    .tp_getattro = PyObject_GenericGetAttr,
+    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
+    .tp_traverse = acalliter_traverse,
 };
 
 /* -------------------------------------- */
@@ -740,7 +728,7 @@ acallawaitable_new(PyObject *iterator)
     }
     aw->aw_iterator = Py_NewRef(iterator);
     aw->aw_wrapped = NULL;
-    aw->aw_closed = 0;
+    aw->aw_closed = false;
     _PyObject_GC_TRACK(aw);
     return (PyObject *)aw;
 }
@@ -903,7 +891,7 @@ acallawaitable_throw(PyObject *op, PyObject *args)
         if (!PyArg_UnpackTuple(args, "throw", 1, 3, &typ, &val, &tb)) {
             return NULL;
         }
-        aw->aw_closed = 1;
+        aw->aw_closed = true;
         (void)_PyGen_SetException(typ, val, tb);
         return NULL;
     }
@@ -917,11 +905,11 @@ acallawaitable_close(PyObject *op, PyObject *Py_UNUSED(dummy))
 
     if (aw->aw_wrapped == NULL) {
         /* Not started, so there is nothing to close. */
-        aw->aw_closed = 1;
+        aw->aw_closed = true;
         Py_RETURN_NONE;
     }
     PyObject *result = acallawaitable_proxy(aw, "close", NULL);
-    aw->aw_closed = 1;
+    aw->aw_closed = true;
     return result;
 }
 
@@ -941,32 +929,14 @@ static PyAsyncMethods acallawaitable_as_async = {
 
 PyTypeObject _PyACallIterAwaitable_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
-    "async_callable_iterator_awaitable",        /* tp_name */
-    sizeof(acallawaitableobject),               /* tp_basicsize */
-    0,                                          /* tp_itemsize */
-    /* methods */
-    acallawaitable_dealloc,                     /* tp_dealloc */
-    0,                                          /* tp_vectorcall_offset */
-    0,                                          /* tp_getattr */
-    0,                                          /* tp_setattr */
-    &acallawaitable_as_async,                   /* tp_as_async */
-    0,                                          /* tp_repr */
-    0,                                          /* tp_as_number */
-    0,                                          /* tp_as_sequence */
-    0,                                          /* tp_as_mapping */
-    0,                                          /* tp_hash */
-    0,                                          /* tp_call */
-    0,                                          /* tp_str */
-    PyObject_GenericGetAttr,                    /* tp_getattro */
-    0,                                          /* tp_setattro */
-    0,                                          /* tp_as_buffer */
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,    /* tp_flags */
-    0,                                          /* tp_doc */
-    acallawaitable_traverse,                    /* tp_traverse */
-    0,                                          /* tp_clear */
-    0,                                          /* tp_richcompare */
-    0,                                          /* tp_weaklistoffset */
-    PyObject_SelfIter,                          /* tp_iter */
-    acallawaitable_iternext,                    /* tp_iternext */
-    acallawaitable_methods,                     /* tp_methods */
+    .tp_name = "async_callable_iterator_awaitable",
+    .tp_basicsize = sizeof(acallawaitableobject),
+    .tp_dealloc = acallawaitable_dealloc,
+    .tp_as_async = &acallawaitable_as_async,
+    .tp_getattro = PyObject_GenericGetAttr,
+    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
+    .tp_traverse = acallawaitable_traverse,
+    .tp_iter = PyObject_SelfIter,
+    .tp_iternext = acallawaitable_iternext,
+    .tp_methods = acallawaitable_methods,
 };