[Python-checkins] CVS: python/dist/src/Doc/ext newtypes.tex,1.7,1.8

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/ext
In directory usw-pr-cvs1:/tmp/cvs-serv21495/ext

Modified Files:
	newtypes.tex 
Log Message:
Describe how to support the iterator protocol in extension types.
This closes SF bug #420851.


Index: newtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/ext/newtypes.tex,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** newtypes.tex	16 Jan 2002 14:55:05 -0000	1.7
--- newtypes.tex	13 Mar 2002 03:55:11 -0000	1.8
***************
*** 714,721 ****
  \subsection{Abstract Protocol Support}
  
  \begin{verbatim}
!   tp_as_number;
!   tp_as_sequence;
!   tp_as_mapping;
  \end{verbatim}
  
--- 714,737 ----
  \subsection{Abstract Protocol Support}
  
+ Python supports a variety of \emph{abstract} `protocols;' the specific
+ interfaces provided to use these interfaces are documented in the
+ \citetitle[../api/api.html]{Python/C API Reference Manual} in the
+ chapter ``\ulink{Abstract Objects Layer}{../api/abstract.html}.''
+ 
+ A number of these abstract interfaces were defined early in the
+ development of the Python implementation.  In particular, the number,
+ mapping, and sequence protocols have been part of Python since the
+ beginning.  Other protocols have been added over time.  For protocols
+ which depend on several handler routines from the type implementation,
+ the older protocols have been defined as optional blocks of handlers
+ referenced by the type object, while newer protocols have been added
+ using additional slots in the main type object, with a flag bit being
+ set to indicate that the slots are present.  (The flag bit does not
+ indicate that the slot values are non-\NULL.)
+ 
  \begin{verbatim}
!     PyNumberMethods   tp_as_number;
!     PySequenceMethods tp_as_sequence;
!     PyMappingMethods  tp_as_mapping;
  \end{verbatim}
  
***************
*** 778,782 ****
  \end{enumerate}
         
! Here is a desultory example of the implementation of call function.
  
  \begin{verbatim}
--- 794,798 ----
  \end{enumerate}
         
! Here is a desultory example of the implementation of the call function.
  
  \begin{verbatim}
***************
*** 805,808 ****
--- 821,864 ----
  }
  \end{verbatim}
+ 
+ XXX some fields need to be added here...
+ 
+ 
+ \begin{verbatim}
+     /* Added in release 2.2 */
+     /* Iterators */
+     getiterfunc tp_iter;
+     iternextfunc tp_iternext;
+ \end{verbatim}
+ 
+ These functions provide support for the iterator protocol.  Any object
+ which wishes to support iteration over it's contents (which may be
+ generated during iteration) must implement the \code{tp_iter}
+ handler.  Objects which are returned by a \code{tp_iter} handler must
+ implement both the \code{tp_iter} and \code{tp_iternext} handlers.
+ Both handlers take exactly one parameter, the instance for which they
+ are being called, and return a new reference.  In the case of an
+ error, they should set an exception and return \NULL.
+ 
+ For an object which represents an iterable collection, the
+ \code{tp_iter} handler must return an iterator object.  The iterator
+ object is responsible for maintaining the state of the iteration.  For
+ collections which can support multiple iterators which do not
+ interfere with each other (as lists and tuples do), a new iterator
+ should be created and returned.  Objects which can only be iterated
+ over once (usually due to side effects of iteration) should implement
+ this handler by returning a new reference to themselves, and should
+ also implement the \code{tp_iternext} handler.  File objects are an
+ example of such an iterator.
+ 
+ Iterator objects should implement both handlers.  The \code{tp_iter}
+ handler should return a new reference to the iterator (this is the
+ same as the \code{tp_iter} handler for objects which can only be
+ iterated over destructively).  The \code{tp_iternext} handler should
+ return a new reference to the next object in the iteration if there is
+ one.  If the iteration has reached the end, it may return \NULL{}
+ without setting an exception or it may set \exception{StopIteration};
+ avoiding the exception can yield slightly better performance.  If an
+ actual error occurs, it should set an exception and return \NULL.