From d61d0d3f6dbd960a761c05ff7fea848cb6490aa3 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Sun, 23 Sep 2001 02:05:26 +0000
Subject: [PATCH] Added API information for the PyCallIter_*() and
 PySeqIter_*() functions. Added signatures for some new PyType_*() functions.

---
 Doc/api/api.tex       | 60 ++++++++++++++++++++++++++++++++++++++++++-
 Doc/api/refcounts.dat |  7 +++++
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 7b205cad888..a7270411cfc 100644
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -2337,6 +2337,18 @@ Returns true if the type object \var{o} sets the feature
 \var{feature}.  Type features are denoted by single bit flags.
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b}
+Returns true if \var{a} is a subtype of \var{b}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type,
+                                                  int nitems}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type,
+                                            PyObject *args, PyObject *kwds}
+\end{cfuncdesc}
+
 
 \subsection{The None Object \label{noneObject}}
 
@@ -4356,11 +4368,57 @@ error, \code{0} on success.
 \end{cfuncdesc}
 
 
+\subsection{Iterator Objects \label{iterator-objects}}
+
+Python provides two general-purpose iterator objects.  The first, a
+sequence iterator, works with an arbitrary sequence supporting the
+\method{__getitem__()} method.  The second works with a callable
+object and a sentinel value, calling the callable for each item in the
+sequence, and ending the iteration when the sentinel value is
+returned.
+
+\begin{cvardesc}{PyTypeObject}{PySeqIter_Type}
+  Type object for iterator objects returned by
+  \cfunction{PySeqIter_New()} and the one-argument form of the
+  \function{iter()} built-in function for built-in sequence types.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PySeqIter_Check}{op}
+  Return true if the type of \var{op} is \cdata{PySeqIter_Type}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq}
+  Return an iterator that works with a general sequence object,
+  \var{seq}.  The iteration ends when the sequence raises
+  \exception{IndexError} for the subscripting operation.
+\end{cfuncdesc}
+
+
+\begin{cvardesc}{PyTypeObject}{PyCallIter_Type}
+  Type object for iterator objects returned by
+  \cfunction{PyCallIter_New()} and the two-argument form of the
+  \function{iter()} built-in function.
+\end{cvardesc}
+
+\begin{cfuncdesc}{int}{PyCallIter_Check}{op}
+  Return true if the type of \var{op} is \cdata{PyCallIter_Type}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable,
+                                             PyObject *sentinel}
+  Return a new iterator.  The first parameter, \var{callable}, can be
+  any Python callable object that can be called with no parameters;
+  each call to it should return the next item in the iteration.  When
+  \var{callable} returns a value equal to \var{sentinel}, the
+  iteration will be terminated.
+\end{cfuncdesc}
+
+
 \subsection{CObjects \label{cObjects}}
 
 \obindex{CObject}
 Refer to \emph{Extending and Embedding the Python Interpreter},
-section 1.12 (``Providing a C API for an Extension Module''), for more 
+section 1.12 (``Providing a C API for an Extension Module), for more 
 information on using these objects.
 
 
diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat
index 5f1680026eb..fa4fe4f8d75 100644
--- a/Doc/api/refcounts.dat
+++ b/Doc/api/refcounts.dat
@@ -67,6 +67,10 @@ PyCObject_FromVoidPtrAndDesc:void(*)(void*,void*):destr::
 PyCObject_GetDesc:void*:::
 PyCObject_GetDesc:PyObject*:self:0:
 
+PyCallIter_New:PyObject*::+1:
+PyCallIter_New:PyObject*:callable::
+PyCallIter_New:PyObject*:sentinel::
+
 PyCallable_Check:int:::
 PyCallable_Check:PyObject*:o:0:
 
@@ -845,6 +849,9 @@ PyRun_String:int:start::
 PyRun_String:PyObject*:globals:0:
 PyRun_String:PyObject*:locals:0:
 
+PySeqIter_New:PyObject*::+1:
+PySeqIter_New:PyObject*:seq::
+
 PySequence_Check:int:::
 PySequence_Check:PyObject*:o:0: