https://github.com/python/cpython/commit/281f980d354d1709018a2dc77f79388faf3... commit: 281f980d354d1709018a2dc77f79388faf3e56c0 branch: main author: Michał D <michcio1234@gmail.com> committer: terryjreedy <tjreedy@udel.edu> date: 2022-04-02T20:52:20-04:00 summary: 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> files: A Misc/NEWS.d/next/Documentation/2022-01-03-18-50-39.bpo-46033.7WeF0f.rst M Doc/reference/compound_stmts.rst diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 92024e51ef4fc..688407195f05d 100644 --- 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 index 0000000000000..a484def239d8b --- /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.