Commits

Anonymous committed 4b71f9a

This commit was manufactured by cvs2svn to create tag 'r222b1'.

  • Participants
  • Parent commits 37c0445
  • Branches 2.2
  • Tags v2.2.2b1

Comments (0)

Files changed (234)

Doc/ext/building.tex

-\chapter{Building C and \Cpp{} Extensions with distutils
-     \label{building}}
-
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-Starting in Python 1.4, Python provides, on \UNIX{}, a special make
-file for building make files for building dynamically-linked
-extensions and custom interpreters.  Starting with Python 2.0, this
-mechanism (known as related to Makefile.pre.in, and Setup files) is no
-longer supported. Building custom interpreters was rarely used, and
-extension modules can be built using distutils.
-
-Building an extension module using distutils requires that distutils
-is installed on the build machine, which is included in Python 2.x and
-available separately for Python 1.5. Since distutils also supports
-creation of binary packages, users don't necessarily need a compiler
-and distutils to install the extension.
-
-A distutils package contains a driver script, \file{setup.py}. This is
-a plain Python file, which, in the most simple case, could look like
-this:
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-
-module1 = Extension('demo',
-                    sources = ['demo.c'])
-
-setup (name = 'PackageName',
-       version = '1.0',
-       description = 'This is a demo package',
-       ext_modules = [module1])
-
-\end{verbatim}
-
-With this \file{setup.py}, and a file \file{demo.c}, running
-
-\begin{verbatim}
-python setup.py build 
-\end{verbatim}
-
-will compile \file{demo.c}, and produce an extension module named
-\samp{demo} in the \file{build} directory. Depending on the system,
-the module file will end up in a subdirectory \file{build/lib.system},
-and may have a name like \file{demo.so} or \file{demo.pyd}.
-
-In the \file{setup.py}, all execution is performed by calling the
-\samp{setup} function. This takes a variable number of keyword 
-arguments, of which the example above uses only a
-subset. Specifically, the example specifies meta-information to build
-packages, and it specifies the contents of the package.  Normally, a
-package will contain of addition modules, like Python source modules,
-documentation, subpackages, etc. Please refer to the distutils
-documentation in \citetitle[../dist/dist.html]{Distributing Python
-Modules} to learn more about the features of distutils; this section
-explains building extension modules only.
-
-It is common to pre-compute arguments to \function{setup}, to better
-structure the driver script. In the example above,
-the\samp{ext_modules} argument to \function{setup} is a list of
-extension modules, each of which is an instance of the
-\class{Extension}. In the example, the instance defines an extension
-named \samp{demo} which is build by compiling a single source file,
-\file{demo.c}.
-
-In many cases, building an extension is more complex, since additional
-preprocessor defines and libraries may be needed. This is demonstrated
-in the example below.
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-
-module1 = Extension('demo',
-                    define_macros = [('MAJOR_VERSION', '1'),
-                                     ('MINOR_VERSION', '0')],
-                    include_dirs = ['/usr/local/include'],
-                    libraries = ['tcl83'],
-                    library_dirs = ['/usr/local/lib'],
-                    sources = ['demo.c'])
-
-setup (name = 'PackageName',
-       version = '1.0',
-       description = 'This is a demo package',
-       author = 'Martin v. Loewis',
-       author_email = 'martin@v.loewis.de',
-       url = 'http://www.python.org/doc/current/ext/building.html',
-       long_description = '''
-This is really just a demo package.
-''',
-       ext_modules = [module1])
-
-\end{verbatim}
-
-In this example, \function{setup} is called with additional
-meta-information, which is recommended when distribution packages have
-to be built. For the extension itself, it specifies preprocessor
-defines, include directories, library directories, and libraries.
-Depending on the compiler, distutils passes this information in
-different ways to the compiler. For example, on \UNIX{}, this may
-result in the compilation commands
-
-\begin{verbatim}
-gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
-
-gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
-\end{verbatim}
-
-These lines are for demonstration purposes only; distutils users
-should trust that distutils gets the invocations right.
-
-\section{Distributing your extension modules
-     \label{distributing}}
-
-When an extension has been successfully build, there are three ways to
-use it.
-
-End-users will typically want to install the module, they do so by
-running
-
-\begin{verbatim}
-python setup.py install
-\end{verbatim}
-
-Module maintainers should produce source packages; to do so, they run
-
-\begin{verbatim}
-python setup.py sdist
-\end{verbatim}
-
-In some cases, additional files need to be included in a source
-distribution; this is done through a \file{MANIFEST.in} file; see the
-distutils documentation for details.
-
-If the source distribution has been build successfully, maintainers
-can also create binary distributions. Depending on the platform, one
-of the following commands can be used to do so.
-
-\begin{verbatim}
-python setup.py bdist_wininst
-python setup.py bdist_rpm
-python setup.py bdist_dumb
-\end{verbatim}
-

Doc/ext/embedding.tex

