\begin{document}
-\pagestyle{empty}
-\pagenumbering{roman}
-
\maketitle
\input{copyright}
\tableofcontents
-\pagenumbering{arabic}
-
\chapter{Extending Python with \C{} or \Cpp{} code}
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
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).
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,
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
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
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
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!)
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).
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
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
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}
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
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}
- 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
-%
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
format string consists of zero or more format codes between
parentheses. For example:
-\bcode\begin{verbatim}
+\begin{verbatim}
int arg;
PyObject *arglist;
PyObject *result;
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
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
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);
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
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
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
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
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)
"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}
\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!
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);
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...
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
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
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.
\begin{document}
-\pagestyle{empty}
-\pagenumbering{roman}
-
\maketitle
\input{copyright}
\tableofcontents
-\pagenumbering{arabic}
-
\chapter{Extending Python with \C{} or \Cpp{} code}
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
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).
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,
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
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
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
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!)
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).
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
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
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}
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
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}
- 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
-%
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
format string consists of zero or more format codes between
parentheses. For example:
-\bcode\begin{verbatim}
+\begin{verbatim}
int arg;
PyObject *arglist;
PyObject *result;
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
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
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);
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
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
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
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
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)
"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}
\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!
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);
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...
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
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
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.
projects / python / commitdiff