bpo-46033: Clarify for-statement execution (GH-30025)

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 92024e51ef4fc79194c279858d6f38fb5c31f771..688407195f05ddb1a24fc07165ba671fa3d57cb3 100644 (file)
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -157,17 +157,14 @@ The :keyword:`for` statement is used to iterate over the elements of a sequence
    for_stmt: "for" `target_list` "in" `starred_list` ":" `suite`
            : ["else" ":" `suite`]
 
-The expression list is evaluated once; it should yield an iterable object.  An
-iterator is created for the result of the ``starred_list``.  The expression
-list can contain starred elements (``*x, *y``) that will be unpacked in the
-final iterator (as when constructing a ``tuple`` or ``list`` literal). The
-suite is then executed once for each item provided by the iterator, in the
-order returned by the iterator.  Each item in turn is assigned to the target
-list using the standard rules for assignments (see :ref:`assignment`), and then
-the suite is executed.  When the items are exhausted (which is immediately when
-the sequence is empty or an iterator raises a :exc:`StopIteration` exception),
-the suite in the :keyword:`!else` clause, if present, is executed, and the loop
-terminates.
+The ``starred_list`` expression is evaluated once; it should yield an
+:term:`iterable` object.  An :term:`iterator` is created for that iterable.
+The first item provided
+by the iterator is then assigned to the target list using the standard
+rules for assignments (see :ref:`assignment`), and the suite is executed.  This
+repeats for each item provided by the iterator.  When the iterator is exhausted,
+the suite in the :keyword:`!else` clause,
+if present, is executed, and the loop terminates.
 
 .. index::
    statement: break

diff --git a/Misc/NEWS.d/next/Documentation/2022-01-03-18-50-39.bpo-46033.7WeF0f.rst b/Misc/NEWS.d/next/Documentation/2022-01-03-18-50-39.bpo-46033.7WeF0f.rst
new file mode 100644 (file)
index 0000000..a484def
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-01-03-18-50-39.bpo-46033.7WeF0f.rst
@@ -0,0 +1 @@
+Clarify ``for`` statement execution in its doc.