Made a start with api.tex, the Python-C API Reference Manual.

Removed extref.tex (which provided the starting point).
Also removed qua.tex, which is out of date and no longer needed.

1 files changed, 884 insertions, 0 deletions

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
new file mode 100644
index 0000000..6c43933
--- /dev/null
+++ b/Doc/api/api.tex
@@ -0,0 +1,884 @@
+\documentstyle[twoside,11pt,myformat]{report}
+
+% NOTE: this file controls which chapters/sections of the library
+% manual are actually printed.  It is easy to customize your manual
+% by commenting out sections that you're not interested in.
+
+\title{Python-C API Reference}
+
+\input{boilerplate}
+
+\makeindex			% tell \index to actually write the .idx file
+
+
+\begin{document}
+
+\pagenumbering{roman}
+
+\maketitle
+
+\input{copyright}
+
+\begin{abstract}
+
+\noindent
+This manual documents the API used by C (or C++) programmers who want
+to write extension modules or embed Python.  It is a companion to
+``Extending and Embedding the Python Interpreter'', which describes
+the general principles of extension writing but does not document the
+API functions in detail.
+
+\end{abstract}
+
+\pagebreak
+
+{
+\parskip = 0mm
+\tableofcontents
+}
+
+\pagebreak
+
+\pagenumbering{arabic}
+
+
+\chapter{Introduction}
+
+From the viewpoint of of C access to Python services, we have:
+
+\begin{enumerate}
+
+\item "Very high level layer": two or three functions that let you
+exec or eval arbitrary Python code given as a string in a module whose
+name is given, passing C values in and getting C values out using
+mkvalue/getargs style format strings.  This does not require the user
+to declare any variables of type \code{PyObject *}.  This should be
+enough to write a simple application that gets Python code from the
+user, execs it, and returns the output or errors.
+
+\item "Abstract objects layer": which is the subject of this chapter.
+It has many functions operating on objects, and lest you do many
+things from C that you can also write in Python, without going through
+the Python parser.
+
+\item "Concrete objects layer": This is the public type-dependent
+interface provided by the standard built-in types, such as floats,
+strings, and lists.  This interface exists and is currently documented
+by the collection of include files provides with the Python
+distributions.
+
+\begin{enumerate}
+
+From the point of view of Python accessing services provided by C
+modules:
+
+\end{enumerate}
+
+\item[4] "Python module interface": this interface consist of the basic
+routines used to define modules and their members.  Most of the
+current extensions-writing guide deals with this interface.
+
+\item[5] "Built-in object interface": this is the interface that a new
+built-in type must provide and the mechanisms and rules that a
+developer of a new built-in type must use and follow.
+
+\end{enumerate}
+
+The Python C API provides four groups of operations on objects,
+corresponding to the same operations in the Python language: object,
+numeric, sequence, and mapping.  Each protocol consists of a
+collection of related operations.  If an operation that is not
+provided by a particular type is invoked, then the standard exception
+\code{TypeError} is raised with a operation name as an argument.
+
+In addition, for convenience this interface defines a set of
+constructors for building objects of built-in types.  This is needed
+so new objects can be returned from C functions that otherwise treat
+objects generically.
+
+\section{Reference Counting}
+
+For most of the functions in the Python-C API, if a function retains a
+reference to a Python object passed as an argument, then the function
+will increase the reference count of the object.  It is unnecessary
+for the caller to increase the reference count of an argument in
+anticipation of the object's retention.
+
+Usually, Python objects returned from functions should be treated as
+new objects.  Functions that return objects assume that the caller
+will retain a reference and the reference count of the object has
+already been incremented to account for this fact.  A caller that does
+not retain a reference to an object that is returned from a function
+must decrement the reference count of the object (using
+\code{Py_DECREF()}) to prevent memory leaks.
+
+Exceptions to these rules will be noted with the individual functions.
+
+\section{Include Files}
+
+All function, type and macro definitions needed to use the Python-C
+API are included in your code by the following line:
+
+\code{\#include "Python.h"}
+
+This implies inclusion of the following standard header files:
+stdio.h, string.h, errno.h, and stdlib.h (if available).
+
+All user visible names defined by Python.h (except those defined by
+the included standard headers) have one of the prefixes \code{Py} or
+\code{_Py}.  Names beginning with \code{_Py} are for internal use
+only.
+
+
+\chapter{Initialization and Shutdown of an Embedded Python Interpreter}
+
+When embedding the Python interpreter in a C or C++ program, the
+interpreter must be initialized.
+
+\begin{cfuncdesc}{void}{PyInitialize}{}
+This function initializes the interpreter.  It must be called before
+any interaction with the interpreter takes place.  If it is called
+more than once, the second and further calls have no effect.
+
+The function performs the following tasks: create an environment in
+which modules can be imported and Python code can be executed;
+initialize the \code{__builtin__} module; initialize the \code{sys}
+module; initialize \code{sys.path}; initialize signal handling; and
+create the empty \code{__main__} module.
+
+In the current system, there is no way to undo all these
+initializations or to create additional interpreter environments.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
+Register a cleanup function to be called when Python exits.  The
+cleanup function will be called with no arguments and should return no
+value.  At most 32 cleanup functions can be registered.  When the
+registration is successful, \code{Py_AtExit} returns 0; on failure, it
+returns -1.  Each cleanup function will be called t most once.  The
+cleanup function registered last is called first.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Exit}{int status}
+Exit the current process.  This calls \code{Py_Cleanup()} (see next
+item) and performs additional cleanup (under some circumstances it
+will attempt to delete all modules), and then calls the standard C
+library function \code{exit(status)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Cleanup}{}
+Perform some of the cleanup that \code{Py_Exit} performs, but don't
+exit the process.  In particular, this invokes the user's
+\code{sys.exitfunc} function (if defined at all), and it invokes the
+cleanup functions registered with \code{Py_AtExit()}, in reverse order
+of their registration.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
+Print a fatal error message and die.  No cleanup is performed.  This
+function should only be invoked when a condition is detected that
+would make it dangerous to continue using the Python interpreter;
+e.g., when the object administration appears to be corrupted.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyImport_Init}{}
+Initialize the module table.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
+Empty the module table.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyBuiltin_Init}{}
+Initialize the \code{__builtin__} module.  For internal use only.
+\end{cfuncdesc}
+
+
+\chapter{Reference Counting}
+
+The functions in this chapter are used for managing reference counts
+of Python objects.
+
+\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
+Increment the reference count for object \code{o}.  The object must
+not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
+\code{Py_XINCREF()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
+Increment the reference count for object \code{o}.  The object may be
+\NULL{}, in which case the function has no effect.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
+Decrement the reference count for object \code{o}.  The object must
+not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
+\code{Py_XDECREF()}.  If the reference count reaches zero, the object's
+type's deallocation function (which must not be \NULL{}) is invoked.
+
+\strong{Warning:} The deallocation function can cause arbitrary Python
+code to be invoked (e.g. when a class instance with a \code{__del__()}
+method is deallocated).  While exceptions in such code are not
+propagated, the executed code has free access to all Python global
+variables.  This means that any object that is reachable from a global
+variable should be in a consistent state before \code{Py_DECREF()} is
+invoked.  For example, code to delete an object from a list should
+copy a reference to the deleted object in a temporary variable, update
+the list data structure, and then call \code{Py_DECREF()} for the
+temporary variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
+Decrement the reference count for object \code{o}.The object may be
+\NULL{}, in which case the function has no effect; otherwise the
+effect is the same as for \code{Py_DECREF()}, and the same warning
+applies.
+\end{cfuncdesc}
+
+
+\chapter{Exception Handling}
+
+The functions in this chapter will let you handle and raise Python
+exceptions.
+
+\begin{cfuncdesc}{void}{PyErr_Print}{}
+\end{cfuncdesc}
+
+
+\chapter{Utilities}
+
+The functions in this chapter perform various utility tasks, such as
+parsing function arguments and constructing Python values from C
+values.
+
+\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
+Return true (nonzero) if the standard I/O file \code{fp} with name
+\code{filename} is deemed interactive.  This is the case for files for
+which \code{isatty(fileno(fp))} is true.  If the global flag
+\code{Py_InteractiveFlag} is true, this function also returns true if
+the \code{name} pointer is \NULL{} or if the name is equal to one of
+the strings \code{"<stdin>"} or \code{"???"}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
+Return the time of last modification of the file \code{filename}.
+The result is encoded in the same way as the timestamp returned by
+the standard C library function \code{time()}.
+\end{cfuncdesc}
+
+
+\chapter{Debugging}
+
+XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
+
+
+\chapter{The Very High Level Layer}
+
+The functions in this chapter will let you execute Python source code
+given in a file or a buffer, but they will not let you interact in a
+more detailed way with the interpreter.
+
+
+\chapter{Abstract Objects Layer}
+
+The functions in this chapter interact with Python objects regardless
+of their type, or with wide classes of object types (e.g. all
+numerical types, or all sequence types).  When used on object types
+for which they do not apply, they will flag a Python exception.
+
+\section{Object Protocol}
+
+\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
+Print an object \code{o}, on file \code{fp}.  Returns -1 on error
+The flags argument is used to enable certain printing
+options. The only option currently supported is \code{Py_Print_RAW}. 
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
+Returns 1 if o has the attribute attr_name, and 0 otherwise.
+This is equivalent to the Python expression:
+\code{hasattr(o,attr_name)}.
+This function always succeeds.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
+Retrieve an attributed named attr_name form object o.
+Returns the attribute value on success, or \NULL{} on failure.
+This is the equivalent of the Python expression: \code{o.attr_name}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
+Returns 1 if o has the attribute attr_name, and 0 otherwise.
+This is equivalent to the Python expression:
+\code{hasattr(o,attr_name)}. 
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
+Retrieve an attributed named attr_name form object o.
+Returns the attribute value on success, or \NULL{} on failure.
+This is the equivalent of the Python expression: o.attr_name.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
+Set the value of the attribute named \code{attr_name}, for object \code{o},
+to the value \code{v}. Returns -1 on failure.  This is
+the equivalent of the Python statement: \code{o.attr_name=v}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
+Set the value of the attribute named \code{attr_name}, for
+object \code{o},
+to the value \code{v}. Returns -1 on failure.  This is
+the equivalent of the Python statement: \code{o.attr_name=v}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
+Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on
+failure.  This is the equivalent of the Python
+statement: \code{del o.attr_name}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
+Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on
+failure.  This is the equivalent of the Python
+statement: \code{del o.attr_name}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
+Compare the values of \code{o1} and \code{o2} using a routine provided by
+\code{o1}, if one exists, otherwise with a routine provided by \code{o2}.
+The result of the comparison is returned in \code{result}.  Returns
+-1 on failure.  This is the equivalent of the Python
+statement: \code{result=cmp(o1,o2)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
+Compare the values of \code{o1} and \code{o2} using a routine provided by
+\code{o1}, if one exists, otherwise with a routine provided by \code{o2}.
+Returns the result of the comparison on success.  On error,
+the value returned is undefined. This is equivalent to the
+Python expression: \code{cmp(o1,o2)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
+Compute the string representation of object, \code{o}.  Returns the
+string representation on success, \NULL{} on failure.  This is
+the equivalent of the Python expression: \code{repr(o)}.
+Called by the \code{repr()} built-in function and by reverse quotes.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
+Compute the string representation of object, \code{o}.  Returns the
+string representation on success, \NULL{} on failure.  This is
+the equivalent of the Python expression: \code{str(o)}.
+Called by the \code{str()} built-in function and by the \code{print}
+statement.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
+Determine if the object \code{o}, is callable.  Return 1 if the
+object is callable and 0 otherwise.
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args}
+Call a callable Python object \code{callable_object}, with
+arguments given by the tuple \code{args}.  If no arguments are
+needed, then args may be \NULL{}.  Returns the result of the
+call on success, or \NULL{} on failure.  This is the equivalent
+of the Python expression: \code{apply(o, args)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
+Call a callable Python object \code{callable_object}, with a
+variable number of C arguments. The C arguments are described
+using a mkvalue-style format string. The format may be \NULL{},
+indicating that no arguments are provided.  Returns the
+result of the call on success, or \NULL{} on failure.  This is
+the equivalent of the Python expression: \code{apply(o,args)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
+Call the method named \code{m} of object \code{o} with a variable number of
+C arguments.  The C arguments are described by a mkvalue
+format string.  The format may be \NULL{}, indicating that no
+arguments are provided. Returns the result of the call on
+success, or \NULL{} on failure.  This is the equivalent of the
+Python expression: \code{o.method(args)}.
+Note that Special method names, such as "\code{__add__}",
+"\code{__getitem__}", and so on are not supported. The specific
+abstract-object routines for these must be used.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
+Compute and return the hash value of an object \code{o}.  On
+failure, return -1.  This is the equivalent of the Python
+expression: \code{hash(o)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
+Returns 1 if the object \code{o} is considered to be true, and
+0 otherwise. This is equivalent to the Python expression:
+\code{not not o}.
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
+On success, returns a type object corresponding to the object
+type of object \code{o}. On failure, returns \NULL{}.  This is
+equivalent to the Python expression: \code{type(o)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
+Return the length of object \code{o}.  If the object \code{o} provides
+both sequence and mapping protocols, the sequence length is
+returned. On error, -1 is returned.  This is the equivalent
+to the Python expression: \code{len(o)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
+Return element of \code{o} corresponding to the object \code{key} or \NULL{}
+on failure. This is the equivalent of the Python expression:
+\code{o[key]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
+Map the object \code{key} to the value \code{v}.
+Returns -1 on failure.  This is the equivalent
+of the Python statement: \code{o[key]=v}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v}
+Delete the mapping for \code{key} from \code{*o}.  Returns -1
+on failure.
+This is the equivalent of the Python statement: del o[key].
+\end{cfuncdesc}
+
+
+\section{Number Protocol}
+
+\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
+Returns 1 if the object \code{o} provides numeric protocols, and
+false otherwise. 
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
+Returns the result of adding \code{o1} and \code{o2}, or null on failure.
+This is the equivalent of the Python expression: \code{o1+o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
+Returns the result of subtracting \code{o2} from \code{o1}, or null on
+failure.  This is the equivalent of the Python expression:
+\code{o1-o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
+Returns the result of multiplying \code{o1} and \code{o2}, or null on
+failure.  This is the equivalent of the Python expression:
+\code{o1*o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
+Returns the result of dividing \code{o1} by \code{o2}, or null on failure.
+This is the equivalent of the Python expression: \code{o1/o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
+Returns the remainder of dividing \code{o1} by \code{o2}, or null on
+failure.  This is the equivalent of the Python expression:
+\code{o1\%o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
+See the built-in function divmod.  Returns \NULL{} on failure.
+This is the equivalent of the Python expression:
+\code{divmod(o1,o2)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
+See the built-in function pow.  Returns \NULL{} on failure.
+This is the equivalent of the Python expression:
+\code{pow(o1,o2,o3)}, where \code{o3} is optional.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
+Returns the negation of \code{o} on success, or null on failure.
+This is the equivalent of the Python expression: \code{-o}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
+Returns \code{o} on success, or \NULL{} on failure.
+This is the equivalent of the Python expression: \code{+o}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
+Returns the absolute value of \code{o}, or null on failure.  This is
+the equivalent of the Python expression: \code{abs(o)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
+Returns the bitwise negation of \code{o} on success, or \NULL{} on
+failure.  This is the equivalent of the Python expression:
+\code{~o}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
+Returns the result of left shifting \code{o1} by \code{o2} on success, or
+\NULL{} on failure.  This is the equivalent of the Python
+expression: \code{o1 << o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
+Returns the result of right shifting \code{o1} by \code{o2} on success, or
+\NULL{} on failure.  This is the equivalent of the Python
+expression: \code{o1 >> o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
+Returns the result of "anding" \code{o2} and \code{o2} on success and \NULL{}
+on failure. This is the equivalent of the Python
+expression: \code{o1 and o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
+Returns the bitwise exclusive or of \code{o1} by \code{o2} on success, or
+\NULL{} on failure.  This is the equivalent of the Python
+expression: \code{o1\^{ }o2}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
+Returns the result or \code{o1} and \code{o2} on success, or \NULL{} on
+failure.  This is the equivalent of the Python expression: 
+\code{o1 or o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject *o1, PyObject *o2}
+This function takes the addresses of two variables of type
+\code{PyObject*}.
+
+If the objects pointed to by \code{*p1} and \code{*p2} have the same type,
+increment their reference count and return 0 (success).
+If the objects can be converted to a common numeric type,
+replace \code{*p1} and \code{*p2} by their converted value (with 'new'
+reference counts), and return 0.
+If no conversion is possible, or if some other error occurs,
+return -1 (failure) and don't increment the reference counts.
+The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
+statement \code{o1, o2 = coerce(o1, o2)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
+Returns the \code{o} converted to an integer object on success, or
+\NULL{} on failure.  This is the equivalent of the Python
+expression: \code{int(o)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
+Returns the \code{o} converted to a long integer object on success,
+or \NULL{} on failure.  This is the equivalent of the Python
+expression: \code{long(o)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
+Returns the \code{o} converted to a float object on success, or \NULL{}
+on failure.  This is the equivalent of the Python expression:
+\code{float(o)}.
+\end{cfuncdesc}
+
+
+\section{Sequence protocol}
+
+\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
+Return 1 if the object provides sequence protocol, and 0
+otherwise.  
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
+Return the concatination of \code{o1} and \code{o2} on success, and \NULL{} on
+failure.   This is the equivalent of the Python
+expression: \code{o1+o2}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
+Return the result of repeating sequence object \code{o} count times,
+or \NULL{} on failure.  This is the equivalent of the Python
+expression: \code{o*count}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
+Return the ith element of \code{o}, or \NULL{} on failure. This is the
+equivalent of the Python expression: \code{o[i]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
+Return the slice of sequence object \code{o} between \code{i1} and \code{i2}, or
+\NULL{} on failure. This is the equivalent of the Python
+expression, \code{o[i1:i2]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
+Assign object \code{v} to the \code{i}th element of \code{o}.
+Returns -1 on failure.  This is the equivalent of the Python
+statement, \code{o[i]=v}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
+Delete the \code{i}th element of object \code{v}.  Returns
+-1 on failure.  This is the equivalent of the Python
+statement: \code{del o[i]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v}
+Assign the sequence object \code{v} to the slice in sequence
+object \code{o} from \code{i1} to \code{i2}.  This is the equivalent of the Python
+statement, \code{o[i1:i2]=v}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
+Delete the slice in sequence object, \code{o}, from \code{i1} to \code{i2}.
+Returns -1 on failure. This is the equivalent of the Python
+statement: \code{del o[i1:i2]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
+Returns the \code{o} as a tuple on success, and \NULL{} on failure.
+This is equivalent to the Python expression: \code{tuple(o)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
+Return the number of occurrences of \code{value} on \code{o}, that is,
+return the number of keys for which \code{o[key]==value}.  On
+failure, return -1.  This is equivalent to the Python
+expression: \code{o.count(value)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value}
+Determine if \code{o} contains \code{value}.  If an item in \code{o} is equal to
+\code{value}, return 1, otherwise return 0.  On error, return -1.  This
+is equivalent to the Python expression: \code{value in o}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
+Return the first index for which \code{o[i]=value}.  On error,
+return -1.    This is equivalent to the Python
+expression: \code{o.index(value)}.
+\end{cfuncdesc}
+
+\section{Mapping protocol}
+
+\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
+Return 1 if the object provides mapping protocol, and 0
+otherwise.  
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
+Returns the number of keys in object \code{o} on success, and -1 on
+failure.  For objects that do not provide sequence protocol,
+this is equivalent to the Python expression: \code{len(o)}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
+Remove the mapping for object \code{key} from the object \code{o}.
+Return -1 on failure.  This is equivalent to
+the Python statement: \code{del o[key]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
+Remove the mapping for object \code{key} from the object \code{o}.
+Return -1 on failure.  This is equivalent to
+the Python statement: \code{del o[key]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
+On success, return 1 if the mapping object has the key \code{key}
+and 0 otherwise.  This is equivalent to the Python expression:
+\code{o.has_key(key)}. 
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
+Return 1 if the mapping object has the key \code{key}
+and 0 otherwise.  This is equivalent to the Python expression:
+\code{o.has_key(key)}. 
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
+On success, return a list of the keys in object \code{o}.  On
+failure, return \NULL{}. This is equivalent to the Python
+expression: \code{o.keys()}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
+On success, return a list of the values in object \code{o}.  On
+failure, return \NULL{}. This is equivalent to the Python
+expression: \code{o.values()}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
+On success, return a list of the items in object \code{o}, where
+each item is a tuple containing a key-value pair.  On
+failure, return \NULL{}. This is equivalent to the Python
+expression: \code{o.items()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o}
+Make object \code{o} empty.  Returns 1 on success and 0 on failure.
+This is equivalent to the Python statement:
+\code{for key in o.keys(): del o[key]}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
+Return element of \code{o} corresponding to the object \code{key} or \NULL{}
+on failure. This is the equivalent of the Python expression:
+\code{o[key]}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
+Map the object \code{key} to the value \code{v} in object \code{o}.  Returns 
+-1 on failure.  This is the equivalent of the Python
+statement: \code{o[key]=v}.
+\end{cfuncdesc}
+
+
+\section{Constructors}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *file_name, char *mode}
+On success, returns a new file object that is opened on the
+file given by \code{file_name}, with a file mode given by \code{mode},
+where \code{mode} has the same semantics as the standard C routine,
+fopen.  On failure, return -1.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del}
+Return a new file object for an already opened standard C
+file pointer, \code{fp}.  A file name, \code{file_name}, and open mode,
+\code{mode}, must be provided as well as a flag, \code{close_on_del}, that
+indicates whether the file is to be closed when the file
+object is destroyed.  On failure, return -1.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
+Returns a new float object with the value \code{v} on success, and
+\NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v}
+Returns a new int object with the value \code{v} on success, and
+\NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyList_New}{int l}
+Returns a new list of length \code{l} on success, and \NULL{} on
+failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
+Returns a new long object with the value \code{v} on success, and
+\NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
+Returns a new long object with the value \code{v} on success, and
+\NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
+Returns a new empty dictionary on success, and \NULL{} on
+failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v}
+Returns a new string object with the value \code{v} on success, and
+\NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int l}
+Returns a new string object with the value \code{v} and length \code{l}
+on success, and \NULL{} on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int l}
+Returns a new tuple of length \code{l} on success, and \NULL{} on
+failure.
+\end{cfuncdesc}
+
+
+\chapter{Concrete Objects Layer}
+
+The functions in this chapter are specific to certain Python object
+types.  Passing them an object of the wrong type is not a good idea;
+if you receive an object from a Python program and you are not sure
+that it has the right type, you must perform a type check first;
+e.g. to check that an object is a dictionary, use
+\code{PyDict_Check()}.
+
+
+\chapter{Defining New Object Types}
+
+\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
+\end{cfuncdesc}
+
+\input{api.ind}			% Index -- must be last
+
+\end{document}