[Py-howto-checkins] CVS: pyhowto python-22.tex,1.8,1.9

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv15684

Modified Files:
	python-22.tex 
Log Message:
Minor rewrites to iterator and generator sections
Credit both Neil and Tim for generators
Fix indentation of a few paragraphs



Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -r1.8 -r1.9
*** python-22.tex	2001/07/16 14:35:52	1.8
--- python-22.tex	2001/07/17 12:48:48	1.9
***************
*** 83,87 ****
  iterators will usually be their own iterators.  Extension types
  implemented in C can implement a \code{tp_iter} function in order to
! return an iterator, too.
  
  So what do iterators do?  They have one required method,
--- 83,88 ----
  iterators will usually be their own iterators.  Extension types
  implemented in C can implement a \code{tp_iter} function in order to
! return an iterator, and extension types that want to behave as
! iterators can define a \code{tp_iternext} function.
  
  So what do iterators do?  They have one required method,
***************
*** 202,218 ****
  function containing a \keyword{yield} statement is a generator
  function; this is detected by Python's bytecode compiler which
! compiles the function specially.  When you call a generator function,
! it doesn't return a single value; instead it returns a generator
! object that supports the iterator interface.  On executing the
! \keyword{yield} statement, the generator outputs the value of
! \code{i}, similar to a \keyword{return} statement.  The big difference
! between \keyword{yield} and a \keyword{return} statement is that, on
! reaching a \keyword{yield} the generator's state of execution is
! suspended and local variables are preserved.  On the next call to the
! generator's \code{.next()} method, the function will resume executing
! immediately after the \keyword{yield} statement.  (For complicated
! reasons, the \keyword{yield} statement isn't allowed inside the
! \keyword{try} block of a \code{try...finally} statement; read PEP 255
! for a full explanation of the interaction between \keyword{yield} and
  exceptions.)
  
--- 203,225 ----
  function containing a \keyword{yield} statement is a generator
  function; this is detected by Python's bytecode compiler which
! compiles the function specially.  Because a new keyword was
! introduced, generators must be explicitly enabled in a module by
! including a \code{from __future__ import generators} statement near
! the top of the module's source code.  In Python 2.3 this statement
! will become unnecessary.
! 
! When you call a generator function, it doesn't return a single value;
! instead it returns a generator object that supports the iterator
! interface.  On executing the \keyword{yield} statement, the generator
! outputs the value of \code{i}, similar to a \keyword{return}
! statement.  The big difference between \keyword{yield} and a
! \keyword{return} statement is that, on reaching a \keyword{yield} the
! generator's state of execution is suspended and local variables are
! preserved.  On the next call to the generator's \code{.next()} method,
! the function will resume executing immediately after the
! \keyword{yield} statement.  (For complicated reasons, the
! \keyword{yield} statement isn't allowed inside the \keyword{try} block
! of a \code{try...finally} statement; read PEP 255 for a full
! explanation of the interaction between \keyword{yield} and
  exceptions.)
  
***************
*** 241,254 ****
  
  Inside a generator function, the \keyword{return} statement can only
! be used without a value, and is equivalent to raising the
! \exception{StopIteration} exception; afterwards the generator cannot
! return any further values.  \keyword{return} with a value, such as
! \code{return 5}, is a syntax error inside a generator function.  You
! can also raise \exception{StopIteration} manually, or just let the
! thread of execution fall off the bottom of the function, to achieve
! the same effect.
  
  You could achieve the effect of generators manually by writing your
! own class, and storing all the local variables of the generator as
  instance variables.  For example, returning a list of integers could
  be done by setting \code{self.count} to 0, and having the
--- 248,261 ----
  
  Inside a generator function, the \keyword{return} statement can only
! be used without a value, and signals the end of the procession of
! values; afterwards the generator cannot return any further values.
! \keyword{return} with a value, such as \code{return 5}, is a syntax
! error inside a generator function.  The end of the generator's results
! can also be indicated by raising \exception{StopIteration} manually,
! or by just letting the flow of execution fall off the bottom of the
! function.
  
  You could achieve the effect of generators manually by writing your
! own class and storing all the local variables of the generator as
  instance variables.  For example, returning a list of integers could
  be done by setting \code{self.count} to 0, and having the
***************
*** 309,315 ****
  \begin{seealso}
  
! \seepep{255}{Simple Generators}{Written by Neil Schemenauer, 
! Tim Peters, Magnus Lie Hetland.  Implemented mostly by Neil
! Schemenauer, with fixes from the Python Labs crew.}
  
  \end{seealso}
--- 316,322 ----
  \begin{seealso}
  
! \seepep{255}{Simple Generators}{Written by Neil Schemenauer, Tim
! Peters, Magnus Lie Hetland.  Implemented mostly by Neil Schemenauer
! and Tim Peters, with other fixes from the Python Labs crew.}
  
  \end{seealso}
***************
*** 517,533 ****
  
    \item Various bugfixes and performance improvements have been made
