Commits

Anonymous committed 8daed16

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

Comments (0)

Files changed (135)

+#ifndef BEOS_DL_EXPORT_H
+#define BEOS_DL_EXPORT_H
+
+/* There are no declarations here, so no #ifdef __cplusplus...
+ *
+ * This is the nasty declaration decorations required by certain systems
+ * (in our case, BeOS) for dynamic object loading.
+ *
+ * This trivial header is released under the same license as the rest of
+ * Python.
+ *
+ * - Chris Herborth (chrish@beoscentral.com)
+ *   January 11, 1999
+ */
+
+#ifndef DL_EXPORT
+#  define DL_EXPORT(RTYPE) __declspec(dllexport) RTYPE
+#endif
+#ifndef DL_IMPORT
+#  ifdef USE_DL_EXPORT
+#    define DL_IMPORT(RTYPE) __declspec(dllexport) RTYPE
+#  else
+#    define DL_IMPORT(RTYPE) __declspec(dllimport) RTYPE
+#  endif
+#endif
+
+#endif
+# Makefile for Python documentation
+# ---------------------------------
+#
+# See also the README file.
+#
+# This is a bit of a mess.  The documents are identified by short names:
+#   api -- Python/C API Reference Manual
+#   doc -- Documenting Python
+#   ext -- Extending and Embedding the Python Interpreter
+#   lib -- Library Reference Manual
+#   mac -- Macintosh Library Modules
+#   ref -- Python Reference Manual
+#   tut -- Python Tutorial
+#   inst -- Installing Python Modules
+#   dist -- Distributing Python Modules
+#
+# The latex sources for each of these documents are in subdirectories
+# with the three-letter designations above as the directory names.
+#
+# The main target creates DVI and PostScript for the main each of the
+# documents.  You can also do "make lib" (etc.) to create the DVI and
+# PostScript versions of individual documents.
+#
+# The document classes and styles are in the texinputs/ directory.
+# These define a number of macros that are similar in name and intent
+# as macros in Texinfo (e.g. \code{...} and \emph{...}), as well as a
+# number of environments for formatting function and data definitions.
+#
+# Everything is processed by LaTeX.  See the file `README' for more
+# information on the tools needed for processing.
+#
+# There's a problem with generating the index which has been solved by
+# a sed command applied to the index file.  The shell script fix_hack
+# does this (the Makefile takes care of calling it).
+#
+# Additional targets attempt to convert selected LaTeX sources to
+# various other formats.  These are generally site specific because
+# the tools used are all but universal.  These targets are:
+#
+#   html -- convert all documents from LaTeX to HTML
+#   pdf  -- convert all documents from LaTeX to the
+#		Portable Document Format
+#
+# See the README file for more information on these targets.
+#
+# The formatted output is located in subdirectories.  For PDF and
+# PostScript, look in the paper-$(PAPER)/ directory.  For HTML, look in
+# the html/ directory.  If you want to fix the GNU info process, look
+# in the info/ directory; please send patches to python-docs@python.org.
+
+# Customizations -- you *may* have to edit these
+
+# you could set this to a4
+PAPER=letter
+
+# Ideally, you shouldn't need to edit beyond this point
+
+HTMLDIR=	html
+INFODIR=	info
+TOOLSDIR=	tools
+
+# This is the *documentation* release, and is used to construct the file
+# names of the downloadable tarballs.
+RELEASE=1.6
+
+
+# These must be declared phony since there
+# are directories with matching names:
+.PHONY: api doc ext lib mac ref tut inst dist
+.PHONY: html info longhtml
+
+
+# Main target
+all:	ps
+
+dvi:
+	(cd paper-$(PAPER); $(MAKE) dvi)
+
+pdf:
+	(cd paper-$(PAPER); $(MAKE) pdf)
+
+ps:
+	(cd paper-$(PAPER); $(MAKE) ps)
+
+world:	ps pdf html tarballs
+
+
+# Targets for each document:
+api api.ps:
+	(cd paper-$(PAPER); $(MAKE) api.ps)
+
+doc doc.ps:
+	(cd paper-$(PAPER); $(MAKE) doc.ps)
+
+ext ext.ps:
+	(cd paper-$(PAPER); $(MAKE) ext.ps)
+
+lib lib.ps:
+	(cd paper-$(PAPER); $(MAKE) lib.ps)
+
+mac mac.ps:
+	(cd paper-$(PAPER); $(MAKE) mac.ps)
+
+ref ref.ps:
+	(cd paper-$(PAPER); $(MAKE) ref.ps)
+
+tut tut.ps:
+	(cd paper-$(PAPER); $(MAKE) tut.ps)
+
+inst inst.ps:
+	(cd paper-$(PAPER); $(MAKE) inst.ps)
+
+dist dist.ps:
+	(cd paper-$(PAPER); $(MAKE) dist.ps)
+
+
+api.dvi:
+	(cd paper-$(PAPER); $(MAKE) api.dvi)
+
+doc.dvi:
+	(cd paper-$(PAPER); $(MAKE) doc.dvi)
+
+ext.dvi:
+	(cd paper-$(PAPER); $(MAKE) ext.dvi)
+
+lib.dvi:
+	(cd paper-$(PAPER); $(MAKE) lib.dvi)
+
+mac.dvi:
+	(cd paper-$(PAPER); $(MAKE) mac.dvi)
+
+ref.dvi:
+	(cd paper-$(PAPER); $(MAKE) ref.dvi)
+
+tut.dvi:
+	(cd paper-$(PAPER); $(MAKE) tut.dvi)
+
+inst.dvi:
+	(cd paper-$(PAPER); $(MAKE) inst.dvi)
+
+dist.dvi:
+	(cd paper-$(PAPER); $(MAKE) dist.dvi)
+
+
+api.pdf:
+	(cd paper-$(PAPER); $(MAKE) api.pdf)
+
+doc.pdf:
+	(cd paper-$(PAPER); $(MAKE) doc.pdf)
+
+ext.pdf:
+	(cd paper-$(PAPER); $(MAKE) ext.pdf)
+
+lib.pdf:
+	(cd paper-$(PAPER); $(MAKE) lib.pdf)
+
+mac.pdf:
+	(cd paper-$(PAPER); $(MAKE) mac.pdf)
+
+ref.pdf:
+	(cd paper-$(PAPER); $(MAKE) ref.pdf)
+
+tut.pdf:
+	(cd paper-$(PAPER); $(MAKE) tut.pdf)
+
+inst.pdf:
+	(cd paper-$(PAPER); $(MAKE) inst.pdf)
+
+dist.pdf:
+	(cd paper-$(PAPER); $(MAKE) dist.pdf)
+
+
+# The remaining part of the Makefile is concerned with various
+# conversions, as described above.  See also the README file.
+
+info:
+	(cd $(INFODIR); $(MAKE))
+
+# Targets to convert the manuals to HTML using Nikos Drakos' LaTeX to
+# HTML converter.  For more info on this program, see
+# <URL:http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html>.
+
+# Note that LaTeX2HTML inserts references to an icons directory in
+# each page that it generates.  I have placed a copy of this directory
+# in the distribution to simplify the process of creating a
+# self-contained HTML distribution; for this purpose I have also added
+# a (trivial) index.html.  Change the definition of $ICONSERVER in
+# perl/l2hinit.perl to use a different location for the icons directory.
+
+# If you have the standard LaTeX2HTML icons installed, the versions shipped
+# with this documentation should be stored in a separate directory and used
+# instead.  The standard set does *not* include all the icons used in the
+# Python documentation.
+
+html:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile)
+
+htmlapi:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile api)
+
+htmldoc:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile doc)
+
+htmlext:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile ext)
+
+htmllib:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile lib)
+
+htmlmac:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile mac)
+
+htmlref:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile ref)
+
+htmltut:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile tut)
+
+htmlinst:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile inst)
+
+htmldist:
+	(cd $(HTMLDIR); $(MAKE) PAPER=$(PAPER) -f ../html/Makefile dist)
+
+longhtml:
+	(cd longhtml; $(MAKE) PAPER=$(PAPER))
+
+
+# webchecker needs an extra flag to process the huge index from the libref
+webcheck:
+	(cd $(HTMLDIR); $(MAKE) -f ../html/Makefile webcheck)
+
+
+# Release packaging targets:
+
+info-$(RELEASE).tgz: info
+	(cd $(INFODIR); tar cf - README python.dir python-???.info*) \
+		| gzip -9 >$@
+
+info-$(RELEASE).tar.bz2: info
+	(cd $(INFODIR); tar cf - README python.dir python-???.info*) \
+		| bzip2 -9 >$@
+
+latex-$(RELEASE).tgz:
+	$(TOOLSDIR)/mksourcepkg --gzip $(RELEASE)
+
+latex-$(RELEASE).tar.bz2:
+	$(TOOLSDIR)/mksourcepkg --bzip2 $(RELEASE)
+
+latex-$(RELEASE).zip:
+	rm -f $@
+	$(TOOLSDIR)/mksourcepkg --zip $(RELEASE)
+
+pdf-$(PAPER)-$(RELEASE).tgz: pdf
+	(cd paper-$(PAPER); tar cf - *.pdf) | gzip -9 >$@
+
+pdf-$(PAPER)-$(RELEASE).tar.bz2: pdf
+	(cd paper-$(PAPER); tar cf - *.pdf) | bzip2 -9 >$@
+
+pdf-$(PAPER)-$(RELEASE).zip: pdf
+	rm -f $@
+	(cd paper-$(PAPER); zip -q -9 ../$@ *.pdf)
+
+postscript-$(PAPER)-$(RELEASE).tar.bz2: ps
+	(cd paper-$(PAPER); $(MAKE) README)
+	(cd paper-$(PAPER); tar cf - *.ps README) | bzip2 -9 >$@
+
+postscript-$(PAPER)-$(RELEASE).tgz: ps
+	(cd paper-$(PAPER); $(MAKE) README)
+	(cd paper-$(PAPER); tar cf - *.ps README) | gzip -9 >$@
+
+postscript-$(PAPER)-$(RELEASE).zip: ps
+	(cd paper-$(PAPER); $(MAKE) README)
+	rm -f $@
+	(cd paper-$(PAPER); zip -q -9 ../$@ *.ps README)
+
+html-$(RELEASE).tgz:	html
+	(cd $(HTMLDIR); \
+		tar cf - *index.html */*.css */*.html */*.gif) \
+		| gzip -9 >$@
+
+html-$(RELEASE).tar.bz2:	html
+	(cd $(HTMLDIR); \
+		tar cf - *index.html */*.css */*.html */*.gif) \
+		| bzip2 -9 >$@
+
+html-$(RELEASE).zip:	html
+	rm -f $@
+	(cd $(HTMLDIR); \
+		zip -q -9 ../$@ *index.html */*.css */*.html */*.gif)
+
+longhtml-$(RELEASE).zip:	longhtml
+	rm -f $@
+	(cd longhtml; \
+		zip -q -9 ../$@ */*.css */*.html */*.gif)
+
+# convenience targets:
+
+tarhtml:	html-$(RELEASE).tgz
+tarinfo:	info-$(RELEASE).tgz
+tarps:		postscript-$(PAPER)-$(RELEASE).tgz
+tarpdf:		pdf-$(PAPER)-$(RELEASE).tgz
+tarlatex:	latex-$(RELEASE).tgz
+
+tarballs:	tarpdf tarps tarhtml
+
+ziphtml:	html-$(RELEASE).zip
+ziplonghtml:	longhtml-$(RELEASE).zip
+zipps:		postscript-$(PAPER)-$(RELEASE).zip
+zippdf:		pdf-$(PAPER)-$(RELEASE).zip
+ziplatex:	latex-$(RELEASE).zip
+
+zips:		zippdf zipps ziphtml ziplonghtml
+
+bziphtml:	html-$(RELEASE).tar.bz2
+bzipinfo:	info-$(RELEASE).tar.bz2
+bzipps:		postscript-$(PAPER)-$(RELEASE).tar.bz2
+bzippdf:	pdf-$(PAPER)-$(RELEASE).tar.bz2
+bziplatex:	latex-$(RELEASE).tar.bz2
+
+bzips:		bzippdf bzipps bziphtml
+
+distfiles:	tarballs zips bzips
+	$(TOOLSDIR)/mksourcepkg --all $(RELEASE)
+
+
+# Housekeeping targets
+
+# Remove temporary files; all except the following:
+# - sources: .tex, .bib, .sty, *.cls
+# - useful results: .dvi, .pdf, .ps, .texi, .info
+clean:
+	(cd paper-$(PAPER); $(MAKE) clean)
+	(cd longhtml; $(MAKE) clean)
+	(cd $(HTMLDIR); $(MAKE) clean)
+	(cd $(INFODIR); $(MAKE) clean)
+
+l2hclean:
+	(cd $(HTMLDIR); $(MAKE) clean)
+
+# Remove temporaries as well as final products
+clobber:
+	(cd $(HTMLDIR); $(MAKE) clobber)
+	rm -f html-$(RELEASE).tgz info-$(RELEASE).tgz
+	rm -f pdf-$(RELEASE).tgz postscript-$(RELEASE).tgz
+	rm -f latex-$(RELEASE).tgz html-$(RELEASE).zip
+	rm -f pdf-$(RELEASE).zip postscript-$(RELEASE).zip
+	(cd paper-$(PAPER); $(MAKE) clobber)
+	(cd longhtml; $(MAKE) clobber)
+	(cd $(HTMLDIR); $(MAKE) clobber)
+	(cd $(INFODIR); $(MAKE) clobber)
+
+realclean:  clobber
+distclean:  clobber
+Python main documentation -- in LaTeX
+-------------------------------------
+
+This directory contains the LaTeX sources to the Python documentation
+and tools required to support the formatting process.  The documents
+now require LaTeX2e; LaTeX 2.09 compatibility has been dropped.
+
+If you don't have LaTeX, or if you'd rather not format the
+documentation yourself, you can ftp a tar file containing HTML, PDF,
+or PostScript versions of all documents.  Additional formats may be
+available.  These should be in the same place where you fetched the
+main Python distribution (try <http://www.python.org> or
+<ftp://ftp.python.org>).
+
+The following are the LaTeX source files:
+
+	api/*.tex	Python/C API Reference Manual
+	ext/*.tex	Extending and Embedding the Python Interpreter
+	lib/*.tex	Python Library Reference
+	mac/*.tex	Macintosh Library Modules
+	ref/*.tex	Python Reference Manual
+	tut/*.tex	Python Tutorial
+        inst/*.tex      Installing Python Modules
+        dist/*.tex      Distributing Python Modules
+
+Most use the "manual" document class and "python" package, derived from 
+the old "myformat.sty" style file.  The Macintosh Library Modules
+document uses the "howto" document class instead.  These contains many
+macro definitions useful in documenting Python, and set some style
+parameters.
+
+There's a Makefile to call LaTeX and the other utilities in the right
+order and the right number of times.  This will produce DVI files for
+each document made; to preview them, use xdvi.  PostScript is produced
+by the same Makefile target that produces the DVI files.  This uses
+the dvips tool.  Printing depends on local conventions; at our site,
+we use lpr.  For example:
+
+	make lib	# create lib.dvi and lib.ps
+	xdvi lib	# preview lib.dvi
+	lpr lib.ps	# print on default printer
+
+
+What if I find a bug?
+---------------------
+
+First, check that the bug is present in the online version of the
+documentation at <http://www.python.org/docs/>; we may have already
+fixed it.
+
+If we haven't, tell us about it.  We'd like the documentation to be
+complete and accurate, but have limited time.  If you discover any
+inconsistencies between the documentation and implementation, or just
+have suggestions as to how to improve the documentation, let is know!
+Send comments and patches to the Python Documentation Team:
+
+			   python-docs@python.org
+
+Thanks!
+
+
+What happened to the Macintosh chapter of the Python Library Reference?
+-----------------------------------------------------------------------
+
+The directory mac/ contains the LaTeX sources for the "Macintosh
+Library Modules" manual; this is built using the standard build
+targets, so check the proper output directory for your chosen format
+and paper size.
+
+
+What tools do I need?
+---------------------
+
+You need to install Python; some of the scripts used to produce the
+documentation are written in Python.  You don't need this
+documentation to install Python; instructions are included in the
+README file in the Python distribution.
+
+The simplest way to get the rest of the tools in the configuration we
+used is to install the teTeX TeX distribution, version 0.4 or 0.9.  More
+information is available on teTeX at <http://www.tug.org/tetex/>.
+This is a Unix-only TeX distribution at this time.  Note that the 0.9
+release is still in testing; this documentation release was tested
+with the 9 Feb 1999 release.  We'll be upgrading to the final version 
+when it becomes available.  Except for the PDF generation, there are
+no known problems with using the ("stable") teTeX 0.4 release.
+
+If you don't want to get teTeX, here is what you'll need:
+
+To create DVI, PDF, or PostScript files:
+
+	- LaTeX2e, 1995/12/01 or newer.  Older versions are likely to 
+	  choke.
+
+	- makeindex.  This is used to produce the indexes for the
+	  library reference and Python/C API reference.
+
+To create PDF files:
+
+	- pdflatex.  We used the one in the teTeX 0.9 distribution
+	  (pdfTeX version 3.14159-13b (Web2C 7.3beta4) at the time of
+	  this writing).  Versions even a couple of patchlevels
+	  earlier are highly likely to fail due to syntax changes for
+	  some of the pdftex primitives.
+
+To create PostScript files:
+
+	- dvips.  Most TeX installations include this.  If you don't
+	  have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
+
+To create info files:
+
+	Note that info support is currently being revised using new
+	conversion tools by Michael Ernst <mernst@cs.washington.edu>.
+
+	- makeinfo.  This is available from any GNU mirror.
+
+	- emacs or xemacs.  Emacs is available from the same place as
+	  makeinfo, and xemacs is available from ftp.xemacs.org.
+
+	- Perl.  Find the software at
+	  <http://language.perl.com/info/software.html>.
+
+To create HTML files:
+
+	- Perl 5.004_04 or newer.  Find the software at
+	  <http://language.perl.com/info/software.html>.
+
+	- LaTeX2HTML 98.2b6.  Older version will fail with the new
+	  directory layout.  Version 98.2b8 specifically does not
+	  work; it translates `` and '' to &ldquo; and &rdquo;, which
+	  are not supported by popular Web browsers.  This also screws 
+	  up code fragments.  ;-(  Releases are available at:
+	  <http://cdc-server.cdc.informatik.tu-darmstadt.de/~latex2html/>.
+	  Really new versions also don't work, but I'm not sure when
+	  things broke.
+
+
+What if Times fonts are not available?
+--------------------------------------
+
+As distributed, the LaTeX documents use PostScript Times fonts.  This
+is done since they are much better looking and produce smaller
+PostScript files.  If, however, your TeX installation does not support 
+them, they may be easily disabled.  Edit the file
+texiinputs/manual.cls and comment out the line that starts
+"\RequirePackage{times}" by inserting a "%" character at the beginning
+of the line.  An alternative is to install the right fonts and LaTeX
+style file.
+
+
+What if I want to use A4 paper?
+-------------------------------
+
+Instead of building the PostScript by giving the command "make", give
+the command "make PAPER=a4"; the output will be produced in the
+paper-a4/ subdirectory.
+
+
+Making HTML files
+-----------------
+
+The LaTeX documents can be converted to HTML using Nikos Drakos'
+LaTeX2HTML converter.  See the Makefile; after some twiddling, "make
+html" should do the trick.
+
+
+What else is in here?
+---------------------
+
+There is a new LaTeX document class called "howto".  This is used for
+the new series of Python HOWTO documents which is being coordinated by
+Andrew Kuchling <amk@acm.org>.  The file templates/howto.tex is a
+commented example which may be used a template.  A script to "do the
+right thing" to format a howto document is included as
+tools/mkhowto.  These documents can be formatted as HTML, PDF,
+PostScript, or ASCII files.  Support for this document class is
+still new, but is expected to evolve rapidly.  Use "mkhowto --help"
+for information on using the formatting tool.
+
+For authors of module documentation, there is a file
+templates/module.tex which may be used as a template for a module
+section.  This may be used in conjunction with either the howto or
+manual document class.  Create the documentation for a new module by
+copying the template to lib<mymodule>.tex and editing according to the 
+instructions in the comments.
+
+
+Copyright notice
+================
+
+The Python source is copyrighted, but you can freely use and copy it
+as long as you don't change or remove the copyright notice.
+\documentclass{manual}
+
+\title{Python/C API Reference Manual}
+
+\input{boilerplate}
+
+\makeindex			% tell \index to actually write the .idx file
+
+
+\begin{document}
+
+\maketitle
+
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+\input{copyright}
+
+\begin{abstract}
+
+\noindent
+This manual documents the API used by C and \Cpp{} programmers who
+want to write extension modules or embed Python.  It is a companion to
+\citetitle[../ext/ext.html]{Extending and Embedding the Python
+Interpreter}, which describes the general principles of extension
+writing but does not document the API functions in detail.
+
+\strong{Warning:} The current version of this document is incomplete.
+I hope that it is nevertheless useful.  I will continue to work on it,
+and release new versions from time to time, independent from Python
+source code releases.
+
+\end{abstract}
+
+\tableofcontents
+
+% XXX Consider moving all this back to ext.tex and giving api.tex
+% XXX a *really* short intro only.
+
+\chapter{Introduction \label{intro}}
+
+The Application Programmer's Interface to Python gives C and
+\Cpp{} programmers access to the Python interpreter at a variety of
+levels.  The API is equally usable from \Cpp{}, but for brevity it is
+generally referred to as the Python/C API.  There are two
+fundamentally different reasons for using the Python/C API.  The first
+reason is to write \emph{extension modules} for specific purposes;
+these are C modules that extend the Python interpreter.  This is
+probably the most common use.  The second reason is to use Python as a
+component in a larger application; this technique is generally
+referred to as \dfn{embedding} Python in an application.
+
+Writing an extension module is a relatively well-understood process, 
+where a ``cookbook'' approach works well.  There are several tools 
+that automate the process to some extent.  While people have embedded 
+Python in other applications since its early existence, the process of 
+embedding Python is less straightforward that writing an extension.  
+
+Many API functions are useful independent of whether you're embedding 
+or extending Python; moreover, most applications that embed Python 
+will need to provide a custom extension as well, so it's probably a 
+good idea to become familiar with writing an extension before 
+attempting to embed Python in a real application.
+
+
+\section{Include Files \label{includes}}
+
+All function, type and macro definitions needed to use the Python/C
+API are included in your code by the following line:
+
+\begin{verbatim}
+#include "Python.h"
+\end{verbatim}
+
+This implies inclusion of the following standard headers:
+\code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
+\code{<stdlib.h>} (if available).
+
+All user visible names defined by Python.h (except those defined by
+the included standard headers) have one of the prefixes \samp{Py} or
+\samp{_Py}.  Names beginning with \samp{_Py} are for internal use by
+the Python implementation and should not be used by extension writers.
+Structure member names do not have a reserved prefix.
+
+\strong{Important:} user code should never define names that begin
+with \samp{Py} or \samp{_Py}.  This confuses the reader, and
+jeopardizes the portability of the user code to future Python
+versions, which may define additional names beginning with one of
+these prefixes.
+
+The header files are typically installed with Python.  On \UNIX, these 
+are located in the directories
+\file{\envvar{prefix}/include/python\var{version}/} and
+\file{\envvar{exec_prefix}/include/python\var{version}/}, where
+\envvar{prefix} and \envvar{exec_prefix} are defined by the
+corresponding parameters to Python's \program{configure} script and
+\var{version} is \code{sys.version[:3]}.  On Windows, the headers are
+installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is
+the installation directory specified to the installer.
+
+To include the headers, place both directories (if different) on your
+compiler's search path for includes.  Do \emph{not} place the parent
+directories on the search path and then use
+\samp{\#include <python1.5/Python.h>}; this will break on
+multi-platform builds since the platform independent headers under
+\envvar{prefix} include the platform specific headers from
+\envvar{exec_prefix}.
+
+
+\section{Objects, Types and Reference Counts \label{objects}}
+
+Most Python/C API functions have one or more arguments as well as a
+return value of type \ctype{PyObject*}.  This type is a pointer
+to an opaque data type representing an arbitrary Python
+object.  Since all Python object types are treated the same way by the
+Python language in most situations (e.g., assignments, scope rules,
+and argument passing), it is only fitting that they should be
+represented by a single C type.  Almost all Python objects live on the
+heap: you never declare an automatic or static variable of type
+\ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can 
+be declared.  The sole exception are the type objects\obindex{type};
+since these must never be deallocated, they are typically static
+\ctype{PyTypeObject} objects.
+
+All Python objects (even Python integers) have a \dfn{type} and a
+\dfn{reference count}.  An object's type determines what kind of object 
+it is (e.g., an integer, a list, or a user-defined function; there are 
+many more as explained in the \citetitle[../ref/ref.html]{Python
+Reference Manual}).  For each of the well-known types there is a macro
+to check whether an object is of that type; for instance,
+\samp{PyList_Check(\var{a})} is true if (and only if) the object
+pointed to by \var{a} is a Python list.
+
+
+\subsection{Reference Counts \label{refcounts}}
+
+The reference count is important because today's computers have a 
+finite (and often severely limited) memory size; it counts how many 
+different places there are that have a reference to an object.  Such a 
+place could be another object, or a global (or static) C variable, or 
+a local variable in some C function.  When an object's reference count 
+becomes zero, the object is deallocated.  If it contains references to 
+other objects, their reference count is decremented.  Those other 
+objects may be deallocated in turn, if this decrement makes their 
+reference count become zero, and so on.  (There's an obvious problem 
+with objects that reference each other here; for now, the solution is 
+``don't do that.'')
+
+Reference counts are always manipulated explicitly.  The normal way is 
+to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to
+increment an object's reference count by one, and
+\cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by  
+one.  The \cfunction{Py_DECREF()} macro is considerably more complex
+than the incref one, since it must check whether the reference count
+becomes zero and then cause the object's deallocator to be called.
+The deallocator is a function pointer contained in the object's type
+structure.  The type-specific deallocator takes care of decrementing
+the reference counts for other objects contained in the object if this
+is a compound object type, such as a list, as well as performing any
+additional finalization that's needed.  There's no chance that the
+reference count can overflow; at least as many bits are used to hold
+the reference count as there are distinct memory locations in virtual
+memory (assuming \code{sizeof(long) >= sizeof(char*)}).  Thus, the
+reference count increment is a simple operation.
+
+It is not necessary to increment an object's reference count for every 
+local variable that contains a pointer to an object.  In theory, the 
+object's reference count goes up by one when the variable is made to 
+point to it and it goes down by one when the variable goes out of 
+scope.  However, these two cancel each other out, so at the end the 
+reference count hasn't changed.  The only real reason to use the 
+reference count is to prevent the object from being deallocated as 
+long as our variable is pointing to it.  If we know that there is at 
+least one other reference to the object that lives at least as long as 
+our variable, there is no need to increment the reference count 
+temporarily.  An important situation where this arises is in objects 
+that are passed as arguments to C functions in an extension module 
+that are called from Python; the call mechanism guarantees to hold a 
+reference to every argument for the duration of the call.
+
+However, a common pitfall is to extract an object from a list and
+hold on to it for a while without incrementing its reference count.
+Some other operation might conceivably remove the object from the
+list, decrementing its reference count and possible deallocating it.
+The real danger is that innocent-looking operations may invoke
+arbitrary Python code which could do this; there is a code path which
+allows control to flow back to the user from a \cfunction{Py_DECREF()},
+so almost any operation is potentially dangerous.
+
+A safe approach is to always use the generic operations (functions 
+whose name begins with \samp{PyObject_}, \samp{PyNumber_},
+\samp{PySequence_} or \samp{PyMapping_}).  These operations always
+increment the reference count of the object they return.  This leaves
+the caller with the responsibility to call
+\cfunction{Py_DECREF()} when they are done with the result; this soon
+becomes second nature.
+
+
+\subsubsection{Reference Count Details \label{refcountDetails}}
+
+The reference count behavior of functions in the Python/C API is best 
+explained in terms of \emph{ownership of references}.  Note that we 
+talk of owning references, never of owning objects; objects are always 
+shared!  When a function owns a reference, it has to dispose of it 
+properly --- either by passing ownership on (usually to its caller) or 
+by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}.  When
+a function passes ownership of a reference on to its caller, the
+caller is said to receive a \emph{new} reference.  When no ownership
+is transferred, the caller is said to \emph{borrow} the reference.
+Nothing needs to be done for a borrowed reference.
+
+Conversely, when calling a function passes it a reference to an 
+object, there are two possibilities: the function \emph{steals} a 
+reference to the object, or it does not.  Few functions steal 
+references; the two notable exceptions are
+\cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and
+\cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which 
+steal a reference to the item (but not to the tuple or list into which
+the item is put!).  These functions were designed to steal a reference
+because of a common idiom for populating a tuple or list with newly
+created objects; for example, the code to create the tuple \code{(1,
+2, "three")} could look like this (forgetting about error handling for
+the moment; a better way to code this is shown below):
+
+\begin{verbatim}
+PyObject *t;
+
+t = PyTuple_New(3);
+PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
+PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
+PyTuple_SetItem(t, 2, PyString_FromString("three"));
+\end{verbatim}
+
+Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
+set tuple items; \cfunction{PySequence_SetItem()} and
+\cfunction{PyObject_SetItem()} refuse to do this since tuples are an
+immutable data type.  You should only use
+\cfunction{PyTuple_SetItem()} for tuples that you are creating
+yourself.
+
+Equivalent code for populating a list can be written using 
+\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.  Such code
+can also use \cfunction{PySequence_SetItem()}; this illustrates the
+difference between the two (the extra \cfunction{Py_DECREF()} calls):
+
+\begin{verbatim}
+PyObject *l, *x;
+
+l = PyList_New(3);
+x = PyInt_FromLong(1L);
+PySequence_SetItem(l, 0, x); Py_DECREF(x);
+x = PyInt_FromLong(2L);
+PySequence_SetItem(l, 1, x); Py_DECREF(x);
+x = PyString_FromString("three");
+PySequence_SetItem(l, 2, x); Py_DECREF(x);
+\end{verbatim}
+
+You might find it strange that the ``recommended'' approach takes more
+code.  However, in practice, you will rarely use these ways of
+creating and populating a tuple or list.  There's a generic function,
+\cfunction{Py_BuildValue()}, that can create most common objects from
+C values, directed by a \dfn{format string}.  For example, the
+above two blocks of code could be replaced by the following (which
+also takes care of the error checking):
+
+\begin{verbatim}
+PyObject *t, *l;
+
+t = Py_BuildValue("(iis)", 1, 2, "three");
+l = Py_BuildValue("[iis]", 1, 2, "three");
+\end{verbatim}
+
+It is much more common to use \cfunction{PyObject_SetItem()} and
+friends with items whose references you are only borrowing, like
+arguments that were passed in to the function you are writing.  In
+that case, their behaviour regarding reference counts is much saner,
+since you don't have to increment a reference count so you can give a
+reference away (``have it be stolen'').  For example, this function
+sets all items of a list (actually, any mutable sequence) to a given
+item:
+
+\begin{verbatim}
+int set_all(PyObject *target, PyObject *item)
+{
+    int i, n;
+
+    n = PyObject_Length(target);
+    if (n < 0)
+        return -1;
+    for (i = 0; i < n; i++) {
+        if (PyObject_SetItem(target, i, item) < 0)
+            return -1;
+    }
+    return 0;
+}
+\end{verbatim}
+\ttindex{set_all()}
+
+The situation is slightly different for function return values.  
+While passing a reference to most functions does not change your 
+ownership responsibilities for that reference, many functions that 
+return a referece to an object give you ownership of the reference.
+The reason is simple: in many cases, the returned object is created 
+on the fly, and the reference you get is the only reference to the 
+object.  Therefore, the generic functions that return object 
+references, like \cfunction{PyObject_GetItem()} and 
+\cfunction{PySequence_GetItem()}, always return a new reference (i.e.,
+the  caller becomes the owner of the reference).
+
+It is important to realize that whether you own a reference returned 
+by a function depends on which function you call only --- \emph{the
+plumage} (i.e., the type of the type of the object passed as an
+argument to the function) \emph{doesn't enter into it!}  Thus, if you 
+extract an item from a list using \cfunction{PyList_GetItem()}, you
+don't own the reference --- but if you obtain the same item from the
+same list using \cfunction{PySequence_GetItem()} (which happens to
+take exactly the same arguments), you do own a reference to the
+returned object.
+
+Here is an example of how you could write a function that computes the
+sum of the items in a list of integers; once using 
+\cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using
+\cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}.
+
+\begin{verbatim}
+long sum_list(PyObject *list)
+{
+    int i, n;
+    long total = 0;
+    PyObject *item;
+
+    n = PyList_Size(list);
+    if (n < 0)
+        return -1; /* Not a list */
+    for (i = 0; i < n; i++) {
+        item = PyList_GetItem(list, i); /* Can't fail */
+        if (!PyInt_Check(item)) continue; /* Skip non-integers */
+        total += PyInt_AsLong(item);
+    }
+    return total;
+}
+\end{verbatim}
+\ttindex{sum_list()}
+
+\begin{verbatim}
+long sum_sequence(PyObject *sequence)
+{
+    int i, n;
+    long total = 0;
+    PyObject *item;
+    n = PySequence_Length(sequence);
+    if (n < 0)
+        return -1; /* Has no length */
+    for (i = 0; i < n; i++) {
+        item = PySequence_GetItem(sequence, i);
+        if (item == NULL)
+            return -1; /* Not a sequence, or other failure */
+        if (PyInt_Check(item))
+            total += PyInt_AsLong(item);
+        Py_DECREF(item); /* Discard reference ownership */
+    }
+    return total;
+}
+\end{verbatim}
+\ttindex{sum_sequence()}
+
+
+\subsection{Types \label{types}}
+
+There are few other data types that play a significant role in 
+the Python/C API; most are simple C types such as \ctype{int}, 
+\ctype{long}, \ctype{double} and \ctype{char*}.  A few structure types 
+are used to describe static tables used to list the functions exported 
+by a module or the data attributes of a new object type, and another
+is used to describe the value of a complex number.  These will 
+be discussed together with the functions that use them.
+
+
+\section{Exceptions \label{exceptions}}
+
+The Python programmer only needs to deal with exceptions if specific 
+error handling is required; unhandled exceptions are automatically 
+propagated to the caller, then to the caller's caller, and so on, until
+they reach the top-level interpreter, where they are reported to the 
+user accompanied by a stack traceback.
+
+For C programmers, however, error checking always has to be explicit.  
+All functions in the Python/C API can raise exceptions, unless an 
+explicit claim is made otherwise in a function's documentation.  In 
+general, when a function encounters an error, it sets an exception, 
+discards any object references that it owns, and returns an 
+error indicator --- usually \NULL{} or \code{-1}.  A few functions 
+return a Boolean true/false result, with false indicating an error.
+Very few functions return no explicit error indicator or have an 
+ambiguous return value, and require explicit testing for errors with 
+\cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}.
+
+Exception state is maintained in per-thread storage (this is 
+equivalent to using global storage in an unthreaded application).  A 
+thread can be in one of two states: an exception has occurred, or not.
+The function \cfunction{PyErr_Occurred()} can be used to check for
+this: it returns a borrowed reference to the exception type object
+when an exception has occurred, and \NULL{} otherwise.  There are a
+number of functions to set the exception state:
+\cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most
+common (though not the most general) function to set the exception
+state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the
+exception state.
+
+The full exception state consists of three objects (all of which can 
+be \NULL{}): the exception type, the corresponding exception 
+value, and the traceback.  These have the same meanings as the Python
+\withsubitem{(in module sys)}{
+  \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
+objects \code{sys.exc_type}, \code{sys.exc_value}, and
+\code{sys.exc_traceback}; however, they are not the same: the Python
+objects represent the last exception being handled by a Python 
+\keyword{try} \ldots\ \keyword{except} statement, while the C level
+exception state only exists while an exception is being passed on
+between C functions until it reaches the Python bytecode interpreter's 
+main loop, which takes care of transferring it to \code{sys.exc_type}
+and friends.
+
+Note that starting with Python 1.5, the preferred, thread-safe way to 
+access the exception state from Python code is to call the function
+\withsubitem{(in module sys)}{\ttindex{exc_info()}}
+\function{sys.exc_info()}, which returns the per-thread exception state 
+for Python code.  Also, the semantics of both ways to access the 
+exception state have changed so that a function which catches an 
+exception will save and restore its thread's exception state so as to 
+preserve the exception state of its caller.  This prevents common bugs 
+in exception handling code caused by an innocent-looking function 
+overwriting the exception being handled; it also reduces the often 
+unwanted lifetime extension for objects that are referenced by the 
+stack frames in the traceback.
+
+As a general principle, a function that calls another function to 
+perform some task should check whether the called function raised an 
+exception, and if so, pass the exception state on to its caller.  It 
+should discard any object references that it owns, and return an 
+error indicator, but it should \emph{not} set another exception ---
+that would overwrite the exception that was just raised, and lose
+important information about the exact cause of the error.
+
+A simple example of detecting exceptions and passing them on is shown
+in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example
+above.  It so happens that that example doesn't need to clean up any
+owned references when it detects an error.  The following example
+function shows some error cleanup.  First, to remind you why you like
+Python, we show the equivalent Python code:
+
+\begin{verbatim}
+def incr_item(dict, key):
+    try:
+        item = dict[key]
+    except KeyError:
+        item = 0
+    return item + 1
+\end{verbatim}
+\ttindex{incr_item()}
+
+Here is the corresponding C code, in all its glory:
+
+\begin{verbatim}
+int incr_item(PyObject *dict, PyObject *key)
+{
+    /* Objects all initialized to NULL for Py_XDECREF */
+    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
+    int rv = -1; /* Return value initialized to -1 (failure) */
+
+    item = PyObject_GetItem(dict, key);
+    if (item == NULL) {
+        /* Handle KeyError only: */
+        if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error;
+
+        /* Clear the error and use zero: */
+        PyErr_Clear();
+        item = PyInt_FromLong(0L);
+        if (item == NULL) goto error;
+    }
+
+    const_one = PyInt_FromLong(1L);
+    if (const_one == NULL) goto error;
+
+    incremented_item = PyNumber_Add(item, const_one);
+    if (incremented_item == NULL) goto error;
+
+    if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
+    rv = 0; /* Success */
+    /* Continue with cleanup code */
+
+ error:
+    /* Cleanup code, shared by success and failure path */
+
+    /* Use Py_XDECREF() to ignore NULL references */
+    Py_XDECREF(item);
+    Py_XDECREF(const_one);
+    Py_XDECREF(incremented_item);
+
+    return rv; /* -1 for error, 0 for success */
+}
+\end{verbatim}
+\ttindex{incr_item()}
+
+This example represents an endorsed use of the \keyword{goto} statement 
+in C!  It illustrates the use of
+\cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and
+\cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to
+handle specific exceptions, and the use of
+\cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to
+dispose of owned references that may be \NULL{} (note the
+\character{X} in the name; \cfunction{Py_DECREF()} would crash when
+confronted with a \NULL{} reference).  It is important that the
+variables used to hold owned references are initialized to \NULL{} for
+this to work; likewise, the proposed return value is initialized to
+\code{-1} (failure) and only set to success after the final call made
+is successful.
+
+
+\section{Embedding Python \label{embedding}}
+
+The one important task that only embedders (as opposed to extension
+writers) of the Python interpreter have to worry about is the
+initialization, and possibly the finalization, of the Python
+interpreter.  Most functionality of the interpreter can only be used
+after the interpreter has been initialized.
+
+The basic initialization function is
+\cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
+This initializes the table of loaded modules, and creates the
+fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
+\module{__main__}\refbimodindex{__main__} and 
+\module{sys}\refbimodindex{sys}.  It also initializes the module
+search path (\code{sys.path}).%
+\indexiii{module}{search}{path}
+\withsubitem{(in module sys)}{\ttindex{path}}
+
+\cfunction{Py_Initialize()} does not set the ``script argument list'' 
+(\code{sys.argv}).  If this variable is needed by Python code that 
+will be executed later, it must be set explicitly with a call to 
+\code{PySys_SetArgv(\var{argc},
+\var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to
+\cfunction{Py_Initialize()}.
+
+On most systems (in particular, on \UNIX{} and Windows, although the
+details are slightly different),
+\cfunction{Py_Initialize()} calculates the module search path based
+upon its best guess for the location of the standard Python
+interpreter executable, assuming that the Python library is found in a
+fixed location relative to the Python interpreter executable.  In
+particular, it looks for a directory named
+\file{lib/python1.5} (replacing \file{1.5} with the current
+interpreter version) relative to the parent directory where the
+executable named \file{python} is found on the shell command search
+path (the environment variable \envvar{PATH}).
+
+For instance, if the Python executable is found in
+\file{/usr/local/bin/python}, it will assume that the libraries are in
+\file{/usr/local/lib/python1.5}.  (In fact, this particular path
+is also the ``fallback'' location, used when no executable file named
+\file{python} is found along \envvar{PATH}.)  The user can override
+this behavior by setting the environment variable \envvar{PYTHONHOME},
+or insert additional directories in front of the standard path by
+setting \envvar{PYTHONPATH}.
+
+The embedding application can steer the search by calling 
+\code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling 
+\cfunction{Py_Initialize()}.  Note that \envvar{PYTHONHOME} still
+overrides this and \envvar{PYTHONPATH} is still inserted in front of
+the standard path.  An application that requires total control has to
+provide its own implementation of
+\cfunction{Py_GetPath()}\ttindex{Py_GetPath()},
+\cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()},
+\cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and
+\cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all
+defined in \file{Modules/getpath.c}).
+
+Sometimes, it is desirable to ``uninitialize'' Python.  For instance, 
+the application may want to start over (make another call to 
+\cfunction{Py_Initialize()}) or the application is simply done with its 
+use of Python and wants to free all memory allocated by Python.  This
+can be accomplished by calling \cfunction{Py_Finalize()}.  The function
+\cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns
+true if Python is currently in the initialized state.  More
+information about these functions is given in a later chapter.
+
+
+\chapter{The Very High Level Layer \label{veryhigh}}
+
+The functions in this chapter will let you execute Python source code
+given in a file or a buffer, but they will not let you interact in a
+more detailed way with the interpreter.
+
+Several of these functions accept a start symbol from the grammar as a 
+parameter.  The available start symbols are \constant{Py_eval_input},
+\constant{Py_file_input}, and \constant{Py_single_input}.  These are
+described following the functions which accept them as parameters.
+
+\begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
+  If \var{fp} refers to a file associated with an interactive device
+  (console or terminal input or \UNIX{} pseudo-terminal), return the
+  value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
+  result of \cfunction{PyRun_SimpleFile()}.  If \var{filename} is
+  \NULL{}, this function uses \code{"???"} as the filename.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
+  Executes the Python source code from \var{command} in the
+  \module{__main__} module.  If \module{__main__} does not already
+  exist, it is created.  Returns \code{0} on success or \code{-1} if
+  an exception was raised.  If there was an error, there is no way to
+  get the exception information.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
+  Similar to \cfunction{PyRun_SimpleString()}, but the Python source
+  code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
+                                                             int start}
+  Parse Python source code from \var{str} using the start token
+  \var{start}.  The result can be used to create a code object which
+  can be evaluated efficiently.  This is useful if a code fragment
+  must be evaluated many times.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
+                                 char *filename, int start}
+  Similar to \cfunction{PyParser_SimpleParseString()}, but the Python
+  source code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
+                                           PyObject *globals,
+                                           PyObject *locals}
+  Execute Python source code from \var{str} in the context specified
+  by the dictionaries \var{globals} and \var{locals}.  The parameter
+  \var{start} specifies the start token that should be used to parse
+  the source code.
+
+  Returns the result of executing the code as a Python object, or
+  \NULL{} if an exception was raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
+                                         int start, PyObject *globals,
+                                         PyObject *locals}
+  Similar to \cfunction{PyRun_String()}, but the Python source code is 
+  read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
+                                               int start}
+  Parse and compile the Python source code in \var{str}, returning the 
+  resulting code object.  The start token is given by \var{start};
+  this can be used to constrain the code which can be compiled and should
+  be \constant{Py_eval_input}, \constant{Py_file_input}, or
+  \constant{Py_single_input}.  The filename specified by
+  \var{filename} is used to construct the code object and may appear
+  in tracebacks or \exception{SyntaxError} exception messages.  This
+  returns \NULL{} if the code cannot be parsed or compiled.
+\end{cfuncdesc}
+
+\begin{cvardesc}{int}{Py_eval_input}
+  The start symbol from the Python grammar for isolated expressions;
+  for use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{Py_file_input}
+  The start symbol from the Python grammar for sequences of statements
+  as read from a file or other source; for use with
+  \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.  This is
+  the symbol to use when compiling arbitrarily long Python source code.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{Py_single_input}
+  The start symbol from the Python grammar for a single statement; for 
+  use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
+  This is the symbol used for the interactive interpreter loop.
+\end{cvardesc}
+
+
+\chapter{Reference Counting \label{countingRefs}}
+
+The macros in this section are used for managing reference counts
+of Python objects.
+
+\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
+Increment the reference count for object \var{o}.  The object must
+not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
+\cfunction{Py_XINCREF()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
+Increment the reference count for object \var{o}.  The object may be
+\NULL{}, in which case the macro has no effect.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
+Decrement the reference count for object \var{o}.  The object must
+not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
+\cfunction{Py_XDECREF()}.  If the reference count reaches zero, the
+object's type's deallocation function (which must not be \NULL{}) is
+invoked.
+
+\strong{Warning:} The deallocation function can cause arbitrary Python
+code to be invoked (e.g. when a class instance with a
+\method{__del__()} method is deallocated).  While exceptions in such
+code are not propagated, the executed code has free access to all
+Python global variables.  This means that any object that is reachable
+from a global variable should be in a consistent state before
+\cfunction{Py_DECREF()} is invoked.  For example, code to delete an
+object from a list should copy a reference to the deleted object in a
+temporary variable, update the list data structure, and then call
+\cfunction{Py_DECREF()} for the temporary variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
+Decrement the reference count for object \var{o}.  The object may be
+\NULL{}, in which case the macro has no effect; otherwise the effect
+is the same as for \cfunction{Py_DECREF()}, and the same warning
+applies.
+\end{cfuncdesc}
+
+The following functions or macros are only for use within the
+interpreter core: \cfunction{_Py_Dealloc()},
+\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
+well as the global variable \cdata{_Py_RefTotal}.
+
+
+\chapter{Exception Handling \label{exceptionHandling}}
+
+The functions described in this chapter will let you handle and raise Python
+exceptions.  It is important to understand some of the basics of
+Python exception handling.  It works somewhat like the
+\UNIX{} \cdata{errno} variable: there is a global indicator (per
+thread) of the last error that occurred.  Most functions don't clear
+this on success, but will set it to indicate the cause of the error on
+failure.  Most functions also return an error indicator, usually
+\NULL{} if they are supposed to return a pointer, or \code{-1} if they
+return an integer (exception: the \cfunction{PyArg_Parse*()} functions
+return \code{1} for success and \code{0} for failure).  When a
+function must fail because some function it called failed, it
+generally doesn't set the error indicator; the function it called
+already set it.
+
+The error indicator consists of three Python objects corresponding to
+\withsubitem{(in module sys)}{
+  \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
+the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
+\code{sys.exc_traceback}.  API functions exist to interact with the
+error indicator in various ways.  There is a separate error indicator
+for each thread.
+
+% XXX Order of these should be more thoughtful.
+% Either alphabetical or some kind of structure.
+
+\begin{cfuncdesc}{void}{PyErr_Print}{}
+Print a standard traceback to \code{sys.stderr} and clear the error
+indicator.  Call this function only when the error indicator is set.
+(Otherwise it will cause a fatal error!)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
+Test whether the error indicator is set.  If set, return the exception
+\emph{type} (the first argument to the last call to one of the
+\cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}).  If
+not set, return \NULL{}.  You do not own a reference to the return
+value, so you do not need to \cfunction{Py_DECREF()} it.
+\strong{Note:}  Do not compare the return value to a specific
+exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
+below.  (The comparison could easily fail since the exception may be
+an instance instead of a class, in the case of a class exception, or
+it may the a subclass of the expected exception.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
+Equivalent to
+\samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
+This should only be called when an exception is actually set; a memory 
+access violation will occur if no exception has been raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
+Return true if the \var{given} exception matches the exception in
+\var{exc}.  If \var{exc} is a class object, this also returns true
+when \var{given} is an instance of a subclass.  If \var{exc} is a tuple, all
+exceptions in the tuple (and recursively in subtuples) are searched
+for a match.  If \var{given} is \NULL, a memory access violation will
+occur.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
+Under certain circumstances, the values returned by
+\cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
+\code{*\var{exc}} is a class object but \code{*\var{val}} is not an
+instance of the  same class.  This function can be used to instantiate
+the class in that case.  If the values are already normalized, nothing
+happens.  The delayed normalization is implemented to improve
+performance.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_Clear}{}
+Clear the error indicator.  If the error indicator is not set, there
+is no effect.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue,
+                                     PyObject **ptraceback}
+Retrieve the error indicator into three variables whose addresses are
+passed.  If the error indicator is not set, set all three variables to
+\NULL{}.  If it is set, it will be cleared and you own a reference to
+each object retrieved.  The value and traceback object may be
+\NULL{} even when the type object is not.  \strong{Note:}  This
+function is normally only used by code that needs to handle exceptions
+or by code that needs to save and restore the error indicator
+temporarily.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, PyObject *traceback}
+Set  the error indicator from the three objects.  If the error
+indicator is already set, it is cleared first.  If the objects are
+\NULL{}, the error indicator is cleared.  Do not pass a \NULL{} type
+and non-\NULL{} value or traceback.  The exception type should be a
+string or class; if it is a class, the value should be an instance of
+that class.  Do not pass an invalid exception type or value.
+(Violating these rules will cause subtle problems later.)  This call
+takes away a reference to each object, i.e. you must own a reference
+to each object before the call and after the call you no longer own
+these references.  (If you don't understand this, don't use this
+function.  I warned you.)  \strong{Note:}  This function is normally
+only used by code that needs to save and restore the error indicator
+temporarily.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
+This is the most common way to set the error indicator.  The first
+argument specifies the exception type; it is normally one of the
+standard exceptions, e.g. \cdata{PyExc_RuntimeError}.  You need not
+increment its reference count.  The second argument is an error
+message; it is converted to a string object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
+This function is similar to \cfunction{PyErr_SetString()} but lets you
+specify an arbitrary Python object for the ``value'' of the exception.
+You need not increment its reference count.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
+                                           const char *format, ...}
+This function sets the error indicator using a printf-style format
+string.  The first argument specifies the exception type and the
+second argument specifies the format string for the exception.  Any
+subsequent arguments are converted to output by the C library's
+\cfunction{vsprintf()} function.  The buffer used internally by
+\cfunction{PyErr_Format()} is 500 bytes long.  The caller is
+responsible for guaranteeing that the formatted output does not
+overflow the buffer.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
+This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
+This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
+\var{message})}, where \var{message} indicates that a built-in operation
+was invoked with an illegal argument.  It is mostly for internal use.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
+This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
+returns \NULL{} so an object allocation function can write
+\samp{return PyErr_NoMemory();} when it runs out of memory.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
+This is a convenience function to raise an exception when a C library
+function has returned an error and set the C variable \cdata{errno}.
+It constructs a tuple object whose first item is the integer
+\cdata{errno} value and whose second item is the corresponding error
+message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and
+then calls
+\samp{PyErr_SetObject(\var{type}, \var{object})}.  On \UNIX{}, when
+the \cdata{errno} value is \constant{EINTR}, indicating an interrupted
+system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
+the error indicator, leaves it set to that.  The function always
+returns \NULL{}, so a wrapper function around a system call can write 
+\samp{return PyErr_SetFromErrno();} when  the system call returns an
+error.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
+This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
+\var{message})}, where \var{message} indicates that an internal
+operation (e.g. a Python/C API function) was invoked with an illegal
+argument.  It is mostly for internal use.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
+This function interacts with Python's signal handling.  It checks
+whether a signal has been sent to the processes and if so, invokes the
+corresponding signal handler.  If the
+\module{signal}\refbimodindex{signal} module is supported, this can
+invoke a signal handler written in Python.  In all cases, the default
+effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
+\withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
+\exception{KeyboardInterrupt} exception.  If an exception is raised the 
+error indicator is set and the function returns \code{1}; otherwise
+the function returns \code{0}.  The error indicator may or may not be
+cleared if it was previously set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
+This function is obsolete.  It simulates the effect of a
+\constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
+\cfunction{PyErr_CheckSignals()} is called,
+\withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
+\exception{KeyboardInterrupt} will be raised.
+It may be called without holding the interpreter lock.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
+                                                 PyObject *base,
+                                                 PyObject *dict}
+This utility function creates and returns a new exception object.  The
+\var{name} argument must be the name of the new exception, a C string
+of the form \code{module.class}.  The \var{base} and
+\var{dict} arguments are normally \NULL{}.  Normally, this creates a
+class object derived from the root for all exceptions, the built-in
+name \exception{Exception} (accessible in C as
+\cdata{PyExc_Exception}).  In this case the \member{__module__}
+attribute of the new class is set to the first part (up to the last
+dot) of the \var{name} argument, and the class name is set to the last
+part (after the last dot).  The
+\var{base} argument can be used to specify an alternate base class.
+The \var{dict} argument can be used to specify a dictionary of class
+variables and methods.
+\end{cfuncdesc}
+
+
+\section{Standard Exceptions \label{standardExceptions}}
+
+All standard Python exceptions are available as global variables whose
+names are \samp{PyExc_} followed by the Python exception name.  These
+have the type \ctype{PyObject*}; they are all class objects.  For
+completeness, here are all the variables:
+
+\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
+  \lineiii{PyExc_Exception}{\exception{Exception}}{(1)}
+  \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)}
+  \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)}
+  \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)}
+  \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
+  \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
+  \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
+  \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)}
+  \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
+  \lineiii{PyExc_IOError}{\exception{IOError}}{}
+  \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
+  \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
+  \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
+  \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
+  \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
+  \lineiii{PyExc_NameError}{\exception{NameError}}{}
+  \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
+  \lineiii{PyExc_OSError}{\exception{OSError}}{}
+  \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
+  \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
+  \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
+  \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
+  \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
+  \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
+  \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
+  \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
+\end{tableiii}
+
+\noindent
+Note:
+\begin{description}
+\item[(1)]
+  This is a base class for other standard exceptions.  If the
+  \code{-X} interpreter option is used, these will be tuples
+  containing the string exceptions which would have otherwise been
+  subclasses.
+\end{description}
+
+
+\section{Deprecation of String Exceptions}
+
+The \code{-X} command-line option will be removed in Python 1.6.  All
+exceptions built into Python or provided in the standard library will
+\withsubitem{(built-in exception)}{\ttindex{Exception}}
+be classes derived from \exception{Exception}.
+
+String exceptions will still be supported in the interpreter to allow
+existing code to run unmodified, but this will also change in a future 
+release.
+
+
+\chapter{Utilities \label{utilities}}
+
+The functions in this chapter perform various utility tasks, such as
+parsing function arguments and constructing Python values from C
+values.
+
+\section{OS Utilities \label{os}}
+
+\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
+Return true (nonzero) if the standard I/O file \var{fp} with name
+\var{filename} is deemed interactive.  This is the case for files for
+which \samp{isatty(fileno(\var{fp}))} is true.  If the global flag
+\cdata{Py_InteractiveFlag} is true, this function also returns true if
+the \var{name} pointer is \NULL{} or if the name is equal to one of
+the strings \code{"<stdin>"} or \code{"???"}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
+Return the time of last modification of the file \var{filename}.
+The result is encoded in the same way as the timestamp returned by
+the standard C library function \cfunction{time()}.
+\end{cfuncdesc}
+
+
+\section{Process Control \label{processControl}}
+
+\begin{cfuncdesc}{void}{Py_FatalError}{char *message}
+Print a fatal error message and kill the process.  No cleanup is
+performed.  This function should only be invoked when a condition is
+detected that would make it dangerous to continue using the Python
+interpreter; e.g., when the object administration appears to be
+corrupted.  On \UNIX{}, the standard C library function
+\cfunction{abort()}\ttindex{abort()} is called which will attempt to
+produce a \file{core} file.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Exit}{int status}
+Exit the current process.  This calls
+\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
+then calls the standard C library function
+\code{exit(\var{status})}\ttindex{exit()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
+Register a cleanup function to be called by
+\cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
+The cleanup function will be called with no arguments and should
+return no value.  At most 32 \index{cleanup functions}cleanup
+functions can be registered.
+When the registration is successful, \cfunction{Py_AtExit()} returns
+\code{0}; on failure, it returns \code{-1}.  The cleanup function
+registered last is called first.  Each cleanup function will be called
+at most once.  Since Python's internal finallization will have
+completed before the cleanup function, no Python APIs should be called
+by \var{func}.
+\end{cfuncdesc}
+
+
+\section{Importing Modules \label{importing}}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name}
+This is a simplified interface to
+\cfunction{PyImport_ImportModuleEx()} below, leaving the
+\var{globals} and \var{locals} arguments set to \NULL{}.  When the
+\var{name} argument contains a dot (i.e., when it specifies a
+submodule of a package), the \var{fromlist} argument is set to the
+list \code{['*']} so that the return value is the named module rather
+than the top-level package containing it as would otherwise be the
+case.  (Unfortunately, this has an additional side effect when
+\var{name} in fact specifies a subpackage instead of a submodule: the
+submodules specified in the package's \code{__all__} variable are
+\index{package variable!\code{__all__}}
+\withsubitem{(package variable)}{\ttindex{__all__}}loaded.)  Return a
+new reference to the imported module, or
+\NULL{} with an exception set on failure (the module may still be
+created in this case --- examine \code{sys.modules} to find out).
+\withsubitem{(in module sys)}{\ttindex{modules}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
+Import a module.  This is best described by referring to the built-in
+Python function \function{__import__()}\bifuncindex{__import__}, as
+the standard \function{__import__()} function calls this function
+directly.
+
+The return value is a new reference to the imported module or
+top-level package, or \NULL{} with an exception set on failure
+(the module may still be created in this case).  Like for
+\function{__import__()}, the return value when a submodule of a
+package was requested is normally the top-level package, unless a
+non-empty \var{fromlist} was given.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
+This is a higher-level interface that calls the current ``import hook
+function''.  It invokes the \function{__import__()} function from the
+\code{__builtins__} of the current globals.  This means that the
+import is done using whatever import hooks are installed in the
+current environment, e.g. by \module{rexec}\refstmodindex{rexec} or
+\module{ihooks}\refstmodindex{ihooks}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m}
+Reload a module.  This is best described by referring to the built-in
+Python function \function{reload()}\bifuncindex{reload}, as the standard
+\function{reload()} function calls this function directly.  Return a
+new reference to the reloaded module, or \NULL{} with an exception set
+on failure (the module still exists in this case).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{char *name}
+Return the module object corresponding to a module name.  The
+\var{name} argument may be of the form \code{package.module}).  First
+check the modules dictionary if there's one there, and if not, create
+a new one and insert in in the modules dictionary.
+Warning: this function does not load or import the module; if the
+module wasn't already loaded, you will get an empty module object.
+Use \cfunction{PyImport_ImportModule()} or one of its variants to
+import a module.
+Return \NULL{} with an exception set on failure.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co}
+Given a module name (possibly of the form \code{package.module}) and a
+code object read from a Python bytecode file or obtained from the
+built-in function \function{compile()}\bifuncindex{compile}, load the
+module.  Return a new reference to the module object, or \NULL{} with
+an exception set if an error occurred (the module may still be created
+in this case).  (This function would reload the module if it was
+already imported.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
+Return the magic number for Python bytecode files (a.k.a.
+\file{.pyc} and \file{.pyo} files).  The magic number should be
+present in the first four bytes of the bytecode file, in little-endian
+byte order.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
+Return the dictionary used for the module administration
+(a.k.a. \code{sys.modules}).  Note that this is a per-interpreter
+variable.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Init}{}
+Initialize the import mechanism.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
+Empty the module table.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{_PyImport_Fini}{}
+Finalize the import mechanism.  For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
+For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
+For internal use only.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
+Load a frozen module.  Return \code{1} for success, \code{0} if the
+module is not found, and \code{-1} with an exception set if the
+initialization failed.  To access the imported module on a successful
+load, use \cfunction{PyImport_ImportModule()}.
+(Note the misnomer --- this function would reload the module if it was
+already imported.)
+\end{cfuncdesc}
+
+\begin{ctypedesc}[_frozen]{struct _frozen}
+This is the structure type definition for frozen module descriptors,
+as generated by the \program{freeze}\index{freeze utility} utility
+(see \file{Tools/freeze/} in the Python source distribution).  Its
+definition is:
+
+\begin{verbatim}
+struct _frozen {
+    char *name;
+    unsigned char *code;
+    int size;
+};
+\end{verbatim}
+\end{ctypedesc}
+
+\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
+This pointer is initialized to point to an array of \ctype{struct
+_frozen} records, terminated by one whose members are all
+\NULL{} or zero.  When a frozen module is imported, it is searched in
+this table.  Third-party code could play tricks with this to provide a 
+dynamically created collection of frozen modules.
+\end{cvardesc}
+
+
+\chapter{Abstract Objects Layer \label{abstract}}
+
+The functions in this chapter interact with Python objects regardless
+of their type, or with wide classes of object types (e.g. all
+numerical types, or all sequence types).  When used on object types
+for which they do not apply, they will raise a Python exception.
+
+\section{Object Protocol \label{object}}
+
+\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
+Print an object \var{o}, on file \var{fp}.  Returns \code{-1} on error.
+The flags argument is used to enable certain printing options.  The
+only option currently supported is \constant{Py_PRINT_RAW}; if given,
+the \function{str()} of the object is written instead of the
+\function{repr()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
+Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
+\code{0} otherwise.  This is equivalent to the Python expression
+\samp{hasattr(\var{o}, \var{attr_name})}.
+This function always succeeds.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
+                                                     char *attr_name}
+Retrieve an attribute named \var{attr_name} from object \var{o}.
+Returns the attribute value on success, or \NULL{} on failure.
+This is the equivalent of the Python expression
+\samp{\var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
+Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
+\code{0} otherwise.  This is equivalent to the Python expression
+\samp{hasattr(\var{o}, \var{attr_name})}. 
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o,
+                                               PyObject *attr_name}
+Retrieve an attribute named \var{attr_name} from object \var{o}.
+Returns the attribute value on success, or \NULL{} on failure.
+This is the equivalent of the Python expression
+\samp{\var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
+Set the value of the attribute named \var{attr_name}, for object
+\var{o}, to the value \var{v}. Returns \code{-1} on failure.  This is
+the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
+\var{v}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
+Set the value of the attribute named \var{attr_name}, for
+object \var{o},
+to the value \var{v}. Returns \code{-1} on failure.  This is
+the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
+\var{v}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
+Delete attribute named \var{attr_name}, for object \var{o}. Returns
+\code{-1} on failure.  This is the equivalent of the Python
+statement: \samp{del \var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
+Delete attribute named \var{attr_name}, for object \var{o}. Returns
+\code{-1} on failure.  This is the equivalent of the Python
+statement \samp{del \var{o}.\var{attr_name}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
+Compare the values of \var{o1} and \var{o2} using a routine provided
+by \var{o1}, if one exists, otherwise with a routine provided by
+\var{o2}.  The result of the comparison is returned in \var{result}.
+Returns \code{-1} on failure.  This is the equivalent of the Python
+statement\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
+Compare the values of \var{o1} and \var{o2} using a routine provided
+by \var{o1}, if one exists, otherwise with a routine provided by
+\var{o2}.  Returns the result of the comparison on success.  On error,
+the value returned is undefined; use \cfunction{PyErr_Occurred()} to
+detect an error.  This is equivalent to the Python
+expression\bifuncindex{cmp} \samp{cmp(\var{o1}, \var{o2})}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
+Compute a string representation of object \var{o}.  Returns the
+string representation on success, \NULL{} on failure.  This is
+the equivalent of the Python expression \samp{repr(\var{o})}.
+Called by the \function{repr()}\bifuncindex{repr} built-in function
+and by reverse quotes.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
+Compute a string representation of object \var{o}.  Returns the
+string representation on success, \NULL{} on failure.  This is
+the equivalent of the Python expression \samp{str(\var{o})}.
+Called by the \function{str()}\bifuncindex{str} built-in function and
+by the \keyword{print} statement.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
+Determine if the object \var{o} is callable.  Return \code{1} if the
+object is callable and \code{0} otherwise.
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object,
+                                                  PyObject *args}
+Call a callable Python object \var{callable_object}, with
+arguments given by the tuple \var{args}.  If no arguments are
+needed, then \var{args} may be \NULL{}.  Returns the result of the
+call on success, or \NULL{} on failure.  This is the equivalent
+of the Python expression \samp{apply(\var{o}, \var{args})}.
+\bifuncindex{apply}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
+Call a callable Python object \var{callable_object}, with a
+variable number of C arguments. The C arguments are described
+using a \cfunction{Py_BuildValue()} style format string. The format may
+be \NULL{}, indicating that no arguments are provided.  Returns the
+result of the call on success, or \NULL{} on failure.  This is
+the equivalent of the Python expression \samp{apply(\var{o},
+\var{args})}.\bifuncindex{apply}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
+Call the method named \var{m} of object \var{o} with a variable number
+of C arguments.  The C arguments are described by a
+\cfunction{Py_BuildValue()} format string.  The format may be \NULL{},
+indicating that no arguments are provided. Returns the result of the
+call on success, or \NULL{} on failure.  This is the equivalent of the
+Python expression \samp{\var{o}.\var{method}(\var{args})}.
+Note that special method names, such as \method{__add__()},
+\method{__getitem__()}, and so on are not supported.  The specific
+abstract-object routines for these must be used.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
+Compute and return the hash value of an object \var{o}.  On
+failure, return \code{-1}.  This is the equivalent of the Python
+expression \samp{hash(\var{o})}.\bifuncindex{hash}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
+Returns \code{1} if the object \var{o} is considered to be true, and
+\code{0} otherwise. This is equivalent to the Python expression
+\samp{not not \var{o}}.
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
+On success, returns a type object corresponding to the object
+type of object \var{o}. On failure, returns \NULL{}.  This is
+equivalent to the Python expression \samp{type(\var{o})}.
+\bifuncindex{type}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
+Return the length of object \var{o}.  If the object \var{o} provides
+both sequence and mapping protocols, the sequence length is
+returned.  On error, \code{-1} is returned.  This is the equivalent
+to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
+Return element of \var{o} corresponding to the object \var{key} or
+\NULL{} on failure. This is the equivalent of the Python expression
+\samp{\var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
+Map the object \var{key} to the value \var{v}.
+Returns \code{-1} on failure.  This is the equivalent
+of the Python statement \samp{\var{o}[\var{key}] = \var{v}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key}
+Delete the mapping for \var{key} from \var{o}.  Returns \code{-1} on
+failure. This is the equivalent of the Python statement \samp{del
+\var{o}[\var{key}]}.
+\end{cfuncdesc}
+
+
+\section{Number Protocol \label{number}}
+
+\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
+Returns \code{1} if the object \var{o} provides numeric protocols, and
+false otherwise. 
+This function always succeeds.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
+Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
+failure.  This is the equivalent of the Python expression
+\samp{\var{o1} + \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
+Returns the result of subtracting \var{o2} from \var{o1}, or
+\NULL{} on failure.  This is the equivalent of the Python expression
+\samp{\var{o1} - \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
+Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
+failure.  This is the equivalent of the Python expression
+\samp{\var{o1} * \var{o2}}.
+\end{cfuncdesc}
+
+
+\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
+Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
+failure. 
+This is the equivalent of the Python expression \samp{\var{o1} /