classification
Title: Mention dict and set comps in library reference
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Mariatta Nosy List: FrankMillman, Mariatta, cheryl.sabella, docs@python, ezio.melotti, josh.r, martin.panter, r.david.murray
Priority: normal Keywords: patch

Created on 2015-03-16 08:50 by FrankMillman, last changed 2019-02-24 22:22 by cheryl.sabella.

Files
File name Uploaded Description Edit
issue23677.diff BreamoreBoy, 2015-03-16 11:05 minimal changes to stdtypes.rst
issue23677_v2.diff BreamoreBoy, 2015-03-17 23:42
Messages (7)
msg238186 - (view) Author: Frank Millman (FrankMillman) Date: 2015-03-16 08:50
This is from the documentation at Section 4.6.4. Lists

"""
Lists may be constructed in several ways:

Using a pair of square brackets to denote the empty list: []
Using square brackets, separating items with commas: [a], [a, b, c]
Using a list comprehension: [x for x in iterable]
Using the type constructor: list() or list(iterable)
"""

Comprehensions are mentioned as a constructor.

This is from the documentation at Section 4.10. Mapping Types

"""
Dictionaries can be created by placing a comma-separated list of key: value pairs within braces, for example: {'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}, or by the dict constructor.

class dict(**kwarg) 
class dict(mapping, **kwarg) 
class dict(iterable, **kwarg) 
Return a new dictionary initialized from an optional positional argument and a possibly empty set of keyword arguments.
"""

There is no mention of dictionary comprehensions.

For consistency, I believe that the documentation for Dicts and Sets should mention comprehensions.
msg238203 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-03-16 14:00
Sounds reasonable.  Dict and set comprehensions were added later than list comprehensions, and we probably just didn't notice this needed updating.

Mark's patch, however, is incorrect.  Mark: the dict/set literal notation is a different thing from a comprehension.
msg238362 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2015-03-17 23:42
That was embarrassing, hopefully this is rather better.
msg238380 - (view) Author: Frank Millman (FrankMillman) Date: 2015-03-18 06:33
Lists and tuples are described like this -

class list([iterable]) 
Lists may be constructed in several ways:
[...]

class tuple([iterable]) 
Tuples may be constructed in a number of ways:
[...]

I think a similar approach to Dicts and Sets could make sense -

class dict([**kwarg])
Dicts may be constructed in a number of ways:

- Using a pair of braces to denote the empty dict: {}
- Placing a comma-separated list of key: value pairs within braces: {'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}
- Using a dict comprehension: {k: v for k, v in iterable}
- Using the dict() built-in: dict() or dict(**kwarg) or dict(mapping, **kwarg) or dict(iterable, **kwarg) 

Add a new example -

f = {k: v for k, v in [('one', 1), ('two', 2), ('three', 3)]}


class set([iterable])
class frozenset([iterable])
Sets may be constructed in a number of ways:

- Non-empty sets (not frozensets) can be created by placing a comma-separated list of elements within braces, for example: {'jack', 'sjoerd'}
- Non-empty sets (not frozensets) can be created by using a set comprehension: {x for x in iterable}
- Using the set() or frozenset() built-in


The 'bullet-point' construction is not really necessary for Sets, but it would make it consistent with the others.


A related point (I can raise a separate Issue if preferred) -

For me, the power of comprehensions lies in their 'filtering' ability. This is not mentioned in any of the above examples, so newcomers may wonder why they should use them.

We don't want to make the examples too complicated. Maybe just add 'if ...' to the example, and provide a cross-reference to Section 6.2.4 in the Language Reference (Displays for lists, sets and dictionaries).
msg257427 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-01-03 21:19
The distiction about non-empty sets is a bit misleading. You can create an empty set via comprehension:

>>> {x for x in ()}
set()
msg257514 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2016-01-05 03:40
Heck, with the addition of additional unpacking generalizations in 3.5, you can make an empty set even without a comprehension: {*()}

Not really recommending the "one-eyed monkey operator", but the addition of unpacking generalizations undoes several of the limits on literals that previously existed.
msg336486 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-02-24 22:22
Assigning to @Mariatta for the CPython mentored sprint.
History
Date User Action Args
2019-02-24 22:22:09cheryl.sabellasetversions: + Python 3.7, Python 3.8, - Python 3.5, Python 3.6
nosy: + Mariatta, cheryl.sabella

messages: + msg336486

assignee: docs@python -> Mariatta
stage: patch review -> needs patch
2019-02-24 22:10:26BreamoreBoysetnosy: - BreamoreBoy
2016-01-05 03:40:28josh.rsetnosy: + josh.r
messages: + msg257514
2016-01-03 21:19:48martin.pantersetnosy: + martin.panter
messages: + msg257427
2016-01-03 09:58:14ezio.melottisetnosy: + ezio.melotti
stage: patch review
type: enhancement

versions: + Python 3.6, - Python 3.4
2015-03-18 06:33:43FrankMillmansetmessages: + msg238380
2015-03-17 23:42:08BreamoreBoysetfiles: + issue23677_v2.diff
nosy: + BreamoreBoy
messages: + msg238362

2015-03-16 14:00:58r.david.murraysetnosy: + r.david.murray
messages: + msg238203
2015-03-16 11:05:30BreamoreBoysetfiles: + issue23677.diff
keywords: + patch
versions: + Python 3.5
2015-03-16 08:50:55FrankMillmancreate