Relocating file to Doc/api.
diff --git a/Doc/api.tex b/Doc/api.tex
deleted file mode 100644
index b0b7bfd..0000000
--- a/Doc/api.tex
+++ /dev/null
@@ -1,3016 +0,0 @@
-\documentclass{manual}
-
-\title{Python/C API Reference Manual}
-
-\input{boilerplate}
-
-\makeindex % tell \index to actually write the .idx file
-
-
-\begin{document}
-
-\maketitle
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-This manual documents the API used by \C{} (or \Cpp{}) programmers who
-want to write extension modules or embed Python. It is a companion to
-\emph{Extending and Embedding the Python Interpreter}, which describes
-the general principles of extension writing but does not document the
-API functions in detail.
-
-\strong{Warning:} The current version of this document is incomplete.
-I hope that it is nevertheless useful. I will continue to work on it,
-and release new versions from time to time, independent from Python
-source code releases.
-
-\end{abstract}
-
-\tableofcontents
-
-% XXX Consider moving all this back to ext.tex and giving api.tex
-% XXX a *really* short intro only.
-
-\chapter{Introduction}
-\label{intro}
-
-The Application Programmer's Interface to Python gives \C{} and \Cpp{}
-programmers access to the Python interpreter at a variety of levels.
-The API is equally usable from \Cpp{}, but for brevity it is generally
-referred to as the Python/\C{} API. There are two fundamentally
-different reasons for using the Python/\C{} API. The first reason is
-to write \emph{extension modules} for specific purposes; these are
-\C{} modules that extend the Python interpreter. This is probably the
-most common use. The second reason is to use Python as a component in
-a larger application; this technique is generally referred to as
-\dfn{embedding} Python in an application.
-
-Writing an extension module is a relatively well-understood process,
-where a ``cookbook'' approach works well. There are several tools
-that automate the process to some extent. While people have embedded
-Python in other applications since its early existence, the process of
-embedding Python is less straightforward that writing an extension.
-Python 1.5 introduces a number of new API functions as well as some
-changes to the build process that make embedding much simpler.
-This manual describes the \version\ state of affairs.
-% XXX Eventually, take the historical notes out
-
-Many API functions are useful independent of whether you're embedding
-or extending Python; moreover, most applications that embed Python
-will need to provide a custom extension as well, so it's probably a
-good idea to become familiar with writing an extension before
-attempting to embed Python in a real application.
-
-\section{Include Files}
-\label{includes}
-
-All function, type and macro definitions needed to use the Python/C
-API are included in your code by the following line:
-
-\begin{verbatim}
-#include "Python.h"
-\end{verbatim}
-
-This implies inclusion of the following standard headers:
-\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
-\code{<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 \samp{Py} or
-\samp{_Py}. Names beginning with \samp{_Py} are for internal use
-only. Structure member names do not have a reserved prefix.
-
-\strong{Important:} user code should never define names that begin
-with \samp{Py} or \samp{_Py}. This confuses the reader, and
-jeopardizes the portability of the user code to future Python
-versions, which may define additional names beginning with one of
-these prefixes.
-
-\section{Objects, Types and Reference Counts}
-\label{objects}
-
-Most Python/C API functions have one or more arguments as well as a
-return value of type \ctype{PyObject *}. This type is a pointer
-to an opaque data type representing an arbitrary Python
-object. Since all Python object types are treated the same way by the
-Python language in most situations (e.g., assignments, scope rules,
-and argument passing), it is only fitting that they should be
-represented by a single \C{} type. All Python objects live on the heap:
-you never declare an automatic or static variable of type
-\ctype{PyObject}, only pointer variables of type \ctype{PyObject *} can
-be declared.
-
-All Python objects (even Python integers) have a \dfn{type} and a
-\dfn{reference count}. An object's type determines what kind of object
-it is (e.g., an integer, a list, or a user-defined function; there are
-many more as explained in the \emph{Python Reference Manual}). For
-each of the well-known types there is a macro to check whether an
-object is of that type; for instance, \samp{PyList_Check(\var{a})} is
-true iff the object pointed to by \var{a} is a Python list.
-
-\subsection{Reference Counts}
-\label{refcounts}
-
-The reference count is important because today's computers have a
-finite (and often severely limited) memory size; it counts how many
-different places there are that have a reference to an object. Such a
-place could be another object, or a global (or static) \C{} variable, or
-a local variable in some \C{} function. When an object's reference count
-becomes zero, the object is deallocated. If it contains references to
-other objects, their reference count is decremented. Those other
-objects may be deallocated in turn, if this decrement makes their
-reference count become zero, and so on. (There's an obvious problem
-with objects that reference each other here; for now, the solution is
-``don't do that''.)
-
-Reference counts are always manipulated explicitly. The normal way is
-to use the macro \cfunction{Py_INCREF()} to increment an object's
-reference count by one, and \cfunction{Py_DECREF()} to decrement it by
-one. The decref macro is considerably more complex than the incref one,
-since it must check whether the reference count becomes zero and then
-cause the object's deallocator, which is a function pointer contained
-in the object's type structure. The type-specific deallocator takes
-care of decrementing the reference counts for other objects contained
-in the object, and so on, if this is a compound object type such as a
-list. There's no chance that the reference count can overflow; at
-least as many bits are used to hold the reference count as there are
-distinct memory locations in virtual memory (assuming
-\code{sizeof(long) >= sizeof(char *)}). Thus, the reference count
-increment is a simple operation.
-
-It is not necessary to increment an object's reference count for every
-local variable that contains a pointer to an object. In theory, the
-object's reference count goes up by one when the variable is made to
-point to it and it goes down by one when the variable goes out of
-scope. However, these two cancel each other out, so at the end the
-reference count hasn't changed. The only real reason to use the
-reference count is to prevent the object from being deallocated as
-long as our variable is pointing to it. If we know that there is at
-least one other reference to the object that lives at least as long as
-our variable, there is no need to increment the reference count
-temporarily. An important situation where this arises is in objects
-that are passed as arguments to \C{} functions in an extension module
-that are called from Python; the call mechanism guarantees to hold a
-reference to every argument for the duration of the call.
-
-However, a common pitfall is to extract an object from a list and
-hold on to it for a while without incrementing its reference count.
-Some other operation might conceivably remove the object from the
-list, decrementing its reference count and possible deallocating it.
-The real danger is that innocent-looking operations may invoke
-arbitrary Python code which could do this; there is a code path which
-allows control to flow back to the user from a \cfunction{Py_DECREF()},
-so almost any operation is potentially dangerous.
-
-A safe approach is to always use the generic operations (functions
-whose name begins with \samp{PyObject_}, \samp{PyNumber_},
-\samp{PySequence_} or \samp{PyMapping_}). These operations always
-increment the reference count of the object they return. This leaves
-the caller with the responsibility to call \cfunction{Py_DECREF()}
-when they are done with the result; this soon becomes second nature.
-
-\subsubsection{Reference Count Details}
-\label{refcountDetails}
-
-The reference count behavior of functions in the Python/C API is best
-expelained in terms of \emph{ownership of references}. Note that we
-talk of owning references, never of owning objects; objects are always
-shared! When a function owns a reference, it has to dispose of it
-properly --- either by passing ownership on (usually to its caller) or
-by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When
-a function passes ownership of a reference on to its caller, the
-caller is said to receive a \emph{new} reference. When no ownership
-is transferred, the caller is said to \emph{borrow} the reference.
-Nothing needs to be done for a borrowed reference.
-
-Conversely, when calling a function passes it a reference to an
-object, there are two possibilities: the function \emph{steals} a
-reference to the object, or it does not. Few functions steal
-references; the two notable exceptions are
-\cfunction{PyList_SetItem()} and \cfunction{PyTuple_SetItem()}, which
-steal a reference to the item (but not to the tuple or list into which
-the item is put!). These functions were designed to steal a reference
-because of a common idiom for populating a tuple or list with newly
-created objects; for example, the code to create the tuple \code{(1,
-2, "three")} could look like this (forgetting about error handling for
-the moment; a better way to code this is shown below anyway):
-
-\begin{verbatim}
-PyObject *t;
-
-t = PyTuple_New(3);
-PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
-PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
-PyTuple_SetItem(t, 2, PyString_FromString("three"));
-\end{verbatim}
-
-Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
-set tuple items; \cfunction{PySequence_SetItem()} and
-\cfunction{PyObject_SetItem()} refuse to do this since tuples are an
-immutable data type. You should only use
-\cfunction{PyTuple_SetItem()} for tuples that you are creating
-yourself.
-
-Equivalent code for populating a list can be written using
-\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
-can also use \cfunction{PySequence_SetItem()}; this illustrates the
-difference between the two (the extra \cfunction{Py_DECREF()} calls):
-
-\begin{verbatim}
-PyObject *l, *x;
-
-l = PyList_New(3);
-x = PyInt_FromLong(1L);
-PySequence_SetItem(l, 0, x); Py_DECREF(x);
-x = PyInt_FromLong(2L);
-PySequence_SetItem(l, 1, x); Py_DECREF(x);
-x = PyString_FromString("three");
-PySequence_SetItem(l, 2, x); Py_DECREF(x);
-\end{verbatim}
-
-You might find it strange that the ``recommended'' approach takes more
-code. However, in practice, you will rarely use these ways of
-creating and populating a tuple or list. There's a generic function,
-\cfunction{Py_BuildValue()}, that can create most common objects from
-\C{} values, directed by a \dfn{format string}. For example, the
-above two blocks of code could be replaced by the following (which
-also takes care of the error checking):
-
-\begin{verbatim}
-PyObject *t, *l;
-
-t = Py_BuildValue("(iis)", 1, 2, "three");
-l = Py_BuildValue("[iis]", 1, 2, "three");
-\end{verbatim}
-
-It is much more common to use \cfunction{PyObject_SetItem()} and
-friends with items whose references you are only borrowing, like
-arguments that were passed in to the function you are writing. In
-that case, their behaviour regarding reference counts is much saner,
-since you don't have to increment a reference count so you can give a
-reference away (``have it be stolen''). For example, this function
-sets all items of a list (actually, any mutable sequence) to a given
-item:
-
-\begin{verbatim}
-int set_all(PyObject *target, PyObject *item)
-{
- int i, n;
-
- n = PyObject_Length(target);
- if (n < 0)
- return -1;
- for (i = 0; i < n; i++) {
- if (PyObject_SetItem(target, i, item) < 0)
- return -1;
- }
- return 0;
-}
-\end{verbatim}
-
-The situation is slightly different for function return values.
-While passing a reference to most functions does not change your
-ownership responsibilities for that reference, many functions that
-return a referece to an object give you ownership of the reference.
-The reason is simple: in many cases, the returned object is created
-on the fly, and the reference you get is the only reference to the
-object. Therefore, the generic functions that return object
-references, like \cfunction{PyObject_GetItem()} and
-\cfunction{PySequence_GetItem()}, always return a new reference (i.e.,
-the caller becomes the owner of the reference).
-
-It is important to realize that whether you own a reference returned
-by a function depends on which function you call only --- \emph{the
-plumage} (i.e., the type of the type of the object passed as an
-argument to the function) \emph{doesn't enter into it!} Thus, if you
-extract an item from a list using \cfunction{PyList_GetItem()}, you
-don't own the reference --- but if you obtain the same item from the
-same list using \cfunction{PySequence_GetItem()} (which happens to
-take exactly the same arguments), you do own a reference to the
-returned object.
-
-Here is an example of how you could write a function that computes the
-sum of the items in a list of integers; once using
-\cfunction{PyList_GetItem()}, once using
-\cfunction{PySequence_GetItem()}.
-
-\begin{verbatim}
-long sum_list(PyObject *list)
-{
- int i, n;
- long total = 0;
- PyObject *item;
-
- n = PyList_Size(list);
- if (n < 0)
- return -1; /* Not a list */
- for (i = 0; i < n; i++) {
- item = PyList_GetItem(list, i); /* Can't fail */
- if (!PyInt_Check(item)) continue; /* Skip non-integers */
- total += PyInt_AsLong(item);
- }
- return total;
-}
-\end{verbatim}
-
-\begin{verbatim}
-long sum_sequence(PyObject *sequence)
-{
- int i, n;
- long total = 0;
- PyObject *item;
- n = PyObject_Size(list);
- if (n < 0)
- return -1; /* Has no length */
- for (i = 0; i < n; i++) {
- item = PySequence_GetItem(list, i);
- if (item == NULL)
- return -1; /* Not a sequence, or other failure */
- if (PyInt_Check(item))
- total += PyInt_AsLong(item);
- Py_DECREF(item); /* Discard reference ownership */
- }
- return total;
-}
-\end{verbatim}
-
-\subsection{Types}
-\label{types}
-
-There are few other data types that play a significant role in
-the Python/C API; most are simple \C{} types such as \ctype{int},
-\ctype{long}, \ctype{double} and \ctype{char *}. A few structure types
-are used to describe static tables used to list the functions exported
-by a module or the data attributes of a new object type. These will
-be discussed together with the functions that use them.
-
-\section{Exceptions}
-\label{exceptions}
-
-The Python programmer only needs to deal with exceptions if specific
-error handling is required; unhandled exceptions are automatically
-propagated to the caller, then to the caller's caller, and so on, till
-they reach the top-level interpreter, where they are reported to the
-user accompanied by a stack traceback.
-
-For \C{} programmers, however, error checking always has to be explicit.
-All functions in the Python/C API can raise exceptions, unless an
-explicit claim is made otherwise in a function's documentation. In
-general, when a function encounters an error, it sets an exception,
-discards any object references that it owns, and returns an
-error indicator --- usually \NULL{} or \code{-1}. A few functions
-return a Boolean true/false result, with false indicating an error.
-Very few functions return no explicit error indicator or have an
-ambiguous return value, and require explicit testing for errors with
-\cfunction{PyErr_Occurred()}.
-
-Exception state is maintained in per-thread storage (this is
-equivalent to using global storage in an unthreaded application). A
-thread can be in one of two states: an exception has occurred, or not.
-The function \cfunction{PyErr_Occurred()} can be used to check for
-this: it returns a borrowed reference to the exception type object
-when an exception has occurred, and \NULL{} otherwise. There are a
-number of functions to set the exception state:
-\cfunction{PyErr_SetString()} is the most common (though not the most
-general) function to set the exception state, and
-\cfunction{PyErr_Clear()} clears the exception state.
-
-The full exception state consists of three objects (all of which can
-be \NULL{}): the exception type, the corresponding exception
-value, and the traceback. These have the same meanings as the Python
-object \code{sys.exc_type}, \code{sys.exc_value},
-\code{sys.exc_traceback}; however, they are not the same: the Python
-objects represent the last exception being handled by a Python
-\keyword{try} \ldots\ \keyword{except} statement, while the \C{} level
-exception state only exists while an exception is being passed on
-between \C{} functions until it reaches the Python interpreter, which
-takes care of transferring it to \code{sys.exc_type} and friends.
-
-Note that starting with Python 1.5, the preferred, thread-safe way to
-access the exception state from Python code is to call the function
-\function{sys.exc_info()}, which returns the per-thread exception state
-for Python code. Also, the semantics of both ways to access the
-exception state have changed so that a function which catches an
-exception will save and restore its thread's exception state so as to
-preserve the exception state of its caller. This prevents common bugs
-in exception handling code caused by an innocent-looking function
-overwriting the exception being handled; it also reduces the often
-unwanted lifetime extension for objects that are referenced by the
-stack frames in the traceback.
-
-As a general principle, a function that calls another function to
-perform some task should check whether the called function raised an
-exception, and if so, pass the exception state on to its caller. It
-should discard any object references that it owns, and returns an
-error indicator, but it should \emph{not} set another exception ---
-that would overwrite the exception that was just raised, and lose
-important information about the exact cause of the error.
-
-A simple example of detecting exceptions and passing them on is shown
-in the \cfunction{sum_sequence()} example above. It so happens that
-that example doesn't need to clean up any owned references when it
-detects an error. The following example function shows some error
-cleanup. First, to remind you why you like Python, we show the
-equivalent Python code:
-
-\begin{verbatim}
-def incr_item(dict, key):
- try:
- item = dict[key]
- except KeyError:
- item = 0
- return item + 1
-\end{verbatim}
-
-Here is the corresponding \C{} code, in all its glory:
-
-\begin{verbatim}
-int incr_item(PyObject *dict, PyObject *key)
-{
- /* Objects all initialized to NULL for Py_XDECREF */
- PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
- int rv = -1; /* Return value initialized to -1 (failure) */
-
- item = PyObject_GetItem(dict, key);
- if (item == NULL) {
- /* Handle KeyError only: */
- if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error;
-
- /* Clear the error and use zero: */
- PyErr_Clear();
- item = PyInt_FromLong(0L);
- if (item == NULL) goto error;
- }
-
- const_one = PyInt_FromLong(1L);
- if (const_one == NULL) goto error;
-
- incremented_item = PyNumber_Add(item, const_one);
- if (incremented_item == NULL) goto error;
-
- if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
- rv = 0; /* Success */
- /* Continue with cleanup code */
-
- error:
- /* Cleanup code, shared by success and failure path */
-
- /* Use Py_XDECREF() to ignore NULL references */
- Py_XDECREF(item);
- Py_XDECREF(const_one);
- Py_XDECREF(incremented_item);
-
- return rv; /* -1 for error, 0 for success */
-}
-\end{verbatim}
-
-This example represents an endorsed use of the \keyword{goto} statement
-in \C{}! It illustrates the use of
-\cfunction{PyErr_ExceptionMatches()} and \cfunction{PyErr_Clear()} to
-handle specific exceptions, and the use of \cfunction{Py_XDECREF()} to
-dispose of owned references that may be \NULL{} (note the \samp{X} in
-the name; \cfunction{Py_DECREF()} would crash when confronted with a
-\NULL{} reference). It is important that the variables used to hold
-owned references are initialized to \NULL{} for this to work;
-likewise, the proposed return value is initialized to \code{-1}
-(failure) and only set to success after the final call made is
-successful.
-
-
-\section{Embedding Python}
-\label{embedding}
-
-The one important task that only embedders (as opposed to extension
-writers) of the Python interpreter have to worry about is the
-initialization, and possibly the finalization, of the Python
-interpreter. Most functionality of the interpreter can only be used
-after the interpreter has been initialized.
-
-The basic initialization function is \cfunction{Py_Initialize()}.
-This initializes the table of loaded modules, and creates the
-fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__} and
-\module{sys}\refbimodindex{sys}. It also initializes the module
-search path (\code{sys.path}).%
-\indexiii{module}{search}{path}
-
-\cfunction{Py_Initialize()} does not set the ``script argument list''
-(\code{sys.argv}). If this variable is needed by Python code that
-will be executed later, it must be set explicitly with a call to
-\code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call
-to \cfunction{Py_Initialize()}.
-
-On most systems (in particular, on \UNIX{} and Windows, although the
-details are slightly different), \cfunction{Py_Initialize()}
-calculates the module search path based upon its best guess for the
-location of the standard Python interpreter executable, assuming that
-the Python library is found in a fixed location relative to the Python
-interpreter executable. In particular, it looks for a directory named
-\file{lib/python1.5} (replacing \file{1.5} with the current
-interpreter version) relative to the parent directory where the
-executable named \file{python} is found on the shell command search
-path (the environment variable \envvar{PATH}).
-
-For instance, if the Python executable is found in
-\file{/usr/local/bin/python}, it will assume that the libraries are in
-\file{/usr/local/lib/python1.5}. (In fact, this particular path
-is also the ``fallback'' location, used when no executable file named
-\file{python} is found along \envvar{PATH}.) The user can override
-this behavior by setting the environment variable \envvar{PYTHONHOME},
-or insert additional directories in front of the standard path by
-setting \envvar{PYTHONPATH}.
-
-The embedding application can steer the search by calling
-\code{Py_SetProgramName(\var{file})} \emph{before} calling
-\cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
-overrides this and \envvar{PYTHONPATH} is still inserted in front of
-the standard path. An application that requires total control has to
-provide its own implementation of \cfunction{Py_GetPath()},
-\cfunction{Py_GetPrefix()}, \cfunction{Py_GetExecPrefix()},
-\cfunction{Py_GetProgramFullPath()} (all defined in
-\file{Modules/getpath.c}).
-
-Sometimes, it is desirable to ``uninitialize'' Python. For instance,
-the application may want to start over (make another call to
-\cfunction{Py_Initialize()}) or the application is simply done with its
-use of Python and wants to free all memory allocated by Python. This
-can be accomplished by calling \cfunction{Py_Finalize()}. The function
-\cfunction{Py_IsInitialized()} returns true iff Python is currently in the
-initialized state. More information about these functions is given in
-a later chapter.
-
-
-\chapter{The Very High Level Layer}
-\label{veryhigh}
-
-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.
-
-\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
- int start}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
- char *filename, int start}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
- PyObject *globals,
- PyObject *locals}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
- int start, PyObject *globals,
- PyObject *locals}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
- int start}
-\end{cfuncdesc}
-
-
-\chapter{Reference Counting}
-\label{countingRefs}
-
-The macros in this section are used for managing reference counts
-of Python objects.
-
-\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
-Increment the reference count for object \var{o}. The object must
-not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
-\cfunction{Py_XINCREF()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
-Increment the reference count for object \var{o}. The object may be
-\NULL{}, in which case the macro has no effect.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
-Decrement the reference count for object \var{o}. The object must
-not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
-\cfunction{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 \method{__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 \cfunction{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 \cfunction{Py_DECREF()} for the
-temporary variable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
-Decrement the reference count for object \var{o}. The object may be
-\NULL{}, in which case the macro has no effect; otherwise the effect
-is the same as for \cfunction{Py_DECREF()}, and the same warning
-applies.
-\end{cfuncdesc}
-
-The following functions or macros are only for internal use:
-\cfunction{_Py_Dealloc()}, \cfunction{_Py_ForgetReference()},
-\cfunction{_Py_NewReference()}, as well as the global variable
-\cdata{_Py_RefTotal}.
-
-XXX Should mention Py_Malloc(), Py_Realloc(), Py_Free(),
-PyMem_Malloc(), PyMem_Realloc(), PyMem_Free(), PyMem_NEW(),
-PyMem_RESIZE(), PyMem_DEL(), PyMem_XDEL().
-
-
-\chapter{Exception Handling}
-\label{exceptionHandling}
-
-The functions in this chapter will let you handle and raise Python
-exceptions. It is important to understand some of the basics of
-Python exception handling. It works somewhat like the \UNIX{}
-\cdata{errno} variable: there is a global indicator (per thread) of the
-last error that occurred. Most functions don't clear this on success,
-but will set it to indicate the cause of the error on failure. Most
-functions also return an error indicator, usually \NULL{} if they are
-supposed to return a pointer, or \code{-1} if they return an integer
-(exception: the \cfunction{PyArg_Parse*()} functions return \code{1} for
-success and \code{0} for failure). When a function must fail because
-some function it called failed, it generally doesn't set the error
-indicator; the function it called already set it.
-
-The error indicator consists of three Python objects corresponding to
-the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
-\code{sys.exc_traceback}. API functions exist to interact with the
-error indicator in various ways. There is a separate error indicator
-for each thread.
-
-% XXX Order of these should be more thoughtful.
-% Either alphabetical or some kind of structure.
-
-\begin{cfuncdesc}{void}{PyErr_Print}{}
-Print a standard traceback to \code{sys.stderr} and clear the error
-indicator. Call this function only when the error indicator is set.
-(Otherwise it will cause a fatal error!)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
-Test whether the error indicator is set. If set, return the exception
-\emph{type} (the first argument to the last call to one of the
-\cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If
-not set, return \NULL{}. You do not own a reference to the return
-value, so you do not need to \cfunction{Py_DECREF()} it.
-\strong{Note:} do not compare the return value to a specific
-exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
-below.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
-Equivalent to
-\samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
-This should only be called when an exception is actually set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
-Return true if the \var{given} exception matches the exception in
-\var{exc}. If \var{exc} is a class object, this also returns true
-when \var{given} is a subclass. If \var{exc} is a tuple, all
-exceptions in the tuple (and recursively in subtuples) are searched
-for a match. This should only be called when an exception is actually
-set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
-Under certain circumstances, the values returned by
-\cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
-\code{*\var{exc}} is a class object but \code{*\var{val}} is not an
-instance of the same class. This function can be used to instantiate
-the class in that case. If the values are already normalized, nothing
-happens.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Clear}{}
-Clear the error indicator. If the error indicator is not set, there
-is no effect.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, PyObject **ptraceback}
-Retrieve the error indicator into three variables whose addresses are
-passed. If the error indicator is not set, set all three variables to
-\NULL{}. If it is set, it will be cleared and you own a reference to
-each object retrieved. The value and traceback object may be \NULL{}
-even when the type object is not. \strong{Note:} this function is
-normally only used by code that needs to handle exceptions or by code
-that needs to save and restore the error indicator temporarily.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, PyObject *traceback}
-Set the error indicator from the three objects. If the error
-indicator is already set, it is cleared first. If the objects are
-\NULL{}, the error indicator is cleared. Do not pass a \NULL{} type
-and non-\NULL{} value or traceback. The exception type should be a
-string or class; if it is a class, the value should be an instance of
-that class. Do not pass an invalid exception type or value.
-(Violating these rules will cause subtle problems later.) This call
-takes away a reference to each object, i.e. you must own a reference
-to each object before the call and after the call you no longer own
-these references. (If you don't understand this, don't use this
-function. I warned you.) \strong{Note:} this function is normally
-only used by code that needs to save and restore the error indicator
-temporarily.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
-This is the most common way to set the error indicator. The first
-argument specifies the exception type; it is normally one of the
-standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not
-increment its reference count. The second argument is an error
-message; it is converted to a string object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
-This function is similar to \cfunction{PyErr_SetString()} but lets you
-specify an arbitrary Python object for the ``value'' of the exception.
-You need not increment its reference count.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
-This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
-This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
-\var{message})}, where \var{message} indicates that a built-in operation
-was invoked with an illegal argument. It is mostly for internal use.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
-This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
-returns \NULL{} so an object allocation function can write
-\samp{return PyErr_NoMemory();} when it runs out of memory.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
-This is a convenience function to raise an exception when a \C{} library
-function has returned an error and set the \C{} variable \cdata{errno}.
-It constructs a tuple object whose first item is the integer
-\cdata{errno} value and whose second item is the corresponding error
-message (gotten from \cfunction{strerror()}), and then calls
-\samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
-the \cdata{errno} value is \constant{EINTR}, indicating an interrupted
-system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
-the error indicator, leaves it set to that. The function always
-returns \NULL{}, so a wrapper function around a system call can write
-\samp{return PyErr_SetFromErrno();} when the system call returns an
-error.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
-This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
-\var{message})}, where \var{message} indicates that an internal
-operation (e.g. a Python/C API function) was invoked with an illegal
-argument. It is mostly for internal use.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
-This function interacts with Python's signal handling. It checks
-whether a signal has been sent to the processes and if so, invokes the
-corresponding signal handler. If the
-\module{signal}\refbimodindex{signal} module is supported, this can
-invoke a signal handler written in Python. In all cases, the default
-effect for \constant{SIGINT} is to raise the
-\exception{KeyboadInterrupt} exception. If an exception is raised the
-error indicator is set and the function returns \code{1}; otherwise
-the function returns \code{0}. The error indicator may or may not be
-cleared if it was previously set.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
-This function is obsolete (XXX or platform dependent?). It simulates
-the effect of a \constant{SIGINT} signal arriving --- the next time
-\cfunction{PyErr_CheckSignals()} is called,
-\exception{KeyboadInterrupt} will be raised.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
- PyObject *base,
- PyObject *dict}
-This utility function creates and returns a new exception object. The
-\var{name} argument must be the name of the new exception, a \C{} string
-of the form \code{module.class}. The \var{base} and \var{dict}
-arguments are normally \NULL{}. Normally, this creates a class
-object derived from the root for all exceptions, the built-in name
-\exception{Exception} (accessible in \C{} as \cdata{PyExc_Exception}).
-In this case the \member{__module__} attribute of the new class is set to the
-first part (up to the last dot) of the \var{name} argument, and the
-class name is set to the last part (after the last dot). When the
-user has specified the \code{-X} command line option to use string
-exceptions, for backward compatibility, or when the \var{base}
-argument is not a class object (and not \NULL{}), a string object
-created from the entire \var{name} argument is returned. The
-\var{base} argument can be used to specify an alternate base class.
-The \var{dict} argument can be used to specify a dictionary of class
-variables and methods.
-\end{cfuncdesc}
-
-
-\section{Standard Exceptions}
-\label{standardExceptions}
-
-All standard Python exceptions are available as global variables whose
-names are \samp{PyExc_} followed by the Python exception name.
-These have the type \ctype{PyObject *}; they are all either class
-objects or string objects, depending on the use of the \code{-X}
-option to the interpreter. For completeness, here are all the
-variables:
-\cdata{PyExc_Exception},
-\cdata{PyExc_StandardError},
-\cdata{PyExc_ArithmeticError},
-\cdata{PyExc_LookupError},
-\cdata{PyExc_AssertionError},
-\cdata{PyExc_AttributeError},
-\cdata{PyExc_EOFError},
-\cdata{PyExc_FloatingPointError},
-\cdata{PyExc_IOError},
-\cdata{PyExc_ImportError},
-\cdata{PyExc_IndexError},
-\cdata{PyExc_KeyError},
-\cdata{PyExc_KeyboardInterrupt},
-\cdata{PyExc_MemoryError},
-\cdata{PyExc_NameError},
-\cdata{PyExc_OverflowError},
-\cdata{PyExc_RuntimeError},
-\cdata{PyExc_SyntaxError},
-\cdata{PyExc_SystemError},
-\cdata{PyExc_SystemExit},
-\cdata{PyExc_TypeError},
-\cdata{PyExc_ValueError},
-\cdata{PyExc_ZeroDivisionError}.
-
-
-\chapter{Utilities}
-\label{utilities}
-
-The functions in this chapter perform various utility tasks, such as
-parsing function arguments and constructing Python values from \C{}
-values.
-
-\section{OS Utilities}
-\label{os}
-
-\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
-Return true (nonzero) if the standard I/O file \var{fp} with name
-\var{filename} is deemed interactive. This is the case for files for
-which \samp{isatty(fileno(\var{fp}))} is true. If the global flag
-\cdata{Py_InteractiveFlag} is true, this function also returns true if
-the \var{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 \var{filename}.
-The result is encoded in the same way as the timestamp returned by
-the standard \C{} library function \cfunction{time()}.
-\end{cfuncdesc}
-
-
-\section{Process Control}
-\label{processControl}
-
-\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
-Print a fatal error message and kill the process. 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. On \UNIX{}, the standard \C{} library function
-\cfunction{abort()} is called which will attempt to produce a
-\file{core} file.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_Exit}{int status}
-Exit the current process. This calls \cfunction{Py_Finalize()} and
-then calls the standard \C{} library function
-\code{exit(\var{status})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
-Register a cleanup function to be called by \cfunction{Py_Finalize()}.
-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, \cfunction{Py_AtExit()} returns
-\code{0}; on failure, it returns \code{-1}. The cleanup function
-registered last is called first. Each cleanup function will be called
-at most once. Since Python's internal finallization will have
-completed before the cleanup function, no Python APIs should be called
-by \var{func}.
-\end{cfuncdesc}
-
-
-\section{Importing Modules}
-\label{importing}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name}
-This is a simplified interface to \cfunction{PyImport_ImportModuleEx()}
-below, leaving the \var{globals} and \var{locals} arguments set to
-\NULL{}. When the \var{name} argument contains a dot (i.e., when
-it specifies a submodule of a package), the \var{fromlist} argument is
-set to the list \code{['*']} so that the return value is the named
-module rather than the top-level package containing it as would
-otherwise be the case. (Unfortunately, this has an additional side
-effect when \var{name} in fact specifies a subpackage instead of a
-submodule: the submodules specified in the package's \code{__all__}
-variable are loaded.) Return a new reference to the imported module,
-or \NULL{} with an exception set on failure (the module may still
-be created in this case --- examine \code{sys.modules} to find out).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
-Import a module. This is best described by referring to the built-in
-Python function \function{__import__()}\bifuncindex{__import__}, as
-the standard \function{__import__()} function calls this function
-directly.
-
-The return value is a new reference to the imported module or
-top-level package, or \NULL{} with an exception set on failure
-(the module may still be created in this case). Like for
-\function{__import__()}, the return value when a submodule of a
-package was requested is normally the top-level package, unless a
-non-empty \var{fromlist} was given.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
-This is a higher-level interface that calls the current ``import hook
-function''. It invokes the \function{__import__()} function from the
-\code{__builtins__} of the current globals. This means that the
-import is done using whatever import hooks are installed in the
-current environment, e.g. by \module{rexec}\refstmodindex{rexec} or
-\module{ihooks}\refstmodindex{ihooks}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m}
-Reload a module. This is best described by referring to the built-in
-Python function \function{reload()}\bifuncindex{reload}, as the standard
-\function{reload()} function calls this function directly. Return a
-new reference to the reloaded module, or \NULL{} with an exception set
-on failure (the module still exists in this case).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name}
-Return the module object corresponding to a module name. The
-\var{name} argument may be of the form \code{package.module}). First
-check the modules dictionary if there's one there, and if not, create
-a new one and insert in in the modules dictionary. Because the former
-action is most common, this does not return a new reference, and you
-do not own the returned reference. Return \NULL{} with an
-exception set on failure. \strong{Note:} this function returns
-a ``borrowed'' reference.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co}
-Given a module name (possibly of the form \code{package.module}) and a
-code object read from a Python bytecode file or obtained from the
-built-in function \function{compile()}\bifuncindex{compile}, load the
-module. Return a new reference to the module object, or \NULL{} with
-an exception set if an error occurred (the module may still be created
-in this case). (This function would reload the module if it was
-already imported.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
-Return the magic number for Python bytecode files (a.k.a. \file{.pyc}
-and \file{.pyo} files). The magic number should be present in the
-first four bytes of the bytecode file, in little-endian byte order.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
-Return the dictionary used for the module administration
-(a.k.a. \code{sys.modules}). Note that this is a per-interpreter
-variable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyImport_Init}{}
-Initialize the import mechanism. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
-Empty the module table. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{_PyImport_Fini}{}
-Finalize the import mechanism. For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
-For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
-For internal use only.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
-Load a frozen module. Return \code{1} for success, \code{0} if the
-module is not found, and \code{-1} with an exception set if the
-initialization failed. To access the imported module on a successful
-load, use \cfunction{PyImport_ImportModule()}.
-(Note the misnomer --- this function would reload the module if it was
-already imported.)
-\end{cfuncdesc}
-
-\begin{ctypedesc}{struct _frozen}
-This is the structure type definition for frozen module descriptors,
-as generated by the \program{freeze}\index{freeze utility} utility
-(see \file{Tools/freeze/} in the Python source distribution). Its
-definition is:
-
-\begin{verbatim}
-struct _frozen {
- char *name;
- unsigned char *code;
- int size;
-};
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
-This pointer is initialized to point to an array of \ctype{struct
-_frozen} records, terminated by one whose members are all \NULL{}
-or zero. When a frozen module is imported, it is searched in this
-table. Third-party code could play tricks with this to provide a
-dynamically created collection of frozen modules.
-\end{cvardesc}
-
-
-\chapter{Abstract Objects Layer}
-\label{abstract}
-
-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}
-\label{object}
-
-\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
-Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error
-The flags argument is used to enable certain printing
-options. The only option currently supported is
-\constant{Py_PRINT_RAW}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
-Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
-\code{0} otherwise. This is equivalent to the Python expression
-\samp{hasattr(\var{o}, \var{attr_name})}.
-This function always succeeds.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
-Retrieve an attribute named \var{attr_name} from object \var{o}.
-Returns the attribute value on success, or \NULL{} on failure.
-This is the equivalent of the Python expression
-\samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
-Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
-\code{0} otherwise. This is equivalent to the Python expression
-\samp{hasattr(\var{o}, \var{attr_name})}.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
-Retrieve an attribute named \var{attr_name} from object \var{o}.
-Returns the attribute value on success, or \NULL{} on failure.
-This is the equivalent of the Python expression
-\samp{\var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
-Set the value of the attribute named \var{attr_name}, for object
-\var{o}, to the value \var{v}. Returns \code{-1} on failure. This is
-the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
-\var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
-Set the value of the attribute named \var{attr_name}, for
-object \var{o},
-to the value \var{v}. Returns \code{-1} on failure. This is
-the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
-\var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
-Delete attribute named \var{attr_name}, for object \var{o}. Returns
-\code{-1} on failure. This is the equivalent of the Python
-statement: \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
-Delete attribute named \var{attr_name}, for object \var{o}. Returns
-\code{-1} on failure. This is the equivalent of the Python
-statement \samp{del \var{o}.\var{attr_name}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
-Compare the values of \var{o1} and \var{o2} using a routine provided
-by \var{o1}, if one exists, otherwise with a routine provided by
-\var{o2}. The result of the comparison is returned in \var{result}.
-Returns \code{-1} on failure. This is the equivalent of the Python
-statement \samp{\var{result} = cmp(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
-Compare the values of \var{o1} and \var{o2} using a routine provided
-by \var{o1}, if one exists, otherwise with a routine provided by
-\var{o2}. Returns the result of the comparison on success. On error,
-the value returned is undefined; use \cfunction{PyErr_Occurred()} to
-detect an error. This is equivalent to the
-Python expression \samp{cmp(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
-Compute the string representation of object, \var{o}. Returns the
-string representation on success, \NULL{} on failure. This is
-the equivalent of the Python expression \samp{repr(\var{o})}.
-Called by the \function{repr()}\bifuncindex{repr} built-in function
-and by reverse quotes.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
-Compute the string representation of object \var{o}. Returns the
-string representation on success, \NULL{} on failure. This is
-the equivalent of the Python expression \samp{str(\var{o})}.
-Called by the \function{str()}\bifuncindex{str} built-in function and
-by the \keyword{print} statement.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
-Determine if the object \var{o}, is callable. Return \code{1} if the
-object is callable and \code{0} otherwise.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args}
-Call a callable Python object \var{callable_object}, with
-arguments given by the tuple \var{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 \samp{apply(\var{o}, \var{args})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
-Call a callable Python object \var{callable_object}, with a
-variable number of \C{} arguments. The \C{} arguments are described
-using a \cfunction{Py_BuildValue()} 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 \samp{apply(\var{o},
-\var{args})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
-Call the method named \var{m} of object \var{o} with a variable number
-of C arguments. The \C{} arguments are described by a
-\cfunction{Py_BuildValue()} 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 \samp{\var{o}.\var{method}(\var{args})}.
-Note that Special method names, such as \method{__add__()},
-\method{__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 \var{o}. On
-failure, return \code{-1}. This is the equivalent of the Python
-expression \samp{hash(\var{o})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
-Returns \code{1} if the object \var{o} is considered to be true, and
-\code{0} otherwise. This is equivalent to the Python expression
-\samp{not not \var{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 \var{o}. On failure, returns \NULL{}. This is
-equivalent to the Python expression \samp{type(\var{o})}.
-\bifuncindex{type}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
-Return the length of object \var{o}. If the object \var{o} provides
-both sequence and mapping protocols, the sequence length is
-returned. On error, \code{-1} is returned. This is the equivalent
-to the Python expression \samp{len(\var{o})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
-Return element of \var{o} corresponding to the object \var{key} or
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
-Map the object \var{key} to the value \var{v}.
-Returns \code{-1} on failure. This is the equivalent
-of the Python statement \samp{\var{o}[\var{key}] = \var{v}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v}
-Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on
-failure. This is the equivalent of the Python statement \samp{del
-\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\section{Number Protocol}
-\label{number}
-
-\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
-Returns \code{1} if the object \var{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 \var{o1} and \var{o2}, or \NULL{} on
-failure. This is the equivalent of the Python expression
-\samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
-Returns the result of subtracting \var{o2} from \var{o1}, or \NULL{}
-on failure. This is the equivalent of the Python expression
-\samp{\var{o1} - \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
-Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
-failure. This is the equivalent of the Python expression
-\samp{\var{o1} * \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
-Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
-failure.
-This is the equivalent of the Python expression \samp{\var{o1} /
-\var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
-Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
-failure. This is the equivalent of the Python expression
-\samp{\var{o1} \% \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
-See the built-in function \function{divmod()}\bifuncindex{divmod}.
-Returns \NULL{} on failure. This is the equivalent of the Python
-expression \samp{divmod(\var{o1}, \var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
-See the built-in function \function{pow()}\bifuncindex{pow}. Returns
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional.
-If \var{o3} is to be ignored, pass \cdata{Py_None} in its place.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
-Returns the negation of \var{o} on success, or \NULL{} on failure.
-This is the equivalent of the Python expression \samp{-\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
-Returns \var{o} on success, or \NULL{} on failure.
-This is the equivalent of the Python expression \samp{+\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
-Returns the absolute value of \var{o}, or \NULL{} on failure. This is
-the equivalent of the Python expression \samp{abs(\var{o})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
-Returns the bitwise negation of \var{o} on success, or \NULL{} on
-failure. This is the equivalent of the Python expression
-\samp{\~\var{o}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
-Returns the result of left shifting \var{o1} by \var{o2} on success,
-or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o1} << \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
-Returns the result of right shifting \var{o1} by \var{o2} on success,
-or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o1} >> \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
-Returns the result of ``anding'' \var{o2} and \var{o2} on success and
-\NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o1} and \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
-Returns the bitwise exclusive or of \var{o1} by \var{o2} on success,
-or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o1} \^{ }\var{o2}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
-Returns the result of \var{o1} and \var{o2} on success, or \NULL{} on
-failure. This is the equivalent of the Python expression
-\samp{\var{o1} or \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
-This function takes the addresses of two variables of type
-\ctype{PyObject*}.
-
-If the objects pointed to by \code{*\var{p1}} and \code{*\var{p2}}
-have the same type, increment their reference count and return
-\code{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 \code{0}.
-If no conversion is possible, or if some other error occurs,
-return \code{-1} (failure) and don't increment the reference counts.
-The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the
-Python statement \samp{\var{o1}, \var{o2} = coerce(\var{o1},
-\var{o2})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
-Returns the \var{o} converted to an integer object on success, or
-\NULL{} on failure. This is the equivalent of the Python
-expression \samp{int(\var{o})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
-Returns the \var{o} converted to a long integer object on success,
-or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{long(\var{o})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
-Returns the \var{o} converted to a float object on success, or \NULL{}
-on failure. This is the equivalent of the Python expression
-\samp{float(\var{o})}.
-\end{cfuncdesc}
-
-
-\section{Sequence Protocol}
-\label{sequence}
-
-\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
-Return \code{1} if the object provides sequence protocol, and \code{0}
-otherwise.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
-Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
-failure. This is the equivalent of the Python
-expression \samp{\var{o1} + \var{o2}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
-Return the result of repeating sequence object \var{o} \var{count}
-times, or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o} * \var{count}}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
-Return the \var{i}th element of \var{o}, or \NULL{} on failure. This
-is the equivalent of the Python expression \samp{\var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
-Return the slice of sequence object \var{o} between \var{i1} and
-\var{i2}, or \NULL{} on failure. This is the equivalent of the Python
-expression \samp{\var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
-Assign object \var{v} to the \var{i}th element of \var{o}.
-Returns \code{-1} on failure. This is the equivalent of the Python
-statement \samp{\var{o}[\var{i}] = \var{v}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
-Delete the \var{i}th element of object \var{v}. Returns
-\code{-1} on failure. This is the equivalent of the Python
-statement \samp{del \var{o}[\var{i}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v}
-Assign the sequence object \var{v} to the slice in sequence
-object \var{o} from \var{i1} to \var{i2}. This is the equivalent of
-the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
-Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}.
-Returns \code{-1} on failure. This is the equivalent of the Python
-statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
-Returns the \var{o} as a tuple on success, and \NULL{} on failure.
-This is equivalent to the Python expression \code{tuple(\var{o})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
-Return the number of occurrences of \var{value} in \var{o}, that is,
-return the number of keys for which \code{\var{o}[\var{key}] ==
-\var{value}}. On failure, return \code{-1}. This is equivalent to
-the Python expression \samp{\var{o}.count(\var{value})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value}
-Determine if \var{o} contains \var{value}. If an item in \var{o} is
-equal to \var{value}, return \code{1}, otherwise return \code{0}. On
-error, return \code{-1}. This is equivalent to the Python expression
-\samp{\var{value} in \var{o}}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
-Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
-\var{value}}. On error, return \code{-1}. This is equivalent to
-the Python expression \samp{\var{o}.index(\var{value})}.
-\end{cfuncdesc}
-
-
-\section{Mapping Protocol}
-\label{mapping}
-
-\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
-Return \code{1} if the object provides mapping protocol, and \code{0}
-otherwise.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
-Returns the number of keys in object \var{o} on success, and \code{-1}
-on failure. For objects that do not provide sequence protocol,
-this is equivalent to the Python expression \samp{len(\var{o})}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
-Remove the mapping for object \var{key} from the object \var{o}.
-Return \code{-1} on failure. This is equivalent to
-the Python statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
-Remove the mapping for object \var{key} from the object \var{o}.
-Return \code{-1} on failure. This is equivalent to
-the Python statement \samp{del \var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
-On success, return \code{1} if the mapping object has the key \var{key}
-and \code{0} otherwise. This is equivalent to the Python expression
-\samp{\var{o}.has_key(\var{key})}.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
-Return \code{1} if the mapping object has the key \var{key} and
-\code{0} otherwise. This is equivalent to the Python expression
-\samp{\var{o}.has_key(\var{key})}.
-This function always succeeds.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
-On success, return a list of the keys in object \var{o}. On
-failure, return \NULL{}. This is equivalent to the Python
-expression \samp{\var{o}.keys()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
-On success, return a list of the values in object \var{o}. On
-failure, return \NULL{}. This is equivalent to the Python
-expression \samp{\var{o}.values()}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
-On success, return a list of the items in object \var{o}, where
-each item is a tuple containing a key-value pair. On
-failure, return \NULL{}. This is equivalent to the Python
-expression \samp{\var{o}.items()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o}
-Make object \var{o} empty. Returns \code{1} on success and \code{0}
-on failure. This is equivalent to the Python statement
-\samp{for key in \var{o}.keys(): del \var{o}[key]}.
-\end{cfuncdesc}
-
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
-Return element of \var{o} corresponding to the object \var{key} or
-\NULL{} on failure. This is the equivalent of the Python expression
-\samp{\var{o}[\var{key}]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
-Map the object \var{key} to the value \var{v} in object \var{o}.
-Returns \code{-1} on failure. This is the equivalent of the Python
-statement \samp{\var{o}[\var{key}] = \var{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 \var{file_name}, with a file mode given by \var{mode},
-where \var{mode} has the same semantics as the standard \C{} routine
-\cfunction{fopen()}. On failure, return \code{-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, \var{fp}. A file name, \var{file_name}, and open mode,
-\var{mode}, must be provided as well as a flag, \var{close_on_del},
-that indicates whether the file is to be closed when the file object
-is destroyed. On failure, return \code{-1}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
-Returns a new float object with the value \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v}
-Returns a new int object with the value \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
-Returns a new list of length \var{len} on success, and \NULL{} on
-failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-Returns a new long object with the value \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-Returns a new long object with the value \var{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 \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int len}
-Returns a new string object with the value \var{v} and length
-\var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{},
-the contents of the string are uninitialized.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
-Returns a new tuple of length \var{len} on success, and \NULL{} on
-failure.
-\end{cfuncdesc}
-
-
-\chapter{Concrete Objects Layer}
-\label{concrete}
-
-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
-\cfunction{PyDict_Check()}. The chapter is structured like the
-``family tree'' of Python object types.
-
-
-\section{Fundamental Objects}
-\label{fundamental}
-
-This section describes Python type objects and the singleton object
-\code{None}.
-
-
-\subsection{Type Objects}
-\label{typeObjects}
-
-\begin{ctypedesc}{PyTypeObject}
-
-\end{ctypedesc}
-
-\begin{cvardesc}{PyObject *}{PyType_Type}
-
-\end{cvardesc}
-
-
-\subsection{The None Object}
-\label{noneObject}
-
-\begin{cvardesc}{PyObject *}{Py_None}
-The Python \code{None} object, denoting lack of value. This object has
-no methods.
-\end{cvardesc}
-
-
-\section{Sequence Objects}
-\label{sequenceObjects}
-
-Generic operations on sequence objects were discussed in the previous
-chapter; this section deals with the specific kinds of sequence
-objects that are intrinsic to the Python language.
-
-
-\subsection{String Objects}
-\label{stringObjects}
-
-\begin{ctypedesc}{PyStringObject}
-This subtype of \ctype{PyObject} represents a Python string object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyString_Type}
-This instance of \ctype{PyTypeObject} represents the Python string type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
-Returns true if the object \var{o} is a string object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v,
- int len}
-Returns a new string object with the value \var{v} and length
-\var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{},
-the contents of the string are uninitialized.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v}
-Returns a new string object with the value \var{v} on success, and
-\NULL{} on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
-Returns the length of the string in string object \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
-Resturns a \NULL{} terminated representation of the contents of \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
- PyObject *newpart}
-Creates a new string object in \var{*string} containing the contents
-of \var{newpart} appended to \var{string}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
- PyObject *newpart}
-Creates a new string object in \var{*string} containing the contents
-of \var{newpart} appended to \var{string}. This version decrements
-the reference count of \var{newpart}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
-A way to resize a string object even though it is ``immutable''.
-Only use this to build up a brand new string object; don't use this if
-the string may already be known in other parts of the code.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
- PyObject *args}
-Returns a new string object from \var{format} and \var{args}. Analogous
-to \code{\var{format} \% \var{args}}. The \var{args} argument must be
-a tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
-Intern the argument \var{*string} in place. The argument must be the
-address of a pointer variable pointing to a Python string object.
-If there is an existing interned string that is the same as
-\var{*string}, it sets \var{*string} to it (decrementing the reference
-count of the old string object and incrementing the reference count of
-the interned string object), otherwise it leaves \var{*string} alone
-and interns it (incrementing its reference count). (Clarification:
-even though there is a lot of talk about reference counts, think of
-this function as reference-count-neutral; you own the object after
-the call if and only if you owned it before the call.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyString_InternFromString}{const char *v}
-A combination of \cfunction{PyString_FromString()} and
-\cfunction{PyString_InternInPlace()}, returning either a new string object
-that has been interned, or a new (``owned'') reference to an earlier
-interned string object with the same value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
-Macro form of \cfunction{PyString_AsString()} but without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
-Macro form of \cfunction{PyString_GetSize()} but without error checking.
-\end{cfuncdesc}
-
-
-
-\subsection{Tuple Objects}
-\label{tupleObjects}
-
-\begin{ctypedesc}{PyTupleObject}
-This subtype of \ctype{PyObject} represents a Python tuple object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyTuple_Type}
-This instance of \ctype{PyTypeObject} represents the Python tuple type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
-Return true if the argument is a tuple object.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_New}{int s}
-Return a new tuple object of size \var{s}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
-Takes a pointer to a tuple object, and returns the size
-of that tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyTupleObject *p, int pos}
-Returns the object at position \var{pos} in the tuple pointed
-to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and
-sets an \exception{IndexError} exception. \strong{Note:} this
-function returns a ``borrowed'' reference.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
-Does the same, but does no checking of its arguments.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
- int low,
- int high}
-Takes a slice of the tuple pointed to by \var{p} from
-\var{low} to \var{high} and returns it as a new tuple.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
- int pos,
- PyObject *o}
-Inserts a reference to object \var{o} at position \var{pos} of
-the tuple pointed to by \var{p}. It returns \code{0} on success.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
- int pos,
- PyObject *o}
-
-Does the same, but does no error checking, and
-should \emph{only} be used to fill in brand new tuples.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p,
- int new,
- int last_is_sticky}
-Can be used to resize a tuple. Because tuples are
-\emph{supposed} to be immutable, this should only be used if there is only
-one module referencing the object. Do \emph{not} use this if the tuple may
-already be known to some other part of the code. \var{last_is_sticky} is
-a flag --- if set, the tuple will grow or shrink at the front, otherwise
-it will grow or shrink at the end. Think of this as destroying the old
-tuple and creating a new one, only more efficiently.
-\end{cfuncdesc}
-
-
-\subsection{List Objects}
-\label{listObjects}
-
-\begin{ctypedesc}{PyListObject}
-This subtype of \ctype{PyObject} represents a Python list object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyList_Type}
-This instance of \ctype{PyTypeObject} represents the Python list type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyListObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_New}{int size}
-Returns a new list of length \var{len} on success, and \NULL{} on
-failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
-Returns the length of the list object in \var{list}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetItem}{PyObject *list, int index}
-Returns the object at position \var{pos} in the list pointed
-to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and
-sets an \exception{IndexError} exception. \strong{Note:} this
-function returns a ``borrowed'' reference.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
- PyObject *item}
-Sets the item at index \var{index} in list to \var{item}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
- PyObject *item}
-Inserts the item \var{item} into list \var{list} in front of index
-\var{index}. Returns 0 if successful; returns -1 and sets an
-exception if unsuccessful. Analogous to \code{list.insert(index, item)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Append}{PyObject *list, PyObject *item}
-Appends the object \var{item} at the end of list \var{list}. Returns
-0 if successful; returns -1 and sets an exception if unsuccessful.
-Analogous to \code{list.append(item)}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
- int low, int high}
-Returns a list of the objects in \var{list} containing the objects
-\emph{between} \var{low} and \var{high}. Returns NULL and sets an
-exception if unsuccessful.
-Analogous to \code{list[low:high]}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
- int low, int high,
- PyObject *itemlist}
-Sets the slice of \var{list} between \var{low} and \var{high} to the contents
-of \var{itemlist}. Analogous to \code{list[low:high]=itemlist}. Returns 0
-on success, -1 on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
-Sorts the items of \var{list} in place. Returns 0 on success, -1 on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
-Reverses the items of \var{list} in place. Returns 0 on success, -1 on failure.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list}
-Returns a new tuple object containing the contents of \var{list}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i}
-Macro form of \cfunction{PyList_GetItem()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyList_SET_ITEM}{PyObject *list, int i,
- PyObject *o}
-Macro form of \cfunction{PyList_SetItem()} without error checking.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
-Macro form of \cfunction{PyList_GetSize()} without error checking.
-\end{cfuncdesc}
-
-
-\section{Mapping Objects}
-\label{mapObjects}
-
-\subsection{Dictionary Objects}
-\label{dictObjects}
-
-\begin{ctypedesc}{PyDictObject}
-This subtype of \ctype{PyObject} represents a Python dictionary object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyDict_Type}
-This instance of \ctype{PyTypeObject} represents the Python dictionary type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyDictObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_New}{}
-Returns a new empty dictionary.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
-Empties an existing dictionary of all key/value pairs.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
- PyObject *key,
- PyObject *val}
-Inserts \var{value} into the dictionary with a key of \var{key}. Both
-\var{key} and \var{value} should be PyObjects, and \var{key} should be
-hashable.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
- char *key,
- PyObject *val}
-Inserts \var{value} into the dictionary using \var{key}
-as a key. \var{key} should be a \ctype{char *}. The key object is
-created using \code{PyString_FromString(\var{key})}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
-Removes the entry in dictionary \var{p} with key \var{key}.
-\var{key} is a PyObject.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
-Removes the entry in dictionary \var{p} which has a key
-specified by the \ctype{char *}\var{key}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
-Returns the object from dictionary \var{p} which has a key
-\var{key}. Returns \NULL{} if the key \var{key} is not present, but
-without (!) setting an exception. \strong{Note:} this function
-returns a ``borrowed'' reference.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyDictObject *p, char *key}
-This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
-specified as a \ctype{char *}, rather than a \ctype{PyObject *}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyDictObject *p}
-Returns a \ctype{PyListObject} containing all the items
-from the dictionary, as in the dictinoary method \method{items()} (see
-the \emph{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyDictObject *p}
-Returns a \ctype{PyListObject} containing all the keys
-from the dictionary, as in the dictionary method \method{keys()} (see the
-\emph{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyDictObject *p}
-Returns a \ctype{PyListObject} containing all the values
-from the dictionary \var{p}, as in the dictionary method
-\method{values()} (see the \emph{Python Library Reference}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
-Returns the number of items in the dictionary.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
- int ppos,
- PyObject **pkey,
- PyObject **pvalue}
-
-\end{cfuncdesc}
-
-
-\section{Numeric Objects}
-\label{numericObjects}
-
-\subsection{Plain Integer Objects}
-\label{intObjects}
-
-\begin{ctypedesc}{PyIntObject}
-This subtype of \ctype{PyObject} represents a Python integer object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyInt_Type}
-This instance of \ctype{PyTypeObject} represents the Python plain
-integer type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
-
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
-Creates a new integer object with a value of \var{ival}.
-
-The current implementation keeps an array of integer objects for all
-integers between \code{-1} and \code{100}, when you create an int in
-that range you actually just get back a reference to the existing
-object. So it should be possible to change the value of \code{1}. I
-suspect the behaviour of Python in this case is undefined. :-)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
-Returns the value of the object \var{io}. No error checking is
-performed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
-Will first attempt to cast the object to a \ctype{PyIntObject}, if
-it is not already one, and then return its value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyInt_GetMax}{}
-Returns the systems idea of the largest integer it can handle
-(\constant{LONG_MAX}, as defined in the system header files).
-\end{cfuncdesc}
-
-
-\subsection{Long Integer Objects}
-\label{longObjects}
-
-\begin{ctypedesc}{PyLongObject}
-This subtype of \ctype{PyObject} represents a Python long integer
-object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyLong_Type}
-This instance of \ctype{PyTypeObject} represents the Python long
-integer type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyLongObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
-Returns a new \ctype{PyLongObject} object from \var{v}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
-Returns a new \ctype{PyLongObject} object from an unsigned \C{} long.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
-Returns a new \ctype{PyLongObject} object from the integer part of \var{v}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
-Returns a \C{} \ctype{long} representation of the contents of \var{pylong}.
-WHAT HAPPENS IF \var{pylong} is greater than \constant{LONG_MAX}?
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
-Returns a \C{} \ctype{unsigned long} representation of the contents of
-\var{pylong}. WHAT HAPPENS IF \var{pylong} is greater than
-\constant{ULONG_MAX}?
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
-Returns a \C{} \ctype{double} representation of the contents of \var{pylong}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
- int base}
-\end{cfuncdesc}
-
-
-\subsection{Floating Point Objects}
-\label{floatObjects}
-
-\begin{ctypedesc}{PyFloatObject}
-This subtype of \ctype{PyObject} represents a Python floating point
-object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFloat_Type}
-This instance of \ctype{PyTypeObject} represents the Python floating
-point type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyFloatObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
-Creates a \ctype{PyFloatObject} object from \var{v}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
-Returns a \C{} \ctype{double} representation of the contents of \var{pyfloat}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
-Returns a \C{} \ctype{double} representation of the contents of
-\var{pyfloat}, but without error checking.
-\end{cfuncdesc}
-
-
-\subsection{Complex Number Objects}
-\label{complexObjects}
-
-\begin{ctypedesc}{Py_complex}
-The \C{} structure which corresponds to the value portion of a Python
-complex number object. Most of the functions for dealing with complex
-number objects use structures of this type as input or output values,
-as appropriate. It is defined as:
-
-\begin{verbatim}
-typedef struct {
- double real;
- double imag;
-} Py_complex;
-\end{verbatim}
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyComplexObject}
-This subtype of \ctype{PyObject} represents a Python complex number object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyComplex_Type}
-This instance of \ctype{PyTypeObject} represents the Python complex
-number type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyComplexObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
- Py_complex divisor}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
-Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
-Returns the real part of \var{op} as a \C{} \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
-Returns the imaginary part of \var{op} as a \C{} \ctype{double}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
-\end{cfuncdesc}
-
-
-
-\section{Other Objects}
-\label{otherObjects}
-
-\subsection{File Objects}
-\label{fileObjects}
-
-\begin{ctypedesc}{PyFileObject}
-This subtype of \ctype{PyObject} represents a Python file object.
-\end{ctypedesc}
-
-\begin{cvardesc}{PyTypeObject}{PyFile_Type}
-This instance of \ctype{PyTypeObject} represents the Python file type.
-\end{cvardesc}
-
-\begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
-Returns true if its argument is a \ctype{PyFileObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *name, char *mode}
-Creates a new \ctype{PyFileObject} pointing to the file
-specified in \var{name} with the mode specified in \var{mode}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp,
- char *name, char *mode, int (*close)}
-Creates a new \ctype{PyFileObject} from the already-open \var{fp}.
-The function \var{close} will be called when the file should be
-closed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
-Returns the file object associated with \var{p} as a \ctype{FILE *}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n}
-undocumented as yet
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p}
-Returns the name of the file specified by \var{p} as a
-\ctype{PyStringObject}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
-Available on systems with \cfunction{setvbuf()} only. This should
-only be called immediately after file object creation.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
-Sets the \member{softspace} attribute of \var{p} to \var{newflag}.
-Returns the previous value. This function clears any errors, and will
-return \code{0} as the previous value if the attribute either does not
-exist or if there were errors in retrieving it. There is no way to
-detect errors from this function, but doing so should not be needed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
- int flags}
-Writes object \var{obj} to file object \var{p}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
- int flags}
-Writes string \var{s} to file object \var{p}.
-\end{cfuncdesc}
-
-
-\subsection{CObjects}
-\label{cObjects}
-
-\begin{ctypedesc}{PyCObject}
-This subtype of \ctype{PyObject} represents an opaque value, useful for
-\C{} extension modules who need to pass an opaque value (as a
-\ctype{void *} pointer) through Python code to other \C{} code. It is
-often used to make a C function pointer defined in one module
-available to other modules, so the regular import mechanism can be
-used to access C APIs defined in dynamically loaded modules.
-\end{ctypedesc}
-
-\begin{cfuncdesc}{PyObject *}{PyCObject_FromVoidPtr}{void* cobj,
- void (*destr)(void *)}
-Creates a \ctype{PyCObject} from the \code{void *} \var{cobj}. The
-\var{destr} function will be called when the object is reclaimed.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject *}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
- void* desc, void (*destr)(void *, void *) }
-Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The
-\var{destr} function will be called when the object is reclaimed. The
-\var{desc} argument can be used to pass extra callback data for the
-destructor function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void *}{PyCObject_AsVoidPtr}{PyObject* self}
-Returns the object \ctype{void *} that the \ctype{PyCObject} \var{self}
-was created with.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void *}{PyCObject_GetDesc}{PyObject* self}
-Returns the description \ctype{void *} that the \ctype{PyCObject}
-\var{self} was created with.
-\end{cfuncdesc}
-
-\chapter{Initialization, Finalization, and Threads}
-\label{initialization}
-
-\begin{cfuncdesc}{void}{Py_Initialize}{}
-Initialize the Python interpreter. In an application embedding
-Python, this should be called before using any other Python/C API
-functions; with the exception of \cfunction{Py_SetProgramName()},
-\cfunction{PyEval_InitThreads()}, \cfunction{PyEval_ReleaseLock()},
-and \cfunction{PyEval_AcquireLock()}. This initializes the table of
-loaded modules (\code{sys.modules}), and creates the fundamental
-modules \module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__} and
-\module{sys}\refbimodindex{sys}. It also initializes the module
-search path (\code{sys.path}).%
-\indexiii{module}{search}{path}
-It does not set \code{sys.argv}; use \cfunction{PySys_SetArgv()} for
-that. This is a no-op when called for a second time (without calling
-\cfunction{Py_Finalize()} first). There is no return value; it is a
-fatal error if the initialization fails.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{Py_IsInitialized}{}
-Return true (nonzero) when the Python interpreter has been
-initialized, false (zero) if not. After \cfunction{Py_Finalize()} is
-called, this returns false until \cfunction{Py_Initialize()} is called
-again.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_Finalize}{}
-Undo all initializations made by \cfunction{Py_Initialize()} and
-subsequent use of Python/C API functions, and destroy all
-sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
-created and not yet destroyed since the last call to
-\cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
-by the Python interpreter. This is a no-op when called for a second
-time (without calling \cfunction{Py_Initialize()} again first). There
-is no return value; errors during finalization are ignored.
-
-This function is provided for a number of reasons. An embedding
-application might want to restart Python without having to restart the
-application itself. An application that has loaded the Python
-interpreter from a dynamically loadable library (or DLL) might want to
-free all memory allocated by Python before unloading the DLL. During a
-hunt for memory leaks in an application a developer might want to free
-all memory allocated by Python before exiting from the application.
-
-\strong{Bugs and caveats:} The destruction of modules and objects in
-modules is done in random order; this may cause destructors
-(\method{__del__()} methods) to fail when they depend on other objects
-(even functions) or modules. Dynamically loaded extension modules
-loaded by Python are not unloaded. Small amounts of memory allocated
-by the Python interpreter may not be freed (if you find a leak, please
-report it). Memory tied up in circular references between objects is
-not freed. Some memory allocated by extension modules may not be
-freed. Some extension may not work properly if their initialization
-routine is called more than once; this can happen if an applcation
-calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
-than once.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
-Create a new sub-interpreter. This is an (almost) totally separate
-environment for the execution of Python code. In particular, the new
-interpreter has separate, independent versions of all imported
-modules, including the fundamental modules
-\module{__builtin__}\refbimodindex{__builtin__},
-\module{__main__}\refbimodindex{__main__} and
-\module{sys}\refbimodindex{sys}. The table of loaded modules
-(\code{sys.modules}) and the module search path (\code{sys.path}) are
-also separate. The new environment has no \code{sys.argv} variable.
-It has new standard I/O stream file objects \code{sys.stdin},
-\code{sys.stdout} and \code{sys.stderr} (however these refer to the
-same underlying \ctype{FILE} structures in the \C{} library).
-
-The return value points to the first thread state created in the new
-sub-interpreter. This thread state is made the current thread state.
-Note that no actual thread is created; see the discussion of thread
-states below. If creation of the new interpreter is unsuccessful,
-\NULL{} is returned; no exception is set since the exception state
-is stored in the current thread state and there may not be a current
-thread state. (Like all other Python/C API functions, the global
-interpreter lock must be held before calling this function and is
-still held when it returns; however, unlike most other Python/C API
-functions, there needn't be a current thread state on entry.)
-
-Extension modules are shared between (sub-)interpreters as follows:
-the first time a particular extension is imported, it is initialized
-normally, and a (shallow) copy of its module's dictionary is
-squirreled away. When the same extension is imported by another
-(sub-)interpreter, a new module is initialized and filled with the
-contents of this copy; the extension's \code{init} function is not
-called. Note that this is different from what happens when an
-extension is imported after the interpreter has been completely
-re-initialized by calling \cfunction{Py_Finalize()} and
-\cfunction{Py_Initialize()}; in that case, the extension's \code{init}
-function \emph{is} called again.
-
-\strong{Bugs and caveats:} Because sub-interpreters (and the main
-interpreter) are part of the same process, the insulation between them
-isn't perfect --- for example, using low-level file operations like
-\function{os.close()} they can (accidentally or maliciously) affect each
-other's open files. Because of the way extensions are shared between
-(sub-)interpreters, some extensions may not work properly; this is
-especially likely when the extension makes use of (static) global
-variables, or when the extension manipulates its module's dictionary
-after its initialization. It is possible to insert objects created in
-one sub-interpreter into a namespace of another sub-interpreter; this
-should be done with great care to avoid sharing user-defined
-functions, methods, instances or classes between sub-interpreters,
-since import operations executed by such objects may affect the
-wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
-a hard-to-fix bug that will be addressed in a future release.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
-Destroy the (sub-)interpreter represented by the given thread state.
-The given thread state must be the current thread state. See the
-discussion of thread states below. When the call returns, the current
-thread state is \NULL{}. All thread states associated with this
-interpreted are destroyed. (The global interpreter lock must be held
-before calling this function and is still held when it returns.)
-\cfunction{Py_Finalize()} will destroy all sub-interpreters that haven't
-been explicitly destroyed at that point.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
-This function should be called before \cfunction{Py_Initialize()} is called
-for the first time, if it is called at all. It tells the interpreter
-the value of the \code{argv[0]} argument to the \cfunction{main()} function
-of the program. This is used by \cfunction{Py_GetPath()} and some other
-functions below to find the Python run-time libraries relative to the
-interpreter executable. The default value is \code{"python"}. The
-argument should point to a zero-terminated character string in static
-storage whose contents will not change for the duration of the
-program's execution. No code in the Python interpreter will change
-the contents of this storage.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetProgramName}{}
-Return the program name set with \cfunction{Py_SetProgramName()}, or the
-default. The returned string points into static storage; the caller
-should not modify its value.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetPrefix}{}
-Return the \emph{prefix} for installed platform-independent files. This
-is derived through a number of complicated rules from the program name
-set with \cfunction{Py_SetProgramName()} and some environment variables;
-for example, if the program name is \code{"/usr/local/bin/python"},
-the prefix is \code{"/usr/local"}. The returned string points into
-static storage; the caller should not modify its value. This
-corresponds to the \makevar{prefix} variable in the top-level
-\file{Makefile} and the \code{-}\code{-prefix} argument to the
-\program{configure} script at build time. The value is available to
-Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
-also the next function.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
-Return the \emph{exec-prefix} for installed platform-\emph{de}pendent
-files. This is derived through a number of complicated rules from the
-program name set with \cfunction{Py_SetProgramName()} and some environment
-variables; for example, if the program name is
-\code{"/usr/local/bin/python"}, the exec-prefix is
-\code{"/usr/local"}. The returned string points into static storage;
-the caller should not modify its value. This corresponds to the
-\makevar{exec_prefix} variable in the top-level \file{Makefile} and the
-\code{-}\code{-exec_prefix} argument to the \program{configure} script
-at build time. The value is available to Python code as
-\code{sys.exec_prefix}. It is only useful on \UNIX{}.
-
-Background: The exec-prefix differs from the prefix when platform
-dependent files (such as executables and shared libraries) are
-installed in a different directory tree. In a typical installation,
-platform dependent files may be installed in the
-\code{"/usr/local/plat"} subtree while platform independent may be
-installed in \code{"/usr/local"}.
-
-Generally speaking, a platform is a combination of hardware and
-software families, e.g. Sparc machines running the Solaris 2.x
-operating system are considered the same platform, but Intel machines
-running Solaris 2.x are another platform, and Intel machines running
-Linux are yet another platform. Different major revisions of the same
-operating system generally also form different platforms. Non-\UNIX{}
-operating systems are a different story; the installation strategies
-on those systems are so different that the prefix and exec-prefix are
-meaningless, and set to the empty string. Note that compiled Python
-bytecode files are platform independent (but not independent from the
-Python version by which they were compiled!).
-
-System administrators will know how to configure the \program{mount} or
-\program{automount} programs to share \code{"/usr/local"} between platforms
-while having \code{"/usr/local/plat"} be a different filesystem for each
-platform.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
-Return the full program name of the Python executable; this is
-computed as a side-effect of deriving the default module search path
-from the program name (set by \cfunction{Py_SetProgramName()} above). The
-returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as
-\code{sys.executable}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{char*}{Py_GetPath}{}
-\indexiii{module}{search}{path}
-Return the default module search path; this is computed from the
-program name (set by \cfunction{Py_SetProgramName()} above) and some
-environment variables. The returned string consists of a series of
-directory names separated by a platform dependent delimiter character.
-The delimiter character is \character{:} on \UNIX{}, \character{;} on
-DOS/Windows, and \character{\\n} (the \ASCII{} newline character) on
-Macintosh. The returned string points into static storage; the caller
-should not modify its value. The value is available to Python code
-as the list \code{sys.path}, which may be modified to change the
-future search path for loaded modules.
-
-% XXX should give the exact rules
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetVersion}{}
-Return the version of this Python interpreter. This is a string that
-looks something like
-
-\begin{verbatim}
-"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
-\end{verbatim}
-
-The first word (up to the first space character) is the current Python
-version; the first three characters are the major and minor version
-separated by a period. The returned string points into static storage;
-the caller should not modify its value. The value is available to
-Python code as the list \code{sys.version}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
-Return the platform identifier for the current platform. On \UNIX{},
-this is formed from the ``official'' name of the operating system,
-converted to lower case, followed by the major revision number; e.g.,
-for Solaris 2.x, which is also known as SunOS 5.x, the value is
-\code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
-is \code{"win"}. The returned string points into static storage;
-the caller should not modify its value. The value is available to
-Python code as \code{sys.platform}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
-Return the official copyright string for the current Python version,
-for example
-
-\code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
-
-The returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as the list
-\code{sys.copyright}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
-Return an indication of the compiler used to build the current Python
-version, in square brackets, for example:
-
-\begin{verbatim}
-"[GCC 2.7.2.2]"
-\end{verbatim}
-
-The returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as part of
-the variable \code{sys.version}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
-Return information about the sequence number and build date and time
-of the current Python interpreter instance, for example
-
-\begin{verbatim}
-"#67, Aug 1 1997, 22:34:28"
-\end{verbatim}
-
-The returned string points into static storage; the caller should not
-modify its value. The value is available to Python code as part of
-the variable \code{sys.version}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
-% XXX
-\end{cfuncdesc}
-
-% XXX Other PySys thingies (doesn't really belong in this chapter)
-
-\section{Thread State and the Global Interpreter Lock}
-\label{threads}
-
-The Python interpreter is not fully thread safe. In order to support
-multi-threaded Python programs, there's a global lock that must be
-held by the current thread before it can safely access Python objects.
-Without the lock, even the simplest operations could cause problems in
-a multi-threaded program: for example, when two threads simultaneously
-increment the reference count of the same object, the reference count
-could end up being incremented only once instead of twice.
-
-Therefore, the rule exists that only the thread that has acquired the
-global interpreter lock may operate on Python objects or call Python/C
-API functions. In order to support multi-threaded Python programs,
-the interpreter regularly release and reacquires the lock --- by
-default, every ten bytecode instructions (this can be changed with
-\function{sys.setcheckinterval()}). The lock is also released and
-reacquired around potentially blocking I/O operations like reading or
-writing a file, so that other threads can run while the thread that
-requests the I/O is waiting for the I/O operation to complete.
-
-The Python interpreter needs to keep some bookkeeping information
-separate per thread --- for this it uses a data structure called
-\ctype{PyThreadState}. This is new in Python 1.5; in earlier versions,
-such state was stored in global variables, and switching threads could
-cause problems. In particular, exception handling is now thread safe,
-when the application uses \function{sys.exc_info()} to access the
-exception last raised in the current thread.
-
-There's one global variable left, however: the pointer to the current
-\ctype{PyThreadState} structure. While most thread packages have a way
-to store ``per-thread global data,'' Python's internal platform
-independent thread abstraction doesn't support this yet. Therefore,
-the current thread state must be manipulated explicitly.
-
-This is easy enough in most cases. Most code manipulating the global
-interpreter lock has the following simple structure:
-
-\begin{verbatim}
-Save the thread state in a local variable.
-Release the interpreter lock.
-...Do some blocking I/O operation...
-Reacquire the interpreter lock.
-Restore the thread state from the local variable.
-\end{verbatim}
-
-This is so common that a pair of macros exists to simplify it:
-
-\begin{verbatim}
-Py_BEGIN_ALLOW_THREADS
-...Do some blocking I/O operation...
-Py_END_ALLOW_THREADS
-\end{verbatim}
-
-The \code{Py_BEGIN_ALLOW_THREADS} macro opens a new block and declares
-a hidden local variable; the \code{Py_END_ALLOW_THREADS} macro closes
-the block. Another advantage of using these two macros is that when
-Python is compiled without thread support, they are defined empty,
-thus saving the thread state and lock manipulations.
-
-When thread support is enabled, the block above expands to the
-following code:
-
-\begin{verbatim}
-{
- PyThreadState *_save;
- _save = PyEval_SaveThread();
- ...Do some blocking I/O operation...
- PyEval_RestoreThread(_save);
-}
-\end{verbatim}
-
-Using even lower level primitives, we can get roughly the same effect
-as follows:
-
-\begin{verbatim}
-{
- PyThreadState *_save;
- _save = PyThreadState_Swap(NULL);
- PyEval_ReleaseLock();
- ...Do some blocking I/O operation...
- PyEval_AcquireLock();
- PyThreadState_Swap(_save);
-}
-\end{verbatim}
-
-There are some subtle differences; in particular,
-\cfunction{PyEval_RestoreThread()} saves and restores the value of the
-global variable \cdata{errno}, since the lock manipulation does not
-guarantee that \cdata{errno} is left alone. Also, when thread support
-is disabled, \cfunction{PyEval_SaveThread()} and
-\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
-case, \cfunction{PyEval_ReleaseLock()} and
-\cfunction{PyEval_AcquireLock()} are not available. This is done so
-that dynamically loaded extensions compiled with thread support
-enabled can be loaded by an interpreter that was compiled with
-disabled thread support.
-
-The global interpreter lock is used to protect the pointer to the
-current thread state. When releasing the lock and saving the thread
-state, the current thread state pointer must be retrieved before the
-lock is released (since another thread could immediately acquire the
-lock and store its own thread state in the global variable).
-Reversely, when acquiring the lock and restoring the thread state, the
-lock must be acquired before storing the thread state pointer.
-
-Why am I going on with so much detail about this? Because when
-threads are created from \C{}, they don't have the global interpreter
-lock, nor is there a thread state data structure for them. Such
-threads must bootstrap themselves into existence, by first creating a
-thread state data structure, then acquiring the lock, and finally
-storing their thread state pointer, before they can start using the
-Python/C API. When they are done, they should reset the thread state
-pointer, release the lock, and finally free their thread state data
-structure.
-
-When creating a thread data structure, you need to provide an
-interpreter state data structure. The interpreter state data
-structure hold global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}). Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \member{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
-
-XXX More?
-
-\begin{ctypedesc}{PyInterpreterState}
-This data structure represents the state shared by a number of
-cooperating threads. Threads belonging to the same interpreter
-share their module administration and a few other internal items.
-There are no public members in this structure.
-
-Threads belonging to different interpreters initially share nothing,
-except process state like available memory, open file descriptors and
-such. The global interpreter lock is also shared by all threads,
-regardless of to which interpreter they belong.
-\end{ctypedesc}
-
-\begin{ctypedesc}{PyThreadState}
-This data structure represents the state of a single thread. The only
-public data member is \ctype{PyInterpreterState *}\member{interp},
-which points to this thread's interpreter state.
-\end{ctypedesc}
-
-\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
-Initialize and acquire the global interpreter lock. It should be
-called in the main thread before creating a second thread or engaging
-in any other thread operations such as
-\cfunction{PyEval_ReleaseLock()} or
-\code{PyEval_ReleaseThread(\var{tstate})}. It is not needed before
-calling \cfunction{PyEval_SaveThread()} or
-\cfunction{PyEval_RestoreThread()}.
-
-This is a no-op when called for a second time. It is safe to call
-this function before calling \cfunction{Py_Initialize()}.
-
-When only the main thread exists, no lock operations are needed. This
-is a common situation (most Python programs do not use threads), and
-the lock operations slow the interpreter down a bit. Therefore, the
-lock is not created initially. This situation is equivalent to having
-acquired the lock: when there is only a single thread, all object
-accesses are safe. Therefore, when this function initializes the
-lock, it also acquires it. Before the Python
-\module{thread}\refbimodindex{thread} module creates a new thread,
-knowing that either it has the lock or the lock hasn't been created
-yet, it calls \cfunction{PyEval_InitThreads()}. When this call
-returns, it is guaranteed that the lock has been created and that it
-has acquired it.
-
-It is \strong{not} safe to call this function when it is unknown which
-thread (if any) currently has the global interpreter lock.
-
-This function is not available when thread support is disabled at
-compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
-Acquire the global interpreter lock. The lock must have been created
-earlier. If this thread already has the lock, a deadlock ensues.
-This function is not available when thread support is disabled at
-compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
-Release the global interpreter lock. The lock must have been created
-earlier. This function is not available when thread support is
-disabled at compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
-Acquire the global interpreter lock and then set the current thread
-state to \var{tstate}, which should not be \NULL{}. The lock must
-have been created earlier. If this thread already has the lock,
-deadlock ensues. This function is not available when thread support
-is disabled at compile time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
-Reset the current thread state to \NULL{} and release the global
-interpreter lock. The lock must have been created earlier and must be
-held by the current thread. The \var{tstate} argument, which must not
-be \NULL{}, is only used to check that it represents the current
-thread state --- if it isn't, a fatal error is reported. This
-function is not available when thread support is disabled at compile
-time.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
-Release the interpreter lock (if it has been created and thread
-support is enabled) and reset the thread state to \NULL{},
-returning the previous thread state (which is not \NULL{}). If
-the lock has been created, the current thread must have acquired it.
-(This function is available even when thread support is disabled at
-compile time.)
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
-Acquire the interpreter lock (if it has been created and thread
-support is enabled) and set the thread state to \var{tstate}, which
-must not be \NULL{}. If the lock has been created, the current
-thread must not have acquired it, otherwise deadlock ensues. (This
-function is available even when thread support is disabled at compile
-time.)
-\end{cfuncdesc}
-
-% XXX These aren't really C types, but the ctypedesc macro is the simplest!
-\begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
-This macro expands to
-\samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
-Note that it contains an opening brace; it must be matched with a
-following \code{Py_END_ALLOW_THREADS} macro. See above for further
-discussion of this macro. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
-
-\begin{ctypedesc}{Py_END_ALLOW_THREADS}
-This macro expands to
-\samp{PyEval_RestoreThread(_save); \}}.
-Note that it contains a closing brace; it must be matched with an
-earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
-discussion of this macro. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
-
-\begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
-This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
-is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
-brace. It is a no-op when thread support is disabled at compile
-time.
-\end{ctypedesc}
-
-\begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
-This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
-equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
-and variable declaration. It is a no-op when thread support is
-disabled at compile time.
-\end{ctypedesc}
-
-All of the following functions are only available when thread support
-is enabled at compile time, and must be called only when the
-interpreter lock has been created.
-
-\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
-Create a new interpreter state object. The interpreter lock must be
-held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
-Reset all information in an interpreter state object. The interpreter
-lock must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
-Destroy an interpreter state object. The interpreter lock need not be
-held. The interpreter state must have been reset with a previous
-call to \cfunction{PyInterpreterState_Clear()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp}
-Create a new thread state object belonging to the given interpreter
-object. The interpreter lock must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
-Reset all information in a thread state object. The interpreter lock
-must be held.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
-Destroy a thread state object. The interpreter lock need not be
-held. The thread state must have been reset with a previous
-call to \cfunction{PyThreadState_Clear()}.
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
-Return the current thread state. The interpreter lock must be held.
-When the current thread state is \NULL{}, this issues a fatal
-error (so that the caller needn't check for \NULL{}).
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate}
-Swap the current thread state with the thread state given by the
-argument \var{tstate}, which may be \NULL{}. The interpreter lock
-must be held.
-\end{cfuncdesc}
-
-
-\chapter{Defining New Object Types}
-\label{newTypes}
-
-\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{PyObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
-\end{cfuncdesc}
-
-\begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
-\end{cfuncdesc}
-
-Py_InitModule (!!!)
-
-PyArg_ParseTupleAndKeywords, PyArg_ParseTuple, PyArg_Parse
-
-Py_BuildValue
-
-PyObject, PyVarObject
-
-PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
-
-Typedefs:
-unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
-intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
-getreadbufferproc, getwritebufferproc, getsegcountproc,
-destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
-setattrofunc, cmpfunc, reprfunc, hashfunc
-
-PyNumberMethods
-
-PySequenceMethods
-
-PyMappingMethods
-
-PyBufferProcs
-
-PyTypeObject
-
-DL_IMPORT
-
-PyType_Type
-
-Py*_Check
-
-Py_None, _Py_NoneStruct
-
-
-\chapter{Debugging}
-\label{debugging}
-
-XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
-
-
-\input{api.ind} % Index -- must be last
-
-\end{document}