-\chapter{Embedding Python in Another Application
-     \label{embedding}}
-
-The previous chapters discussed how to extend Python, that is, how to
-extend the functionality of Python by attaching a library of C
-functions to it.  It is also possible to do it the other way around:
-enrich your C/\Cpp{} application by embedding Python in it.  Embedding
-provides your application with the ability to implement some of the
-functionality of your application in Python rather than C or \Cpp.
-This can be used for many purposes; one example would be to allow
-users to tailor the application to their needs by writing some scripts
-in Python.  You can also use it yourself if some of the functionality
-can be written in Python more easily.
-
-Embedding Python is similar to extending it, but not quite.  The
-difference is that when you extend Python, the main program of the
-application is still the Python interpreter, while if you embed
-Python, the main program may have nothing to do with Python ---
-instead, some parts of the application occasionally call the Python
-interpreter to run some Python code.
-
-So if you are embedding Python, you are providing your own main
-program.  One of the things this main program has to do is initialize
-the Python interpreter.  At the very least, you have to call the
-function \cfunction{Py_Initialize()} (on Mac OS, call
-\cfunction{PyMac_Initialize()} instead).  There are optional calls to
-pass command line arguments to Python.  Then later you can call the
-interpreter from any part of the application.
-
-There are several different ways to call the interpreter: you can pass
-a string containing Python statements to
-\cfunction{PyRun_SimpleString()}, or you can pass a stdio file pointer
-and a file name (for identification in error messages only) to
-\cfunction{PyRun_SimpleFile()}.  You can also call the lower-level
-operations described in the previous chapters to construct and use
-Python objects.
-
-A simple demo of embedding Python can be found in the directory
-\file{Demo/embed/} of the source distribution.
-
-
-\begin{seealso}
-  \seetitle[../api/api.html]{Python/C API Reference Manual}{The
-            details of Python's C interface are given in this manual.
-            A great deal of necessary information can be found here.}
-\end{seealso}
-
-
-\section{Very High Level Embedding
-         \label{high-level-embedding}}
-
-The simplest form of embedding Python is the use of the very
-high level interface. This interface is intended to execute a
-Python script without needing to interact with the application
-directly. This can for example be used to perform some operation
-on a file.
-
-\begin{verbatim}
-#include <Python.h>
-
-int
-main(int argc, char *argv[])
-{
-  Py_Initialize();
-  PyRun_SimpleString("from time import time,ctime\n"
-                     "print 'Today is',ctime(time())\n");
-  Py_Finalize();
-  return 0;
-}
-\end{verbatim}
-
-The above code first initializes the Python interpreter with
-\cfunction{Py_Initialize()}, followed by the execution of a hard-coded
-Python script that print the date and time.  Afterwards, the
-\cfunction{Py_Finalize()} call shuts the interpreter down, followed by
-the end of the program.  In a real program, you may want to get the
-Python script from another source, perhaps a text-editor routine, a
-file, or a database.  Getting the Python code from a file can better
-be done by using the \cfunction{PyRun_SimpleFile()} function, which
-saves you the trouble of allocating memory space and loading the file
-contents.
-
-
-\section{Beyond Very High Level Embedding: An overview
-         \label{lower-level-embedding}}
-
-The high level interface gives you the ability to execute
-arbitrary pieces of Python code from your application, but
-exchanging data values is quite cumbersome to say the least. If
-you want that, you should use lower level calls. At the cost of
-having to write more C code, you can achieve almost anything.
-
-It should be noted that extending Python and embedding Python
-is quite the same activity, despite the different intent. Most
-topics discussed in the previous chapters are still valid. To
-show this, consider what the extension code from Python to C
-really does:
-
-\begin{enumerate}
-    \item Convert data values from Python to C,
-    \item Perform a function call to a C routine using the
-        converted values, and
-    \item Convert the data values from the call from C to Python.
-\end{enumerate}
-
-When embedding Python, the interface code does:
-
-\begin{enumerate}
-    \item Convert data values from C to Python,
-    \item Perform a function call to a Python interface routine
-        using the converted values, and
-    \item Convert the data values from the call from Python to C.
-\end{enumerate}
-
-As you can see, the data conversion steps are simply swapped to
-accomodate the different direction of the cross-language transfer.
-The only difference is the routine that you call between both
-data conversions. When extending, you call a C routine, when
-embedding, you call a Python routine.
-
-This chapter will not discuss how to convert data from Python
-to C and vice versa.  Also, proper use of references and dealing
-with errors is assumed to be understood.  Since these aspects do not
-differ from extending the interpreter, you can refer to earlier
-chapters for the required information.
-
-
-\section{Pure Embedding
-         \label{pure-embedding}}
-
-The first program aims to execute a function in a Python
-script. Like in the section about the very high level interface,
-the Python interpreter does not directly interact with the
-application (but that will change in th next section).
-
-The code to run a function defined in a Python script is:
-
-\verbatiminput{run-func.c}
-
-This code loads a Python script using \code{argv[1]}, and calls the
-function named in \code{argv[2]}.  Its integer arguments are the other
-values of the \code{argv} array.  If you compile and link this
-program (let's call the finished executable \program{call}), and use
-it to execute a Python script, such as:
-
-\begin{verbatim}
-def multiply(a,b):
-    print "Thy shall add", a, "times", b
-    c = 0
-    for i in range(0, a):
-        c = c + b
-    return c
-\end{verbatim}
-
-then the result should be:
-
-\begin{verbatim}
-$ call multiply 3 2
-Thy shall add 3 times 2
-Result of call: 6
-\end{verbatim} % $
-
-Although the program is quite large for its functionality, most of the
-code is for data conversion between Python and C, and for error
-reporting.  The interesting part with respect to embedding Python
-starts with
-
-\begin{verbatim}
-    Py_Initialize();
-    pName = PyString_FromString(argv[1]);
-    /* Error checking of pName left out */
-    pModule = PyImport_Import(pName);
-\end{verbatim}
-
-After initializing the interpreter, the script is loaded using
-\cfunction{PyImport_Import()}.  This routine needs a Python string
-as its argument, which is constructed using the
-\cfunction{PyString_FromString()} data conversion routine.
-
-\begin{verbatim}
-    pDict = PyModule_GetDict(pModule);
-    /* pDict is a borrowed reference */
-
-    pFunc = PyDict_GetItemString(pDict, argv[2]);
-    /* pFun is a borrowed reference */
-
-    if (pFunc && PyCallable_Check(pFunc)) {
-        ...
-    }
-\end{verbatim}
-
-Once the script is loaded, its dictionary is retrieved with
-\cfunction{PyModule_GetDict()}.  The dictionary is then searched using
-the normal dictionary access routines for the function name.  If the
-name exists, and the object returned is callable, you can safely
-assume that it is a function.  The program then proceeds by
-constructing a tuple of arguments as normal.  The call to the python
-function is then made with:
-
-\begin{verbatim}
-    pValue = PyObject_CallObject(pFunc, pArgs);
-\end{verbatim}
-
-Upon return of the function, \code{pValue} is either \NULL{} or it
-contains a reference to the return value of the function.  Be sure to
-release the reference after examining the value.
-
-
-\section{Extending Embedded Python
-         \label{extending-with-embedding}}
-
-Until now, the embedded Python interpreter had no access to
-functionality from the application itself.  The Python API allows this
-by extending the embedded interpreter.  That is, the embedded
-interpreter gets extended with routines provided by the application.
-While it sounds complex, it is not so bad.  Simply forget for a while
-that the application starts the Python interpreter.  Instead, consider
-the application to be a set of subroutines, and write some glue code
-that gives Python access to those routines, just like you would write
-a normal Python extension.  For example:
-
-\begin{verbatim}
-static int numargs=0;
-
-/* Return the number of arguments of the application command line */
-static PyObject*
-emb_numargs(PyObject *self, PyObject *args)
-{
-    if(!PyArg_ParseTuple(args, ":numargs"))
-        return NULL;
-    return Py_BuildValue("i", numargs);
-}
-
-static PyMethodDef EmbMethods[] = {
-    {"numargs", emb_numargs, METH_VARARGS,
-     "Return the number of arguments received by the process."},
-    {NULL, NULL, 0, NULL}
-};
-\end{verbatim}
-
-Insert the above code just above the \cfunction{main()} function.
-Also, insert the following two statements directly after
-\cfunction{Py_Initialize()}:
-
-\begin{verbatim}
-    numargs = argc;
-    Py_InitModule("emb", EmbMethods);
-\end{verbatim}
-
-These two lines initialize the \code{numargs} variable, and make the
-\function{emb.numargs()} function accessible to the embedded Python
-interpreter.  With these extensions, the Python script can do things
-like
-
-\begin{verbatim}
-import emb
-print "Number of arguments", emb.numargs()
-\end{verbatim}
-
-In a real application, the methods will expose an API of the
-application to Python.
-
-
-%\section{For the future}
-%
-%You don't happen to have a nice library to get textual
-%equivalents of numeric values do you :-) ?
-%Callbacks here ? (I may be using information from that section
-%?!)
-%threads
-%code examples do not really behave well if errors happen
-% (what to watch out for)
-
-
-\section{Embedding Python in \Cpp
-     \label{embeddingInCplusplus}}
-
-It is also possible to embed Python in a \Cpp{} program; precisely how this
-is done will depend on the details of the \Cpp{} system used; in general you
-will need to write the main program in \Cpp, and use the \Cpp{} compiler
-to compile and link your program.  There is no need to recompile Python
-itself using \Cpp.
-
-
-\section{Linking Requirements
-         \label{link-reqs}}
-
-While the \program{configure} script shipped with the Python sources
-will correctly build Python to export the symbols needed by
-dynamically linked extensions, this is not automatically inherited by
-applications which embed the Python library statically, at least on
-\UNIX.  This is an issue when the application is linked to the static
-runtime library (\file{libpython.a}) and needs to load dynamic
-extensions (implemented as \file{.so} files).
-
-The problem is that some entry points are defined by the Python
-runtime solely for extension modules to use.  If the embedding
-application does not use any of these entry points, some linkers will
-not include those entries in the symbol table of the finished
-executable.  Some additional options are needed to inform the linker
-not to remove these symbols.
-
-Determining the right options to use for any given platform can be
-quite difficult, but fortunately the Python configuration already has
-those values.  To retrieve them from an installed Python interpreter,
-start an interactive interpreter and have a short session like this:
-
-\begin{verbatim}
->>> import distutils.sysconfig
->>> distutils.sysconfig.get_config_var('LINKFORSHARED')
-'-Xlinker -export-dynamic'
-\end{verbatim}
-\refstmodindex{distutils.sysconfig}
-
-The contents of the string presented will be the options that should
-be used.  If the string is empty, there's no need to add any
-additional options.  The \constant{LINKFORSHARED} definition
-corresponds to the variable of the same name in Python's top-level
-\file{Makefile}.

Doc/ext/ext.tex

-\documentclass{manual}
-
-% XXX PM explain how to add new types to Python
-
-\title{Extending and Embedding the Python Interpreter}
-
-\input{boilerplate}
-
-% Tell \index to actually write the .idx file
-\makeindex
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-
-\begin{abstract}
-
-\noindent
-Python is an interpreted, object-oriented programming language.  This
-document describes how to write modules in C or \Cpp{} to extend the
-Python interpreter with new modules.  Those modules can define new
-functions but also new object types and their methods.  The document
-also describes how to embed the Python interpreter in another
-application, for use as an extension language.  Finally, it shows how
-to compile and link extension modules so that they can be loaded
-dynamically (at run time) into the interpreter, if the underlying
-operating system supports this feature.
-
-This document assumes basic knowledge about Python.  For an informal
-introduction to the language, see the
-\citetitle[../tut/tut.html]{Python Tutorial}.  The
-\citetitle[../ref/ref.html]{Python Reference Manual} gives a more
-formal definition of the language.  The
-\citetitle[../lib/lib.html]{Python Library Reference} documents the
-existing object types, functions and modules (both built-in and
-written in Python) that give the language its wide application range.
-
-For a detailed description of the whole Python/C API, see the separate
-\citetitle[../api/api.html]{Python/C API Reference Manual}.
-
-\end{abstract}
-
-\tableofcontents
-
-
-\input{extending}
-\input{newtypes}
-\input{building}
-\input{windows}
-\input{embedding}
-
-
-\appendix
-\chapter{Reporting Bugs}
-\input{reportingbugs}
-
-\chapter{History and License}
-\input{license}
-
-\end{document}

