From: Brett Cannon <bcannon@gmail.com>
Date: Sun, 8 Apr 2007 04:29:32 +0000 (+0000)
Subject: Doc that file.next() has undefined behaviour when called on a file opened with
X-Git-Tag: v2.6a1~1857
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=55a1864832a02725b339a9ae98dd6849251c623b;p=python

Doc that file.next() has undefined behaviour when called on a file opened with
'w'.  Closes bug #1569057.

To be backported once 2.5 branch is unfrozen.
---

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index 3cad43b301..0ad2ebcca3 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -1615,14 +1615,15 @@ A file object is its own iterator, for example \code{iter(\var{f})} returns
 iterator, typically in a \keyword{for} loop (for example,
 \code{for line in f: print line}), the \method{next()} method is
 called repeatedly.  This method returns the next input line, or raises
-\exception{StopIteration} when \EOF{} is hit.  In order to make a
-\keyword{for} loop the most efficient way of looping over the lines of
-a file (a very common operation), the \method{next()} method uses a
-hidden read-ahead buffer.  As a consequence of using a read-ahead
-buffer, combining \method{next()} with other file methods (like
-\method{readline()}) does not work right.  However, using
-\method{seek()} to reposition the file to an absolute position will
-flush the read-ahead buffer.
+\exception{StopIteration} when \EOF{} is hit when the file is open for
+reading (behavior is undefined when the file is open for writing).  In
+order to make a \keyword{for} loop the most efficient way of looping
+over the lines of a file (a very common operation), the
+\method{next()} method uses a hidden read-ahead buffer.  As a
+consequence of using a read-ahead buffer, combining \method{next()}
+with other file methods (like \method{readline()}) does not work
+right.  However, using \method{seek()} to reposition the file to an
+absolute position will flush the read-ahead buffer.
 \versionadded{2.3}
 \end{methoddesc}
 
diff --git a/Misc/NEWS b/Misc/NEWS
index 12d4413244..d15f673275 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -736,6 +736,9 @@ Tools
 Documentation
 -------------
 
+- Bug #1569057: Document that calling file.next() when the file is open for
+  writing is undefined.
+
 - Patch #1489771: the syntax rules in Python Reference Manual were
   updated to reflect the current Python syntax.