This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: info hidden
Type: Stage:
Components: Documentation Versions: Python 2.3
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: Nosy List: grubert, jlgijsbers, nickjacobson, rhettinger, rodsenra
Priority: normal Keywords:

Created on 2004-09-28 22:42 by nickjacobson, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (5)
msg22562 - (view) Author: Nick Jacobson (nickjacobson) Date: 2004-09-28 22:42
(A.M. Kuchling told me to post this bug report.)

In section 2.3.8, "File Objects", of the Python Library 
Reference, the following section is given for

In order to make a for loop the most efficient way of 
looping over the lines of a file (a very common 
operation), the next() method uses a hidden read-ahead 
buffer. As a consequence of using a read-ahead buffer, 
combining next() with other file methods (like readline()) 
does not work right.

This information is necessary for anyone who mixes "for 
line in file:" with read()/tell()/etc.  However, in the 
statement "for line in file:", next() is called implicitly, and 
therefore it may not occur to the programmer to find the 
information there.

Therefore the documentation should be reorganized.
One solution is to have the read()/tell()/etc. methods 
refer to the above section.  i.e. "Don't use this method 
with next() or 'for line in file:'; see next()."

A second solution is to move the above section to 
before the methods section (i.e. after the second 
paragraph after the 2.3.8 header), and to mention 'for 
line in file:'.
i.e. "As a consequence of using a read-ahead buffer, 
combining next() or 'for line in file:' with other file 
methods (like readline()) does not work right."

(Also, saying "with other file methods (like readline())" is 
too vague.  IMHO it should specify which ones not to 
use.  That's debatable though.)
msg22563 - (view) Author: engelbert gruber (grubert) * Date: 2004-10-05 13:55
Logged In: YES 

see also for lin in file: file.tell() tells wrong
msg22564 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2004-10-27 17:22
Logged In: YES 

IMO, the docs are fine as-is.  Sometimes, trying to be over
specific makes the docs less usable rather than more.  The
current wording pretty much covers why the iterator protocol
is at odds with the readline() style methods.

Of course, this could be argued to death.  So, I'll leave
the report open so that others can express their take.
msg22565 - (view) Author: Rodrigo Dias Arruda Senra (rodsenra) Date: 2004-11-07 18:55
Logged In: YES 

I agree this should be closed without any modification to
the docs.
The information that clarifies the matter is under "File
Objects", where
anybody with doubts about "for i in fileobject:" should look
msg22566 - (view) Author: Johannes Gijsbers (jlgijsbers) * (Python triager) Date: 2004-11-07 19:28
Logged In: YES 

I agree. Doesn't seem to be a need to "argue this to death",
so I'm closing this.
Date User Action Args
2022-04-11 14:56:07adminsetgithub: 40962
2004-09-28 22:42:45nickjacobsoncreate