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.)

Here is a desultory example of the implementation of the call function.

XXX some fields need to be added here...

\begin{verbatim}

\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.