[issue20402] List comprehensions should be noted in for loop documentation
New submission from Rob Lanphier: 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_f... 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") ---------- assignee: docs@python components: Documentation messages: 209380 nosy: docs@python, robla priority: normal severity: normal status: open title: List comprehensions should be noted in for loop documentation type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +easy nosy: +ezio.melotti stage: -> needs patch versions: +Python 2.7, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Westley Martínez added the comment: 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. ---------- nosy: +westley.martinez _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Alexander Grigorievskiy added the comment: 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. ---------- keywords: +patch nosy: +AlexGrig Added file: http://bugs.python.org/file36204/issue20402.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Raymond Hettinger added the comment: 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). ---------- assignee: docs@python -> rhettinger nosy: +rhettinger versions: -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Rob Lanphier added the comment:
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." ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Raymond Hettinger added the comment: 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. ---------- resolution: -> rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: needs patch -> resolved _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20402> _______________________________________
participants (5)
-
Alexander Grigorievskiy -
Ezio Melotti
-
Raymond Hettinger
-
Rob Lanphier
-
Westley Martínez