@@ -205,74 +205,100 @@ block, nesting from left to right, and evaluating the expression to produce a
205205list element each time the innermost block is reached [# ]_.
206206
207207
208+ .. _comprehensions :
209+
210+ Displays for sets and dictionaries
211+ ----------------------------------
212+
213+ For constructing a set or a dictionary Python provides special syntax
214+ called "displays", each of them in two flavors:
215+
216+ * either the container contents are listed explicitly, or
217+
218+ * they are computed via a set of looping and filtering instructions, called a
219+ :dfn: `comprehension `.
220+
221+ Common syntax elements for comprehensions are:
222+
223+ .. productionlist ::
224+ comprehension: `expression ` `comp_for `
225+ comp_for: "for" `target_list ` "in" `or_test ` [`comp_iter `]
226+ comp_iter: `comp_for ` | `comp_if `
227+ comp_if: "if" `expression_nocond ` [`comp_iter `]
228+
229+ The comprehension consists of a single expression followed by at least one
230+ :keyword: `for ` clause and zero or more :keyword: `for ` or :keyword: `if ` clauses.
231+ In this case, the elements of the new container are those that would be produced
232+ by considering each of the :keyword: `for ` or :keyword: `if ` clauses a block,
233+ nesting from left to right, and evaluating the expression to produce an element
234+ each time the innermost block is reached.
235+
236+ Note that the comprehension is executed in a separate scope, so names assigned
237+ to in the target list don't "leak" in the enclosing scope.
238+
239+
208240.. _genexpr :
209241
210242Generator expressions
211243---------------------
212244
213245.. index :: pair: generator; expression
246+ object: generator
214247
215248A generator expression is a compact generator notation in parentheses:
216249
217250.. productionlist ::
218- generator_expression: "(" `expression ` `genexpr_for ` ")"
219- genexpr_for: "for" `target_list ` "in" `or_test ` [`genexpr_iter `]
220- genexpr_iter: `genexpr_for ` | `genexpr_if `
221- genexpr_if: "if" `old_expression ` [`genexpr_iter `]
251+ generator_expression: "(" `expression ` `comp_for ` ")"
222252
223- .. index :: object: generator
253+ A generator expression yields a new generator object. Its syntax is the same as
254+ for comprehensions, except that it is enclosed in parentheses instead of
255+ brackets or curly braces.
224256
225- A generator expression yields a new generator object. It consists of a single
226- expression followed by at least one :keyword: `for ` clause and zero or more
227- :keyword: `for ` or :keyword: `if ` clauses. The iterating values of the new
228- generator are those that would be produced by considering each of the
229- :keyword: `for ` or :keyword: `if ` clauses a block, nesting from left to right, and
230- evaluating the expression to yield a value that is reached the innermost block
231- for each iteration.
232-
233- Variables used in the generator expression are evaluated lazily in a separate
234- scope when the :meth: `next ` method is called for the generator object (in the
235- same fashion as for normal generators). However, the :keyword: `in ` expression
236- of the leftmost :keyword: `for ` clause is immediately evaluated in the current
237- scope so that an error produced by it can be seen before any other possible
257+ Variables used in the generator expression are evaluated lazily when the
258+ :meth: `__next__ ` method is called for generator object (in the same fashion as
259+ normal generators). However, the leftmost :keyword: `for ` clause is immediately
260+ evaluated, so that an error produced by it can be seen before any other possible
238261error in the code that handles the generator expression. Subsequent
239- :keyword: `for ` and :keyword: ` if ` clauses cannot be evaluated immediately since
240- they may depend on the previous :keyword: `for ` loop. For example:
241- `` (x*y for x in range(10) for y in bar(x)) ``.
262+ :keyword: `for ` clauses cannot be evaluated immediately since they may depend on
263+ the previous :keyword: `for ` loop. For example: `` (x*y for x in range(10) for y
264+ in bar(x)) ``.
242265
243- The parentheses can be omitted on calls with only one argument. See section
266+ The parentheses can be omitted on calls with only one argument. See section
244267:ref: `calls ` for the detail.
245268
246-
247269.. _dict :
248270
249271Dictionary displays
250272-------------------
251273
252274.. index :: pair: dictionary; display
253-
254- .. index ::
255- single: key
256- single: datum
257- single: key/datum pair
275+ key, datum, key/datum pair
276+ object: dictionary
258277
259278A dictionary display is a possibly empty series of key/datum pairs enclosed in
260279curly braces:
261280
262281.. productionlist ::
263- dict_display: "{" [`key_datum_list `] "}"
282+ dict_display: "{" [`key_datum_list ` | ` dict_comprehension ` ] "}"
264283 key_datum_list: `key_datum ` ("," `key_datum `)* [","]
265284 key_datum: `expression ` ":" `expression `
266-
267- .. index :: object: dictionary
285+ dict_comprehension: `expression ` ":" `expression ` `comp_for `
268286
269287A dictionary display yields a new dictionary object.
270288
271- The key/datum pairs are evaluated from left to right to define the entries of
272- the dictionary: each key object is used as a key into the dictionary to store
273- the corresponding datum.
289+ If a comma-separated sequence of key/datum pairs is given, they are evaluated
290+ from left to right to define the entries of the dictionary: each key object is
291+ used as a key into the dictionary to store the corresponding datum. This means
292+ that you can specify the same key multiple times in the key/datum list, and the
293+ final dictionary's value for that key will be the last one given.
294+
295+ A dict comprehension, in contrast to list and set comprehensions, needs two
296+ expressions separated with a colon followed by the usual "for" and "if" clauses.
297+ When the comprehension is run, the resulting key and value elements are inserted
298+ in the new dictionary in the order they are produced.
274299
275300.. index :: pair: immutable; object
301+ hashable
276302
277303Restrictions on the types of the key values are listed earlier in section
278304:ref: `types `. (To summarize, the key type should be :term: `hashable `, which excludes
0 commit comments