Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 0fc0186

Browse files
committed
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.)
1 parent 817918c commit 0fc0186

2 files changed

Lines changed: 26 additions & 9 deletions

File tree

Doc/lib/libstdtypes.tex

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1122,12 +1122,6 @@ \subsection{File Objects
11221122
objects.
11231123
\end{methoddesc}
11241124

1125-
\begin{methoddesc}[file]{isatty}{}
1126-
Return \code{True} if the file is connected to a tty(-like) device, else
1127-
\code{False}. \note{If a file-like object is not associated
1128-
with a real file, this method should \emph{not} be implemented.}
1129-
\end{methoddesc}
1130-
11311125
\begin{methoddesc}[file]{fileno}{}
11321126
\index{file descriptor}
11331127
\index{descriptor, file}
@@ -1141,6 +1135,29 @@ \subsection{File Objects
11411135
this method!}
11421136
\end{methoddesc}
11431137

1138+
\begin{methoddesc}[file]{isatty}{}
1139+
Return \code{True} if the file is connected to a tty(-like) device, else
1140+
\code{False}. \note{If a file-like object is not associated
1141+
with a real file, this method should \emph{not} be implemented.}
1142+
\end{methoddesc}
1143+
1144+
\begin{methoddesc}[file]{next}{}
1145+
A file object is its own iterator, i.e. \code{iter(\var{f})} returns
1146+
\var{f} (unless \var{f} is closed). When a file is used as an
1147+
iterator, typically in a \keyword{for} loop (for example,
1148+
\code{for line in f: print line}), the \method{next()} method is
1149+
called repeatedly. This method returns the next input line, or raises
1150+
\exception{StopIteration} when \EOF{} is hit. In order to make a
1151+
\keyword{for} loop the most efficient way of looping over the lines of
1152+
a file (a very common operation), the \method{next()} method uses a
1153+
hidden read-ahead buffer. As a consequence of using a read-ahead
1154+
buffer, combining \method{next()} with other file methods (like
1155+
\method{readline()}) does not work right. However, using
1156+
\method{seek()} to reposition the file to an absolute position will
1157+
flush the read-ahead buffer.
1158+
\versionadded{2.3}
1159+
\end{methoddesc}
1160+
11441161
\begin{methoddesc}[file]{read}{\optional{size}}
11451162
Read at most \var{size} bytes from the file (less if the read hits
11461163
\EOF{} before obtaining \var{size} bytes). If the \var{size}
@@ -1184,10 +1201,9 @@ \subsection{File Objects
11841201
\end{methoddesc}
11851202

11861203
\begin{methoddesc}[file]{xreadlines}{}
1187-
Equivalent to
1188-
\function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
1189-
(See the \refmodule{xreadlines} module for more information.)
1204+
This method returns the same thing as \code{iter(f)}.
11901205
\versionadded{2.1}
1206+
\deprecated{2.3}{Use \code{for line in file} instead.}
11911207
\end{methoddesc}
11921208

11931209
\begin{methoddesc}[file]{seek}{offset\optional{, whence}}

Doc/lib/libxreadlines.tex

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ \section{\module{xreadlines} ---
66

77
\versionadded{2.1}
88

9+
\deprecated{2.3}{Use \code{for line in file} instead.}
910

1011
This module defines a new object type which can efficiently iterate
1112
over the lines of a file. An xreadlines object is a sequence type

0 commit comments

Comments
 (0)