[Python-checkins] python/dist/src/Doc/lib libstdtypes.tex,1.102,1.103 libxreadlines.tex,1.3,1.4

2002年8月06日 10:01:31 -0700

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv22817
Modified Files:
	libstdtypes.tex libxreadlines.tex 
Log Message:
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.)
Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.102
retrieving revision 1.103
diff -C2 -d -r1.102 -r1.103
*** libstdtypes.tex	6 Aug 2002 16:58:20 -0000	1.102
--- libstdtypes.tex	6 Aug 2002 17:01:28 -0000	1.103
***************
*** 1123,1132 ****
 \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}
--- 1123,1126 ----
***************
*** 1142,1145 ****
--- 1136,1162 ----
 \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
***************
*** 1185,1192 ****

 \begin{methoddesc}[file]{xreadlines}{}
! Equivalent to
! \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
! (See the \refmodule{xreadlines} module for more information.)
 \versionadded{2.1}
 \end{methoddesc}

--- 1202,1208 ----

 \begin{methoddesc}[file]{xreadlines}{}
! 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}

Index: libxreadlines.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libxreadlines.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libxreadlines.tex	6 May 2002 16:02:42 -0000	1.3
--- libxreadlines.tex	6 Aug 2002 17:01:28 -0000	1.4
***************
*** 7,10 ****
--- 7,11 ----
 \versionadded{2.1}

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

 This module defines a new object type which can efficiently iterate