Document file.next(). Mark xreadlines obsolete (both method and

module).  (One thing remains to be done: the gzip class has an
xreadline method; this ought to be replaced by an iterator as well.)

2 files changed, 26 insertions, 9 deletions

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index df602cd..5caefb3 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -1122,12 +1122,6 @@ Files have the following methods:
   objects.
 \end{methoddesc}
 
-\begin{methoddesc}[file]{isatty}{}
-  Return \code{True} if the file is connected to a tty(-like) device, else
-  \code{False}.  \note{If a file-like object is not associated
-  with a real file, this method should \emph{not} be implemented.}
-\end{methoddesc}
-
 \begin{methoddesc}[file]{fileno}{}
   \index{file descriptor}
   \index{descriptor, file}
@@ -1141,6 +1135,29 @@ Files have the following methods:
   this method!}
 \end{methoddesc}
 
+\begin{methoddesc}[file]{isatty}{}
+  Return \code{True} if the file is connected to a tty(-like) device, else
+  \code{False}.  \note{If a file-like object is not associated
+  with a real file, this method should \emph{not} be implemented.}
+\end{methoddesc}
+
+\begin{methoddesc}[file]{next}{}
+A file object is its own iterator, i.e. \code{iter(\var{f})} returns
+\var{f} (unless \var{f} is closed).  When a file is used as an
+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.
+\versionadded{2.3}
+\end{methoddesc}
+
 \begin{methoddesc}[file]{read}{\optional{size}}
   Read at most \var{size} bytes from the file (less if the read hits
   \EOF{} before obtaining \var{size} bytes).  If the \var{size}
@@ -1184,10 +1201,9 @@ Files have the following methods:
 \end{methoddesc}
 
 \begin{methoddesc}[file]{xreadlines}{}
-  Equivalent to
-  \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
-  (See the \refmodule{xreadlines} module for more information.)
+  This method returns the same thing as \code{iter(f)}.
   \versionadded{2.1}
+  \deprecated{2.3}{Use \code{for line in file} instead.}
 \end{methoddesc}
 
 \begin{methoddesc}[file]{seek}{offset\optional{, whence}}
diff --git a/Doc/lib/libxreadlines.tex b/Doc/lib/libxreadlines.tex
index dda56e7..f2fbe24 100644
--- a/Doc/lib/libxreadlines.tex
+++ b/Doc/lib/libxreadlines.tex
@@ -6,6 +6,7 @@
 
 \versionadded{2.1}
 
+\deprecated{2.3}{Use \code{for line in file} instead.}
 
 This module defines a new object type which can efficiently iterate
 over the lines of a file.  An xreadlines object is a sequence type