[3.12] For-else deserves its own section in the tutorial (GH-123946) (#…

…124563)


(cherry picked from commit ffdc80e)

Co-authored-by: Ned Batchelder <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>

Doc/tutorial/controlflow.rst

@@ -160,16 +160,52 @@ arguments.  In chapter :ref:`tut-structures`, we will discuss in more detail abo
 
 .. _tut-break:
 
-:keyword:`!break` and :keyword:`!continue` Statements, and :keyword:`!else` Clauses on Loops
-============================================================================================
+:keyword:`!break` and :keyword:`!continue` Statements
+=====================================================
 
 The :keyword:`break` statement breaks out of the innermost enclosing
-:keyword:`for` or :keyword:`while` loop.
+:keyword:`for` or :keyword:`while` loop::
 
-A :keyword:`!for` or :keyword:`!while` loop can include an :keyword:`!else` clause.
+    >>> for n in range(2, 10):
+    ...     for x in range(2, n):
+    ...         if n % x == 0:
+    ...             print(f"{n} equals {x} * {n//x}")
+    ...             break
+    ...
+    4 equals 2 * 2
+    6 equals 2 * 3
+    8 equals 2 * 4
+    9 equals 3 * 3
+
+The :keyword:`continue` statement continues with the next
+iteration of the loop::
+
+    >>> for num in range(2, 10):
+    ...     if num % 2 == 0:
+    ...         print(f"Found an even number {num}")
+    ...         continue
+    ...     print(f"Found an odd number {num}")
+    ...
+    Found an even number 2
+    Found an odd number 3
+    Found an even number 4
+    Found an odd number 5
+    Found an even number 6
+    Found an odd number 7
+    Found an even number 8
+    Found an odd number 9
+
+.. _tut-for-else:
+
+:keyword:`!else` Clauses on Loops
+=================================
+
+In a :keyword:`!for` or :keyword:`!while` loop the :keyword:`!break` statement
+may be paired with an :keyword:`!else` clause.  If the loop finishes without
+executing the :keyword:`!break`, the :keyword:`!else` clause executes.
 
 In a :keyword:`for` loop, the :keyword:`!else` clause is executed
-after the loop reaches its final iteration.
+after the loop finishes its final iteration, that is, if no break occurred.
 
 In a :keyword:`while` loop, it's executed after the loop's condition becomes false.
 
@@ -198,32 +234,19 @@ which searches for prime numbers::
    9 equals 3 * 3
 
 (Yes, this is the correct code.  Look closely: the ``else`` clause belongs to
-the :keyword:`for` loop, **not** the :keyword:`if` statement.)
-
-When used with a loop, the ``else`` clause has more in common with the
-``else`` clause of a :keyword:`try` statement than it does with that of
-:keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
-when no exception occurs, and a loop's ``else`` clause runs when no ``break``
-occurs. For more on the :keyword:`!try` statement and exceptions, see
-:ref:`tut-handling`.
-
-The :keyword:`continue` statement, also borrowed from C, continues with the next
-iteration of the loop::
-
-    >>> for num in range(2, 10):
-    ...     if num % 2 == 0:
-    ...         print("Found an even number", num)
-    ...         continue
-    ...     print("Found an odd number", num)
-    ...
-    Found an even number 2
-    Found an odd number 3
-    Found an even number 4
-    Found an odd number 5
-    Found an even number 6
-    Found an odd number 7
-    Found an even number 8
-    Found an odd number 9
+the ``for`` loop, **not** the ``if`` statement.)
+
+One way to think of the else clause is to imagine it paired with the ``if``
+inside the loop.  As the loop executes, it will run a sequence like
+if/if/if/else. The ``if`` is inside the loop, encountered a number of times. If
+the condition is ever true, a ``break`` will happen. If the condition is never
+true, the ``else`` clause outside the loop will execute.
+
+When used with a loop, the ``else`` clause has more in common with the ``else``
+clause of a :keyword:`try` statement than it does with that of ``if``
+statements: a ``try`` statement's ``else`` clause runs when no exception
+occurs, and a loop's ``else`` clause runs when no ``break`` occurs. For more on
+the ``try`` statement and exceptions, see :ref:`tut-handling`.
 
 .. _tut-pass: