summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>2002-08-06 17:01:28 (GMT)
committerGuido van Rossum <guido@python.org>2002-08-06 17:01:28 (GMT)
commit0fc01865f3a71f84484b0424d7e8952e35855bc7 (patch)
tree3e53a9e1d4402322f8e4e0e04fb8e52f38e80346 /Doc
parent817918cc3c10d0ed6b14e0e3f2bc0c5227c508cd (diff)
downloadcpython-0fc01865f3a71f84484b0424d7e8952e35855bc7.zip
cpython-0fc01865f3a71f84484b0424d7e8952e35855bc7.tar.gz
cpython-0fc01865f3a71f84484b0424d7e8952e35855bc7.tar.bz2
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.)
Diffstat (limited to 'Doc')
-rw-r--r--Doc/lib/libstdtypes.tex34
-rw-r--r--Doc/lib/libxreadlines.tex1
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