Backport r54712: document that calling file.next() on a file open for writing

leads to undefined behaviour.

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
+\exception{StopIteration} when \EOF{} is hit when the file is open for
-\keyword{for} loop the most efficient way of looping over the lines of
+reading (behavior is undefined when the file is open for writing).  In
-a file (a very common operation), the \method{next()} method uses a
+order to make a \keyword{for} loop the most efficient way of looping
-hidden read-ahead buffer.  As a consequence of using a read-ahead
+over the lines of a file (a very common operation), the
-buffer, combining \method{next()} with other file methods (like
+\method{next()} method uses a hidden read-ahead buffer.  As a
-\method{readline()}) does not work right.  However, using
+consequence of using a read-ahead buffer, combining \method{next()}
-\method{seek()} to reposition the file to an absolute position will
+with other file methods (like \method{readline()}) does not work
-flush the read-ahead buffer.
+right.  However, using \method{seek()} to reposition the file to an
+absolute position will flush the read-ahead buffer.
 \versionadded{2.3}
 \end{methoddesc}
 

Misc/NEWS

@@ -25,6 +25,13 @@ Library
   run in verbose mode.
 
 
+Documentation
+-------------
+
+- Bug #1569057: Document that calling file.next() on a file open for writing
+  has undefined behaviour.  Backport of r54712.
+
+
 What's New in Python 2.5.1?
 =============================