classification
Title: Python 2 docs 'control flow/pass' section contains bad example
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: charles.newey, docs@python, ezio.melotti, r.david.murray, rhettinger
Priority: normal Keywords:

Created on 2014-07-30 10:47 by charles.newey, last changed 2014-07-30 18:06 by ezio.melotti. This issue is now closed.

Messages (7)
msg224296 - (view) Author: Charles Newey (charles.newey) Date: 2014-07-30 10:47
URL: https://docs.python.org/2/tutorial/controlflow.html#pass-statements

Quoted verbatim:
"""
The pass statement does nothing. It can be used when a statement is required syntactically but the program requires no action. For example:
>>>

>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...

"""

While the example illustrates the point, it *may* give bad ideas to novice programmers reading it - "while True: pass" is an antipattern as it's very inefficient.
msg224297 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-30 10:59
Do you have any suggestion?
The section already includes examples about empty classes and as placeholder inside functions, and the only other "realistic" situations I can think of is inside an except to ignore errors -- but that might be considered an anti-pattern too.
It could be used with "for" loops if you want to e.g. consume an iterator, or with the "with" statement if you want to create an empty file, but these cases are not very common.
msg224298 - (view) Author: Charles Newey (charles.newey) Date: 2014-07-30 11:16
Your point about using "pass" with the "with" statement sounds like a better example than using "pass" in a loop.

Perhaps even something like adding a note to the example to clarify it:
"""
# Don't use this in Python code - it is for illustrative purposes only
while True:
    pass  # Busy-wait for keyboard interrupt (Ctrl+C)
"""

On the other hand -- one could argue that the documentation should not show "incorrect" uses of Python syntax at all.
msg224300 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-07-30 12:23
How about something like:

   for x in my_generator():
       pass   # Exhaust co-routine generator to make sure all data is processed.

I have no idea if you'd ever actually do that in a well-structured co-routine context, though, not having written very much of that kind of code.
msg224306 - (view) Author: Charles Newey (charles.newey) Date: 2014-07-30 13:49
@David I have no idea either (no having written much of that sort of code myself either), but that looks more sensible.

I'm just nitpicking really, anyway.
msg224307 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-30 13:57
Keep in mind that this is in one of the first sections of the tutorial, where try/except, with, and generators have not been introduced yet.
Maybe the comment could be changed to a simpler "loop forever (use ctrl+c to stop)" so that it doesn't suggest that this is the way to wait for keyboard interrupts and/or a note like "note that this will use 100% of the CPU" could be added as well.
msg224335 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-07-30 18:05
Sorry Charles, this is a non-issue.  The section does a great job communicating what "pass" does.  It has been in the docs since 2007 and no harm has come of it.
History
Date User Action Args
2014-07-30 18:06:08ezio.melottisetstage: resolved
2014-07-30 18:05:36rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg224335

resolution: not a bug
2014-07-30 13:57:53ezio.melottisetmessages: + msg224307
2014-07-30 13:49:25charles.neweysetmessages: + msg224306
2014-07-30 12:23:18r.david.murraysetnosy: + r.david.murray
messages: + msg224300
2014-07-30 11:16:42charles.neweysetmessages: + msg224298
2014-07-30 10:59:33ezio.melottisetnosy: + ezio.melotti
messages: + msg224297
2014-07-30 10:47:09charles.neweycreate