! to the SRE engine underlying the \module{re} module.  For example,
! \function{re.sub()} will now use \function{string.replace()}
! automatically when the pattern and its replacement are both just
! literal strings without regex metacharacters.  Another contributed
! patch speeds up certain Unicode character ranges by a factor of
! two. (SRE is maintained by Fredrik Lundh.  The BIGCHARSET patch
! was contributed by Martin von L\"owis.)
  
    \item The \module{imaplib} module now has support for the IMAP
! NAMESPACE extension defined in \rfc{2342}.  (Contributed by Michel
! Pelletier.)
  
! 
  \end{itemize}
  
--- 524,544 ----
  
    \item Various bugfixes and performance improvements have been made
!   to the SRE engine underlying the \module{re} module.  For example,
!   \function{re.sub()} will now use \function{string.replace()}
!   automatically when the pattern and its replacement are both just
!   literal strings without regex metacharacters.  Another contributed
!   patch speeds up certain Unicode character ranges by a factor of
!   two. (SRE is maintained by Fredrik Lundh.  The BIGCHARSET patch was
!   contributed by Martin von L\"owis.)
  
    \item The \module{imaplib} module now has support for the IMAP
!   NAMESPACE extension defined in \rfc{2342}.  (Contributed by Michel
!   Pelletier.)
  
!   \item The \module{rfc822} module's parsing of e-mail addresses is
!   now compliant with \rfc{2822}, an update to \rfc{822}.  The module's
!   name is \emph{not} going to be changed to \samp{rfc2822}.
!   (Contributed by Barry Warsaw.)
!   
  \end{itemize}
  
***************
*** 556,588 ****
    again.  The license changes were also applied to the Python 2.0.1
    and 2.1.1 releases.
- 
- \item Profiling and tracing functions can now be implemented in C,
- which can operate at much higher speeds than Python-based functions
- and should reduce the overhead of enabling profiling and tracing, so
- it will be of interest to authors of development environments for
- Python.  Two new C functions were added to Python's API,
- \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
- The existing \function{sys.setprofile()} and \function{sys.settrace()}
- functions still exist, and have simply been changed to use the new
- C-level interface.
  
  
    \item The \file{Tools/scripts/ftpmirror.py} script
    now parses a \file{.netrc} file, if you have one.
!   (Contributed by XXX.) Patch \#430754: Makes ftpmirror.py .netrc aware
  
! \item Some features of the object returned by the \function{xrange()}
! function are now deprecated, and trigger warnings when they're
! accessed; they'll disappear in Python 2.3.  \class{xrange} objects
! tried to pretend they were full sequence types by supporting slicing,
! sequence multiplication, and the \keyword{in} operator, but these
! features were rarely used and therefore buggy.  (The implementation of
! the \keyword{in} operator had an off-by-one error introduced in Python
! XXX that no one noticed until XXX, XXX years later.  The
! \method{tolist()} method and the \member{start}, \member{stop}, and
! \member{step} attributes are also being deprecated.  At the C level,
! the fourth argument to the \cfunction{PyRange_New()} function,
! \samp{repeat}, has also been deprecated.  
  
    \item XXX C API: Reorganization of object calling 
  
--- 567,600 ----
    again.  The license changes were also applied to the Python 2.0.1
    and 2.1.1 releases.
  
+   \item Profiling and tracing functions can now be implemented in C,
+   which can operate at much higher speeds than Python-based functions
+   and should reduce the overhead of enabling profiling and tracing, so
+   it will be of interest to authors of development environments for
+   Python.  Two new C functions were added to Python's API,
+   \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
+   The existing \function{sys.setprofile()} and
+   \function{sys.settrace()} functions still exist, and have simply
+   been changed to use the new C-level interface.
  
    \item The \file{Tools/scripts/ftpmirror.py} script
    now parses a \file{.netrc} file, if you have one.
!   (Contributed by Mike Romberg.) 
  
!   \item Some features of the object returned by the
!   \function{xrange()} function are now deprecated, and trigger
!   warnings when they're accessed; they'll disappear in Python 2.3.
!   \class{xrange} objects tried to pretend they were full sequence
!   types by supporting slicing, sequence multiplication, and the
!   \keyword{in} operator, but these features were rarely used and
!   therefore buggy.  The \method{tolist()} method and the
!   \member{start}, \member{stop}, and \member{step} attributes are also
!   being deprecated.  At the C level, the fourth argument to the
!   \cfunction{PyRange_New()} function, \samp{repeat}, has also been
!   deprecated.
  
+   \item On Windows, Python can now be compiled with Borland C thanks 
+   to a number of patches contribued by Stephen Hansen.
+ 
    \item XXX C API: Reorganization of object calling 
  
***************
*** 604,611 ****
  %PyEval_GetFuncDesc(), PyEval_EvalCodeEx() (formerly get_func_name(),
  %get_func_desc(), and eval_code2().
- 
-   \item XXX SF patch \#418147 Fixes to allow compiling w/ Borland, from Stephen Hansen.
  
!    \item XXX Add support for Windows using "mbcs" as the default Unicode encoding when dealing with the file system.  As discussed on python-dev and in patch 410465.
  
    \item XXX Lots of patches to dictionaries; measure performance improvement, if any.
--- 616,623 ----
  %PyEval_GetFuncDesc(), PyEval_EvalCodeEx() (formerly get_func_name(),
  %get_func_desc(), and eval_code2().
  
!   \item XXX Add support for Windows using "mbcs" as the default
!   Unicode encoding when dealing with the file system.  As discussed on
!   python-dev and in patch 410465.
  
    \item XXX Lots of patches to dictionaries; measure performance improvement, if any.
***************
*** 619,623 ****
  
  The author would like to thank the following people for offering
! suggestions on various drafts of this article: No one yet.
  
  \end{document}
--- 631,635 ----
  
  The author would like to thank the following people for offering
! suggestions on various drafts of this article: Tim Peters, Neil Schemenauer.
  
  \end{document}