require list comprehensions to start with a for clause

2 files changed, 23 insertions, 6 deletions

diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 1abc6cb..f6d3b9c 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -153,7 +153,7 @@ square brackets:
 
 \begin{verbatim}
 list_display:   "[" [listmaker] "]"
-listmaker:   expression ( list_iter | ( "," expression)* [","] )
+listmaker:   expression ( list_for | ( "," expression)* [","] )
 list_iter:   list_for | list_if
 list_for:    "for" expression_list "in" testlist [list_iter]
 list_if:     "if" test [list_iter]
@@ -164,7 +164,8 @@ by providing either a list of expressions or a list comprehension.
 When a comma-separated list of expressions is supplied, its elements are
 evaluated from left to right and placed into the list object in that
 order.  When a list comprehension is supplied, it consists of a
-single expression followed by one or more "for" or "if" clauses.  In this
+single expression followed by at least one "for" clause and zero or  more
+"for" or "if" clauses.  In this 
 case, the elements of the new list are those that would be produced
 by considering each of the "for" or "if" clauses a block, nesting from
 left to right, and evaluating the expression to produce a list element
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 6451e2a..c5a9294 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -1755,10 +1755,15 @@ item, then to the result and the next item, and so on.  For example,
 
 \subsection{List Comprehensions}
 
-List comprehensions provide a concise way to create lists without
-resorting to use of the \function{map()} or \function{filter()}
-functions.  The resulting construct tends often to be clearer than use
-of those functions.
+List comprehensions provide a concise way to create lists without resorting
+to use of \function{map()}, \function{filter()} and/or \keyword{lambda}.
+The resulting list definition tends often to be clearer than lists built
+using those constructs.  Each list comprehension consists of an expression
+following by a \keyword{for} clause, then zero or more \keyword{for} or
+\keyword{if} clauses.  The result will be a list resulting from evaluating
+the expression in the context of the \keyword{for} and \keyword{if} clauses
+which follow it.  If the expression would evaluate to a tuple, it must be
+parenthesized.
 
 \begin{verbatim}
 >>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
@@ -1771,6 +1776,17 @@ of those functions.
 [12, 18]
 >>> [3*x for x in vec if x < 2]
 []
+>>> [{x: x**2} for x in vec]
+[{2: 4}, {4: 16}, {6: 36}]
+>>> [[x,x**2] for x in vec]
+[[2, 4], [4, 16], [6, 36]]
+>>> [x, x**2 for x in vec]	# error - parens required for tuples
+  File "<stdin>", line 1
+    [x, x**2 for x in vec]
+               ^
+SyntaxError: invalid syntax
+>>> [(x, x**2) for x in vec]
+[(2, 4), (4, 16), (6, 36)]
 >>> vec1 = [2, 4, 6]
 >>> vec2 = [4, 3, -9]
 >>> [x*y for x in vec1 for y in vec2]