Delete the LaTeX doc tree.

14 files changed, 0 insertions, 5092 deletions

diff --git a/Doc/ext/building.tex b/Doc/ext/building.tex
deleted file mode 100644
index 42384c1..0000000
--- a/Doc/ext/building.tex
+++ /dev/null
@@ -1,143 +0,0 @@
-\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}
-
diff --git a/Doc/ext/embedding.tex b/Doc/ext/embedding.tex
deleted file mode 100644
index 58ec5ca..0000000
--- a/Doc/ext/embedding.tex
+++ /dev/null
@@ -1,316 +0,0 @@
-\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
-accommodate 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 the 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 "Will compute", 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 multiply 3 2
-Will compute 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}
-    pFunc = PyObject_GetAttrString(pModule, argv[2]);
-    /* pFunc is a new reference */
-
-    if (pFunc && PyCallable_Check(pFunc)) {
-        ...
-    }
-    Py_XDECREF(pFunc);
-\end{verbatim}
-
-Once the script is loaded, the name we're looking for is retrieved
-using \cfunction{PyObject_GetAttrString()}.  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}.
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
deleted file mode 100644
index b4130d1..0000000
--- a/Doc/ext/ext.tex
+++ /dev/null
@@ -1,67 +0,0 @@
-\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}
diff --git a/Doc/ext/extending.tex b/Doc/ext/extending.tex
deleted file mode 100644
index 53d90db..0000000
--- a/Doc/ext/extending.tex
+++ /dev/null
@@ -1,1390 +0,0 @@
-\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 straightforward 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).
-
-\begin{notice}[warning]
-  Since Python may define some pre-processor definitions which affect
-  the standard headers on some systems, you \emph{must} include
-  \file{Python.h} before any standard headers are included.
-\end{notice}
-
-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(PyObject *self, PyObject *args)
-{
-    const 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}
-PyMODINIT_FUNC
-initspam(void)
-{
-    PyObject *m;
-
-    m = Py_InitModule("spam", SpamMethods);
-    if (m == NULL)
-        return;
-
-    SpamError = PyErr_NewException("spam.error", NULL, NULL);
-    Py_INCREF(SpamError);
-    PyModule_AddObject(m, "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.
-
-We discuss the use of PyMODINIT_FUNC as a function return type later in this
-sample.
-
-\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 (which is implemented by the
-\csimplemacro{Py_RETURN_NONE} macro):
-
-\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}
-PyMODINIT_FUNC
-initspam(void)
-{
-    (void) Py_InitModule("spam", SpamMethods);
-}
-\end{verbatim}
-
-Note that PyMODINIT_FUNC declares the function as \code{void} return type, 
-declares any special linkage declarations required by the platform, and for 
-\Cpp{} declares the function as \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 may abort with a fatal error
-for certain errors, or return \NULL{} if the module could not be
-initialized satisfactorily.
-
-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()}:
-
-\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.
-
-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(PyObject *dummy, PyObject *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}}
-
-\ttindex{PyArg_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 in
-``\ulink{Parsing arguments and building
-values}{../api/arg-parsing.html}'' in the
-\citetitle[../api/api.html]{Python/C API Reference Manual}.  The
-remaining arguments must be addresses of variables whose type is
-determined by the format string.
-
-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!
-
-Note that any Python object references which are provided to the
-caller are \emph{borrowed} references; do not decrement their
-reference count!
-
-Some example calls:
-
-\begin{verbatim}
-    int ok;
-    int i, j;
-    long k, l;
-    const 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}
-    {
-        const char *file;
-        const 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}}
-
-\ttindex{PyArg_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(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 */
-};
-\end{verbatim}
-
-\begin{verbatim}
-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.
-
-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 and
-we'll restrict the following discussion to the C case.
-
-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
-calling \cfunction{Py_DECREF()} when the reference is no longer
-needed.  Ownership of a reference can be transferred.  There are three
-ways to dispose of an owned reference: pass it on, store it, or call
-\cfunction{Py_DECREF()}.  Forgetting to dispose of an owned reference
-creates a memory leak.
-
-It is also possible to \dfn{borrow}\footnote{The metaphor of
-``borrowing'' a reference is not completely correct: the owner still
-has a copy of the reference.} a reference to an object.  The borrower
-of a reference should not call \cfunction{Py_DECREF()}.  The borrower must
-not hold on to the object longer than the owner from which it was
-borrowed.  Using a borrowed reference after the owner has disposed of
-it risks using freed memory and should be avoided
-completely.\footnote{Checking that the reference count is at least 1
-\strong{does not work} --- the reference count itself could be in
-freed memory and may thus be reused for another object!}
-
-The advantage of borrowing over owning a reference is that you don't
-need to take care of disposing of the reference on all possible paths
-through the code --- in other words, with a borrowed reference you
-don't run the risk of leaking when a premature exit is taken.  The
-disadvantage of borrowing over leaking is that there are some subtle
-situations where in seemingly correct code a borrowed reference can be
-used after the owner from which it was borrowed has in fact disposed
-of it.
-
-A borrowed reference can be changed into an owned reference by calling
-\cfunction{Py_INCREF()}.  This does not affect the status of the owner from
-which the reference was borrowed --- it creates a new owned reference,
-and gives full owner responsibilities (the new owner must
-dispose of the reference properly, as well as the previous owner).
-
-
-\subsection{Ownership Rules
-            \label{ownershipRules}}
-
-Whenever an object reference is passed into or out of a function, it
-is part of the function's interface specification whether ownership is
-transferred with the reference or not.
-
-Most functions that return a reference to an object pass on ownership
-with the reference.  In particular, all functions whose function it is
-to create a new object, such as \cfunction{PyInt_FromLong()} and
-\cfunction{Py_BuildValue()}, pass ownership to the receiver.  Even if
-the object is not actually new, you still receive ownership of a new
-reference to that object.  For instance, \cfunction{PyInt_FromLong()}
-maintains a cache of popular values and can return a reference to a
-cached item.
-
-Many functions that extract objects from other objects also transfer
-ownership with the reference, for instance
-\cfunction{PyObject_GetAttrString()}.  The picture is less clear, here,
-however, since a few common routines are exceptions:
-\cfunction{PyTuple_GetItem()}, \cfunction{PyList_GetItem()},
-\cfunction{PyDict_GetItem()}, and \cfunction{PyDict_GetItemString()}
-all return references that you borrow from the tuple, list or
-dictionary.
-
-The function \cfunction{PyImport_AddModule()} also returns a borrowed
-reference, even though it may actually create the object it returns:
-this is possible because an owned reference to the object is stored in
-\code{sys.modules}.
-
-When you pass an object reference into another function, in general,
-the function borrows the reference from you --- if it needs to store
-it, it will use \cfunction{Py_INCREF()} to become an independent
-owner.  There are exactly two important exceptions to this rule:
-\cfunction{PyTuple_SetItem()} and \cfunction{PyList_SetItem()}.  These
-functions take over ownership of the item passed to them --- even if
-they fail!  (Note that \cfunction{PyDict_SetItem()} and friends don't
-take over ownership --- they are ``normal.'')
-
-When a C function is called from Python, it borrows references to its
-arguments from the caller.  The caller owns a reference to the object,
-so the borrowed reference's lifetime is guaranteed until the function
-returns.  Only when such a borrowed reference must be stored or passed
-on, it must be turned into an owned reference by calling
-\cfunction{Py_INCREF()}.
-
-The object reference returned from a C function that is called from
-Python must be an owned reference --- ownership is transferred from
-the function to its caller.
-
-
-\subsection{Thin Ice
-            \label{thinIce}}
-
-There are a few situations where seemingly harmless use of a borrowed
-reference can lead to problems.  These all have to do with implicit
-invocations of the interpreter, which can cause the owner of a
-reference to dispose of it.
-
-The first and most important case to know about is using
-\cfunction{Py_DECREF()} on an unrelated object while borrowing a
-reference to a list item.  For instance:
-
-\begin{verbatim}
-void
-bug(PyObject *list)
-{
-    PyObject *item = PyList_GetItem(list, 0);
-
-    PyList_SetItem(list, 1, PyInt_FromLong(0L));
-    PyObject_Print(item, stdout, 0); /* BUG! */
-}
-\end{verbatim}
-
-This function first borrows a reference to \code{list[0]}, then
-replaces \code{list[1]} with the value \code{0}, and finally prints
-the borrowed reference.  Looks harmless, right?  But it's not!
-
-Let's follow the control flow into \cfunction{PyList_SetItem()}.  The list
-owns references to all its items, so when item 1 is replaced, it has
-to dispose of the original item 1.  Now let's suppose the original
-item 1 was an instance of a user-defined class, and let's further
-suppose that the class defined a \method{__del__()} method.  If this
-class instance has a reference count of 1, disposing of it will call
-its \method{__del__()} method.
-
-Since it is written in Python, the \method{__del__()} method can execute
-arbitrary Python code.  Could it perhaps do something to invalidate
-the reference to \code{item} in \cfunction{bug()}?  You bet!  Assuming
-that the list passed into \cfunction{bug()} is accessible to the
-\method{__del__()} method, it could execute a statement to the effect of
-\samp{del list[0]}, and assuming this was the last reference to that
-object, it would free the memory associated with it, thereby
-invalidating \code{item}.
-
-The solution, once you know the source of the problem, is easy:
-temporarily increment the reference count.  The correct version of the
-function reads:
-
-\begin{verbatim}
-void
-no_bug(PyObject *list)
-{
-    PyObject *item = PyList_GetItem(list, 0);
-
-    Py_INCREF(item);
-    PyList_SetItem(list, 1, PyInt_FromLong(0L));
-    PyObject_Print(item, stdout, 0);
-    Py_DECREF(item);
-}
-\end{verbatim}
-
-This is a true story.  An older version of Python contained variants
-of this bug and someone spent a considerable amount of time in a C
-debugger to figure out why his \method{__del__()} methods would fail...
-
-The second case of problems with a borrowed reference is a variant
-involving threads.  Normally, multiple threads in the Python
-interpreter can't get in each other's way, because there is a global
-lock protecting Python's entire object space.  However, it is possible
-to temporarily release this lock using the macro
-\csimplemacro{Py_BEGIN_ALLOW_THREADS}, and to re-acquire it using
-\csimplemacro{Py_END_ALLOW_THREADS}.  This is common around blocking
-I/O calls, to let other threads use the processor while waiting for
-the I/O to complete.  Obviously, the following function has the same
-problem as the previous one:
-
-\begin{verbatim}
-void
-bug(PyObject *list)
-{
-    PyObject *item = PyList_GetItem(list, 0);
-    Py_BEGIN_ALLOW_THREADS
-    ...some blocking I/O call...
-    Py_END_ALLOW_THREADS
-    PyObject_Print(item, stdout, 0); /* BUG! */
-}
-\end{verbatim}
-
-
-\subsection{NULL Pointers
-            \label{nullPointers}}
-
-In general, functions that take object references as arguments do not
-expect you to pass them \NULL{} pointers, and will dump core (or
-cause later core dumps) if you do so.  Functions that return object
-references generally return \NULL{} only to indicate that an
-exception occurred.  The reason for not testing for \NULL{}
-arguments is that functions often pass the objects they receive on to
-other function --- if each function were to test for \NULL,
-there would be a lot of redundant tests and the code would run more
-slowly.
-
-It is better to test for \NULL{} only at the ``source:'' when a
-pointer that may be \NULL{} is received, for example, from
-\cfunction{malloc()} or from a function that may raise an exception.
-
-The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
-do not check for \NULL{} pointers --- however, their variants
-\cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()} do.
-
-The macros for checking for a particular object type
-(\code{Py\var{type}_Check()}) don't check for \NULL{} pointers ---
-again, there is much code that calls several of these in a row to test
-an object against various different expected types, and this would
-generate redundant tests.  There are no variants with \NULL{}
-checking.
-
-The C function calling mechanism guarantees that the argument list
-passed to C functions (\code{args} in the examples) is never
-\NULL{} --- in fact it guarantees that it is always a tuple.\footnote{
-These guarantees don't hold when you use the ``old'' style
-calling convention --- this is still found in much existing code.}
-
-It is a severe error to ever let a \NULL{} pointer ``escape'' to
-the Python user.
-
-% Frank Stajano:
-% A pedagogically buggy example, along the lines of the previous listing, 
-% would be helpful here -- showing in more concrete terms what sort of 
-% actions could cause the problem. I can't very well imagine it from the 
-% description.
-
-
-\section{Writing Extensions in \Cpp
-         \label{cplusplus}}
-
-It is possible to write extension modules in \Cpp.  Some restrictions
-apply.  If the main program (the Python interpreter) is compiled and
-linked by the C compiler, global or static objects with constructors
-cannot be used.  This is not a problem if the main program is linked
-by the \Cpp{} compiler.  Functions that will be called by the
-Python interpreter (in particular, module initialization functions)
-have to be declared using \code{extern "C"}.
-It is unnecessary to enclose the Python header files in
-\code{extern "C" \{...\}} --- they use this form already if the symbol
-\samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
-symbol).
-
-
-\section{Providing a C API for an Extension Module
-         \label{using-cobjects}}
-\sectionauthor{Konrad Hinsen}{hinsen@cnrs-orleans.fr}
-
-Many extension modules just provide new functions and types to be
-used from Python, but sometimes the code in an extension module can
-be useful for other extension modules. For example, an extension
-module could implement a type ``collection'' which works like lists
-without order. Just like the standard Python list type has a C API
-which permits extension modules to create and manipulate lists, this
-new collection type should have a set of C functions for direct
-manipulation from other extension modules.
-
-At first sight this seems easy: just write the functions (without
-declaring them \keyword{static}, of course), provide an appropriate
-header file, and document the C API. And in fact this would work if
-all extension modules were always linked statically with the Python
-interpreter. When modules are used as shared libraries, however, the
-symbols defined in one module may not be visible to another module.
-The details of visibility depend on the operating system; some systems
-use one global namespace for the Python interpreter and all extension
-modules (Windows, for example), whereas others require an explicit
-list of imported symbols at module link time (AIX is one example), or
-offer a choice of different strategies (most Unices). And even if
-symbols are globally visible, the module whose functions one wishes to
-call might not have been loaded yet!
-
-Portability therefore requires not to make any assumptions about
-symbol visibility. This means that all symbols in extension modules
-should be declared \keyword{static}, except for the module's
-initialization function, in order to avoid name clashes with other
-extension modules (as discussed in section~\ref{methodTable}). And it
-means that symbols that \emph{should} be accessible from other
-extension modules must be exported in a different way.
-
-Python provides a special mechanism to pass C-level information
-(pointers) from one extension module to another one: CObjects.
-A CObject is a Python data type which stores a pointer (\ctype{void
-*}).  CObjects can only be created and accessed via their C API, but
-they can be passed around like any other Python object. In particular, 
-they can be assigned to a name in an extension module's namespace.
-Other extension modules can then import this module, retrieve the
-value of this name, and then retrieve the pointer from the CObject.
-
-There are many ways in which CObjects can be used to export the C API
-of an extension module. Each name could get its own CObject, or all C
-API pointers could be stored in an array whose address is published in
-a CObject. And the various tasks of storing and retrieving the pointers
-can be distributed in different ways between the module providing the
-code and the client modules.
-
-The following example demonstrates an approach that puts most of the
-burden on the writer of the exporting module, which is appropriate
-for commonly used library modules. It stores all C API pointers
-(just one in the example!) in an array of \ctype{void} pointers which
-becomes the value of a CObject. The header file corresponding to
-the module provides a macro that takes care of importing the module
-and retrieving its C API pointers; client modules only have to call
-this macro before accessing the C API.
-
-The exporting module is a modification of the \module{spam} module from
-section~\ref{simpleExample}. The function \function{spam.system()}
-does not call the C library function \cfunction{system()} directly,
-but a function \cfunction{PySpam_System()}, which would of course do
-something more complicated in reality (such as adding ``spam'' to
-every command). This function \cfunction{PySpam_System()} is also
-exported to other extension modules.
-
-The function \cfunction{PySpam_System()} is a plain C function,
-declared \keyword{static} like everything else:
-
-\begin{verbatim}
-static int
-PySpam_System(const char *command)
-{
-    return system(command);
-}
-\end{verbatim}
-
-The function \cfunction{spam_system()} is modified in a trivial way:
-
-\begin{verbatim}
-static PyObject *
-spam_system(PyObject *self, PyObject *args)
-{
-    const char *command;
-    int sts;
-
-    if (!PyArg_ParseTuple(args, "s", &command))
-        return NULL;
-    sts = PySpam_System(command);
-    return Py_BuildValue("i", sts);
-}
-\end{verbatim}
-
-In the beginning of the module, right after the line
-
-\begin{verbatim}
-#include "Python.h"
-\end{verbatim}
-
-two more lines must be added:
-
-\begin{verbatim}
-#define SPAM_MODULE
-#include "spammodule.h"
-\end{verbatim}
-
-The \code{\#define} is used to tell the header file that it is being
-included in the exporting module, not a client module. Finally,
-the module's initialization function must take care of initializing
-the C API pointer array:
-
-\begin{verbatim}
-PyMODINIT_FUNC
-initspam(void)
-{
-    PyObject *m;
-    static void *PySpam_API[PySpam_API_pointers];
-    PyObject *c_api_object;
-
-    m = Py_InitModule("spam", SpamMethods);
-    if (m == NULL)
-        return;
-
-    /* Initialize the C API pointer array */
-    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
-
-    /* Create a CObject containing the API pointer array's address */
-    c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
-
-    if (c_api_object != NULL)
-        PyModule_AddObject(m, "_C_API", c_api_object);
-}
-\end{verbatim}
-
-Note that \code{PySpam_API} is declared \keyword{static}; otherwise
-the pointer array would disappear when \function{initspam()} terminates!
-
-The bulk of the work is in the header file \file{spammodule.h},
-which looks like this:
-
-\begin{verbatim}
-#ifndef Py_SPAMMODULE_H
-#define Py_SPAMMODULE_H
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/* Header file for spammodule */
-
-/* C API functions */
-#define PySpam_System_NUM 0
-#define PySpam_System_RETURN int
-#define PySpam_System_PROTO (const char *command)
-
-/* Total number of C API pointers */
-#define PySpam_API_pointers 1
-
-
-#ifdef SPAM_MODULE
-/* This section is used when compiling spammodule.c */
-
-static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;
-
-#else
-/* This section is used in modules that use spammodule's API */
-
-static void **PySpam_API;
-
-#define PySpam_System \
- (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
-
-/* Return -1 and set exception on error, 0 on success. */
-static int
-import_spam(void)
-{
-    PyObject *module = PyImport_ImportModule("spam");
-
-    if (module != NULL) {
-        PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
-        if (c_api_object == NULL)
-            return -1;
-        if (PyCObject_Check(c_api_object))
-            PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
-        Py_DECREF(c_api_object);
-    }
-    return 0;
-}
-
-#endif
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* !defined(Py_SPAMMODULE_H) */
-\end{verbatim}
-
-All that a client module must do in order to have access to the
-function \cfunction{PySpam_System()} is to call the function (or
-rather macro) \cfunction{import_spam()} in its initialization
-function:
-
-\begin{verbatim}
-PyMODINIT_FUNC
-initclient(void)
-{
-    PyObject *m;
-
-    m = Py_InitModule("client", ClientMethods);
-    if (m == NULL)
-        return;
-    if (import_spam() < 0)
-        return;
-    /* additional initialization can happen here */
-}
-\end{verbatim}
-
-The main disadvantage of this approach is that the file
-\file{spammodule.h} is rather complicated. However, the
-basic structure is the same for each function that is
-exported, so it has to be learned only once.
-
-Finally it should be mentioned that CObjects offer additional
-functionality, which is especially useful for memory allocation and
-deallocation of the pointer stored in a CObject. The details
-are described in the \citetitle[../api/api.html]{Python/C API
-Reference Manual} in the section
-``\ulink{CObjects}{../api/cObjects.html}'' and in the implementation
-of CObjects (files \file{Include/cobject.h} and
-\file{Objects/cobject.c} in the Python source code distribution).
diff --git a/Doc/ext/newtypes.tex b/Doc/ext/newtypes.tex
deleted file mode 100644
index 5c1f0ae..0000000
--- a/Doc/ext/newtypes.tex
+++ /dev/null
@@ -1,1765 +0,0 @@
-\chapter{Defining New Types
-        \label{defining-new-types}}
-\sectionauthor{Michael Hudson}{mwh@python.net}
-\sectionauthor{Dave Kuhlman}{dkuhlman@rexx.com}
-\sectionauthor{Jim Fulton}{jim@zope.com}
-
-As mentioned in the last chapter, Python allows the writer of an
-extension module to define new types that can be manipulated from
-Python code, much like strings and lists in core Python.
-
-This is not hard; the code for all extension types follows a pattern,
-but there are some details that you need to understand before you can
-get started.
-
-\begin{notice}
-The way new types are defined changed dramatically (and for the
-better) in Python 2.2.  This document documents how to define new
-types for Python 2.2 and later.  If you need to support older
-versions of Python, you will need to refer to
-\ulink{older versions of this documentation}
-      {http://www.python.org/doc/versions/}.
-\end{notice}
-
-\section{The Basics
-    \label{dnt-basics}}
-
-The Python runtime sees all Python objects as variables of type
-\ctype{PyObject*}.  A \ctype{PyObject} is not a very magnificent
-object - it just contains the refcount and a pointer to the object's
-``type object''.  This is where the action is; the type object
-determines which (C) functions get called when, for instance, an
-attribute gets looked up on an object or it is multiplied by another
-object.  These C functions are called ``type methods'' to distinguish
-them from things like \code{[].append} (which we call ``object
-methods'').
-
-So, if you want to define a new object type, you need to create a new
-type object.
-
-This sort of thing can only be explained by example, so here's a
-minimal, but complete, module that defines a new type:
-
-\verbatiminput{noddy.c}
-
-Now that's quite a bit to take in at once, but hopefully bits will
-seem familiar from the last chapter.
-
-The first bit that will be new is:
-
-\begin{verbatim}
-typedef struct {
-    PyObject_HEAD
-} noddy_NoddyObject;
-\end{verbatim}
-
-This is what a Noddy object will contain---in this case, nothing more
-than every Python object contains, namely a refcount and a pointer to a type
-object.  These are the fields the \code{PyObject_HEAD} macro brings
-in.  The reason for the macro is to standardize the layout and to
-enable special debugging fields in debug builds.  Note that there is
-no semicolon after the \code{PyObject_HEAD} macro; one is included in
-the macro definition.  Be wary of adding one by accident; it's easy to
-do from habit, and your compiler might not complain, but someone
-else's probably will!  (On Windows, MSVC is known to call this an
-error and refuse to compile the code.)
-
-For contrast, let's take a look at the corresponding definition for
-standard Python integers:
-
-\begin{verbatim}
-typedef struct {
-    PyObject_HEAD
-    long ob_ival;
-} PyIntObject;
-\end{verbatim}
-
-Moving on, we come to the crunch --- the type object.
-
-\begin{verbatim}
-static PyTypeObject noddy_NoddyType = {
-    PyObject_HEAD_INIT(NULL)
-    0,                         /*ob_size*/
-    "noddy.Noddy",             /*tp_name*/
-    sizeof(noddy_NoddyObject), /*tp_basicsize*/
-    0,                         /*tp_itemsize*/
-    0,                         /*tp_dealloc*/
-    0,                         /*tp_print*/
-    0,                         /*tp_getattr*/
-    0,                         /*tp_setattr*/
-    0,                         /*tp_compare*/
-    0,                         /*tp_repr*/
-    0,                         /*tp_as_number*/
-    0,                         /*tp_as_sequence*/
-    0,                         /*tp_as_mapping*/
-    0,                         /*tp_hash */
-    0,                         /*tp_call*/
-    0,                         /*tp_str*/
-    0,                         /*tp_getattro*/
-    0,                         /*tp_setattro*/
-    0,                         /*tp_as_buffer*/
-    Py_TPFLAGS_DEFAULT,        /*tp_flags*/
-    "Noddy objects",           /* tp_doc */
-};
-\end{verbatim}
-
-Now if you go and look up the definition of \ctype{PyTypeObject} in
-\file{object.h} you'll see that it has many more fields that the
-definition above.  The remaining fields will be filled with zeros by
-the C compiler, and it's common practice to not specify them
-explicitly unless you need them.
-
-This is so important that we're going to pick the top of it apart still
-further:
-
-\begin{verbatim}
-    PyObject_HEAD_INIT(NULL)
-\end{verbatim}
-
-This line is a bit of a wart; what we'd like to write is:
-
-\begin{verbatim}
-    PyObject_HEAD_INIT(&PyType_Type)
-\end{verbatim}
-
-as the type of a type object is ``type'', but this isn't strictly
-conforming C and some compilers complain.  Fortunately, this member
-will be filled in for us by \cfunction{PyType_Ready()}.
-
-\begin{verbatim}
-    0,                          /* ob_size */
-\end{verbatim}
-
-The \member{ob_size} field of the header is not used; its presence in
-the type structure is a historical artifact that is maintained for
-binary compatibility with extension modules compiled for older
-versions of Python.  Always set this field to zero.
-
-\begin{verbatim}
-    "noddy.Noddy",              /* tp_name */
-\end{verbatim}
-
-The name of our type.  This will appear in the default textual
-representation of our objects and in some error messages, for example:
-
-\begin{verbatim}
->>> "" + noddy.new_noddy()
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-TypeError: cannot add type "noddy.Noddy" to string
-\end{verbatim}
-
-Note that the name is a dotted name that includes both the module name
-and the name of the type within the module. The module in this case is
-\module{noddy} and the type is \class{Noddy}, so we set the type name
-to \class{noddy.Noddy}.
-
-\begin{verbatim}
-    sizeof(noddy_NoddyObject),  /* tp_basicsize */
-\end{verbatim}
-
-This is so that Python knows how much memory to allocate when you call
-\cfunction{PyObject_New()}.
-
-\note{If you want your type to be subclassable from Python, and your
-type has the same \member{tp_basicsize} as its base type, you may
-have problems with multiple inheritance.  A Python subclass of your
-type will have to list your type first in its \member{__bases__}, or
-else it will not be able to call your type's \method{__new__} method
-without getting an error.  You can avoid this problem by ensuring
-that your type has a larger value for \member{tp_basicsize} than
-its base type does.  Most of the time, this will be true anyway,
-because either your base type will be \class{object}, or else you will
-be adding data members to your base type, and therefore increasing its
-size.}
-
-\begin{verbatim}
-    0,                          /* tp_itemsize */
-\end{verbatim}
-
-This has to do with variable length objects like lists and strings.
-Ignore this for now.
-
-Skipping a number of type methods that we don't provide, we set the
-class flags to \constant{Py_TPFLAGS_DEFAULT}.
-
-\begin{verbatim}
-    Py_TPFLAGS_DEFAULT,        /*tp_flags*/
-\end{verbatim}
-
-All types should include this constant in their flags.  It enables all
-of the members defined by the current version of Python.
-
-We provide a doc string for the type in \member{tp_doc}.
-
-\begin{verbatim}
-    "Noddy objects",           /* tp_doc */
-\end{verbatim}
-
-Now we get into the type methods, the things that make your objects
-different from the others.  We aren't going to implement any of these
-in this version of the module.  We'll expand this example later to
-have more interesting behavior.
-
-For now, all we want to be able to do is to create new \class{Noddy}
-objects. To enable object creation, we have to provide a
-\member{tp_new} implementation. In this case, we can just use the
-default implementation provided by the API function
-\cfunction{PyType_GenericNew()}.  We'd like to just assign this to the
-\member{tp_new} slot, but we can't, for portability sake, On some
-platforms or compilers, we can't statically initialize a structure
-member with a function defined in another C module, so, instead, we'll
-assign the \member{tp_new} slot in the module initialization function
-just before calling \cfunction{PyType_Ready()}:
-
-\begin{verbatim}
-    noddy_NoddyType.tp_new = PyType_GenericNew;
-    if (PyType_Ready(&noddy_NoddyType) < 0)
-        return;
-\end{verbatim}
-
-All the other type methods are \NULL, so we'll go over them later
---- that's for a later section!
-
-Everything else in the file should be familiar, except for some code
-in \cfunction{initnoddy()}:
-
-\begin{verbatim}
-    if (PyType_Ready(&noddy_NoddyType) < 0)
-        return;
-\end{verbatim}
-
-This initializes the \class{Noddy} type, filing in a number of
-members, including \member{ob_type} that we initially set to \NULL.
-
-\begin{verbatim}
-    PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
-\end{verbatim}
-
-This adds the type to the module dictionary.  This allows us to create
-\class{Noddy} instances by calling the \class{Noddy} class:
-
-\begin{verbatim}
->>> import noddy
->>> mynoddy = noddy.Noddy()
-\end{verbatim}
-
-That's it!  All that remains is to build it; put the above code in a
-file called \file{noddy.c} and
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-setup(name="noddy", version="1.0",
-      ext_modules=[Extension("noddy", ["noddy.c"])])
-\end{verbatim}
-
-in a file called \file{setup.py}; then typing
-
-\begin{verbatim}
-$ python setup.py build
-\end{verbatim} %$ <-- bow to font-lock  ;-(
-
-at a shell should produce a file \file{noddy.so} in a subdirectory;
-move to that directory and fire up Python --- you should be able to
-\code{import noddy} and play around with Noddy objects.
-
-That wasn't so hard, was it?
-
-Of course, the current Noddy type is pretty uninteresting. It has no
-data and doesn't do anything. It can't even be subclassed.
-
-\subsection{Adding data and methods to the Basic example}
-
-Let's expend the basic example to add some data and methods.  Let's
-also make the type usable as a base class. We'll create
-a new module, \module{noddy2} that adds these capabilities:
-
-\verbatiminput{noddy2.c}
-
-This version of the module has a number of changes.
-
-We've added an extra include:
-
-\begin{verbatim}
-#include "structmember.h"
-\end{verbatim}
-
-This include provides declarations that we use to handle attributes,
-as described a bit later.
-
-The name of the \class{Noddy} object structure has been shortened to
-\class{Noddy}.  The type object name has been shortened to
-\class{NoddyType}.
-
-The  \class{Noddy} type now has three data attributes, \var{first},
-\var{last}, and \var{number}.  The \var{first} and \var{last}
-variables are Python strings containing first and last names. The
-\var{number} attribute is an integer.
-
-The object structure is updated accordingly:
-
-\begin{verbatim}
-typedef struct {
-    PyObject_HEAD
-    PyObject *first;
-    PyObject *last;
-    int number;
-} Noddy;
-\end{verbatim}
-
-Because we now have data to manage, we have to be more careful about
-object allocation and deallocation.  At a minimum, we need a
-deallocation method:
-
-\begin{verbatim}
-static void
-Noddy_dealloc(Noddy* self)
-{
-    Py_XDECREF(self->first);
-    Py_XDECREF(self->last);
-    self->ob_type->tp_free((PyObject*)self);
-}
-\end{verbatim}
-
-which is assigned to the \member{tp_dealloc} member:
-
-\begin{verbatim}
-    (destructor)Noddy_dealloc, /*tp_dealloc*/
-\end{verbatim}
-
-This method decrements the reference counts of the two Python
-attributes. We use \cfunction{Py_XDECREF()} here because the
-\member{first} and \member{last} members could be \NULL.  It then
-calls the \member{tp_free} member of the object's type to free the
-object's memory.  Note that the object's type might not be
-\class{NoddyType}, because the object may be an instance of a
-subclass.
-
-We want to make sure that the first and last names are initialized to
-empty strings, so we provide a new method:
-
-\begin{verbatim}
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
-    Noddy *self;
-
-    self = (Noddy *)type->tp_alloc(type, 0);
-    if (self != NULL) {
-        self->first = PyString_FromString("");
-        if (self->first == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-
-        self->last = PyString_FromString("");
-        if (self->last == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-
-        self->number = 0;
-    }
-
-    return (PyObject *)self;
-}
-\end{verbatim}
-
-and install it in the \member{tp_new} member:
-
-\begin{verbatim}
-    Noddy_new,                 /* tp_new */
-\end{verbatim}
-
-The new member is responsible for creating (as opposed to
-initializing) objects of the type.  It is exposed in Python as the
-\method{__new__()} method.  See the paper titled ``Unifying types and
-classes in Python'' for a detailed discussion of the \method{__new__()}
-method.  One reason to implement a new method is to assure the initial
-values of instance variables.  In this case, we use the new method to
-make sure that the initial values of the members \member{first} and
-\member{last} are not \NULL. If we didn't care whether the initial
-values were \NULL, we could have used \cfunction{PyType_GenericNew()} as
-our new method, as we did before.  \cfunction{PyType_GenericNew()}
-initializes all of the instance variable members to \NULL.
-
-The new method is a static method that is passed the type being
-instantiated and any arguments passed when the type was called,
-and that returns the new object created. New methods always accept
-positional and keyword arguments, but they often ignore the arguments,
-leaving the argument handling to initializer methods. Note that if the
-type supports subclassing, the type passed may not be the type being
-defined.  The new method calls the tp_alloc slot to allocate memory.
-We don't fill the \member{tp_alloc} slot ourselves. Rather
-\cfunction{PyType_Ready()} fills it for us by inheriting it from our
-base class, which is \class{object} by default.  Most types use the
-default allocation.
-
-\note{If you are creating a co-operative \member{tp_new} (one that
-calls a base type's \member{tp_new} or \method{__new__}), you
-must \emph{not} try to determine what method to call using
-method resolution order at runtime.  Always statically determine
-what type you are going to call, and call its \member{tp_new}
-directly, or via \code{type->tp_base->tp_new}.  If you do
-not do this, Python subclasses of your type that also inherit
-from other Python-defined classes may not work correctly.
-(Specifically, you may not be able to create instances of
-such subclasses without getting a \exception{TypeError}.)}
-
-We provide an initialization function:
-
-\begin{verbatim}
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
-    PyObject *first=NULL, *last=NULL, *tmp;
-
-    static char *kwlist[] = {"first", "last", "number", NULL};
-
-    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
-                                      &first, &last,
-                                      &self->number))
-        return -1;
-
-    if (first) {
-        tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
-        Py_XDECREF(tmp);
-    }
-
-    if (last) {
-        tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
-        Py_XDECREF(tmp);
-    }
-
-    return 0;
-}
-\end{verbatim}
-
-by filling the \member{tp_init} slot.
-
-\begin{verbatim}
-    (initproc)Noddy_init,         /* tp_init */
-\end{verbatim}
-
-The \member{tp_init} slot is exposed in Python as the
-\method{__init__()} method. It is used to initialize an object after
-it's created. Unlike the new method, we can't guarantee that the
-initializer is called.  The initializer isn't called when unpickling
-objects and it can be overridden.  Our initializer accepts arguments
-to provide initial values for our instance. Initializers always accept
-positional and keyword arguments.
-
-Initializers can be called multiple times.  Anyone can call the
-\method{__init__()} method on our objects.  For this reason, we have
-to be extra careful when assigning the new values.  We might be
-tempted, for example to assign the \member{first} member like this:
-
-\begin{verbatim}
-    if (first) {
-        Py_XDECREF(self->first);
-        Py_INCREF(first);
-        self->first = first;
-    }
-\end{verbatim}
-
-But this would be risky.  Our type doesn't restrict the type of the
-\member{first} member, so it could be any kind of object.  It could
-have a destructor that causes code to be executed that tries to
-access the \member{first} member.  To be paranoid and protect
-ourselves against this possibility, we almost always reassign members
-before decrementing their reference counts.  When don't we have to do
-this?
-\begin{itemize}
-\item when we absolutely know that the reference count is greater than
-  1
-\item when we know that deallocation of the object\footnote{This is
-  true when we know that the object is a basic type, like a string or
-  a float.} will not cause any
-  calls back into our type's code
-\item when decrementing a reference count in a \member{tp_dealloc}
-  handler when garbage-collections is not supported\footnote{We relied
-  on this in the \member{tp_dealloc} handler in this example, because
-  our type doesn't support garbage collection. Even if a type supports
-  garbage collection, there are calls that can be made to ``untrack''
-  the object from garbage collection, however, these calls are
-  advanced and not covered here.}
-\end{itemize}
-
-
-We want to want to expose our instance variables as attributes. There
-are a number of ways to do that. The simplest way is to define member
-definitions:
-
-\begin{verbatim}
-static PyMemberDef Noddy_members[] = {
-    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
-     "first name"},
-    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
-     "last name"},
-    {"number", T_INT, offsetof(Noddy, number), 0,
-     "noddy number"},
-    {NULL}  /* Sentinel */
-};
-\end{verbatim}
-
-and put the definitions in the \member{tp_members} slot:
-
-\begin{verbatim}
-    Noddy_members,             /* tp_members */
-\end{verbatim}
-
-Each member definition has a member name, type, offset, access flags
-and documentation string. See the ``Generic Attribute Management''
-section below for details.
-
-A disadvantage of this approach is that it doesn't provide a way to
-restrict the types of objects that can be assigned to the Python
-attributes.  We expect the first and last names to be strings, but any
-Python objects can be assigned.  Further, the attributes can be
-deleted, setting the C pointers to \NULL.  Even though we can make
-sure the members are initialized to non-\NULL{} values, the members can
-be set to \NULL{} if the attributes are deleted.
-
-We define a single method, \method{name}, that outputs the objects
-name as the concatenation of the first and last names.
-
-\begin{verbatim}
-static PyObject *
-Noddy_name(Noddy* self)
-{
-    static PyObject *format = NULL;
-    PyObject *args, *result;
-
-    if (format == NULL) {
-        format = PyString_FromString("%s %s");
-        if (format == NULL)
-            return NULL;
-    }
-
-    if (self->first == NULL) {
-        PyErr_SetString(PyExc_AttributeError, "first");
-        return NULL;
-    }
-
-    if (self->last == NULL) {
-        PyErr_SetString(PyExc_AttributeError, "last");
-        return NULL;
-    }
-
-    args = Py_BuildValue("OO", self->first, self->last);
-    if (args == NULL)
-        return NULL;
-
-    result = PyString_Format(format, args);
-    Py_DECREF(args);
-
-    return result;
-}
-\end{verbatim}
-
-The method is implemented as a C function that takes a \class{Noddy} (or
-\class{Noddy} subclass) instance as the first argument.  Methods
-always take an instance as the first argument. Methods often take
-positional and keyword arguments as well, but in this cased we don't
-take any and don't need to accept a positional argument tuple or
-keyword argument dictionary. This method is equivalent to the Python
-method:
-
-\begin{verbatim}
-    def name(self):
-       return "%s %s" % (self.first, self.last)
-\end{verbatim}
-
-Note that we have to check for the possibility that our \member{first}
-and \member{last} members are \NULL.  This is because they can be
-deleted, in which case they are set to \NULL.  It would be better to
-prevent deletion of these attributes and to restrict the attribute
-values to be strings.  We'll see how to do that in the next section.
-
-Now that we've defined the method, we need to create an array of
-method definitions:
-
-\begin{verbatim}
-static PyMethodDef Noddy_methods[] = {
-    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
-     "Return the name, combining the first and last name"
-    },
-    {NULL}  /* Sentinel */
-};
-\end{verbatim}
-
-and assign them to the \member{tp_methods} slot:
-
-\begin{verbatim}
-    Noddy_methods,             /* tp_methods */
-\end{verbatim}
-
-Note that we used the \constant{METH_NOARGS} flag to indicate that the
-method is passed no arguments.
-
-Finally, we'll make our type usable as a base class.  We've written
-our methods carefully so far so that they don't make any assumptions
-about the type of the object being created or used, so all we need to
-do is to add the \constant{Py_TPFLAGS_BASETYPE} to our class flag
-definition:
-
-\begin{verbatim}
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
-\end{verbatim}
-
-We rename \cfunction{initnoddy()} to \cfunction{initnoddy2()}
-and update the module name passed to \cfunction{Py_InitModule3()}.
-
-Finally, we update our \file{setup.py} file to build the new module:
-
-\begin{verbatim}
-from distutils.core import setup, Extension
-setup(name="noddy", version="1.0",
-      ext_modules=[
-         Extension("noddy", ["noddy.c"]),
-         Extension("noddy2", ["noddy2.c"]),
-         ])
-\end{verbatim}
-
-\subsection{Providing finer control over data attributes}
-
-In this section, we'll provide finer control over how the
-\member{first} and \member{last} attributes are set in the
-\class{Noddy} example. In the previous version of our module, the
-instance variables \member{first} and \member{last} could be set to
-non-string values or even deleted. We want to make sure that these
-attributes always contain strings.
-
-\verbatiminput{noddy3.c}
-
-To provide greater control, over the \member{first} and \member{last}
-attributes, we'll use custom getter and setter functions.  Here are
-the functions for getting and setting the \member{first} attribute:
-
-\begin{verbatim}
-Noddy_getfirst(Noddy *self, void *closure)
-{
-    Py_INCREF(self->first);
-    return self->first;
-}
-
-static int
-Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
-{
-  if (value == NULL) {
-    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
-    return -1;
-  }
-
-  if (! PyString_Check(value)) {
-    PyErr_SetString(PyExc_TypeError,
-                    "The first attribute value must be a string");
-    return -1;
-  }
-
-  Py_DECREF(self->first);
-  Py_INCREF(value);
-  self->first = value;
-
-  return 0;
-}
-\end{verbatim}
-
-The getter function is passed a \class{Noddy} object and a
-``closure'', which is void pointer. In this case, the closure is
-ignored. (The closure supports an advanced usage in which definition
-data is passed to the getter and setter. This could, for example, be
-used to allow a single set of getter and setter functions that decide
-the attribute to get or set based on data in the closure.)
-
-The setter function is passed the \class{Noddy} object, the new value,
-and the closure. The new value may be \NULL, in which case the
-attribute is being deleted.  In our setter, we raise an error if the
-attribute is deleted or if the attribute value is not a string.
-
-We create an array of \ctype{PyGetSetDef} structures:
-
-\begin{verbatim}
-static PyGetSetDef Noddy_getseters[] = {
-    {"first",
-     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
-     "first name",
-     NULL},
-    {"last",
-     (getter)Noddy_getlast, (setter)Noddy_setlast,
-     "last name",
-     NULL},
-    {NULL}  /* Sentinel */
-};
-\end{verbatim}
-
-and register it in the \member{tp_getset} slot:
-
-\begin{verbatim}
-    Noddy_getseters,           /* tp_getset */
-\end{verbatim}
-
-to register out attribute getters and setters.
-
-The last item in a \ctype{PyGetSetDef} structure is the closure
-mentioned above. In this case, we aren't using the closure, so we just
-pass \NULL.
-
-We also remove the member definitions for these attributes:
-
-\begin{verbatim}
-static PyMemberDef Noddy_members[] = {
-    {"number", T_INT, offsetof(Noddy, number), 0,
-     "noddy number"},
-    {NULL}  /* Sentinel */
-};
-\end{verbatim}
-
-We also need to update the \member{tp_init} handler to only allow
-strings\footnote{We now know that the first and last members are strings,
-so perhaps we could be less careful about decrementing their
-reference counts, however, we accept instances of string subclasses.
-Even though deallocating normal strings won't call back into our
-objects, we can't guarantee that deallocating an instance of a string
-subclass won't. call back into out objects.} to be passed:
-
-\begin{verbatim}
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
-    PyObject *first=NULL, *last=NULL, *tmp;
-
-    static char *kwlist[] = {"first", "last", "number", NULL};
-
-    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,
-                                      &first, &last,
-                                      &self->number))
-        return -1;
-
-    if (first) {
-        tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
-        Py_DECREF(tmp);
-    }
-
-    if (last) {
-        tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
-        Py_DECREF(tmp);
-    }
-
-    return 0;
-}
-\end{verbatim}
-
-With these changes, we can assure that the \member{first} and
-\member{last} members are never \NULL{} so we can remove checks for \NULL{}
-values in almost all cases. This means that most of the
-\cfunction{Py_XDECREF()} calls can be converted to \cfunction{Py_DECREF()}
-calls. The only place we can't change these calls is in the
-deallocator, where there is the possibility that the initialization of
-these members failed in the constructor.
-
-We also rename the module initialization function and module name in
-the initialization function, as we did before, and we add an extra
-definition to the \file{setup.py} file.
-
-\subsection{Supporting cyclic garbage collection}
-
-Python has a cyclic-garbage collector that can identify unneeded
-objects even when their reference counts are not zero. This can happen
-when objects are involved in cycles.  For example, consider:
-
-\begin{verbatim}
->>> l = []
->>> l.append(l)
->>> del l
-\end{verbatim}
-
-In this example, we create a list that contains itself. When we delete
-it, it still has a reference from itself. Its reference count doesn't
-drop to zero.  Fortunately, Python's cyclic-garbage collector will
-eventually figure out that the list is garbage and free it.
-
-In the second version of the \class{Noddy} example, we allowed any
-kind of object to be stored in the \member{first} or \member{last}
-attributes.\footnote{Even in the third version, we aren't guaranteed to
-avoid cycles.  Instances of string subclasses are allowed and string
-subclasses could allow cycles even if normal strings don't.} This
-means that \class{Noddy} objects can participate in cycles:
-
-\begin{verbatim}
->>> import noddy2
->>> n = noddy2.Noddy()
->>> l = [n]
->>> n.first = l
-\end{verbatim}
-
-This is pretty silly, but it gives us an excuse to add support for the
-cyclic-garbage collector to the \class{Noddy} example.  To support
-cyclic garbage collection, types need to fill two slots and set a
-class flag that enables these slots:
-
-\verbatiminput{noddy4.c}
-
-The traversal method provides access to subobjects that
-could participate in cycles:
-
-\begin{verbatim}
-static int
-Noddy_traverse(Noddy *self, visitproc visit, void *arg)
-{
-    int vret;
-
-    if (self->first) {
-        vret = visit(self->first, arg);
-        if (vret != 0)
-            return vret;
-    }
-    if (self->last) {
-        vret = visit(self->last, arg);
-        if (vret != 0)
-            return vret;
-    }
-
-    return 0;
-}
-\end{verbatim}
-
-For each subobject that can participate in cycles, we need to call the
-\cfunction{visit()} function, which is passed to the traversal method.
-The \cfunction{visit()} function takes as arguments the subobject and
-the extra argument \var{arg} passed to the traversal method.  It
-returns an integer value that must be returned if it is non-zero.
-
-
-Python 2.4 and higher provide a \cfunction{Py_VISIT()} macro that automates
-calling visit functions.  With \cfunction{Py_VISIT()},
-\cfunction{Noddy_traverse()} can be simplified:
-
-
-\begin{verbatim}
-static int
-Noddy_traverse(Noddy *self, visitproc visit, void *arg)
-{
-    Py_VISIT(self->first);
-    Py_VISIT(self->last);
-    return 0;
-}
-\end{verbatim}
-
-\note{Note that the \member{tp_traverse} implementation must name its
-    arguments exactly \var{visit} and \var{arg} in order to use
-    \cfunction{Py_VISIT()}.  This is to encourage uniformity
-    across these boring implementations.}
-
-We also need to provide a method for clearing any subobjects that can
-participate in cycles.  We implement the method and reimplement the
-deallocator to use it:
-
-\begin{verbatim}
-static int
-Noddy_clear(Noddy *self)
-{
-    PyObject *tmp;
-
-    tmp = self->first;
-    self->first = NULL;
-    Py_XDECREF(tmp);
-
-    tmp = self->last;
-    self->last = NULL;
-    Py_XDECREF(tmp);
-
-    return 0;
-}
-
-static void
-Noddy_dealloc(Noddy* self)
-{
-    Noddy_clear(self);
-    self->ob_type->tp_free((PyObject*)self);
-}
-\end{verbatim}
-
-Notice the use of a temporary variable in \cfunction{Noddy_clear()}.
-We use the temporary variable so that we can set each member to \NULL{}
-before decrementing its reference count.  We do this because, as was
-discussed earlier, if the reference count drops to zero, we might
-cause code to run that calls back into the object.  In addition,
-because we now support garbage collection, we also have to worry about
-code being run that triggers garbage collection.  If garbage
-collection is run, our \member{tp_traverse} handler could get called.
-We can't take a chance of having \cfunction{Noddy_traverse()} called
-when a member's reference count has dropped to zero and its value
-hasn't been set to \NULL.
-
-Python 2.4 and higher provide a \cfunction{Py_CLEAR()} that automates
-the careful decrementing of reference counts.  With
-\cfunction{Py_CLEAR()}, the \cfunction{Noddy_clear()} function can be
-simplified:
-
-\begin{verbatim}
-static int
-Noddy_clear(Noddy *self)
-{
-    Py_CLEAR(self->first);
-    Py_CLEAR(self->last);
-    return 0;
-}
-\end{verbatim}
-
-Finally, we add the \constant{Py_TPFLAGS_HAVE_GC} flag to the class
-flags:
-
-\begin{verbatim}
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
-\end{verbatim}
-
-That's pretty much it.  If we had written custom \member{tp_alloc} or
-\member{tp_free} slots, we'd need to modify them for cyclic-garbage
-collection. Most extensions will use the versions automatically
-provided.
-
-\subsection{Subclassing other types}
-
-It is possible to create new extension types that are derived from existing
-types. It is easiest to inherit from the built in types, since an extension
-can easily use the \class{PyTypeObject} it needs. It can be difficult to
-share these \class{PyTypeObject} structures between extension modules.
-
-In this example we will create a \class{Shoddy} type that inherits from
-the builtin \class{list} type. The new type will be completely compatible
-with regular lists, but will have an additional \method{increment()} method
-that increases an internal counter.
-
-\begin{verbatim}
->>> import shoddy
->>> s = shoddy.Shoddy(range(3))
->>> s.extend(s)
->>> print len(s)
-6
->>> print s.increment()
-1
->>> print s.increment()
-2
-\end{verbatim}
-
-\verbatiminput{shoddy.c}
-
-As you can see, the source code closely resembles the \class{Noddy} examples in previous
-sections. We will break down the main differences between them.
-
-\begin{verbatim}
-typedef struct {
-	PyListObject list;
-	int state;
-} Shoddy;
-\end{verbatim}
-
-The primary difference for derived type objects is that the base type's
-object structure must be the first value. The base type will already
-include the \cfunction{PyObject_HEAD} at the beginning of its structure.
-
-When a Python object is a \class{Shoddy} instance, its \var{PyObject*} pointer
-can be safely cast to both \var{PyListObject*} and \var{Shoddy*}.
-
-\begin{verbatim}
-static int
-Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
-{
-	if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
-		return -1;
-	self->state = 0;
-	return 0;
-}
-\end{verbatim}
-
-In the \member{__init__} method for our type, we can see how to call through
-to the \member{__init__} method of the base type.
-
-This pattern is important when writing a type with custom \member{new} and
-\member{dealloc} methods. The \member{new} method should not actually create the
-memory for the object with \member{tp_alloc}, that will be handled by
-the base class when calling its \member{tp_new}.
-
-When filling out the \cfunction{PyTypeObject} for the \class{Shoddy} type,
-you see a slot for \cfunction{tp_base}. Due to cross platform compiler
-issues, you can't fill that field directly with the \cfunction{PyList_Type};
-it can be done later in the module's \cfunction{init} function.
-
-\begin{verbatim}
-PyMODINIT_FUNC
-initshoddy(void)
-{
-	PyObject *m;
-
-	ShoddyType.tp_base = &PyList_Type;
-	if (PyType_Ready(&ShoddyType) < 0)
-		return;
-
-	m = Py_InitModule3("shoddy", NULL, "Shoddy module");
-	if (m == NULL)
-		return;
-
-	Py_INCREF(&ShoddyType);
-	PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
-}
-\end{verbatim}
-
-Before calling \cfunction{PyType_Ready}, the type structure must have the
-\member{tp_base} slot filled in. When we are deriving a new type, it is
-not necessary to fill out the \member{tp_alloc} slot with
-\cfunction{PyType_GenericNew} -- the allocate function from the base type
-will be inherited.
-
-After that, calling \cfunction{PyType_Ready} and adding the type object
-to the module is the same as with the basic \class{Noddy} examples.
-
-
-\section{Type Methods
-         \label{dnt-type-methods}}
-
-This section aims to give a quick fly-by on the various type methods
-you can implement and what they do.
-
-Here is the definition of \ctype{PyTypeObject}, with some fields only
-used in debug builds omitted:
-
-\verbatiminput{typestruct.h}
-
-Now that's a \emph{lot} of methods.  Don't worry too much though - if
-you have a type you want to define, the chances are very good that you
-will only implement a handful of these.
-
-As you probably expect by now, we're going to go over this and give
-more information about the various handlers.  We won't go in the order
-they are defined in the structure, because there is a lot of
-historical baggage that impacts the ordering of the fields; be sure
-your type initialization keeps the fields in the right order!  It's
-often easiest to find an example that includes all the fields you need
-(even if they're initialized to \code{0}) and then change the values
-to suit your new type.
-
-\begin{verbatim}
-    char *tp_name; /* For printing */
-\end{verbatim}
-
-The name of the type - as mentioned in the last section, this will
-appear in various places, almost entirely for diagnostic purposes.
-Try to choose something that will be helpful in such a situation!
-
-\begin{verbatim}
-    int tp_basicsize, tp_itemsize; /* For allocation */
-\end{verbatim}
-
-These fields tell the runtime how much memory to allocate when new
-objects of this type are created.  Python has some built-in support
-for variable length structures (think: strings, lists) which is where
-the \member{tp_itemsize} field comes in.  This will be dealt with
-later.
-
-\begin{verbatim}
-    char *tp_doc;
-\end{verbatim}
-
-Here you can put a string (or its address) that you want returned when
-the Python script references \code{obj.__doc__} to retrieve the
-doc string.
-
-Now we come to the basic type methods---the ones most extension types
-will implement.
-
-
-\subsection{Finalization and De-allocation}
-
-\index{object!deallocation}
-\index{deallocation, object}
-\index{object!finalization}
-\index{finalization, of objects}
-
-\begin{verbatim}
-    destructor tp_dealloc;
-\end{verbatim}
-
-This function is called when the reference count of the instance of
-your type is reduced to zero and the Python interpreter wants to
-reclaim it.  If your type has memory to free or other clean-up to
-perform, put it here.  The object itself needs to be freed here as
-well.  Here is an example of this function:
-
-\begin{verbatim}
-static void
-newdatatype_dealloc(newdatatypeobject * obj)
-{
-    free(obj->obj_UnderlyingDatatypePtr);
-    obj->ob_type->tp_free(obj);
-}
-\end{verbatim}
-
-One important requirement of the deallocator function is that it
-leaves any pending exceptions alone.  This is important since
-deallocators are frequently called as the interpreter unwinds the
-Python stack; when the stack is unwound due to an exception (rather
-than normal returns), nothing is done to protect the deallocators from
-seeing that an exception has already been set.  Any actions which a
-deallocator performs which may cause additional Python code to be
-executed may detect that an exception has been set.  This can lead to
-misleading errors from the interpreter.  The proper way to protect
-against this is to save a pending exception before performing the
-unsafe action, and restoring it when done.  This can be done using the
-\cfunction{PyErr_Fetch()}\ttindex{PyErr_Fetch()} and
-\cfunction{PyErr_Restore()}\ttindex{PyErr_Restore()} functions:
-
-\begin{verbatim}
-static void
-my_dealloc(PyObject *obj)
-{
-    MyObject *self = (MyObject *) obj;
-    PyObject *cbresult;
-
-    if (self->my_callback != NULL) {
-        PyObject *err_type, *err_value, *err_traceback;
-        int have_error = PyErr_Occurred() ? 1 : 0;
-
-        if (have_error)
-            PyErr_Fetch(&err_type, &err_value, &err_traceback);
-
-        cbresult = PyObject_CallObject(self->my_callback, NULL);
-        if (cbresult == NULL)
-            PyErr_WriteUnraisable(self->my_callback);
-        else
-            Py_DECREF(cbresult);
-
-        if (have_error)
-            PyErr_Restore(err_type, err_value, err_traceback);
-
-        Py_DECREF(self->my_callback);
-    }
-    obj->ob_type->tp_free((PyObject*)self);
-}
-\end{verbatim}
-
-
-\subsection{Object Presentation}
-
-In Python, there are three ways to generate a textual representation
-of an object: the \function{repr()}\bifuncindex{repr} function (or
-equivalent back-tick syntax), the \function{str()}\bifuncindex{str}
-function, and the \keyword{print} statement.  For most objects, the
-\keyword{print} statement is equivalent to the \function{str()}
-function, but it is possible to special-case printing to a
-\ctype{FILE*} if necessary; this should only be done if efficiency is
-identified as a problem and profiling suggests that creating a
-temporary string object to be written to a file is too expensive.
-
-These handlers are all optional, and most types at most need to
-implement the \member{tp_str} and \member{tp_repr} handlers.
-
-\begin{verbatim}
-    reprfunc tp_repr;
-    reprfunc tp_str;
-    printfunc tp_print;
-\end{verbatim}
-
-The \member{tp_repr} handler should return a string object containing
-a representation of the instance for which it is called.  Here is a
-simple example:
-
-\begin{verbatim}
-static PyObject *
-newdatatype_repr(newdatatypeobject * obj)
-{
-    return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
-                               obj->obj_UnderlyingDatatypePtr->size);
-}
-\end{verbatim}
-
-If no \member{tp_repr} handler is specified, the interpreter will
-supply a representation that uses the type's \member{tp_name} and a
-uniquely-identifying value for the object.
-
-The \member{tp_str} handler is to \function{str()} what the
-\member{tp_repr} handler described above is to \function{repr()}; that
-is, it is called when Python code calls \function{str()} on an
-instance of your object.  Its implementation is very similar to the
-\member{tp_repr} function, but the resulting string is intended for
-human consumption.  If \member{tp_str} is not specified, the
-\member{tp_repr} handler is used instead.
-
-Here is a simple example:
-
-\begin{verbatim}
-static PyObject *
-newdatatype_str(newdatatypeobject * obj)
-{
-    return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
-                               obj->obj_UnderlyingDatatypePtr->size);
-}
-\end{verbatim}
-
-The print function will be called whenever Python needs to "print" an
-instance of the type.  For example, if 'node' is an instance of type
-TreeNode, then the print function is called when Python code calls:
-
-\begin{verbatim}
-print node
-\end{verbatim}
-
-There is a flags argument and one flag, \constant{Py_PRINT_RAW}, and
-it suggests that you print without string quotes and possibly without
-interpreting escape sequences.
-
-The print function receives a file object as an argument. You will
-likely want to write to that file object.
-
-Here is a sample print function:
-
-\begin{verbatim}
-static int
-newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
-{
-    if (flags & Py_PRINT_RAW) {
-        fprintf(fp, "<{newdatatype object--size: %d}>",
-                obj->obj_UnderlyingDatatypePtr->size);
-    }
-    else {
-        fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
-                obj->obj_UnderlyingDatatypePtr->size);
-    }
-    return 0;
-}
-\end{verbatim}
-
-
-\subsection{Attribute Management}
-
-For every object which can support attributes, the corresponding type
-must provide the functions that control how the attributes are
-resolved.  There needs to be a function which can retrieve attributes
-(if any are defined), and another to set attributes (if setting
-attributes is allowed).  Removing an attribute is a special case, for
-which the new value passed to the handler is \NULL.
-
-Python supports two pairs of attribute handlers; a type that supports
-attributes only needs to implement the functions for one pair.  The
-difference is that one pair takes the name of the attribute as a
-\ctype{char*}, while the other accepts a \ctype{PyObject*}.  Each type
-can use whichever pair makes more sense for the implementation's
-convenience.
-
-\begin{verbatim}
-    getattrfunc  tp_getattr;        /* char * version */
-    setattrfunc  tp_setattr;
-    /* ... */
-    getattrofunc tp_getattrofunc;   /* PyObject * version */
-    setattrofunc tp_setattrofunc;
-\end{verbatim}
-
-If accessing attributes of an object is always a simple operation
-(this will be explained shortly), there are generic implementations
-which can be used to provide the \ctype{PyObject*} version of the
-attribute management functions.  The actual need for type-specific
-attribute handlers almost completely disappeared starting with Python
-2.2, though there are many examples which have not been updated to use
-some of the new generic mechanism that is available.
-
-
-\subsubsection{Generic Attribute Management}
-
-\versionadded{2.2}
-
-Most extension types only use \emph{simple} attributes.  So, what
-makes the attributes simple?  There are only a couple of conditions
-that must be met:
-
-\begin{enumerate}
-  \item   The name of the attributes must be known when
-          \cfunction{PyType_Ready()} is called.
-
-  \item   No special processing is needed to record that an attribute
-          was looked up or set, nor do actions need to be taken based
-          on the value.
-\end{enumerate}
-
-Note that this list does not place any restrictions on the values of
-the attributes, when the values are computed, or how relevant data is
-stored.
-
-When \cfunction{PyType_Ready()} is called, it uses three tables
-referenced by the type object to create \emph{descriptors} which are
-placed in the dictionary of the type object.  Each descriptor controls
-access to one attribute of the instance object.  Each of the tables is
-optional; if all three are \NULL, instances of the type will only have
-attributes that are inherited from their base type, and should leave
-the \member{tp_getattro} and \member{tp_setattro} fields \NULL{} as
-well, allowing the base type to handle attributes.
-
-The tables are declared as three fields of the type object:
-
-\begin{verbatim}
-    struct PyMethodDef *tp_methods;
-    struct PyMemberDef *tp_members;
-    struct PyGetSetDef *tp_getset;
-\end{verbatim}
-
-If \member{tp_methods} is not \NULL, it must refer to an array of
-\ctype{PyMethodDef} structures.  Each entry in the table is an
-instance of this structure:
-
-\begin{verbatim}
-typedef struct PyMethodDef {
-    char        *ml_name;       /* method name */
-    PyCFunction  ml_meth;       /* implementation function */
-    int	         ml_flags;      /* flags */
-    char        *ml_doc;        /* docstring */
-} PyMethodDef;
-\end{verbatim}
-
-One entry should be defined for each method provided by the type; no
-entries are needed for methods inherited from a base type.  One
-additional entry is needed at the end; it is a sentinel that marks the
-end of the array.  The \member{ml_name} field of the sentinel must be
-\NULL.
-
-XXX Need to refer to some unified discussion of the structure fields,
-shared with the next section.
-
-The second table is used to define attributes which map directly to
-data stored in the instance.  A variety of primitive C types are
-supported, and access may be read-only or read-write.  The structures
-in the table are defined as:
-
-\begin{verbatim}
-typedef struct PyMemberDef {
-    char *name;
-    int   type;
-    int   offset;
-    int   flags;
-    char *doc;
-} PyMemberDef;
-\end{verbatim}
-
-For each entry in the table, a descriptor will be constructed and
-added to the type which will be able to extract a value from the
-instance structure.  The \member{type} field should contain one of the
-type codes defined in the \file{structmember.h} header; the value will
-be used to determine how to convert Python values to and from C
-values.  The \member{flags} field is used to store flags which control
-how the attribute can be accessed.
-
-XXX Need to move some of this to a shared section!
-
-The following flag constants are defined in \file{structmember.h};
-they may be combined using bitwise-OR.
-
-\begin{tableii}{l|l}{constant}{Constant}{Meaning}
-  \lineii{READONLY \ttindex{READONLY}}
-         {Never writable.}
-  \lineii{RO \ttindex{RO}}
-         {Shorthand for \constant{READONLY}.}
-  \lineii{READ_RESTRICTED \ttindex{READ_RESTRICTED}}
-         {Not readable in restricted mode.}
-  \lineii{WRITE_RESTRICTED \ttindex{WRITE_RESTRICTED}}
-         {Not writable in restricted mode.}
-  \lineii{RESTRICTED \ttindex{RESTRICTED}}
-         {Not readable or writable in restricted mode.}
-\end{tableii}
-
-An interesting advantage of using the \member{tp_members} table to
-build descriptors that are used at runtime is that any attribute
-defined this way can have an associated doc string simply by providing
-the text in the table.  An application can use the introspection API
-to retrieve the descriptor from the class object, and get the
-doc string using its \member{__doc__} attribute.
-
-As with the \member{tp_methods} table, a sentinel entry with a
-\member{name} value of \NULL{} is required.
-
-
-% XXX Descriptors need to be explained in more detail somewhere, but
-% not here.
-%
-% Descriptor objects have two handler functions which correspond to
-% the \member{tp_getattro} and \member{tp_setattro} handlers.  The
-% \method{__get__()} handler is a function which is passed the
-% descriptor, instance, and type objects, and returns the value of the
-% attribute, or it returns \NULL{} and sets an exception.  The
-% \method{__set__()} handler is passed the descriptor, instance, type,
-% and new value;
-
-
-\subsubsection{Type-specific Attribute Management}
-
-For simplicity, only the \ctype{char*} version will be demonstrated
-here; the type of the name parameter is the only difference between
-the \ctype{char*} and \ctype{PyObject*} flavors of the interface.
-This example effectively does the same thing as the generic example
-above, but does not use the generic support added in Python 2.2.  The
-value in showing this is two-fold: it demonstrates how basic attribute
-management can be done in a way that is portable to older versions of
-Python, and explains how the handler functions are called, so that if
-you do need to extend their functionality, you'll understand what
-needs to be done.
-
-The \member{tp_getattr} handler is called when the object requires an
-attribute look-up.  It is called in the same situations where the
-\method{__getattr__()} method of a class would be called.
-
-A likely way to handle this is (1) to implement a set of functions
-(such as \cfunction{newdatatype_getSize()} and
-\cfunction{newdatatype_setSize()} in the example below), (2) provide a
-method table listing these functions, and (3) provide a getattr
-function that returns the result of a lookup in that table.  The
-method table uses the same structure as the \member{tp_methods} field
-of the type object.
-
-Here is an example:
-
-\begin{verbatim}
-static PyMethodDef newdatatype_methods[] = {
-    {"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS,
-     "Return the current size."},
-    {"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS,
-     "Set the size."},
-    {NULL, NULL, 0, NULL}           /* sentinel */
-};
-
-static PyObject *
-newdatatype_getattr(newdatatypeobject *obj, char *name)
-{
-    return Py_FindMethod(newdatatype_methods, (PyObject *)obj, name);
-}
-\end{verbatim}
-
-The \member{tp_setattr} handler is called when the
-\method{__setattr__()} or \method{__delattr__()} method of a class
-instance would be called.  When an attribute should be deleted, the
-third parameter will be \NULL.  Here is an example that simply raises
-an exception; if this were really all you wanted, the
-\member{tp_setattr} handler should be set to \NULL.
-
-\begin{verbatim}
-static int
-newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
-{
-    (void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
-    return -1;
-}
-\end{verbatim}
-
-
-\subsection{Object Comparison}
-
-\begin{verbatim}
-    cmpfunc tp_compare;
-\end{verbatim}
-
-The \member{tp_compare} handler is called when comparisons are needed
-and the object does not implement the specific rich comparison method
-which matches the requested comparison.  (It is always used if defined
-and the \cfunction{PyObject_Compare()} or \cfunction{PyObject_Cmp()}
-functions are used, or if \function{cmp()} is used from Python.)
-It is analogous to the \method{__cmp__()} method.  This function
-should return \code{-1} if \var{obj1} is less than
-\var{obj2}, \code{0} if they are equal, and \code{1} if
-\var{obj1} is greater than
-\var{obj2}.
-(It was previously allowed to return arbitrary negative or positive
-integers for less than and greater than, respectively; as of Python
-2.2, this is no longer allowed.  In the future, other return values
-may be assigned a different meaning.)
-
-A \member{tp_compare} handler may raise an exception.  In this case it
-should return a negative value.  The caller has to test for the
-exception using \cfunction{PyErr_Occurred()}.
-
-
-Here is a sample implementation:
-
-\begin{verbatim}
-static int
-newdatatype_compare(newdatatypeobject * obj1, newdatatypeobject * obj2)
-{
-    long result;
-
-    if (obj1->obj_UnderlyingDatatypePtr->size <
-        obj2->obj_UnderlyingDatatypePtr->size) {
-        result = -1;
-    }
-    else if (obj1->obj_UnderlyingDatatypePtr->size >
-             obj2->obj_UnderlyingDatatypePtr->size) {
-        result = 1;
-    }
-    else {
-        result = 0;
-    }
-    return result;
-}
-\end{verbatim}
-
-
-\subsection{Abstract Protocol Support}
-
-Python supports a variety of \emph{abstract} `protocols;' the specific
-interfaces provided to use these interfaces are documented in the
-\citetitle[../api/api.html]{Python/C API Reference Manual} in the
-chapter ``\ulink{Abstract Objects Layer}{../api/abstract.html}.''
-
-A number of these abstract interfaces were defined early in the
-development of the Python implementation.  In particular, the number,
-mapping, and sequence protocols have been part of Python since the
-beginning.  Other protocols have been added over time.  For protocols
-which depend on several handler routines from the type implementation,
-the older protocols have been defined as optional blocks of handlers
-referenced by the type object.  For newer protocols there are
-additional slots in the main type object, with a flag bit being set to
-indicate that the slots are present and should be checked by the
-interpreter.  (The flag bit does not indicate that the slot values are
-non-\NULL. The flag may be set to indicate the presence of a slot,
-but a slot may still be unfilled.)
-
-\begin{verbatim}
-    PyNumberMethods   tp_as_number;
-    PySequenceMethods tp_as_sequence;
-    PyMappingMethods  tp_as_mapping;
-\end{verbatim}
-
-If you wish your object to be able to act like a number, a sequence,
-or a mapping object, then you place the address of a structure that
-implements the C type \ctype{PyNumberMethods},
-\ctype{PySequenceMethods}, or \ctype{PyMappingMethods}, respectively.
-It is up to you to fill in this structure with appropriate values. You
-can find examples of the use of each of these in the \file{Objects}
-directory of the Python source distribution.
-
-
-\begin{verbatim}
-    hashfunc tp_hash;
-\end{verbatim}
-
-This function, if you choose to provide it, should return a hash
-number for an instance of your data type. Here is a moderately
-pointless example:
-
-\begin{verbatim}
-static long
-newdatatype_hash(newdatatypeobject *obj)
-{
-    long result;
-    result = obj->obj_UnderlyingDatatypePtr->size;
-    result = result * 3;
-    return result;
-}
-\end{verbatim}
-
-\begin{verbatim}
-    ternaryfunc tp_call;
-\end{verbatim}
-
-This function is called when an instance of your data type is "called",
-for example, if \code{obj1} is an instance of your data type and the Python
-script contains \code{obj1('hello')}, the \member{tp_call} handler is
-invoked.
-
-This function takes three arguments:
-
-\begin{enumerate}
-  \item
-    \var{arg1} is the instance of the data type which is the subject of
-    the call. If the call is \code{obj1('hello')}, then \var{arg1} is
-    \code{obj1}.
-
-  \item
-    \var{arg2} is a tuple containing the arguments to the call.  You
-    can use \cfunction{PyArg_ParseTuple()} to extract the arguments.
-
-  \item
-    \var{arg3} is a dictionary of keyword arguments that were passed.
-    If this is non-\NULL{} and you support keyword arguments, use
-    \cfunction{PyArg_ParseTupleAndKeywords()} to extract the
-    arguments.  If you do not want to support keyword arguments and
-    this is non-\NULL, raise a \exception{TypeError} with a message
-    saying that keyword arguments are not supported.
-\end{enumerate}
-
-Here is a desultory example of the implementation of the call function.
-
-\begin{verbatim}
-/* Implement the call function.
- *    obj1 is the instance receiving the call.
- *    obj2 is a tuple containing the arguments to the call, in this
- *         case 3 strings.
- */
-static PyObject *
-newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
-{
-    PyObject *result;
-    char *arg1;
-    char *arg2;
-    char *arg3;
-
-    if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
-        return NULL;
-    }
-    result = PyString_FromFormat(
-        "Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n",
-        obj->obj_UnderlyingDatatypePtr->size,
-        arg1, arg2, arg3);
-    printf("\%s", PyString_AS_STRING(result));
-    return result;
-}
-\end{verbatim}
-
-XXX some fields need to be added here...
-
-
-\begin{verbatim}
-    /* Added in release 2.2 */
-    /* Iterators */
-    getiterfunc tp_iter;
-    iternextfunc tp_iternext;
-\end{verbatim}
-
-These functions provide support for the iterator protocol.  Any object
-which wishes to support iteration over its contents (which may be
-generated during iteration) must implement the \code{tp_iter}
-handler.  Objects which are returned by a \code{tp_iter} handler must
-implement both the \code{tp_iter} and \code{tp_iternext} handlers.
-Both handlers take exactly one parameter, the instance for which they
-are being called, and return a new reference.  In the case of an
-error, they should set an exception and return \NULL.
-
-For an object which represents an iterable collection, the
-\code{tp_iter} handler must return an iterator object.  The iterator
-object is responsible for maintaining the state of the iteration.  For
-collections which can support multiple iterators which do not
-interfere with each other (as lists and tuples do), a new iterator
-should be created and returned.  Objects which can only be iterated
-over once (usually due to side effects of iteration) should implement
-this handler by returning a new reference to themselves, and should
-also implement the \code{tp_iternext} handler.  File objects are an
-example of such an iterator.
-
-Iterator objects should implement both handlers.  The \code{tp_iter}
-handler should return a new reference to the iterator (this is the
-same as the \code{tp_iter} handler for objects which can only be
-iterated over destructively).  The \code{tp_iternext} handler should
-return a new reference to the next object in the iteration if there is
-one.  If the iteration has reached the end, it may return \NULL{}
-without setting an exception or it may set \exception{StopIteration};
-avoiding the exception can yield slightly better performance.  If an
-actual error occurs, it should set an exception and return \NULL.
-
-
-\subsection{Weak Reference Support\label{weakref-support}}
-
-One of the goals of Python's weak-reference implementation is to allow
-any type to participate in the weak reference mechanism without
-incurring the overhead on those objects which do not benefit by weak
-referencing (such as numbers).
-
-For an object to be weakly referencable, the extension must include a
-\ctype{PyObject*} field in the instance structure for the use of the
-weak reference mechanism; it must be initialized to \NULL{} by the
-object's constructor.  It must also set the \member{tp_weaklistoffset}
-field of the corresponding type object to the offset of the field.
-For example, the instance type is defined with the following
-structure:
-
-\begin{verbatim}
-typedef struct {
-    PyObject_HEAD
-    PyClassObject *in_class;       /* The class object */
-    PyObject      *in_dict;        /* A dictionary */
-    PyObject      *in_weakreflist; /* List of weak references */
-} PyInstanceObject;
-\end{verbatim}
-
-The statically-declared type object for instances is defined this way:
-
-\begin{verbatim}
-PyTypeObject PyInstance_Type = {
-    PyObject_HEAD_INIT(&PyType_Type)
-    0,
-    "module.instance",
-
-    /* Lots of stuff omitted for brevity... */
-
-    Py_TPFLAGS_DEFAULT,                         /* tp_flags */
-    0,                                          /* tp_doc */
-    0,                                          /* tp_traverse */
-    0,                                          /* tp_clear */
-    0,                                          /* tp_richcompare */
-    offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
-};
-\end{verbatim}
-
-The type constructor is responsible for initializing the weak reference
-list to \NULL:
-
-\begin{verbatim}
-static PyObject *
-instance_new() {
-    /* Other initialization stuff omitted for brevity */
-
-    self->in_weakreflist = NULL;
-
-    return (PyObject *) self;
-}
-\end{verbatim}
-
-The only further addition is that the destructor needs to call the
-weak reference manager to clear any weak references.  This should be
-done before any other parts of the destruction have occurred, but is
-only required if the weak reference list is non-\NULL:
-
-\begin{verbatim}
-static void
-instance_dealloc(PyInstanceObject *inst)
-{
-    /* Allocate temporaries if needed, but do not begin
-       destruction just yet.
-     */
-
-    if (inst->in_weakreflist != NULL)
-        PyObject_ClearWeakRefs((PyObject *) inst);
-
-    /* Proceed with object destruction normally. */
-}
-\end{verbatim}
-
-
-\subsection{More Suggestions}
-
-Remember that you can omit most of these functions, in which case you
-provide \code{0} as a value.  There are type definitions for each of
-the functions you must provide.  They are in \file{object.h} in the
-Python include directory that comes with the source distribution of
-Python.
-
-In order to learn how to implement any specific method for your new
-data type, do the following: Download and unpack the Python source
-distribution.  Go the \file{Objects} directory, then search the
-C source files for \code{tp_} plus the function you want (for
-example, \code{tp_print} or \code{tp_compare}).  You will find
-examples of the function you want to implement.
-
-When you need to verify that an object is an instance of the type
-you are implementing, use the \cfunction{PyObject_TypeCheck} function.
-A sample of its use might be something like the following:
-
-\begin{verbatim}
-    if (! PyObject_TypeCheck(some_object, &MyType)) {
-        PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
-        return NULL;
-    }
-\end{verbatim}
diff --git a/Doc/ext/noddy.c b/Doc/ext/noddy.c
deleted file mode 100644
index ec2d669..0000000
--- a/Doc/ext/noddy.c
+++ /dev/null
@@ -1,54 +0,0 @@
-#include <Python.h>
-
-typedef struct {
-    PyObject_HEAD
-    /* Type-specific fields go here. */
-} noddy_NoddyObject;
-
-static PyTypeObject noddy_NoddyType = {
-    PyObject_HEAD_INIT(NULL)
-    0,                         /*ob_size*/
-    "noddy.Noddy",             /*tp_name*/
-    sizeof(noddy_NoddyObject), /*tp_basicsize*/
-    0,                         /*tp_itemsize*/
-    0,                         /*tp_dealloc*/
-    0,                         /*tp_print*/
-    0,                         /*tp_getattr*/
-    0,                         /*tp_setattr*/
-    0,                         /*tp_compare*/
-    0,                         /*tp_repr*/
-    0,                         /*tp_as_number*/
-    0,                         /*tp_as_sequence*/
-    0,                         /*tp_as_mapping*/
-    0,                         /*tp_hash */
-    0,                         /*tp_call*/
-    0,                         /*tp_str*/
-    0,                         /*tp_getattro*/
-    0,                         /*tp_setattro*/
-    0,                         /*tp_as_buffer*/
-    Py_TPFLAGS_DEFAULT,        /*tp_flags*/
-    "Noddy objects",           /* tp_doc */
-};
-
-static PyMethodDef noddy_methods[] = {
-    {NULL}  /* Sentinel */
-};
-
-#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
-#define PyMODINIT_FUNC void
-#endif
-PyMODINIT_FUNC
-initnoddy(void) 
-{
-    PyObject* m;
-
-    noddy_NoddyType.tp_new = PyType_GenericNew;
-    if (PyType_Ready(&noddy_NoddyType) < 0)
-        return;
-
-    m = Py_InitModule3("noddy", noddy_methods,
-                       "Example module that creates an extension type.");
-
-    Py_INCREF(&noddy_NoddyType);
-    PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
-}
diff --git a/Doc/ext/noddy2.c b/Doc/ext/noddy2.c
deleted file mode 100644
index 2caf985..0000000
--- a/Doc/ext/noddy2.c
+++ /dev/null
@@ -1,190 +0,0 @@
-#include <Python.h>
-#include "structmember.h"
-
-typedef struct {
-    PyObject_HEAD
-    PyObject *first; /* first name */
-    PyObject *last;  /* last name */
-    int number;
-} Noddy;
-
-static void
-Noddy_dealloc(Noddy* self)
-{
-    Py_XDECREF(self->first);
-    Py_XDECREF(self->last);
-    self->ob_type->tp_free((PyObject*)self);
-}
-
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
-    Noddy *self;
-
-    self = (Noddy *)type->tp_alloc(type, 0);
-    if (self != NULL) {
-        self->first = PyString_FromString("");
-        if (self->first == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-        
-        self->last = PyString_FromString("");
-        if (self->last == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-
-        self->number = 0;
-    }
-
-    return (PyObject *)self;
-}
-
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
-    PyObject *first=NULL, *last=NULL, *tmp;
-
-    static char *kwlist[] = {"first", "last", "number", NULL};
-
-    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, 
-                                      &first, &last, 
-                                      &self->number))
-        return -1; 
-
-    if (first) {
-        tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
-        Py_XDECREF(tmp);
-    }
-
-    if (last) {
-        tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
-        Py_XDECREF(tmp);
-    }
-
-    return 0;
-}
-
-
-static PyMemberDef Noddy_members[] = {
-    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
-     "first name"},
-    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
-     "last name"},
-    {"number", T_INT, offsetof(Noddy, number), 0,
-     "noddy number"},
-    {NULL}  /* Sentinel */
-};
-
-static PyObject *
-Noddy_name(Noddy* self)
-{
-    static PyObject *format = NULL;
-    PyObject *args, *result;
-
-    if (format == NULL) {
-        format = PyString_FromString("%s %s");
-        if (format == NULL)
-            return NULL;
-    }
-
-    if (self->first == NULL) {
-        PyErr_SetString(PyExc_AttributeError, "first");
-        return NULL;
-    }
-
-    if (self->last == NULL) {
-        PyErr_SetString(PyExc_AttributeError, "last");
-        return NULL;
-    }
-
-    args = Py_BuildValue("OO", self->first, self->last);
-    if (args == NULL)
-        return NULL;
-
-    result = PyString_Format(format, args);
-    Py_DECREF(args);
-    
-    return result;
-}
-
-static PyMethodDef Noddy_methods[] = {
-    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
-     "Return the name, combining the first and last name"
-    },
-    {NULL}  /* Sentinel */
-};
-
-static PyTypeObject NoddyType = {
-    PyObject_HEAD_INIT(NULL)
-    0,                         /*ob_size*/
-    "noddy.Noddy",             /*tp_name*/
-    sizeof(Noddy),             /*tp_basicsize*/
-    0,                         /*tp_itemsize*/
-    (destructor)Noddy_dealloc, /*tp_dealloc*/
-    0,                         /*tp_print*/
-    0,                         /*tp_getattr*/
-    0,                         /*tp_setattr*/
-    0,                         /*tp_compare*/
-    0,                         /*tp_repr*/
-    0,                         /*tp_as_number*/
-    0,                         /*tp_as_sequence*/
-    0,                         /*tp_as_mapping*/
-    0,                         /*tp_hash */
-    0,                         /*tp_call*/
-    0,                         /*tp_str*/
-    0,                         /*tp_getattro*/
-    0,                         /*tp_setattro*/
-    0,                         /*tp_as_buffer*/
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
-    "Noddy objects",           /* tp_doc */
-    0,		               /* tp_traverse */
-    0,		               /* tp_clear */
-    0,		               /* tp_richcompare */
-    0,		               /* tp_weaklistoffset */
-    0,		               /* tp_iter */
-    0,		               /* tp_iternext */
-    Noddy_methods,             /* tp_methods */
-    Noddy_members,             /* tp_members */
-    0,                         /* tp_getset */
-    0,                         /* tp_base */
-    0,                         /* tp_dict */
-    0,                         /* tp_descr_get */
-    0,                         /* tp_descr_set */
-    0,                         /* tp_dictoffset */
-    (initproc)Noddy_init,      /* tp_init */
-    0,                         /* tp_alloc */
-    Noddy_new,                 /* tp_new */
-};
-
-static PyMethodDef module_methods[] = {
-    {NULL}  /* Sentinel */
-};
-
-#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
-#define PyMODINIT_FUNC void
-#endif
-PyMODINIT_FUNC
-initnoddy2(void) 
-{
-    PyObject* m;
-
-    if (PyType_Ready(&NoddyType) < 0)
-        return;
-
-    m = Py_InitModule3("noddy2", module_methods,
-                       "Example module that creates an extension type.");
-
-    if (m == NULL)
-      return;
-
-    Py_INCREF(&NoddyType);
-    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
-}
diff --git a/Doc/ext/noddy3.c b/Doc/ext/noddy3.c
deleted file mode 100644
index 60260ad..0000000
--- a/Doc/ext/noddy3.c
+++ /dev/null
@@ -1,243 +0,0 @@
-#include <Python.h>
-#include "structmember.h"
-
-typedef struct {
-    PyObject_HEAD
-    PyObject *first;
-    PyObject *last;
-    int number;
-} Noddy;
-
-static void
-Noddy_dealloc(Noddy* self)
-{
-    Py_XDECREF(self->first);
-    Py_XDECREF(self->last);
-    self->ob_type->tp_free((PyObject*)self);
-}
-
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
-    Noddy *self;
-
-    self = (Noddy *)type->tp_alloc(type, 0);
-    if (self != NULL) {
-        self->first = PyString_FromString("");
-        if (self->first == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-        
-        self->last = PyString_FromString("");
-        if (self->last == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-
-        self->number = 0;
-    }
-
-    return (PyObject *)self;
-}
-
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
-    PyObject *first=NULL, *last=NULL, *tmp;
-
-    static char *kwlist[] = {"first", "last", "number", NULL};
-
-    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist, 
-                                      &first, &last, 
-                                      &self->number))
-        return -1; 
-
-    if (first) {
-        tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
-        Py_DECREF(tmp);
-    }
-
-    if (last) {
-        tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
-        Py_DECREF(tmp);
-    }
-
-    return 0;
-}
-
-static PyMemberDef Noddy_members[] = {
-    {"number", T_INT, offsetof(Noddy, number), 0,
-     "noddy number"},
-    {NULL}  /* Sentinel */
-};
-
-static PyObject *
-Noddy_getfirst(Noddy *self, void *closure)
-{
-    Py_INCREF(self->first);
-    return self->first;
-}
-
-static int
-Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
-{
-  if (value == NULL) {
-    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
-    return -1;
-  }
-  
-  if (! PyString_Check(value)) {
-    PyErr_SetString(PyExc_TypeError, 
-                    "The first attribute value must be a string");
-    return -1;
-  }
-      
-  Py_DECREF(self->first);
-  Py_INCREF(value);
-  self->first = value;    
-
-  return 0;
-}
-
-static PyObject *
-Noddy_getlast(Noddy *self, void *closure)
-{
-    Py_INCREF(self->last);
-    return self->last;
-}
-
-static int
-Noddy_setlast(Noddy *self, PyObject *value, void *closure)
-{
-  if (value == NULL) {
-    PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
-    return -1;
-  }
-  
-  if (! PyString_Check(value)) {
-    PyErr_SetString(PyExc_TypeError, 
-                    "The last attribute value must be a string");
-    return -1;
-  }
-      
-  Py_DECREF(self->last);
-  Py_INCREF(value);
-  self->last = value;    
-
-  return 0;
-}
-
-static PyGetSetDef Noddy_getseters[] = {
-    {"first", 
-     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
-     "first name",
-     NULL},
-    {"last", 
-     (getter)Noddy_getlast, (setter)Noddy_setlast,
-     "last name",
-     NULL},
-    {NULL}  /* Sentinel */
-};
-
-static PyObject *
-Noddy_name(Noddy* self)
-{
-    static PyObject *format = NULL;
-    PyObject *args, *result;
-
-    if (format == NULL) {
-        format = PyString_FromString("%s %s");
-        if (format == NULL)
-            return NULL;
-    }
-
-    args = Py_BuildValue("OO", self->first, self->last);
-    if (args == NULL)
-        return NULL;
-
-    result = PyString_Format(format, args);
-    Py_DECREF(args);
-    
-    return result;
-}
-
-static PyMethodDef Noddy_methods[] = {
-    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
-     "Return the name, combining the first and last name"
-    },
-    {NULL}  /* Sentinel */
-};
-
-static PyTypeObject NoddyType = {
-    PyObject_HEAD_INIT(NULL)
-    0,                         /*ob_size*/
-    "noddy.Noddy",             /*tp_name*/
-    sizeof(Noddy),             /*tp_basicsize*/
-    0,                         /*tp_itemsize*/
-    (destructor)Noddy_dealloc, /*tp_dealloc*/
-    0,                         /*tp_print*/
-    0,                         /*tp_getattr*/
-    0,                         /*tp_setattr*/
-    0,                         /*tp_compare*/
-    0,                         /*tp_repr*/
-    0,                         /*tp_as_number*/
-    0,                         /*tp_as_sequence*/
-    0,                         /*tp_as_mapping*/
-    0,                         /*tp_hash */
-    0,                         /*tp_call*/
-    0,                         /*tp_str*/
-    0,                         /*tp_getattro*/
-    0,                         /*tp_setattro*/
-    0,                         /*tp_as_buffer*/
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
-    "Noddy objects",           /* tp_doc */
-    0,		               /* tp_traverse */
-    0,		               /* tp_clear */
-    0,		               /* tp_richcompare */
-    0,		               /* tp_weaklistoffset */
-    0,		               /* tp_iter */
-    0,		               /* tp_iternext */
-    Noddy_methods,             /* tp_methods */
-    Noddy_members,             /* tp_members */
-    Noddy_getseters,           /* tp_getset */
-    0,                         /* tp_base */
-    0,                         /* tp_dict */
-    0,                         /* tp_descr_get */
-    0,                         /* tp_descr_set */
-    0,                         /* tp_dictoffset */
-    (initproc)Noddy_init,      /* tp_init */
-    0,                         /* tp_alloc */
-    Noddy_new,                 /* tp_new */
-};
-
-static PyMethodDef module_methods[] = {
-    {NULL}  /* Sentinel */
-};
-
-#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
-#define PyMODINIT_FUNC void
-#endif
-PyMODINIT_FUNC
-initnoddy3(void) 
-{
-    PyObject* m;
-
-    if (PyType_Ready(&NoddyType) < 0)
-        return;
-
-    m = Py_InitModule3("noddy3", module_methods,
-                       "Example module that creates an extension type.");
-
-    if (m == NULL)
-      return;
-
-    Py_INCREF(&NoddyType);
-    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
-}
diff --git a/Doc/ext/noddy4.c b/Doc/ext/noddy4.c
deleted file mode 100644
index 878e086..0000000
--- a/Doc/ext/noddy4.c
+++ /dev/null
@@ -1,224 +0,0 @@
-#include <Python.h>
-#include "structmember.h"
-
-typedef struct {
-    PyObject_HEAD
-    PyObject *first;
-    PyObject *last;
-    int number;
-} Noddy;
-
-static int
-Noddy_traverse(Noddy *self, visitproc visit, void *arg)
-{
-    int vret;
-
-    if (self->first) {
-        vret = visit(self->first, arg);
-        if (vret != 0)
-            return vret;
-    }
-    if (self->last) {
-        vret = visit(self->last, arg);
-        if (vret != 0)
-            return vret;
-    }
-
-    return 0;
-}
-
-static int 
-Noddy_clear(Noddy *self)
-{
-    PyObject *tmp;
-
-    tmp = self->first;
-    self->first = NULL;
-    Py_XDECREF(tmp);
-
-    tmp = self->last;
-    self->last = NULL;
-    Py_XDECREF(tmp);
-
-    return 0;
-}
-
-static void
-Noddy_dealloc(Noddy* self)
-{
-    Noddy_clear(self);
-    self->ob_type->tp_free((PyObject*)self);
-}
-
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
-    Noddy *self;
-
-    self = (Noddy *)type->tp_alloc(type, 0);
-    if (self != NULL) {
-        self->first = PyString_FromString("");
-        if (self->first == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-        
-        self->last = PyString_FromString("");
-        if (self->last == NULL)
-          {
-            Py_DECREF(self);
-            return NULL;
-          }
-
-        self->number = 0;
-    }
-
-    return (PyObject *)self;
-}
-
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
-    PyObject *first=NULL, *last=NULL, *tmp;
-
-    static char *kwlist[] = {"first", "last", "number", NULL};
-
-    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, 
-                                      &first, &last, 
-                                      &self->number))
-        return -1; 
-
-    if (first) {
-        tmp = self->first;
-        Py_INCREF(first);
-        self->first = first;
-        Py_XDECREF(tmp);
-    }
-
-    if (last) {
-        tmp = self->last;
-        Py_INCREF(last);
-        self->last = last;
-        Py_XDECREF(tmp);
-    }
-
-    return 0;
-}
-
-
-static PyMemberDef Noddy_members[] = {
-    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
-     "first name"},
-    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
-     "last name"},
-    {"number", T_INT, offsetof(Noddy, number), 0,
-     "noddy number"},
-    {NULL}  /* Sentinel */
-};
-
-static PyObject *
-Noddy_name(Noddy* self)
-{
-    static PyObject *format = NULL;
-    PyObject *args, *result;
-
-    if (format == NULL) {
-        format = PyString_FromString("%s %s");
-        if (format == NULL)
-            return NULL;
-    }
-
-    if (self->first == NULL) {
-        PyErr_SetString(PyExc_AttributeError, "first");
-        return NULL;
-    }
-
-    if (self->last == NULL) {
-        PyErr_SetString(PyExc_AttributeError, "last");
-        return NULL;
-    }
-
-    args = Py_BuildValue("OO", self->first, self->last);
-    if (args == NULL)
-        return NULL;
-
-    result = PyString_Format(format, args);
-    Py_DECREF(args);
-    
-    return result;
-}
-
-static PyMethodDef Noddy_methods[] = {
-    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
-     "Return the name, combining the first and last name"
-    },
-    {NULL}  /* Sentinel */
-};
-
-static PyTypeObject NoddyType = {
-    PyObject_HEAD_INIT(NULL)
-    0,                         /*ob_size*/
-    "noddy.Noddy",             /*tp_name*/
-    sizeof(Noddy),             /*tp_basicsize*/
-    0,                         /*tp_itemsize*/
-    (destructor)Noddy_dealloc, /*tp_dealloc*/
-    0,                         /*tp_print*/
-    0,                         /*tp_getattr*/
-    0,                         /*tp_setattr*/
-    0,                         /*tp_compare*/
-    0,                         /*tp_repr*/
-    0,                         /*tp_as_number*/
-    0,                         /*tp_as_sequence*/
-    0,                         /*tp_as_mapping*/
-    0,                         /*tp_hash */
-    0,                         /*tp_call*/
-    0,                         /*tp_str*/
-    0,                         /*tp_getattro*/
-    0,                         /*tp_setattro*/
-    0,                         /*tp_as_buffer*/
-    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
-    "Noddy objects",           /* tp_doc */
-    (traverseproc)Noddy_traverse,   /* tp_traverse */
-    (inquiry)Noddy_clear,           /* tp_clear */
-    0,		               /* tp_richcompare */
-    0,		               /* tp_weaklistoffset */
-    0,		               /* tp_iter */
-    0,		               /* tp_iternext */
-    Noddy_methods,             /* tp_methods */
-    Noddy_members,             /* tp_members */
-    0,                         /* tp_getset */
-    0,                         /* tp_base */
-    0,                         /* tp_dict */
-    0,                         /* tp_descr_get */
-    0,                         /* tp_descr_set */
-    0,                         /* tp_dictoffset */
-    (initproc)Noddy_init,      /* tp_init */
-    0,                         /* tp_alloc */
-    Noddy_new,                 /* tp_new */
-};
-
-static PyMethodDef module_methods[] = {
-    {NULL}  /* Sentinel */
-};
-
-#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
-#define PyMODINIT_FUNC void
-#endif
-PyMODINIT_FUNC
-initnoddy4(void) 
-{
-    PyObject* m;
-
-    if (PyType_Ready(&NoddyType) < 0)
-        return;
-
-    m = Py_InitModule3("noddy4", module_methods,
-                       "Example module that creates an extension type.");
-
-    if (m == NULL)
-      return;
-
-    Py_INCREF(&NoddyType);
-    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
-}
diff --git a/Doc/ext/run-func.c b/Doc/ext/run-func.c
deleted file mode 100644
index 5a7df0d..0000000
--- a/Doc/ext/run-func.c
+++ /dev/null
@@ -1,68 +0,0 @@
-#include <Python.h>
-
-int
-main(int argc, char *argv[])
-{
-    PyObject *pName, *pModule, *pDict, *pFunc;
-    PyObject *pArgs, *pValue;
-    int i;
-
-    if (argc < 3) {
-        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
-        return 1;
-    }
-
-    Py_Initialize();
-    pName = PyString_FromString(argv[1]);
-    /* Error checking of pName left out */
-
-    pModule = PyImport_Import(pName);
-    Py_DECREF(pName);
-
-    if (pModule != NULL) {
-        pFunc = PyObject_GetAttrString(pModule, argv[2]);
-        /* pFunc is a new reference */
-
-        if (pFunc && PyCallable_Check(pFunc)) {
-            pArgs = PyTuple_New(argc - 3);
-            for (i = 0; i < argc - 3; ++i) {
-                pValue = PyInt_FromLong(atoi(argv[i + 3]));
-                if (!pValue) {
-                    Py_DECREF(pArgs);
-                    Py_DECREF(pModule);
-                    fprintf(stderr, "Cannot convert argument\n");
-                    return 1;
-                }
-                /* pValue reference stolen here: */
-                PyTuple_SetItem(pArgs, i, pValue);
-            }
-            pValue = PyObject_CallObject(pFunc, pArgs);
-            Py_DECREF(pArgs);
-            if (pValue != NULL) {
-                printf("Result of call: %ld\n", PyInt_AsLong(pValue));
-                Py_DECREF(pValue);
-            }
-            else {
-                Py_DECREF(pFunc);
-                Py_DECREF(pModule);
-                PyErr_Print();
-                fprintf(stderr,"Call failed\n");
-                return 1;
-            }
-        }
-        else {
-            if (PyErr_Occurred())
-                PyErr_Print();
-            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
-        }
-        Py_XDECREF(pFunc);
-        Py_DECREF(pModule);
-    }
-    else {
-        PyErr_Print();
-        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
-        return 1;
-    }
-    Py_Finalize();
-    return 0;
-}
diff --git a/Doc/ext/setup.py b/Doc/ext/setup.py
deleted file mode 100644
index b853d23..0000000
--- a/Doc/ext/setup.py
+++ /dev/null
@@ -1,8 +0,0 @@
-from distutils.core import setup, Extension
-setup(name="noddy", version="1.0",
-      ext_modules=[
-         Extension("noddy", ["noddy.c"]),
-         Extension("noddy2", ["noddy2.c"]),
-         Extension("noddy3", ["noddy3.c"]),
-         Extension("noddy4", ["noddy4.c"]),
-         ])
diff --git a/Doc/ext/shoddy.c b/Doc/ext/shoddy.c
deleted file mode 100644
index 07a4177..0000000
--- a/Doc/ext/shoddy.c
+++ /dev/null
@@ -1,91 +0,0 @@
-#include <Python.h>
-
-typedef struct {
-    PyListObject list;
-    int state;
-} Shoddy;
-
-
-static PyObject *
-Shoddy_increment(Shoddy *self, PyObject *unused)
-{
-    self->state++;
-    return PyInt_FromLong(self->state);
-}
-
-
-static PyMethodDef Shoddy_methods[] = {
-    {"increment", (PyCFunction)Shoddy_increment, METH_NOARGS,
-     PyDoc_STR("increment state counter")},
-    {NULL,	NULL},
-};
-
-static int
-Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
-{
-    if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
-        return -1;
-    self->state = 0;
-    return 0;
-}
-
-
-static PyTypeObject ShoddyType = {
-    PyObject_HEAD_INIT(NULL)
-    0,                       /* ob_size */
-    "shoddy.Shoddy",         /* tp_name */
-    sizeof(Shoddy),          /* tp_basicsize */
-    0,                       /* tp_itemsize */
-    0,                       /* tp_dealloc */
-    0,                       /* tp_print */
-    0,                       /* tp_getattr */
-    0,                       /* tp_setattr */
-    0,                       /* tp_compare */
-    0,                       /* tp_repr */
-    0,                       /* tp_as_number */
-    0,                       /* tp_as_sequence */
-    0,                       /* tp_as_mapping */
-    0,                       /* tp_hash */
-    0,                       /* tp_call */
-    0,                       /* tp_str */
-    0,                       /* tp_getattro */
-    0,                       /* tp_setattro */
-    0,                       /* tp_as_buffer */
-    Py_TPFLAGS_DEFAULT |
-      Py_TPFLAGS_BASETYPE,   /* tp_flags */
-    0,                       /* tp_doc */
-    0,                       /* tp_traverse */
-    0,                       /* tp_clear */
-    0,                       /* tp_richcompare */
-    0,                       /* tp_weaklistoffset */
-    0,                       /* tp_iter */
-    0,                       /* tp_iternext */
-    Shoddy_methods,          /* tp_methods */
-    0,                       /* tp_members */
-    0,                       /* tp_getset */
-    0,                       /* tp_base */
-    0,                       /* tp_dict */
-    0,                       /* tp_descr_get */
-    0,                       /* tp_descr_set */
-    0,                       /* tp_dictoffset */
-    (initproc)Shoddy_init,   /* tp_init */
-    0,                       /* tp_alloc */
-    0,                       /* tp_new */
-};
-
-PyMODINIT_FUNC
-initshoddy(void)
-{
-    PyObject *m;
-
-    ShoddyType.tp_base = &PyList_Type;
-    if (PyType_Ready(&ShoddyType) < 0)
-        return;
-
-    m = Py_InitModule3("shoddy", NULL, "Shoddy module");
-    if (m == NULL)
-        return;
-
-    Py_INCREF(&ShoddyType);
-    PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
-}
diff --git a/Doc/ext/test.py b/Doc/ext/test.py
deleted file mode 100644
index 7ebf46a..0000000
--- a/Doc/ext/test.py
+++ /dev/null
@@ -1,213 +0,0 @@
-"""Test module for the noddy examples
-
-Noddy 1:
-
->>> import noddy
->>> n1 = noddy.Noddy()
->>> n2 = noddy.Noddy()
->>> del n1
->>> del n2
-
-
-Noddy 2
-
->>> import noddy2
->>> n1 = noddy2.Noddy('jim', 'fulton', 42)
->>> n1.first
-'jim'
->>> n1.last
-'fulton'
->>> n1.number
-42
->>> n1.name()
-'jim fulton'
->>> n1.first = 'will'
->>> n1.name()
-'will fulton'
->>> n1.last = 'tell'
->>> n1.name()
-'will tell'
->>> del n1.first
->>> n1.name()
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n1.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n1.first = 'drew'
->>> n1.first
-'drew'
->>> del n1.number
-Traceback (most recent call last):
-...
-TypeError: can't delete numeric/char attribute
->>> n1.number=2
->>> n1.number
-2
->>> n1.first = 42
->>> n1.name()
-'42 tell'
->>> n2 = noddy2.Noddy()
->>> n2.name()
-' '
->>> n2.first
-''
->>> n2.last
-''
->>> del n2.first
->>> n2.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n2.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n2.name()
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-AttributeError: first
->>> n2.number
-0
->>> n3 = noddy2.Noddy('jim', 'fulton', 'waaa')
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-TypeError: an integer is required
->>> del n1
->>> del n2
-
-
-Noddy 3
-
->>> import noddy3
->>> n1 = noddy3.Noddy('jim', 'fulton', 42)
->>> n1 = noddy3.Noddy('jim', 'fulton', 42)
->>> n1.name()
-'jim fulton'
->>> del n1.first
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-TypeError: Cannot delete the first attribute
->>> n1.first = 42
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-TypeError: The first attribute value must be a string
->>> n1.first = 'will'
->>> n1.name()
-'will fulton'
->>> n2 = noddy3.Noddy()
->>> n2 = noddy3.Noddy()
->>> n2 = noddy3.Noddy()
->>> n3 = noddy3.Noddy('jim', 'fulton', 'waaa')
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-TypeError: an integer is required
->>> del n1
->>> del n2
-
-Noddy 4
-
->>> import noddy4
->>> n1 = noddy4.Noddy('jim', 'fulton', 42)
->>> n1.first
-'jim'
->>> n1.last
-'fulton'
->>> n1.number
-42
->>> n1.name()
-'jim fulton'
->>> n1.first = 'will'
->>> n1.name()
-'will fulton'
->>> n1.last = 'tell'
->>> n1.name()
-'will tell'
->>> del n1.first
->>> n1.name()
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n1.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n1.first = 'drew'
->>> n1.first
-'drew'
->>> del n1.number
-Traceback (most recent call last):
-...
-TypeError: can't delete numeric/char attribute
->>> n1.number=2
->>> n1.number
-2
->>> n1.first = 42
->>> n1.name()
-'42 tell'
->>> n2 = noddy4.Noddy()
->>> n2 = noddy4.Noddy()
->>> n2 = noddy4.Noddy()
->>> n2 = noddy4.Noddy()
->>> n2.name()
-' '
->>> n2.first
-''
->>> n2.last
-''
->>> del n2.first
->>> n2.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n2.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n2.name()
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-AttributeError: first
->>> n2.number
-0
->>> n3 = noddy4.Noddy('jim', 'fulton', 'waaa')
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-TypeError: an integer is required
-
-
-Test cyclic gc(?)
-
->>> import gc
->>> gc.disable()
-
->>> x = []
->>> l = [x]
->>> n2.first = l
->>> n2.first
-[[]]
->>> l.append(n2)
->>> del l
->>> del n1
->>> del n2
->>> sys.getrefcount(x)
-3
->>> ignore = gc.collect()
->>> sys.getrefcount(x)
-2
-
->>> gc.enable()
-"""
-
-import os
-import sys
-from distutils.util import get_platform
-PLAT_SPEC = "%s-%s" % (get_platform(), sys.version[0:3])
-src = os.path.join("build", "lib.%s" % PLAT_SPEC)
-sys.path.append(src)
-
-if __name__ == "__main__":
-    import doctest, __main__
-    doctest.testmod(__main__)
diff --git a/Doc/ext/windows.tex b/Doc/ext/windows.tex
deleted file mode 100644
index f9de548..0000000
--- a/Doc/ext/windows.tex
+++ /dev/null
@@ -1,320 +0,0 @@
-\chapter{Building C and \Cpp{} Extensions on Windows%
-     \label{building-on-windows}}
-
-
-This chapter briefly explains how to create a Windows extension module
-for Python using Microsoft Visual \Cpp, and follows with more
-detailed background information on how it works.  The explanatory
-material is useful for both the Windows programmer learning to build
-Python extensions and the \UNIX{} programmer interested in producing
-software which can be successfully built on both \UNIX{} and Windows.
-
-Module authors are encouraged to use the distutils approach for
-building extension modules, instead of the one described in this
-section. You will still need the C compiler that was used to build
-Python; typically Microsoft Visual \Cpp.
-
-\begin{notice}
-  This chapter mentions a number of filenames that include an encoded
-  Python version number.  These filenames are represented with the
-  version number shown as \samp{XY}; in practive, \character{X} will
-  be the major version number and \character{Y} will be the minor
-  version number of the Python release you're working with.  For
-  example, if you are using Python 2.2.1, \samp{XY} will actually be
-  \samp{22}.
-\end{notice}
-
-
-\section{A Cookbook Approach \label{win-cookbook}}
-
-There are two approaches to building extension modules on Windows,
-just as there are on \UNIX: use the
-\ulink{\module{distutils}}{../lib/module-distutils.html} package to
-control the build process, or do things manually.  The distutils
-approach works well for most extensions; documentation on using
-\ulink{\module{distutils}}{../lib/module-distutils.html} to build and
-package extension modules is available in
-\citetitle[../dist/dist.html]{Distributing Python Modules}.  This
-section describes the manual approach to building Python extensions
-written in C or \Cpp.
-
-To build extensions using these instructions, you need to have a copy
-of the Python sources of the same version as your installed Python.
-You will need Microsoft Visual \Cpp{} ``Developer Studio''; project
-files are supplied for V\Cpp{} version 7.1, but you can use older
-versions of V\Cpp.  Notice that you should use the same version of
-V\Cpp that was used to build Python itself. The example files
-described here are distributed with the Python sources in the
-\file{PC\textbackslash example_nt\textbackslash} directory.
-
-\begin{enumerate}
-  \item
-  \strong{Copy the example files}\\
-    The \file{example_nt} directory is a subdirectory of the \file{PC}
-    directory, in order to keep all the PC-specific files under the
-    same directory in the source distribution.  However, the
-    \file{example_nt} directory can't actually be used from this
-    location.  You first need to copy or move it up one level, so that
-    \file{example_nt} is a sibling of the \file{PC} and \file{Include}
-    directories.  Do all your work from within this new location.
-
-  \item
-  \strong{Open the project}\\
-    From V\Cpp, use the \menuselection{File \sub Open Solution}
-    dialog (not \menuselection{File \sub Open}!).  Navigate to and
-    select the file \file{example.sln}, in the \emph{copy} of the
-    \file{example_nt} directory you made above.  Click Open.
-
-  \item
-  \strong{Build the example DLL}\\
-    In order to check that everything is set up right, try building:
-
-    \begin{enumerate}
-      \item
-        Select a configuration.  This step is optional.  Choose
-        \menuselection{Build \sub Configuration Manager \sub Active 
-        Solution Configuration} and select either \guilabel{Release} 
-        or\guilabel{Debug}.  If you skip this step,
-        V\Cpp{} will use the Debug configuration by default.
-
-      \item
-        Build the DLL.  Choose \menuselection{Build \sub Build
-        Solution}.  This creates all intermediate and result files in
-        a subdirectory called either \file{Debug} or \file{Release},
-        depending on which configuration you selected in the preceding
-        step.
-    \end{enumerate}
-
-  \item
-  \strong{Testing the debug-mode DLL}\\
-    Once the Debug build has succeeded, bring up a DOS box, and change
-    to the \file{example_nt\textbackslash Debug} directory.  You
-    should now be able to repeat the following session (\code{C>} is
-    the DOS prompt, \code{>>>} is the Python prompt; note that
-    build information and various debug output from Python may not
-    match this screen dump exactly):
-
-\begin{verbatim}
-C>..\..\PCbuild\python_d
-Adding parser accelerators ...
-Done.
-Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
-Type "copyright", "credits" or "license" for more information.
->>> import example
-[4897 refs]
->>> example.foo()
-Hello, world
-[4903 refs]
->>>
-\end{verbatim}
-
-    Congratulations!  You've successfully built your first Python
-    extension module.
-
-  \item
-  \strong{Creating your own project}\\
-    Choose a name and create a directory for it.  Copy your C sources
-    into it.  Note that the module source file name does not
-    necessarily have to match the module name, but the name of the
-    initialization function should match the module name --- you can
-    only import a module \module{spam} if its initialization function
-    is called \cfunction{initspam()}, and it should call
-    \cfunction{Py_InitModule()} with the string \code{"spam"} as its
-    first argument (use the minimal \file{example.c} in this directory
-    as a guide).  By convention, it lives in a file called
-    \file{spam.c} or \file{spammodule.c}.  The output file should be
-    called \file{spam.dll} or \file{spam.pyd} (the latter is supported
-    to avoid confusion with a system library \file{spam.dll} to which
-    your module could be a Python interface) in Release mode, or
-    \file{spam_d.dll} or \file{spam_d.pyd} in Debug mode.
-
-    Now your options are:
-
-    \begin{enumerate}
-      \item  Copy \file{example.sln} and \file{example.vcproj}, rename
-             them to \file{spam.*}, and edit them by hand, or
-      \item  Create a brand new project; instructions are below.
-    \end{enumerate}
-
-    In either case, copy \file{example_nt\textbackslash example.def}
-    to \file{spam\textbackslash spam.def}, and edit the new
-    \file{spam.def} so its second line contains the string
-    `\code{initspam}'.  If you created a new project yourself, add the
-    file \file{spam.def} to the project now.  (This is an annoying
-    little file with only two lines.  An alternative approach is to
-    forget about the \file{.def} file, and add the option
-    \programopt{/export:initspam} somewhere to the Link settings, by
-    manually editing the setting in Project Properties dialog).
-
-  \item
-  \strong{Creating a brand new project}\\
-    Use the \menuselection{File \sub New \sub Project} dialog to
-    create a new Project Workspace.  Select \guilabel{Visual C++
-    Projects/Win32/ Win32 Project}, enter the name (\samp{spam}), and
-    make sure the Location is set to parent of the \file{spam}
-    directory you have created (which should be a direct subdirectory
-    of the Python build tree, a sibling of \file{Include} and
-    \file{PC}).  Select Win32 as the platform (in my version, this is
-    the only choice).  Make sure the Create new workspace radio button
-    is selected.  Click OK.
-
-    You should now create the file \file{spam.def} as instructed in
-    the previous section. Add the source files to the project, using
-    \menuselection{Project \sub Add Existing Item}. Set the pattern to
-    \code{*.*} and select both \file{spam.c} and \file{spam.def} and
-    click OK.  (Inserting them one by one is fine too.)
-
-    Now open the \menuselection{Project \sub spam properties} dialog.
-    You only need to change a few settings.  Make sure \guilabel{All
-    Configurations} is selected from the \guilabel{Settings for:}
-    dropdown list.  Select the C/\Cpp{} tab.  Choose the General
-    category in the popup menu at the top.  Type the following text in
-    the entry box labeled \guilabel{Additional Include Directories}:
-
-\begin{verbatim}
-..\Include,..\PC
-\end{verbatim}
-
-    Then, choose the General category in the Linker tab, and enter
-
-\begin{verbatim}
-..\PCbuild
-\end{verbatim}
-
-    in the text box labelled \guilabel{Additional library Directories}.
-
-    Now you need to add some mode-specific settings:
-
-    Select \guilabel{Release} in the \guilabel{Configuration}
-    dropdown list.  Choose the \guilabel{Link} tab, choose the
-    \guilabel{Input} category, and append \code{pythonXY.lib} to the
-    list in the \guilabel{Additional Dependencies} box.
-
-    Select \guilabel{Debug} in the \guilabel{Configuration} dropdown
-    list, and append \code{pythonXY_d.lib} to the list in the
-    \guilabel{Additional Dependencies} box.  Then click the C/\Cpp{}
-    tab, select \guilabel{Code Generation}, and select
-    \guilabel{Multi-threaded Debug DLL} from the \guilabel{Runtime
-    library} dropdown list.
-
-    Select \guilabel{Release} again from the \guilabel{Configuration}
-    dropdown list.  Select \guilabel{Multi-threaded DLL} from the
-    \guilabel{Runtime library} dropdown list.
-\end{enumerate}
-
-
-If your module creates a new type, you may have trouble with this line:
-
-\begin{verbatim}
-    PyObject_HEAD_INIT(&PyType_Type)
-\end{verbatim}
-
-Change it to:
-
-\begin{verbatim}
-    PyObject_HEAD_INIT(NULL)
-\end{verbatim}
-
-and add the following to the module initialization function:
-
-\begin{verbatim}
-    MyObject_Type.ob_type = &PyType_Type;
-\end{verbatim}
-
-Refer to section~3 of the
-\citetitle[http://www.python.org/doc/FAQ.html]{Python FAQ} for details
-on why you must do this.
-
-
-\section{Differences Between \UNIX{} and Windows
-     \label{dynamic-linking}}
-\sectionauthor{Chris Phoenix}{cphoenix@best.com}
-
-
-\UNIX{} and Windows use completely different paradigms for run-time
-loading of code.  Before you try to build a module that can be
-dynamically loaded, be aware of how your system works.
-
-In \UNIX, a shared object (\file{.so}) file contains code to be used by the
-program, and also the names of functions and data that it expects to
-find in the program.  When the file is joined to the program, all
-references to those functions and data in the file's code are changed
-to point to the actual locations in the program where the functions
-and data are placed in memory.  This is basically a link operation.
-
-In Windows, a dynamic-link library (\file{.dll}) file has no dangling
-references.  Instead, an access to functions or data goes through a
-lookup table.  So the DLL code does not have to be fixed up at runtime
-to refer to the program's memory; instead, the code already uses the
-DLL's lookup table, and the lookup table is modified at runtime to
-point to the functions and data.
-
-In \UNIX, there is only one type of library file (\file{.a}) which
-contains code from several object files (\file{.o}).  During the link
-step to create a shared object file (\file{.so}), the linker may find
-that it doesn't know where an identifier is defined.  The linker will
-look for it in the object files in the libraries; if it finds it, it
-will include all the code from that object file.
-
-In Windows, there are two types of library, a static library and an
-import library (both called \file{.lib}).  A static library is like a
-\UNIX{} \file{.a} file; it contains code to be included as necessary.
-An import library is basically used only to reassure the linker that a
-certain identifier is legal, and will be present in the program when
-the DLL is loaded.  So the linker uses the information from the
-import library to build the lookup table for using identifiers that
-are not included in the DLL.  When an application or a DLL is linked,
-an import library may be generated, which will need to be used for all
-future DLLs that depend on the symbols in the application or DLL.
-
-Suppose you are building two dynamic-load modules, B and C, which should
-share another block of code A.  On \UNIX, you would \emph{not} pass
-\file{A.a} to the linker for \file{B.so} and \file{C.so}; that would
-cause it to be included twice, so that B and C would each have their
-own copy.  In Windows, building \file{A.dll} will also build
-\file{A.lib}.  You \emph{do} pass \file{A.lib} to the linker for B and
-C.  \file{A.lib} does not contain code; it just contains information
-which will be used at runtime to access A's code.  
-
-In Windows, using an import library is sort of like using \samp{import
-spam}; it gives you access to spam's names, but does not create a
-separate copy.  On \UNIX, linking with a library is more like
-\samp{from spam import *}; it does create a separate copy.
-
-
-\section{Using DLLs in Practice \label{win-dlls}}
-\sectionauthor{Chris Phoenix}{cphoenix@best.com}
-
-Windows Python is built in Microsoft Visual \Cpp; using other
-compilers may or may not work (though Borland seems to).  The rest of
-this section is MSV\Cpp{} specific.
-
-When creating DLLs in Windows, you must pass \file{pythonXY.lib} to
-the linker.  To build two DLLs, spam and ni (which uses C functions
-found in spam), you could use these commands:
-
-\begin{verbatim}
-cl /LD /I/python/include spam.c ../libs/pythonXY.lib
-cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
-\end{verbatim}
-
-The first command created three files: \file{spam.obj},
-\file{spam.dll} and \file{spam.lib}.  \file{Spam.dll} does not contain
-any Python functions (such as \cfunction{PyArg_ParseTuple()}), but it
-does know how to find the Python code thanks to \file{pythonXY.lib}.
-
-The second command created \file{ni.dll} (and \file{.obj} and
-\file{.lib}), which knows how to find the necessary functions from
-spam, and also from the Python executable.
-
-Not every identifier is exported to the lookup table.  If you want any
-other modules (including Python) to be able to see your identifiers,
-you have to say \samp{_declspec(dllexport)}, as in \samp{void
-_declspec(dllexport) initspam(void)} or \samp{PyObject
-_declspec(dllexport) *NiGetSpamData(void)}.
-
-Developer Studio will throw in a lot of import libraries that you do
-not really need, adding about 100K to your executable.  To get rid of
-them, use the Project Settings dialog, Link tab, to specify
-\emph{ignore default libraries}.  Add the correct
-\file{msvcrt\var{xx}.lib} to the list of libraries.