Doc: clarify distinction between nested listcomps and multi-for listcomps

petya3 · web-flow · commit 8578308ed8aa · 2026-05-14T17:22:34.000+02:00
In section 5.1.3, the flatten example uses a single list comprehension
with two `for` clauses. In section 5.1.4, the actual nested list
comprehension (a comprehension whose expression is itself a
comprehension) is introduced.

The current wording creates two problems:

1. The flatten example in 5.1.3 has no label distinguishing it from
   a "nested" comprehension, so readers may already think they've seen
   nesting before reaching 5.1.4.

2. Section 5.1.4 opens with "As we saw in the previous section...",
   implying the two constructs are the same idea continued, rather
   than two distinct concepts.

This commit:
- Adds "single ... with two 'for' clauses" to the flatten comment in
  5.1.3 to preemptively distinguish it.
- Rewrites the opening sentence of the 5.1.4 explanation to explicitly
  contrast the two constructs and clarify what makes a list
  comprehension truly "nested".
diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
@@ -265,7 +265,7 @@ it must be parenthesized. ::
        [x, x**2 for x in range(6)]
         ^^^^^^^
    SyntaxError: did you forget parentheses around the comprehension target?
-   >>> # flatten a list using a listcomp with two 'for'
+   >>> # flatten a list using a single listcomp with two 'for' clauses
    >>> vec = [[1,2,3], [4,5,6], [7,8,9]]
    >>> [num for elem in vec for num in elem]
    [1, 2, 3, 4, 5, 6, 7, 8, 9]
@@ -296,9 +296,12 @@ The following list comprehension will transpose rows and columns::
    >>> [[row[i] for row in matrix] for i in range(4)]
    [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
 
-As we saw in the previous section, the inner list comprehension is evaluated in
-the context of the :keyword:`for` that follows it, so this example is
-equivalent to::
+Unlike a list comprehension with multiple ``for`` clauses (as seen in
+the previous section), here the expression itself is a complete list
+comprehension — this is what makes it *nested*. The inner list
+comprehension ``[row[i] for row in matrix]`` is evaluated once for
+each value of ``i`` in the outer :keyword:`for`, so this example is
+equivalent to:
 
    >>> transposed = []
    >>> for i in range(4):
