classification
Title: List comprehensions should be noted in for loop documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: AlexGrig, docs@python, ezio.melotti, rhettinger, robla, westley.martinez
Priority: normal Keywords: easy, patch

Created on 2014-01-27 03:24 by robla, last changed 2014-08-04 14:06 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue20402.diff AlexGrig, 2014-08-02 11:22 review
Messages (6)
msg209380 - (view) Author: Rob Lanphier (robla) Date: 2014-01-27 03:24
The current list comprehension documentation is difficult to find for someone who doesn't know what a list comprehension is.  Example of this problem:
http://www.reddit.com/r/learnprogramming/comments/1w6slm/different_kind_of_for_loop_python/

Since list comprehensions are a riff off of "for" loop syntax, they should at least be noted and linked to from section 4.2 ("for statements" section) and quite possibly 5.6 ("Looping constructs")
msg211467 - (view) Author: Westley Martínez (westley.martinez) * Date: 2014-02-18 00:46
I'm curious what the best way to do this would be.  Obviously the simplest would just be 'See also list comprehensions.'  However since this is a tutorial, I was thinking of adding something like this:
'In other languages, for loops are often used to fill a sequence with data.  While this method works just as well in Python, it is often better to use a list comprehension' and then there could be an example like that found here:
http://docs.python.org/2/tutorial/datastructures.html#list-comprehensions

Followed by a link to more info on list comprehensions.
msg224554 - (view) Author: Alexander Grigorievskiy (AlexGrig) * Date: 2014-08-02 11:22
I have added some clarification following Westley Martínez recommendation. I provided references to the list comprehensions and generator expressions. I tried to make the description short.
msg224594 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-08-02 22:33
We do have prominent entries in the glossary and tutorial:

https://docs.python.org/2.7/glossary.html#term-list-comprehension
https://docs.python.org/2.7/tutorial/datastructures.html#list-comprehensions

Moving it earlier in the tutorial is likely to do more harm than help.  In teaching Python, you need some gap between learning for-loops and learning list comprehensions (the former is a prerequisite for the latter).
msg224677 - (view) Author: Rob Lanphier (robla) Date: 2014-08-04 03:57
> Moving it earlier in the tutorial is likely to do more harm than help.
> In teaching Python, you need some gap between learning for-loops and 
> learning list comprehensions (the former is a prerequisite for the
> latter).

The problem here is that many people get list comprehensions foisted on them by reading code that has them in it.  Since list comprehensions aren't called "list comprehensions" in the code, but rather, they look like funny for loops, many people will turn to the for loop documentation, and as of this writing, they won't find anything.

There doesn't necessarily need to be the full example as in Alex's patch (though Alex's version seems fine to me), I think there should at least be some link to the list comprehension documentation, e.g. "It is also possible to prepend a function onto a 'for' loop.  This is a :ref:`list comprehensions <tut-listcomps>`, and is explained further in the next chapter."
msg224681 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-08-04 05:17
Sorry, I'm going to close this one because I believe it would make the documentation worse.

I don't believe that making a forward reference from section 4.2 to section 5.6 helps anyone.
History
Date User Action Args
2014-08-04 14:06:02ezio.melottisetstage: needs patch -> resolved
2014-08-04 05:17:38rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg224681
2014-08-04 03:57:44roblasetmessages: + msg224677
2014-08-02 22:33:01rhettingersetversions: - Python 3.3
nosy: + rhettinger

messages: + msg224594

assignee: docs@python -> rhettinger
2014-08-02 11:22:26AlexGrigsetfiles: + issue20402.diff

nosy: + AlexGrig
messages: + msg224554

keywords: + patch
2014-02-18 00:46:59westley.martinezsetnosy: + westley.martinez
messages: + msg211467
2014-02-15 15:48:12ezio.melottisetkeywords: + easy
nosy: + ezio.melotti
stage: needs patch

versions: + Python 2.7, Python 3.3, Python 3.4, Python 3.5
2014-01-27 03:24:16roblacreate