Doc/ext/extending.tex

-\chapter{Extending Python with C or \Cpp \label{intro}}
-
-
-It is quite easy to add new built-in modules to Python, if you know
-how to program in C.  Such \dfn{extension modules} can do two things
-that can't be done directly in Python: they can implement new built-in
-object types, and they can call C library functions and system calls.
-
-To support extensions, the Python API (Application Programmers
-Interface) defines a set of functions, macros and variables that
-provide access to most aspects of the Python run-time system.  The
-Python API is incorporated in a C source file by including the header
-\code{"Python.h"}.
-
-The compilation of an extension module depends on its intended use as
-well as on your system setup; details are given in later chapters.
-
-
-\section{A Simple Example
-         \label{simpleExample}}
-
-Let's create an extension module called \samp{spam} (the favorite food
-of Monty Python fans...) and let's say we want to create a Python
-interface to the C library function \cfunction{system()}.\footnote{An
-interface for this function already exists in the standard module
-\module{os} --- it was chosen as a simple and straightfoward example.}
-This function takes a null-terminated character string as argument and
-returns an integer.  We want this function to be callable from Python
-as follows:
-
-\begin{verbatim}
->>> import spam
->>> status = spam.system("ls -l")
-\end{verbatim}
-
-Begin by creating a file \file{spammodule.c}.  (Historically, if a
-module is called \samp{spam}, the C file containing its implementation
-is called \file{spammodule.c}; if the module name is very long, like
-\samp{spammify}, the module name can be just \file{spammify.c}.)
-
-The first line of our file can be:
-
-\begin{verbatim}
-#include <Python.h>
-\end{verbatim}
-
-which pulls in the Python API (you can add a comment describing the
-purpose of the module and a copyright notice if you like).
-Since Python may define some pre-processor definitions which affect
-the standard headers on some systems, you must include \file{Python.h}
-before any standard headers are included.
-
-All user-visible symbols defined by \file{Python.h} have a prefix of
-\samp{Py} or \samp{PY}, except those defined in standard header files.
-For convenience, and since they are used extensively by the Python
-interpreter, \code{"Python.h"} includes a few standard header files:
-\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
-\code{<stdlib.h>}.  If the latter header file does not exist on your
-system, it declares the functions \cfunction{malloc()},
-\cfunction{free()} and \cfunction{realloc()} directly.
-
-The next thing we add to our module file is the C function that will
-be called when the Python expression \samp{spam.system(\var{string})}
-is evaluated (we'll see shortly how it ends up being called):
-
-\begin{verbatim}
-static PyObject *
-spam_system(self, args)
-    PyObject *self;
-    PyObject *args;
-{
-    char *command;
-    int sts;
-
-    if (!PyArg_ParseTuple(args, "s", &command))
-        return NULL;
-    sts = system(command);
-    return Py_BuildValue("i", sts);
-}
-\end{verbatim}
-
-There is a straightforward translation from the argument list in
-Python (for example, the single expression \code{"ls -l"}) to the
-arguments passed to the C function.  The C function always has two
-arguments, conventionally named \var{self} and \var{args}.
-
-The \var{self} argument is only used when the C function implements a
-built-in method, not a function. In the example, \var{self} will
-always be a \NULL{} pointer, since we are defining a function, not a
-method.  (This is done so that the interpreter doesn't have to
-understand two different types of C functions.)
-
-The \var{args} argument will be a pointer to a Python tuple object
-containing the arguments.  Each item of the tuple corresponds to an
-argument in the call's argument list.  The arguments are Python
-objects --- in order to do anything with them in our C function we have
-to convert them to C values.  The function \cfunction{PyArg_ParseTuple()}
-in the Python API checks the argument types and converts them to C
-values.  It uses a template string to determine the required types of
-the arguments as well as the types of the C variables into which to
-store the converted values.  More about this later.
-
-\cfunction{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
-the right type and its components have been stored in the variables
-whose addresses are passed.  It returns false (zero) if an invalid
-argument list was passed.  In the latter case it also raises an
-appropriate exception so the calling function can return
-\NULL{} immediately (as we saw in the example).
-
-
-\section{Intermezzo: Errors and Exceptions
-         \label{errors}}
-
-An important convention throughout the Python interpreter is the
-following: when a function fails, it should set an exception condition
-and return an error value (usually a \NULL{} pointer).  Exceptions
-are stored in a static global variable inside the interpreter; if this
-variable is \NULL{} no exception has occurred.  A second global
-variable stores the ``associated value'' of the exception (the second
-argument to \keyword{raise}).  A third variable contains the stack
-traceback in case the error originated in Python code.  These three
-variables are the C equivalents of the Python variables
-\code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback} (see
-the section on module \module{sys} in the
-\citetitle[../lib/lib.html]{Python Library Reference}).  It is
-important to know about them to understand how errors are passed
-around.
-
-The Python API defines a number of functions to set various types of
-exceptions.
-
-The most common one is \cfunction{PyErr_SetString()}.  Its arguments
-are an exception object and a C string.  The exception object is
-usually a predefined object like \cdata{PyExc_ZeroDivisionError}.  The
-C string indicates the cause of the error and is converted to a
-Python string object and stored as the ``associated value'' of the
-exception.
-
-Another useful function is \cfunction{PyErr_SetFromErrno()}, which only
-takes an exception argument and constructs the associated value by
-inspection of the global variable \cdata{errno}.  The most
-general function is \cfunction{PyErr_SetObject()}, which takes two object
-arguments, the exception and its associated value.  You don't need to
-\cfunction{Py_INCREF()} the objects passed to any of these functions.
-
-You can test non-destructively whether an exception has been set with
-\cfunction{PyErr_Occurred()}.  This returns the current exception object,
-or \NULL{} if no exception has occurred.  You normally don't need
-to call \cfunction{PyErr_Occurred()} to see whether an error occurred in a
-function call, since you should be able to tell from the return value.
-
-When a function \var{f} that calls another function \var{g} detects
-that the latter fails, \var{f} should itself return an error value
-(usually \NULL{} or \code{-1}).  It should \emph{not} call one of the
-\cfunction{PyErr_*()} functions --- one has already been called by \var{g}.
-\var{f}'s caller is then supposed to also return an error indication
-to \emph{its} caller, again \emph{without} calling \cfunction{PyErr_*()},
-and so on --- the most detailed cause of the error was already
-reported by the function that first detected it.  Once the error
-reaches the Python interpreter's main loop, this aborts the currently
-executing Python code and tries to find an exception handler specified
-by the Python programmer.
-
-(There are situations where a module can actually give a more detailed
-error message by calling another \cfunction{PyErr_*()} function, and in
-such cases it is fine to do so.  As a general rule, however, this is
-not necessary, and can cause information about the cause of the error
-to be lost: most operations can fail for a variety of reasons.)
-
-To ignore an exception set by a function call that failed, the exception
-condition must be cleared explicitly by calling \cfunction{PyErr_Clear()}. 
-The only time C code should call \cfunction{PyErr_Clear()} is if it doesn't
-want to pass the error on to the interpreter but wants to handle it
-completely by itself (possibly by trying something else, or pretending
-nothing went wrong).
-
-Every failing \cfunction{malloc()} call must be turned into an
-exception --- the direct caller of \cfunction{malloc()} (or
-\cfunction{realloc()}) must call \cfunction{PyErr_NoMemory()} and
-return a failure indicator itself.  All the object-creating functions
-(for example, \cfunction{PyInt_FromLong()}) already do this, so this
-note is only relevant to those who call \cfunction{malloc()} directly.
-
-Also note that, with the important exception of
-\cfunction{PyArg_ParseTuple()} and friends, functions that return an
-integer status usually return a positive value or zero for success and
-\code{-1} for failure, like \UNIX{} system calls.
-
-Finally, be careful to clean up garbage (by making
-\cfunction{Py_XDECREF()} or \cfunction{Py_DECREF()} calls for objects
-you have already created) when you return an error indicator!
-
-The choice of which exception to raise is entirely yours.  There are
-predeclared C objects corresponding to all built-in Python exceptions,
-such as \cdata{PyExc_ZeroDivisionError}, which you can use directly.
-Of course, you should choose exceptions wisely --- don't use
-\cdata{PyExc_TypeError} to mean that a file couldn't be opened (that
-should probably be \cdata{PyExc_IOError}).  If something's wrong with
-the argument list, the \cfunction{PyArg_ParseTuple()} function usually
-raises \cdata{PyExc_TypeError}.  If you have an argument whose value
-must be in a particular range or must satisfy other conditions,
-\cdata{PyExc_ValueError} is appropriate.
-
-You can also define a new exception that is unique to your module.
-For this, you usually declare a static object variable at the
-beginning of your file:
-
-\begin{verbatim}
-static PyObject *SpamError;
-\end{verbatim}
-
-and initialize it in your module's initialization function
-(\cfunction{initspam()}) with an exception object (leaving out
-the error checking for now):
-
-\begin{verbatim}
-void
-initspam(void)
-{
-    PyObject *m, *d;
-
-    m = Py_InitModule("spam", SpamMethods);
-    d = PyModule_GetDict(m);
-    SpamError = PyErr_NewException("spam.error", NULL, NULL);
-    PyDict_SetItemString(d, "error", SpamError);
-}
-\end{verbatim}
-
-Note that the Python name for the exception object is
-\exception{spam.error}.  The \cfunction{PyErr_NewException()} function
-may create a class with the base class being \exception{Exception}
-(unless another class is passed in instead of \NULL), described in the
-\citetitle[../lib/lib.html]{Python Library Reference} under ``Built-in
-Exceptions.''
-
-Note also that the \cdata{SpamError} variable retains a reference to
-the newly created exception class; this is intentional!  Since the
-exception could be removed from the module by external code, an owned
-reference to the class is needed to ensure that it will not be
-discarded, causing \cdata{SpamError} to become a dangling pointer.
-Should it become a dangling pointer, C code which raises the exception
-could cause a core dump or other unintended side effects.
-
-
-\section{Back to the Example
-         \label{backToExample}}
-
-Going back to our example function, you should now be able to
-understand this statement:
-
-\begin{verbatim}
-    if (!PyArg_ParseTuple(args, "s", &command))
-        return NULL;
-\end{verbatim}
-
-It returns \NULL{} (the error indicator for functions returning
-object pointers) if an error is detected in the argument list, relying
-on the exception set by \cfunction{PyArg_ParseTuple()}.  Otherwise the
-string value of the argument has been copied to the local variable
-\cdata{command}.  This is a pointer assignment and you are not supposed
-to modify the string to which it points (so in Standard C, the variable
-\cdata{command} should properly be declared as \samp{const char
-*command}).
-
-The next statement is a call to the \UNIX{} function
-\cfunction{system()}, passing it the string we just got from
-\cfunction{PyArg_ParseTuple()}:
-
-\begin{verbatim}
-    sts = system(command);
-\end{verbatim}
-
-Our \function{spam.system()} function must return the value of
-\cdata{sts} as a Python object.  This is done using the function
-\cfunction{Py_BuildValue()}, which is something like the inverse of
-\cfunction{PyArg_ParseTuple()}: it takes a format string and an
-arbitrary number of C values, and returns a new Python object.
-More info on \cfunction{Py_BuildValue()} is given later.
-
-\begin{verbatim}
-    return Py_BuildValue("i", sts);
-\end{verbatim}
-
-In this case, it will return an integer object.  (Yes, even integers
-are objects on the heap in Python!)
-
-If you have a C function that returns no useful argument (a function
-returning \ctype{void}), the corresponding Python function must return
-\code{None}.   You need this idiom to do so:
-
-\begin{verbatim}
-    Py_INCREF(Py_None);
-    return Py_None;
-\end{verbatim}
-
-\cdata{Py_None} is the C name for the special Python object
-\code{None}.  It is a genuine Python object rather than a \NULL{}
-pointer, which means ``error'' in most contexts, as we have seen.
-
-
-\section{The Module's Method Table and Initialization Function
-         \label{methodTable}}
-
-I promised to show how \cfunction{spam_system()} is called from Python
-programs.  First, we need to list its name and address in a ``method
-table'':
-
-\begin{verbatim}
-static PyMethodDef SpamMethods[] = {
-    ...
-    {"system",  spam_system, METH_VARARGS,
-     "Execute a shell command."},
-    ...
-    {NULL, NULL, 0, NULL}        /* Sentinel */
-};
-\end{verbatim}
-
-Note the third entry (\samp{METH_VARARGS}).  This is a flag telling
-the interpreter the calling convention to be used for the C
-function.  It should normally always be \samp{METH_VARARGS} or
-\samp{METH_VARARGS | METH_KEYWORDS}; a value of \code{0} means that an
-obsolete variant of \cfunction{PyArg_ParseTuple()} is used.
-
-When using only \samp{METH_VARARGS}, the function should expect
-the Python-level parameters to be passed in as a tuple acceptable for
-parsing via \cfunction{PyArg_ParseTuple()}; more information on this
-function is provided below.
-
-The \constant{METH_KEYWORDS} bit may be set in the third field if
-keyword arguments should be passed to the function.  In this case, the
-C function should accept a third \samp{PyObject *} parameter which
-will be a dictionary of keywords.  Use
-\cfunction{PyArg_ParseTupleAndKeywords()} to parse the arguments to
-such a function.
-
-The method table must be passed to the interpreter in the module's
-initialization function.  The initialization function must be named
-\cfunction{init\var{name}()}, where \var{name} is the name of the
-module, and should be the only non-\keyword{static} item defined in
-the module file:
-
-\begin{verbatim}
-void
-initspam(void)
-{
-    (void) Py_InitModule("spam", SpamMethods);
-}
-\end{verbatim}
-
-Note that for \Cpp, this method must be declared \code{extern "C"}.
-
-When the Python program imports module \module{spam} for the first
-time, \cfunction{initspam()} is called. (See below for comments about
-embedding Python.)  It calls
-\cfunction{Py_InitModule()}, which creates a ``module object'' (which
-is inserted in the dictionary \code{sys.modules} under the key
-\code{"spam"}), and inserts built-in function objects into the newly
-created module based upon the table (an array of \ctype{PyMethodDef}
-structures) that was passed as its second argument.
-\cfunction{Py_InitModule()} returns a pointer to the module object
-that it creates (which is unused here).  It aborts with a fatal error
-if the module could not be initialized satisfactorily, so the caller
-doesn't need to check for errors.
-
-When embedding Python, the \cfunction{initspam()} function is not
-called automatically unless there's an entry in the
-\cdata{_PyImport_Inittab} table.  The easiest way to handle this is to 
-statically initialize your statically-linked modules by directly
-calling \cfunction{initspam()} after the call to
-\cfunction{Py_Initialize()} or \cfunction{PyMac_Initialize()}:
-
-\begin{verbatim}
-int main(int argc, char **argv)
-{
-    /* Pass argv[0] to the Python interpreter */
-    Py_SetProgramName(argv[0]);
-
-    /* Initialize the Python interpreter.  Required. */
-    Py_Initialize();
-
-    /* Add a static module */
-    initspam();
-\end{verbatim}
-
-An example may be found in the file \file{Demo/embed/demo.c} in the
-Python source distribution.
-
-\note{Removing entries from \code{sys.modules} or importing
-compiled modules into multiple interpreters within a process (or
-following a \cfunction{fork()} without an intervening
-\cfunction{exec()}) can create problems for some extension modules.
-Extension module authors should exercise caution when initializing
-internal data structures.
-Note also that the \function{reload()} function can be used with
-extension modules, and will call the module initialization function
-(\cfunction{initspam()} in the example), but will not load the module
-again if it was loaded from a dynamically loadable object file
-(\file{.so} on \UNIX, \file{.dll} on Windows).}
-
-A more substantial example module is included in the Python source
-distribution as \file{Modules/xxmodule.c}.  This file may be used as a 
-template or simply read as an example.  The \program{modulator.py}
-script included in the source distribution or Windows install provides 
-a simple graphical user interface for declaring the functions and
-objects which a module should implement, and can generate a template
-which can be filled in.  The script lives in the
-\file{Tools/modulator/} directory; see the \file{README} file there
-for more information.
-
-
-\section{Compilation and Linkage
-         \label{compilation}}
-
-There are two more things to do before you can use your new extension:
-compiling and linking it with the Python system.  If you use dynamic
-loading, the details may depend on the style of dynamic loading your
-system uses; see the chapters about building extension modules
-(chapter \ref{building}) and additional information that pertains only
-to building on Windows (chapter \ref{building-on-windows}) for more
-information about this.
-% XXX Add information about Mac OS
-
-If you can't use dynamic loading, or if you want to make your module a
-permanent part of the Python interpreter, you will have to change the
-configuration setup and rebuild the interpreter.  Luckily, this is
-very simple on \UNIX: just place your file (\file{spammodule.c} for
-example) in the \file{Modules/} directory of an unpacked source
-distribution, add a line to the file \file{Modules/Setup.local}
-describing your file:
-
-\begin{verbatim}
-spam spammodule.o
-\end{verbatim}
-
-and rebuild the interpreter by running \program{make} in the toplevel
-directory.  You can also run \program{make} in the \file{Modules/}
-subdirectory, but then you must first rebuild \file{Makefile}
-there by running `\program{make} Makefile'.  (This is necessary each
-time you change the \file{Setup} file.)
-
-If your module requires additional libraries to link with, these can
-be listed on the line in the configuration file as well, for instance:
-
-\begin{verbatim}
-spam spammodule.o -lX11
-\end{verbatim}
-
-\section{Calling Python Functions from C
-         \label{callingPython}}
-
-So far we have concentrated on making C functions callable from
-Python.  The reverse is also useful: calling Python functions from C.
-This is especially the case for libraries that support so-called
-``callback'' functions.  If a C interface makes use of callbacks, the
-equivalent Python often needs to provide a callback mechanism to the
-Python programmer; the implementation will require calling the Python
-callback functions from a C callback.  Other uses are also imaginable.
-
-Fortunately, the Python interpreter is easily called recursively, and
-there is a standard interface to call a Python function.  (I won't
-dwell on how to call the Python parser with a particular string as
-input --- if you're interested, have a look at the implementation of
-the \programopt{-c} command line option in \file{Python/pythonmain.c}
-from the Python source code.)
-
-Calling a Python function is easy.  First, the Python program must
-somehow pass you the Python function object.  You should provide a
-function (or some other interface) to do this.  When this function is
-called, save a pointer to the Python function object (be careful to
-\cfunction{Py_INCREF()} it!) in a global variable --- or wherever you
-see fit. For example, the following function might be part of a module
-definition:
-
-\begin{verbatim}
-static PyObject *my_callback = NULL;
-
-static PyObject *
-my_set_callback(dummy, args)
-    PyObject *dummy, *args;
-{
-    PyObject *result = NULL;
-    PyObject *temp;
-
-    if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
-        if (!PyCallable_Check(temp)) {
-            PyErr_SetString(PyExc_TypeError, "parameter must be callable");
-            return NULL;
-        }
-        Py_XINCREF(temp);         /* Add a reference to new callback */
-        Py_XDECREF(my_callback);  /* Dispose of previous callback */
-        my_callback = temp;       /* Remember new callback */
-        /* Boilerplate to return "None" */
-        Py_INCREF(Py_None);
-        result = Py_None;
-    }
-    return result;
-}
-\end{verbatim}
-
-This function must be registered with the interpreter using the
-\constant{METH_VARARGS} flag; this is described in section
-\ref{methodTable}, ``The Module's Method Table and Initialization
-Function.''  The \cfunction{PyArg_ParseTuple()} function and its
-arguments are documented in section~\ref{parseTuple}, ``Extracting
-Parameters in Extension Functions.''
-
-The macros \cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()}
-increment/decrement the reference count of an object and are safe in
-the presence of \NULL{} pointers (but note that \var{temp} will not be 
-\NULL{} in this context).  More info on them in
-section~\ref{refcounts}, ``Reference Counts.''
-
-Later, when it is time to call the function, you call the C function
-\cfunction{PyEval_CallObject()}.\ttindex{PyEval_CallObject()}  This
-function has two arguments, both pointers to arbitrary Python objects:
-the Python function, and the argument list.  The argument list must
-always be a tuple object, whose length is the number of arguments.  To
-call the Python function with no arguments, pass an empty tuple; to
-call it with one argument, pass a singleton tuple.
-\cfunction{Py_BuildValue()} returns a tuple when its format string
-consists of zero or more format codes between parentheses.  For
-example:
-
-\begin{verbatim}
-    int arg;
-    PyObject *arglist;
-    PyObject *result;
-    ...
-    arg = 123;
-    ...
-    /* Time to call the callback */
-    arglist = Py_BuildValue("(i)", arg);
-    result = PyEval_CallObject(my_callback, arglist);
-    Py_DECREF(arglist);
-\end{verbatim}
-
-\cfunction{PyEval_CallObject()} returns a Python object pointer: this is
-the return value of the Python function.  \cfunction{PyEval_CallObject()} is
-``reference-count-neutral'' with respect to its arguments.  In the
-example a new tuple was created to serve as the argument list, which
-is \cfunction{Py_DECREF()}-ed immediately after the call.
-
-The return value of \cfunction{PyEval_CallObject()} is ``new'': either it
-is a brand new object, or it is an existing object whose reference
-count has been incremented.  So, unless you want to save it in a
-global variable, you should somehow \cfunction{Py_DECREF()} the result,
-even (especially!) if you are not interested in its value.
-
-Before you do this, however, it is important to check that the return
-value isn't \NULL.  If it is, the Python function terminated by
-raising an exception.  If the C code that called
-\cfunction{PyEval_CallObject()} is called from Python, it should now
-return an error indication to its Python caller, so the interpreter
-can print a stack trace, or the calling Python code can handle the
-exception.  If this is not possible or desirable, the exception should
-be cleared by calling \cfunction{PyErr_Clear()}.  For example:
-
-\begin{verbatim}
-    if (result == NULL)
-        return NULL; /* Pass error back */
-    ...use result...
-    Py_DECREF(result); 
-\end{verbatim}
-
-Depending on the desired interface to the Python callback function,
-you may also have to provide an argument list to
-\cfunction{PyEval_CallObject()}.  In some cases the argument list is
-also provided by the Python program, through the same interface that
-specified the callback function.  It can then be saved and used in the
-same manner as the function object.  In other cases, you may have to
-construct a new tuple to pass as the argument list.  The simplest way
-to do this is to call \cfunction{Py_BuildValue()}.  For example, if
-you want to pass an integral event code, you might use the following
-code:
-
-\begin{verbatim}
-    PyObject *arglist;
-    ...
-    arglist = Py_BuildValue("(l)", eventcode);
-    result = PyEval_CallObject(my_callback, arglist);
-    Py_DECREF(arglist);
-    if (result == NULL)
-        return NULL; /* Pass error back */
-    /* Here maybe use the result */
-    Py_DECREF(result);
-\end{verbatim}
-
-Note the placement of \samp{Py_DECREF(arglist)} immediately after the
-call, before the error check!  Also note that strictly spoken this
-code is not complete: \cfunction{Py_BuildValue()} may run out of
-memory, and this should be checked.
-
-
-\section{Extracting Parameters in Extension Functions
-         \label{parseTuple}}
-
-The \cfunction{PyArg_ParseTuple()} function is declared as follows:
-
-\begin{verbatim}
-int PyArg_ParseTuple(PyObject *arg, char *format, ...);
-\end{verbatim}
-
-The \var{arg} argument must be a tuple object containing an argument
-list passed from Python to a C function.  The \var{format} argument
-must be a format string, whose syntax is explained below.  The
-remaining arguments must be addresses of variables whose type is
-determined by the format string.  For the conversion to succeed, the
-\var{arg} object must match the format and the format must be
-exhausted.  On success, \cfunction{PyArg_ParseTuple()} returns true,
-otherwise it returns false and raises an appropriate exception.
-
-Note that while \cfunction{PyArg_ParseTuple()} checks that the Python
-arguments have the required types, it cannot check the validity of the
-addresses of C variables passed to the call: if you make mistakes
-there, your code will probably crash or at least overwrite random bits
-in memory.  So be careful!
-
-A format string consists of zero or more ``format units''.  A format
-unit describes one Python object; it is usually a single character or
-a parenthesized sequence of format units.  With a few exceptions, a
-format unit that is not a parenthesized sequence normally corresponds
-to a single address argument to \cfunction{PyArg_ParseTuple()}.  In the
-following description, the quoted form is the format unit; the entry
-in (round) parentheses is the Python object type that matches the
-format unit; and the entry in [square] brackets is the type of the C
-variable(s) whose address should be passed.  (Use the \samp{\&}
-operator to pass a variable's address.)
-
-Note that any Python object references which are provided to the
-caller are \emph{borrowed} references; do not decrement their
-reference count!
-
-\begin{description}
-
-\item[\samp{s} (string or Unicode object) {[char *]}]
-Convert a Python string or Unicode object to a C pointer to a
-character string.  You must not provide storage for the string
-itself; a pointer to an existing string is stored into the character
-pointer variable whose address you pass.  The C string is
-null-terminated.  The Python string must not contain embedded null
-bytes; if it does, a \exception{TypeError} exception is raised.
-Unicode objects are converted to C strings using the default
-encoding. If this conversion fails, an \exception{UnicodeError} is
-raised.
-
-\item[\samp{s\#} (string, Unicode or any read buffer compatible object) 
-{[char *, int]}]
-This variant on \samp{s} stores into two C variables, the first one a
-pointer to a character string, the second one its length.  In this
-case the Python string may contain embedded null bytes.  Unicode
-objects pass back a pointer to the default encoded string version of the
-object if such a conversion is possible. All other read buffer
-compatible objects pass back a reference to the raw internal data
-representation.
-
-\item[\samp{z} (string or \code{None}) {[char *]}]
-Like \samp{s}, but the Python object may also be \code{None}, in which
-case the C pointer is set to \NULL.
-
-\item[\samp{z\#} (string or \code{None} or any read buffer compatible object) 
-{[char *, int]}]
-This is to \samp{s\#} as \samp{z} is to \samp{s}.
-
-\item[\samp{u} (Unicode object) {[Py_UNICODE *]}]
-Convert a Python Unicode object to a C pointer to a null-terminated
-buffer of 16-bit Unicode (UTF-16) data.  As with \samp{s}, there is no need
-to provide storage for the Unicode data buffer; a pointer to the
-existing Unicode data is stored into the Py_UNICODE pointer variable whose
-address you pass.  
-
-\item[\samp{u\#} (Unicode object) {[Py_UNICODE *, int]}]
-This variant on \samp{u} stores into two C variables, the first one
-a pointer to a Unicode data buffer, the second one its length.
-
-\item[\samp{es} (string, Unicode object or character buffer compatible
-object) {[const char *encoding, char **buffer]}]
-This variant on \samp{s} is used for encoding Unicode and objects
-convertible to Unicode into a character buffer. It only works for
-encoded data without embedded \NULL{} bytes.
-
-The variant reads one C variable and stores into two C variables, the
-first one a pointer to an encoding name string (\var{encoding}), and the
-second a pointer to a pointer to a character buffer (\var{**buffer},
-the buffer used for storing the encoded data).
-
-The encoding name must map to a registered codec. If set to \NULL,
-the default encoding is used.
-
-\cfunction{PyArg_ParseTuple()} will allocate a buffer of the needed
-size using \cfunction{PyMem_NEW()}, copy the encoded data into this
-buffer and adjust \var{*buffer} to reference the newly allocated
-storage. The caller is responsible for calling
-\cfunction{PyMem_Free()} to free the allocated buffer after usage.
-
-\item[\samp{et} (string, Unicode object or character buffer compatible
-object) {[const char *encoding, char **buffer]}]
-Same as \samp{es} except that string objects are passed through without
-recoding them. Instead, the implementation assumes that the string
-object uses the encoding passed in as parameter.
-
-\item[\samp{es\#} (string, Unicode object or character buffer compatible
-object) {[const char *encoding, char **buffer, int *buffer_length]}]
-This variant on \samp{s\#} is used for encoding Unicode and objects
-convertible to Unicode into a character buffer. It reads one C
-variable and stores into three C variables, the first one a pointer to
-an encoding name string (\var{encoding}), the second a pointer to a
-pointer to a character buffer (\var{**buffer}, the buffer used for
-storing the encoded data) and the third one a pointer to an integer
-(\var{*buffer_length}, the buffer length).
-
-The encoding name must map to a registered codec. If set to \NULL,
-the default encoding is used.
-
-There are two modes of operation: 
-
-If \var{*buffer} points a \NULL{} pointer,
-\cfunction{PyArg_ParseTuple()} will allocate a buffer of the needed
-size using \cfunction{PyMem_NEW()}, copy the encoded data into this
-buffer and adjust \var{*buffer} to reference the newly allocated
-storage. The caller is responsible for calling
-\cfunction{PyMem_Free()} to free the allocated buffer after usage.
-
-If \var{*buffer} points to a non-\NULL{} pointer (an already allocated
-buffer), \cfunction{PyArg_ParseTuple()} will use this location as
-buffer and interpret \var{*buffer_length} as buffer size. It will then
-copy the encoded data into the buffer and 0-terminate it. Buffer
-overflow is signalled with an exception.
-
-In both cases, \var{*buffer_length} is set to the length of the
-encoded data without the trailing 0-byte.
-
-\item[\samp{et\#} (string, Unicode object or character buffer compatible
-object) {[const char *encoding, char **buffer]}]
-Same as \samp{es\#} except that string objects are passed through without
-recoding them. Instead, the implementation assumes that the string
-object uses the encoding passed in as parameter.
-
-\item[\samp{b} (integer) {[char]}]
-Convert a Python integer to a tiny int, stored in a C \ctype{char}.
-
-\item[\samp{h} (integer) {[short int]}]
-Convert a Python integer to a C \ctype{short int}.
-
-\item[\samp{i} (integer) {[int]}]
-Convert a Python integer to a plain C \ctype{int}.
-
-\item[\samp{l} (integer) {[long int]}]
-Convert a Python integer to a C \ctype{long int}.
-
-\item[\samp{L} (integer) {[LONG_LONG]}]
-Convert a Python integer to a C \ctype{long long}.  This format is only
-available on platforms that support \ctype{long long} (or \ctype{_int64}
-on Windows).
-
-\item[\samp{c} (string of length 1) {[char]}]
-Convert a Python character, represented as a string of length 1, to a
-C \ctype{char}.
-
-\item[\samp{f} (float) {[float]}]
-Convert a Python floating point number to a C \ctype{float}.
-
-\item[\samp{d} (float) {[double]}]
-Convert a Python floating point number to a C \ctype{double}.
-
-\item[\samp{D} (complex) {[Py_complex]}]
-Convert a Python complex number to a C \ctype{Py_complex} structure.
-
-\item[\samp{O} (object) {[PyObject *]}]
-Store a Python object (without any conversion) in a C object pointer.
-The C program thus receives the actual object that was passed.  The
-object's reference count is not increased.  The pointer stored is not
-\NULL.
-
-\item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
-Store a Python object in a C object pointer.  This is similar to
-\samp{O}, but takes two C arguments: the first is the address of a
-Python type object, the second is the address of the C variable (of
-type \ctype{PyObject *}) into which the object pointer is stored.
-If the Python object does not have the required type,
-\exception{TypeError} is raised.
-
-\item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
-Convert a Python object to a C variable through a \var{converter}
-function.  This takes two arguments: the first is a function, the
-second is the address of a C variable (of arbitrary type), converted
-to \ctype{void *}.  The \var{converter} function in turn is called as
-follows:
-
-\var{status}\code{ = }\var{converter}\code{(}\var{object}, \var{address}\code{);}
-
-where \var{object} is the Python object to be converted and
-\var{address} is the \ctype{void *} argument that was passed to
-\cfunction{PyArg_ParseTuple()}.  The returned \var{status} should be
-\code{1} for a successful conversion and \code{0} if the conversion
-has failed.  When the conversion fails, the \var{converter} function
-should raise an exception.
-
-\item[\samp{S} (string) {[PyStringObject *]}]
-Like \samp{O} but requires that the Python object is a string object.
-Raises \exception{TypeError} if the object is not a string object.
-The C variable may also be declared as \ctype{PyObject *}.
-
-\item[\samp{U} (Unicode string) {[PyUnicodeObject *]}]
-Like \samp{O} but requires that the Python object is a Unicode object.
-Raises \exception{TypeError} if the object is not a Unicode object.
-The C variable may also be declared as \ctype{PyObject *}.
-
-\item[\samp{t\#} (read-only character buffer) {[char *, int]}]
-Like \samp{s\#}, but accepts any object which implements the read-only 
-buffer interface.  The \ctype{char *} variable is set to point to the
-first byte of the buffer, and the \ctype{int} is set to the length of
-the buffer.  Only single-segment buffer objects are accepted;
-\exception{TypeError} is raised for all others.
-
-\item[\samp{w} (read-write character buffer) {[char *]}]
-Similar to \samp{s}, but accepts any object which implements the
-read-write buffer interface.  The caller must determine the length of
-the buffer by other means, or use \samp{w\#} instead.  Only
-single-segment buffer objects are accepted; \exception{TypeError} is
-raised for all others.
-
-\item[\samp{w\#} (read-write character buffer) {[char *, int]}]
-Like \samp{s\#}, but accepts any object which implements the
-read-write buffer interface.  The \ctype{char *} variable is set to
-point to the first byte of the buffer, and the \ctype{int} is set to
-the length of the buffer.  Only single-segment buffer objects are
-accepted; \exception{TypeError} is raised for all others.
-
-\item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
-The object must be a Python sequence whose length is the number of
-format units in \var{items}.  The C arguments must correspond to the
-individual format units in \var{items}.  Format units for sequences
-may be nested.
-
-\note{Prior to Python version 1.5.2, this format specifier
-only accepted a tuple containing the individual parameters, not an
-arbitrary sequence.  Code which previously caused
-\exception{TypeError} to be raised here may now proceed without an
-exception.  This is not expected to be a problem for existing code.}
-
-\end{description}
-
-It is possible to pass Python long integers where integers are
-requested; however no proper range checking is done --- the most
-significant bits are silently truncated when the receiving field is
-too small to receive the value (actually, the semantics are inherited
-from downcasts in C --- your mileage may vary).
-
-A few other characters have a meaning in a format string.  These may
-not occur inside nested parentheses.  They are:
-
-\begin{description}
-
-\item[\samp{|}]
-Indicates that the remaining arguments in the Python argument list are
-optional.  The C variables corresponding to optional arguments should
-be initialized to their default value --- when an optional argument is
-not specified, \cfunction{PyArg_ParseTuple()} does not touch the contents
-of the corresponding C variable(s).
-
-\item[\samp{:}]
-The list of format units ends here; the string after the colon is used
-as the function name in error messages (the ``associated value'' of
-the exception that \cfunction{PyArg_ParseTuple()} raises).
-
-\item[\samp{;}]
-The list of format units ends here; the string after the semicolon is
-used as the error message \emph{instead} of the default error message.
-Clearly, \samp{:} and \samp{;} mutually exclude each other.
-
-\end{description}
-
-Some example calls:
-
-\begin{verbatim}
-    int ok;
-    int i, j;
-    long k, l;
-    char *s;
-    int size;
-
-    ok = PyArg_ParseTuple(args, ""); /* No arguments */
-        /* Python call: f() */
-\end{verbatim}
-
-\begin{verbatim}
-    ok = PyArg_ParseTuple(args, "s", &s); /* A string */
-        /* Possible Python call: f('whoops!') */
-\end{verbatim}
-
-\begin{verbatim}
-    ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
-        /* Possible Python call: f(1, 2, 'three') */
-\end{verbatim}
-
-\begin{verbatim}
-    ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
-        /* A pair of ints and a string, whose size is also returned */
-        /* Possible Python call: f((1, 2), 'three') */
-\end{verbatim}
-
-\begin{verbatim}
-    {
-        char *file;
-        char *mode = "r";
-        int bufsize = 0;
-        ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
-        /* A string, and optionally another string and an integer */
-        /* Possible Python calls:
-           f('spam')
-           f('spam', 'w')
-           f('spam', 'wb', 100000) */
-    }
-\end{verbatim}
-
-\begin{verbatim}
-    {
-        int left, top, right, bottom, h, v;
-        ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
-                 &left, &top, &right, &bottom, &h, &v);
-        /* A rectangle and a point */
-        /* Possible Python call:
-           f(((0, 0), (400, 300)), (10, 10)) */
-    }
-\end{verbatim}
-
-\begin{verbatim}
-    {
-        Py_complex c;
-        ok = PyArg_ParseTuple(args, "D:myfunction", &c);
-        /* a complex, also providing a function name for errors */
-        /* Possible Python call: myfunction(1+2j) */
-    }
-\end{verbatim}
-
-
-\section{Keyword Parameters for Extension Functions
-         \label{parseTupleAndKeywords}}
-
-The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
-follows:
-
-\begin{verbatim}
-int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
-                                char *format, char **kwlist, ...);
-\end{verbatim}
-
-The \var{arg} and \var{format} parameters are identical to those of the
-\cfunction{PyArg_ParseTuple()} function.  The \var{kwdict} parameter
-is the dictionary of keywords received as the third parameter from the
-Python runtime.  The \var{kwlist} parameter is a \NULL-terminated
-list of strings which identify the parameters; the names are matched
-with the type information from \var{format} from left to right.  On
-success, \cfunction{PyArg_ParseTupleAndKeywords()} returns true,
-otherwise it returns false and raises an appropriate exception.
-
-\note{Nested tuples cannot be parsed when using keyword
-arguments!  Keyword parameters passed in which are not present in the
-\var{kwlist} will cause \exception{TypeError} to be raised.}
-
-Here is an example module which uses keywords, based on an example by
-Geoff Philbrick (\email{philbrick@hks.com}):%
-\index{Philbrick, Geoff}
-
-\begin{verbatim}
-#include "Python.h"
-
-static PyObject *
-keywdarg_parrot(self, args, keywds)
-    PyObject *self;
-    PyObject *args;
-    PyObject *keywds;
-{  
-    int voltage;
-    char *state = "a stiff";
-    char *action = "voom";
-    char *type = "Norwegian Blue";
-
-    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
-
-    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist, 
-                                     &voltage, &state, &action, &type))
-        return NULL; 
-  
-    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n", 
-           action, voltage);
-    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
-
-    Py_INCREF(Py_None);
-
-    return Py_None;
-}
-
-static PyMethodDef keywdarg_methods[] = {
-    /* The cast of the function is necessary since PyCFunction values
-     * only take two PyObject* parameters, and keywdarg_parrot() takes
-     * three.
-     */
-    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS|METH_KEYWORDS,
-     "Print a lovely skit to standard output."},
-    {NULL, NULL, 0, NULL}   /* sentinel */
-};
-
-void
-initkeywdarg(void)
-{
-  /* Create the module and add the functions */
-  Py_InitModule("keywdarg", keywdarg_methods);
-}
-\end{verbatim}
-
-
-\section{Building Arbitrary Values
-         \label{buildValue}}
-
-This function is the counterpart to \cfunction{PyArg_ParseTuple()}.  It is
-declared as follows:
-
-\begin{verbatim}
-PyObject *Py_BuildValue(char *format, ...);
-\end{verbatim}
-
-It recognizes a set of format units similar to the ones recognized by
-\cfunction{PyArg_ParseTuple()}, but the arguments (which are input to the
-function, not output) must not be pointers, just values.  It returns a
-new Python object, suitable for returning from a C function called
-from Python.
-
-One difference with \cfunction{PyArg_ParseTuple()}: while the latter
-requires its first argument to be a tuple (since Python argument lists
-are always represented as tuples internally),
-\cfunction{Py_BuildValue()} does not always build a tuple.  It builds
-a tuple only if its format string contains two or more format units.
-If the format string is empty, it returns \code{None}; if it contains
-exactly one format unit, it returns whatever object is described by
-that format unit.  To force it to return a tuple of size 0 or one,
-parenthesize the format string.
-
-When memory buffers are passed as parameters to supply data to build
-objects, as for the \samp{s} and \samp{s\#} formats, the required data
-is copied.  Buffers provided by the caller are never referenced by the
-objects created by \cfunction{Py_BuildValue()}.  In other words, if
-your code invokes \cfunction{malloc()} and passes the allocated memory
-to \cfunction{Py_BuildValue()}, your code is responsible for
-calling \cfunction{free()} for that memory once
-\cfunction{Py_BuildValue()} returns.
-
-In the following description, the quoted form is the format unit; the
-entry in (round) parentheses is the Python object type that the format
-unit will return; and the entry in [square] brackets is the type of
-the C value(s) to be passed.
-
-The characters space, tab, colon and comma are ignored in format
-strings (but not within format units such as \samp{s\#}).  This can be
-used to make long format strings a tad more readable.
-
-\begin{description}
-
-\item[\samp{s} (string) {[char *]}]
-Convert a null-terminated C string to a Python object.  If the C
-string pointer is \NULL, \code{None} is used.
-
-\item[\samp{s\#} (string) {[char *, int]}]
-Convert a C string and its length to a Python object.  If the C string
-pointer is \NULL, the length is ignored and \code{None} is
-returned.
-
-\item[\samp{z} (string or \code{None}) {[char *]}]
-Same as \samp{s}.
-
-\item[\samp{z\#} (string or \code{None}) {[char *, int]}]
-Same as \samp{s\#}.
-
-\item[\samp{u} (Unicode string) {[Py_UNICODE *]}]
-Convert a null-terminated buffer of Unicode (UCS-2) data to a Python
-Unicode object.  If the Unicode buffer pointer is \NULL,
-\code{None} is returned.
-
-\item[\samp{u\#} (Unicode string) {[Py_UNICODE *, int]}]
-Convert a Unicode (UCS-2) data buffer and its length to a Python
-Unicode object.   If the Unicode buffer pointer is \NULL, the length
-is ignored and \code{None} is returned.
-
-\item[\samp{i} (integer) {[int]}]
-Convert a plain C \ctype{int} to a Python integer object.
-
-\item[\samp{b} (integer) {[char]}]
-Same as \samp{i}.
-
-\item[\samp{h} (integer) {[short int]}]
-Same as \samp{i}.
-
-\item[\samp{l} (integer) {[long int]}]
-Convert a C \ctype{long int} to a Python integer object.
-
-\item[\samp{c} (string of length 1) {[char]}]
-Convert a C \ctype{int} representing a character to a Python string of
-length 1.
-
-\item[\samp{d} (float) {[double]}]
-Convert a C \ctype{double} to a Python floating point number.
-
-\item[\samp{f} (float) {[float]}]
-Same as \samp{d}.
-
-\item[\samp{D} (complex) {[Py_complex *]}]
-Convert a C \ctype{Py_complex} structure to a Python complex number.
-
-\item[\samp{O} (object) {[PyObject *]}]
-Pass a Python object untouched (except for its reference count, which
-is incremented by one).  If the object passed in is a \NULL{}
-pointer, it is assumed that this was caused because the call producing
-the argument found an error and set an exception.  Therefore,
-\cfunction{Py_BuildValue()} will return \NULL{} but won't raise an
-exception.  If no exception has been raised yet,
-\cdata{PyExc_SystemError} is set.
-
-\item[\samp{S} (object) {[PyObject *]}]
-Same as \samp{O}.
-
-\item[\samp{U} (object) {[PyObject *]}]
-Same as \samp{O}.
-
-\item[\samp{N} (object) {[PyObject *]}]
-Same as \samp{O}, except it doesn't increment the reference count on
-the object.  Useful when the object is created by a call to an object
-constructor in the argument list.
-
-\item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
-Convert \var{anything} to a Python object through a \var{converter}
-function.  The function is called with \var{anything} (which should be
-compatible with \ctype{void *}) as its argument and should return a
-``new'' Python object, or \NULL{} if an error occurred.
-
-\item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
-Convert a sequence of C values to a Python tuple with the same number
-of items.
-
-\item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
-Convert a sequence of C values to a Python list with the same number
-of items.
-
-\item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
-Convert a sequence of C values to a Python dictionary.  Each pair of
-consecutive C values adds one item to the dictionary, serving as key
-and value, respectively.
-
-\end{description}
-
-If there is an error in the format string, the
-\cdata{PyExc_SystemError} exception is raised and \NULL{} returned.
-
-Examples (to the left the call, to the right the resulting Python value):
-
-\begin{verbatim}
-    Py_BuildValue("")                        None
-    Py_BuildValue("i", 123)                  123
-    Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
-    Py_BuildValue("s", "hello")              'hello'
-    Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
-    Py_BuildValue("s#", "hello", 4)          'hell'
-    Py_BuildValue("()")                      ()
-    Py_BuildValue("(i)", 123)                (123,)
-    Py_BuildValue("(ii)", 123, 456)          (123, 456)
-    Py_BuildValue("(i,i)", 123, 456)         (123, 456)
-    Py_BuildValue("[i,i]", 123, 456)         [123, 456]
-    Py_BuildValue("{s:i,s:i}",
-                  "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
-    Py_BuildValue("((ii)(ii)) (ii)",
-                  1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))
-\end{verbatim}
-
-
-\section{Reference Counts
-         \label{refcounts}}
-
-In languages like C or \Cpp, the programmer is responsible for
-dynamic allocation and deallocation of memory on the heap.  In C,
-this is done using the functions \cfunction{malloc()} and
-\cfunction{free()}.  In \Cpp, the operators \keyword{new} and
-\keyword{delete} are used with essentially the same meaning; they are
-actually implemented using \cfunction{malloc()} and
-\cfunction{free()}, so we'll restrict the following discussion to the
-latter.
-
-Every block of memory allocated with \cfunction{malloc()} should
-eventually be returned to the pool of available memory by exactly one
-call to \cfunction{free()}.  It is important to call
-\cfunction{free()} at the right time.  If a block's address is
-forgotten but \cfunction{free()} is not called for it, the memory it
-occupies cannot be reused until the program terminates.  This is
-called a \dfn{memory leak}.  On the other hand, if a program calls
-\cfunction{free()} for a block and then continues to use the block, it
-creates a conflict with re-use of the block through another
-\cfunction{malloc()} call.  This is called \dfn{using freed memory}.
-It has the same bad consequences as referencing uninitialized data ---
-core dumps, wrong results, mysterious crashes.
-
-Common causes of memory leaks are unusual paths through the code.  For
-instance, a function may allocate a block of memory, do some
-calculation, and then free the block again.  Now a change in the
-requirements for the function may add a test to the calculation that
-detects an error condition and can return prematurely from the
-function.  It's easy to forget to free the allocated memory block when
-taking this premature exit, especially when it is added later to the
-code.  Such leaks, once introduced, often go undetected for a long
-time: the error exit is taken only in a small fraction of all calls,
-and most modern machines have plenty of virtual memory, so the leak
-only becomes apparent in a long-running process that uses the leaking
-function frequently.  Therefore, it's important to prevent leaks from
-happening by having a coding convention or strategy that minimizes
-this kind of errors.
-
-Since Python makes heavy use of \cfunction{malloc()} and
-\cfunction{free()}, it needs a strategy to avoid memory leaks as well
-as the use of freed memory.  The chosen method is called
-\dfn{reference counting}.  The principle is simple: every object
-contains a counter, which is incremented when a reference to the
-object is stored somewhere, and which is decremented when a reference
-to it is deleted.  When the counter reaches zero, the last reference
-to the object has been deleted and the object is freed.
-
-An alternative strategy is called \dfn{automatic garbage collection}.
-(Sometimes, reference counting is also referred to as a garbage
-collection strategy, hence my use of ``automatic'' to distinguish the
-two.)  The big advantage of automatic garbage collection is that the
-user doesn't need to call \cfunction{free()} explicitly.  (Another claimed
-advantage is an improvement in speed or memory usage --- this is no
-hard fact however.)  The disadvantage is that for C, there is no
-truly portable automatic garbage collector, while reference counting
-can be implemented portably (as long as the functions \cfunction{malloc()}
-and \cfunction{free()} are available --- which the C Standard guarantees).
-Maybe some day a sufficiently portable automatic garbage collector
-will be available for C.  Until then, we'll have to live with
-reference counts.
-
-While Python uses the traditional reference counting implementation,
-it also offers a cycle detector that works to detect reference
-cycles.  This allows applications to not worry about creating direct
-or indirect circular references; these are the weakness of garbage
-collection implemented using only reference counting.  Reference
-cycles consist of objects which contain (possibly indirect) references
-to themselves, so that each object in the cycle has a reference count
-which is non-zero.  Typical reference counting implementations are not
-able to reclaim the memory belonging to any objects in a reference
-cycle, or referenced from the objects in the cycle, even though there
-are no further references to the cycle itself.
-
-The cycle detector is able to detect garbage cycles and can reclaim
-them so long as there are no finalizers implemented in Python
-(\method{__del__()} methods).  When there are such finalizers, the
-detector exposes the cycles through the \ulink{\module{gc}
-module}{../lib/module-gc.html} (specifically, the \code{garbage}
-variable in that module).  The \module{gc} module also exposes a way
-to run the detector (the \function{collect()} function), as well as
-configuration interfaces and the ability to disable the detector at
-runtime.  The cycle detector is considered an optional component;
-though it is included by default, it can be disabled at build time
-using the \longprogramopt{without-cycle-gc} option to the
-\program{configure} script on \UNIX{} platforms (including Mac OS X)
-or by removing the definition of \code{WITH_CYCLE_GC} in the
-\file{pyconfig.h} header on other platforms.  If the cycle detector is
-disabled in this way, the \module{gc} module will not be available.
-
-
-\subsection{Reference Counting in Python
-            \label{refcountsInPython}}
-
-There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
-which handle the incrementing and decrementing of the reference count.
-\cfunction{Py_DECREF()} also frees the object when the count reaches zero.
-For flexibility, it doesn't call \cfunction{free()} directly --- rather, it
-makes a call through a function pointer in the object's \dfn{type
-object}.  For this purpose (and others), every object also contains a
-pointer to its type object.
-
-The big question now remains: when to use \code{Py_INCREF(x)} and
-\code{Py_DECREF(x)}?  Let's first introduce some terms.  Nobody
-``owns'' an object; however, you can \dfn{own a reference} to an
-object.  An object's reference count is now defined as the number of
-owned references to it.  The owner of a reference is responsible for