Remove \bcode / \ecode everywhere.
Make all the indentations in {verbatim} environments have column 0 of the
listing in column 0 of the file.
Remove pagenumbering / pagestyle cruft.
diff --git a/Doc/ext.tex b/Doc/ext.tex
index 5603fde..0045191 100644
--- a/Doc/ext.tex
+++ b/Doc/ext.tex
@@ -12,9 +12,6 @@
\begin{document}
-\pagestyle{empty}
-\pagenumbering{roman}
-
\maketitle
\input{copyright}
@@ -50,8 +47,6 @@
\tableofcontents
-\pagenumbering{arabic}
-
\chapter{Extending Python with \C{} or \Cpp{} code}
@@ -84,11 +79,11 @@
returns an integer. We want this function to be callable from Python
as follows:
-\bcode\begin{verbatim}
- >>> import spam
- >>> status = spam.system("ls -l")
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+>>> import spam
+>>> status = spam.system("ls -l")
+\end{verbatim}
+
Begin by creating a file \samp{spammodule.c}. (In general, 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
@@ -96,10 +91,10 @@
The first line of our file can be:
-\bcode\begin{verbatim}
- #include "Python.h"
-\end{verbatim}\ecode
-%
+\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).
@@ -116,21 +111,21 @@
be called when the Python expression \samp{spam.system(\var{string})}
is evaluated (we'll see shortly how it ends up being called):
-\bcode\begin{verbatim}
- static PyObject *
- spam_system(self, args)
- PyObject *self;
- PyObject *args;
- {
- char *command;
- int sts;
- if (!PyArg_ParseTuple(args, "s", &command))
- return NULL;
- sts = system(command);
- return Py_BuildValue("i", sts);
- }
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+static PyObject *
+spam_system(self, args)
+ PyObject *self;
+ PyObject *args;
+{
+ char *command;
+ int sts;
+ if (!PyArg_ParseTuple(args, "s", &command))
+ return NULL;
+ sts = system(command);
+ return Py_BuildValue("i", sts);
+}
+\end{verbatim}
+
There is a straightforward translation from the argument list in
Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
passed to the \C{} function. The \C{} function always has two arguments,
@@ -254,26 +249,26 @@
For this, you usually declare a static object variable at the
beginning of your file, e.g.
-\bcode\begin{verbatim}
- static PyObject *SpamError;
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+static PyObject *SpamError;
+\end{verbatim}
+
and initialize it in your module's initialization function
(\code{initspam()}) with a string object, e.g. (leaving out the error
checking for now):
-\bcode\begin{verbatim}
- void
- initspam()
- {
- PyObject *m, *d;
- m = Py_InitModule("spam", SpamMethods);
- d = PyModule_GetDict(m);
- SpamError = PyString_FromString("spam.error");
- PyDict_SetItemString(d, "error", SpamError);
- }
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+void
+initspam()
+{
+ PyObject *m, *d;
+ m = Py_InitModule("spam", SpamMethods);
+ d = PyModule_GetDict(m);
+ SpamError = PyString_FromString("spam.error");
+ PyDict_SetItemString(d, "error", SpamError);
+}
+\end{verbatim}
+
Note that the Python name for the exception object is
\code{spam.error}. It is conventional for module and exception names
to be spelled in lower case. It is also conventional that the
@@ -286,11 +281,11 @@
Going back to our example function, you should now be able to
understand this statement:
-\bcode\begin{verbatim}
- if (!PyArg_ParseTuple(args, "s", &command))
- return NULL;
-\end{verbatim}\ecode
-%
+\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 \code{PyArg_ParseTuple()}. Otherwise the
@@ -303,10 +298,10 @@
The next statement is a call to the \UNIX{} function \code{system()},
passing it the string we just got from \code{PyArg_ParseTuple()}:
-\bcode\begin{verbatim}
- sts = system(command);
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+ sts = system(command);
+\end{verbatim}
+
Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of
@@ -314,10 +309,10 @@
number of \C{} values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later.
-\bcode\begin{verbatim}
- return Py_BuildValue("i", sts);
-\end{verbatim}\ecode
-%
+\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!)
@@ -325,11 +320,11 @@
returning \code{void}), the corresponding Python function must return
\code{None}. You need this idiom to do so:
-\bcode\begin{verbatim}
- Py_INCREF(Py_None);
- return Py_None;
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+ Py_INCREF(Py_None);
+ return Py_None;
+\end{verbatim}
+
\code{Py_None} is the \C{} name for the special Python object
\code{None}. It is a genuine Python object (not a \NULL{}
pointer, which means ``error'' in most contexts, as we have seen).
@@ -341,15 +336,15 @@
programs. First, we need to list its name and address in a ``method
table'':
-\bcode\begin{verbatim}
- static PyMethodDef SpamMethods[] = {
- ...
- {"system", spam_system, METH_VARARGS},
- ...
- {NULL, NULL} /* Sentinel */
- };
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+static PyMethodDef SpamMethods[] = {
+ ...
+ {"system", spam_system, METH_VARARGS},
+ ...
+ {NULL, 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
@@ -371,14 +366,14 @@
initialization function (which should be the only non-\code{static}
item defined in the module file):
-\bcode\begin{verbatim}
- void
- initspam()
- {
- (void) Py_InitModule("spam", SpamMethods);
- }
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+void
+initspam()
+{
+ (void) Py_InitModule("spam", SpamMethods);
+}
+\end{verbatim}
+
When the Python program imports module \code{spam} for the first time,
\code{initspam()} is called. It calls \code{Py_InitModule()}, which
creates a ``module object'' (which is inserted in the dictionary
@@ -406,10 +401,10 @@
the \file{Modules} directory, add a line to the file
\file{Modules/Setup} describing your file:
-\bcode\begin{verbatim}
- spam spammodule.o
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+spam spammodule.o
+\end{verbatim}
+
and rebuild the interpreter by running \code{make} in the toplevel
directory. You can also run \code{make} in the \file{Modules}
subdirectory, but then you must first rebuilt the \file{Makefile}
@@ -419,10 +414,10 @@
If your module requires additional libraries to link with, these can
be listed on the line in the \file{Setup} file as well, for instance:
-\bcode\begin{verbatim}
- spam spammodule.o -lX11
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+spam spammodule.o -lX11
+\end{verbatim}
+
\section{Calling Python Functions From \C{}}
So far we have concentrated on making \C{} functions callable from
@@ -447,22 +442,22 @@
For example, the following function might be part of a module
definition:
-\bcode\begin{verbatim}
- static PyObject *my_callback = NULL;
+\begin{verbatim}
+static PyObject *my_callback = NULL;
- static PyObject *
- my_set_callback(dummy, arg)
- PyObject *dummy, *arg;
- {
- Py_XDECREF(my_callback); /* Dispose of previous callback */
- Py_XINCREF(arg); /* Add a reference to new callback */
- my_callback = arg; /* Remember new callback */
- /* Boilerplate to return "None" */
- Py_INCREF(Py_None);
- return Py_None;
- }
-\end{verbatim}\ecode
-%
+static PyObject *
+my_set_callback(dummy, arg)
+ PyObject *dummy, *arg;
+{
+ Py_XDECREF(my_callback); /* Dispose of previous callback */
+ Py_XINCREF(arg); /* Add a reference to new callback */
+ my_callback = arg; /* Remember new callback */
+ /* Boilerplate to return "None" */
+ Py_INCREF(Py_None);
+ return Py_None;
+}
+\end{verbatim}
+
The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
the reference count of an object and are safe in the presence of
\NULL{} pointers. More info on them in the section on Reference
@@ -478,7 +473,7 @@
format string consists of zero or more format codes between
parentheses. For example:
-\bcode\begin{verbatim}
+\begin{verbatim}
int arg;
PyObject *arglist;
PyObject *result;
@@ -489,8 +484,8 @@
arglist = Py_BuildValue("(i)", arg);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
-\end{verbatim}\ecode
-%
+\end{verbatim}
+
\code{PyEval_CallObject()} returns a Python object pointer: this is
the return value of the Python function. \code{PyEval_CallObject()} is
``reference-count-neutral'' with respect to its arguments. In the
@@ -512,13 +507,13 @@
or desirable, the exception should be cleared by calling
\code{PyErr_Clear()}. For example:
-\bcode\begin{verbatim}
+\begin{verbatim}
if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
-\end{verbatim}\ecode
-%
+\end{verbatim}
+
Depending on the desired interface to the Python callback function,
you may also have to provide an argument list to \code{PyEval_CallObject()}.
In some cases the argument list is also provided by the Python
@@ -529,7 +524,7 @@
call \code{Py_BuildValue()}. For example, if you want to pass an integral
event code, you might use the following code:
-\bcode\begin{verbatim}
+\begin{verbatim}
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
@@ -539,8 +534,8 @@
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
-\end{verbatim}\ecode
-%
+\end{verbatim}
+
Note the placement of \code{Py_DECREF(argument)} immediately after the call,
before the error check! Also note that strictly spoken this code is
not complete: \code{Py_BuildValue()} may run out of memory, and this should
@@ -551,10 +546,10 @@
The \code{PyArg_ParseTuple()} function is declared as follows:
-\bcode\begin{verbatim}
- int PyArg_ParseTuple(PyObject *arg, char *format, ...);
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+int PyArg_ParseTuple(PyObject *arg, char *format, ...);
+\end{verbatim}
+
The \var{arg} argument must be a tuple object containing an argument
list passed from Python to a \C{} function. The \var{format} argument
must be a format string, whose syntax is explained below. The
@@ -757,10 +752,10 @@
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
follows:
-\bcode\begin{verbatim}
- int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
- char *format, char **kwlist, ...);
-\end{verbatim}\ecode
+\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
@@ -826,10 +821,10 @@
This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows:
-\bcode\begin{verbatim}
- PyObject *Py_BuildValue(char *format, ...);
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+PyObject *Py_BuildValue(char *format, ...);
+\end{verbatim}
+
It recognizes a set of format units similar to the ones recognized by
\code{PyArg_ParseTuple()}, but the arguments (which are input to the
function, not output) must not be pointers, just values. It returns a
@@ -931,7 +926,7 @@
Examples (to the left the call, to the right the resulting Python value):
-\bcode\begin{verbatim}
+\begin{verbatim}
Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
@@ -947,8 +942,8 @@
"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}\ecode
-%
+\end{verbatim}
+
\section{Reference Counts}
\subsection{Introduction}
@@ -1117,14 +1112,14 @@
\code{Py_DECREF()} on an unrelated object while borrowing a reference
to a list item. For instance:
-\bcode\begin{verbatim}
+\begin{verbatim}
bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
PyList_SetItem(list, 1, PyInt_FromLong(0L));
PyObject_Print(item, stdout, 0); /* BUG! */
}
-\end{verbatim}\ecode
-%
+\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!
@@ -1150,7 +1145,7 @@
temporarily increment the reference count. The correct version of the
function reads:
-\bcode\begin{verbatim}
+\begin{verbatim}
no_bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
Py_INCREF(item);
@@ -1158,8 +1153,8 @@
PyObject_Print(item, stdout, 0);
Py_DECREF(item);
}
-\end{verbatim}\ecode
-%
+\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 \code{__del__()} methods would fail...
@@ -1175,7 +1170,7 @@
complete. Obviously, the following function has the same problem as
the previous one:
-\bcode\begin{verbatim}
+\begin{verbatim}
bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
Py_BEGIN_ALLOW_THREADS
@@ -1183,8 +1178,8 @@
Py_END_ALLOW_THREADS
PyObject_Print(item, stdout, 0); /* BUG! */
}
-\end{verbatim}\ecode
-%
+\end{verbatim}
+
\subsection{NULL Pointers}
In general, functions that take object references as arguments don't
@@ -1391,20 +1386,20 @@
system.
On SunOS 4, use
-\bcode\begin{verbatim}
- ld spammodule.o -o spammodule.so
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+ld spammodule.o -o spammodule.so
+\end{verbatim}
+
On Solaris 2, use
-\bcode\begin{verbatim}
- ld -G spammodule.o -o spammodule.so
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+ld -G spammodule.o -o spammodule.so
+\end{verbatim}
+
On SGI IRIX 5, use
-\bcode\begin{verbatim}
- ld -shared spammodule.o -o spammodule.so
-\end{verbatim}\ecode
-%
+\begin{verbatim}
+ld -shared spammodule.o -o spammodule.so
+\end{verbatim}
+
On other systems, consult the manual page for \code{ld}(1) to find what
flags, if any, must be used.