traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Revise prologue and frontmatter to use latex2e (not in 2.09 compatibility 

mode) and take advantage of changes in myformat.sty.

Change "C" to "\C{}" and "\code{NULL}" to "\NULL{}" everywhere for consistency
and control.

Started a description of PyArg_ParseTupleAndKeywords().
This commit is contained in:
Fred Drake 1998-01-09 05:39:38 +00:00
parent 1f8449af4e
commit 0fd8268189
2 changed files with 272 additions and 264 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

268
Doc/ext.tex
View File

@ -1,4 +1,5 @@
\documentstyle[twoside,11pt,myformat]{report} \documentclass[twoside]{report}
\usepackage{myformat}
% XXX PM Modulator % XXX PM Modulator
@ -11,6 +12,7 @@
\begin{document} \begin{document}
\pagestyle{empty}
\pagenumbering{roman} \pagenumbering{roman}
\maketitle \maketitle
@ -21,7 +23,7 @@
\noindent \noindent
Python is an interpreted, object-oriented programming language. This Python is an interpreted, object-oriented programming language. This
document describes how to write modules in C or \Cpp{} to extend the document describes how to write modules in \C{} or \Cpp{} to extend the
Python interpreter with new modules. Those modules can define new Python interpreter with new modules. Those modules can define new
functions but also new object types and their methods. The document functions but also new object types and their methods. The document
also describes how to embed the Python interpreter in another also describes how to embed the Python interpreter in another
@ -37,8 +39,8 @@ Python Library Reference documents the existing object types,
functions and modules (both built-in and written in Python) that give functions and modules (both built-in and written in Python) that give
the language its wide application range. the language its wide application range.
For a detailed description of the whole Python/C API, see the separate For a detailed description of the whole Python/\C{} API, see the separate
Python/C API Reference Manual. \strong{Note:} While that manual is Python/\C{} API Reference Manual. \strong{Note:} While that manual is
still in a state of flux, it is safe to say that it is much more up to still in a state of flux, it is safe to say that it is much more up to
date than the manual you're reading currently (which has been in need date than the manual you're reading currently (which has been in need
for an upgrade for some time now). for an upgrade for some time now).
@ -46,32 +48,25 @@ for an upgrade for some time now).
\end{abstract} \end{abstract}
\pagebreak \mytableofcontents
{
\parskip = 0mm
\tableofcontents
}
\pagebreak
\pagenumbering{arabic} \pagenumbering{arabic}
\chapter{Extending Python with C or \Cpp{} code} \chapter{Extending Python with \C{} or \Cpp{} code}
\section{Introduction} \section{Introduction}
It is quite easy to add new built-in modules to Python, if you know It is quite easy to add new built-in modules to Python, if you know
how to program in C. Such \dfn{extension modules} can do two things how to program in \C{}. Such \dfn{extension modules} can do two things
that can't be done directly in Python: they can implement new built-in that can't be done directly in Python: they can implement new built-in
object types, and they can call C library functions and system calls. object types, and they can call \C{} library functions and system calls.
To support extensions, the Python API (Application Programmers To support extensions, the Python API (Application Programmers
Interface) defines a set of functions, macros and variables that Interface) defines a set of functions, macros and variables that
provide access to most aspects of the Python run-time system. The provide access to most aspects of the Python run-time system. The
Python API is incorporated in a C source file by including the header Python API is incorporated in a \C{} source file by including the header
\code{"Python.h"}. \code{"Python.h"}.
The compilation of an extension module depends on its intended use as The compilation of an extension module depends on its intended use as
@ -82,7 +77,7 @@ well as on your system setup; details are given in a later section.
Let's create an extension module called \samp{spam} (the favorite food Let's create an extension module called \samp{spam} (the favorite food
of Monty Python fans...) and let's say we want to create a Python of Monty Python fans...) and let's say we want to create a Python
interface to the C library function \code{system()}.\footnote{An interface to the \C{} library function \code{system()}.\footnote{An
interface for this function already exists in the standard module interface for this function already exists in the standard module
\code{os} --- it was chosen as a simple and straightfoward example.} \code{os} --- it was chosen as a simple and straightfoward example.}
This function takes a null-terminated character string as argument and This function takes a null-terminated character string as argument and
@ -95,7 +90,7 @@ as follows:
\end{verbatim}\ecode \end{verbatim}\ecode
% %
Begin by creating a file \samp{spammodule.c}. (In general, if a Begin by creating a file \samp{spammodule.c}. (In general, if a
module is called \samp{spam}, the C file containing its implementation module is called \samp{spam}, the \C{} file containing its implementation
is called \file{spammodule.c}; if the module name is very long, like is called \file{spammodule.c}; if the module name is very long, like
\samp{spammify}, the module name can be just \file{spammify.c}.) \samp{spammify}, the module name can be just \file{spammify.c}.)
@ -117,7 +112,7 @@ interpreter, \code{"Python.h"} includes a few standard header files:
system, it declares the functions \code{malloc()}, \code{free()} and system, it declares the functions \code{malloc()}, \code{free()} and
\code{realloc()} directly. \code{realloc()} directly.
The next thing we add to our module file is the C function that will The next thing we add to our module file is the \C{} function that will
be called when the Python expression \samp{spam.system(\var{string})} be called when the Python expression \samp{spam.system(\var{string})}
is evaluated (we'll see shortly how it ends up being called): is evaluated (we'll see shortly how it ends up being called):
@ -138,23 +133,23 @@ is evaluated (we'll see shortly how it ends up being called):
% %
There is a straightforward translation from the argument list in There is a straightforward translation from the argument list in
Python (e.g.\ the single expression \code{"ls -l"}) to the arguments Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
passed to the C function. The C function always has two arguments, passed to the \C{} function. The \C{} function always has two arguments,
conventionally named \var{self} and \var{args}. conventionally named \var{self} and \var{args}.
The \var{self} argument is only used when the C function implements a The \var{self} argument is only used when the \C{} function implements a
builtin method. This will be discussed later. In the example, builtin method. This will be discussed later. In the example,
\var{self} will always be a \code{NULL} pointer, since we are defining \var{self} will always be a \NULL{} pointer, since we are defining
a function, not a method. (This is done so that the interpreter a function, not a method. (This is done so that the interpreter
doesn't have to understand two different types of C functions.) doesn't have to understand two different types of \C{} functions.)
The \var{args} argument will be a pointer to a Python tuple object The \var{args} argument will be a pointer to a Python tuple object
containing the arguments. Each item of the tuple corresponds to an containing the arguments. Each item of the tuple corresponds to an
argument in the call's argument list. The arguments are Python argument in the call's argument list. The arguments are Python
objects -- in order to do anything with them in our C function we have objects -- in order to do anything with them in our \C{} function we have
to convert them to C values. The function \code{PyArg_ParseTuple()} to convert them to \C{} values. The function \code{PyArg_ParseTuple()}
in the Python API checks the argument types and converts them to C in the Python API checks the argument types and converts them to \C{}
values. It uses a template string to determine the required types of values. It uses a template string to determine the required types of
the arguments as well as the types of the C variables into which to the arguments as well as the types of the \C{} variables into which to
store the converted values. More about this later. store the converted values. More about this later.
\code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have \code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
@ -162,20 +157,20 @@ the right type and its components have been stored in the variables
whose addresses are passed. It returns false (zero) if an invalid whose addresses are passed. It returns false (zero) if an invalid
argument list was passed. In the latter case it also raises an argument list was passed. In the latter case it also raises an
appropriate exception by so the calling function can return appropriate exception by so the calling function can return
\code{NULL} immediately (as we saw in the example). \NULL{} immediately (as we saw in the example).
\section{Intermezzo: Errors and Exceptions} \section{Intermezzo: Errors and Exceptions}
An important convention throughout the Python interpreter is the An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition following: when a function fails, it should set an exception condition
and return an error value (usually a \code{NULL} pointer). Exceptions and return an error value (usually a \NULL{} pointer). Exceptions
are stored in a static global variable inside the interpreter; if this are stored in a static global variable inside the interpreter; if this
variable is \code{NULL} no exception has occurred. A second global variable is \NULL{} no exception has occurred. A second global
variable stores the ``associated value'' of the exception (the second variable stores the ``associated value'' of the exception (the second
argument to \code{raise}). A third variable contains the stack argument to \code{raise}). A third variable contains the stack
traceback in case the error originated in Python code. These three traceback in case the error originated in Python code. These three
variables are the C equivalents of the Python variables variables are the \C{} equivalents of the Python variables
\code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback} \code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback}
(see the section on module \code{sys} in the Library Reference (see the section on module \code{sys} in the Library Reference
Manual). It is important to know about them to understand how errors Manual). It is important to know about them to understand how errors
@ -185,8 +180,8 @@ The Python API defines a number of functions to set various types of
exceptions. exceptions.
The most common one is \code{PyErr_SetString()}. Its arguments are an The most common one is \code{PyErr_SetString()}. Its arguments are an
exception object and a C string. The exception object is usually a exception object and a \C{} string. The exception object is usually a
predefined object like \code{PyExc_ZeroDivisionError}. The C string predefined object like \code{PyExc_ZeroDivisionError}. The \C{} string
indicates the cause of the error and is converted to a Python string indicates the cause of the error and is converted to a Python string
object and stored as the ``associated value'' of the exception. object and stored as the ``associated value'' of the exception.
@ -199,13 +194,13 @@ arguments, the exception and its associated value. You don't need to
You can test non-destructively whether an exception has been set with You can test non-destructively whether an exception has been set with
\code{PyErr_Occurred()}. This returns the current exception object, \code{PyErr_Occurred()}. This returns the current exception object,
or \code{NULL} if no exception has occurred. You normally don't need or \NULL{} if no exception has occurred. You normally don't need
to call \code{PyErr_Occurred()} to see whether an error occurred in a to call \code{PyErr_Occurred()} to see whether an error occurred in a
function call, since you should be able to tell from the return value. function call, since you should be able to tell from the return value.
When a function \var{f} that calls another function \var{g} detects When a function \var{f} that calls another function \var{g} detects
that the latter fails, \var{f} should itself return an error value that the latter fails, \var{f} should itself return an error value
(e.g. \code{NULL} or \code{-1}). It should \emph{not} call one of the (e.g. \NULL{} or \code{-1}). It should \emph{not} call one of the
\code{PyErr_*()} functions --- one has already been called by \var{g}. \code{PyErr_*()} functions --- one has already been called by \var{g}.
\var{f}'s caller is then supposed to also return an error indication \var{f}'s caller is then supposed to also return an error indication
to \emph{its} caller, again \emph{without} calling \code{PyErr_*()}, to \emph{its} caller, again \emph{without} calling \code{PyErr_*()},
@ -223,7 +218,7 @@ to be lost: most operations can fail for a variety of reasons.)
To ignore an exception set by a function call that failed, the exception To ignore an exception set by a function call that failed, the exception
condition must be cleared explicitly by calling \code{PyErr_Clear()}. condition must be cleared explicitly by calling \code{PyErr_Clear()}.
The only time C code should call \code{PyErr_Clear()} is if it doesn't The only time \C{} code should call \code{PyErr_Clear()} is if it doesn't
want to pass the error on to the interpreter but wants to handle it want to pass the error on to the interpreter but wants to handle it
completely by itself (e.g. by trying something else or pretending completely by itself (e.g. by trying something else or pretending
nothing happened). nothing happened).
@ -245,7 +240,7 @@ or \code{Py_DECREF()} calls for objects you have already created) when
you return an error indicator! you return an error indicator!
The choice of which exception to raise is entirely yours. There are The choice of which exception to raise is entirely yours. There are
predeclared C objects corresponding to all built-in Python exceptions, predeclared \C{} objects corresponding to all built-in Python exceptions,
e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of
course, you should choose exceptions wisely --- don't use course, you should choose exceptions wisely --- don't use
\code{PyExc_TypeError} to mean that a file couldn't be opened (that \code{PyExc_TypeError} to mean that a file couldn't be opened (that
@ -296,12 +291,12 @@ understand this statement:
return NULL; return NULL;
\end{verbatim}\ecode \end{verbatim}\ecode
% %
It returns \code{NULL} (the error indicator for functions returning It returns \NULL{} (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying object pointers) if an error is detected in the argument list, relying
on the exception set by \code{PyArg_ParseTuple()}. Otherwise the on the exception set by \code{PyArg_ParseTuple()}. Otherwise the
string value of the argument has been copied to the local variable string value of the argument has been copied to the local variable
\code{command}. This is a pointer assignment and you are not supposed \code{command}. This is a pointer assignment and you are not supposed
to modify the string to which it points (so in Standard C, the variable to modify the string to which it points (so in Standard \C{}, the variable
\code{command} should properly be declared as \samp{const char \code{command} should properly be declared as \samp{const char
*command}). *command}).
@ -316,7 +311,7 @@ Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of \code{Py_BuildValue()}, which is something like the inverse of
\code{PyArg_ParseTuple()}: it takes a format string and an arbitrary \code{PyArg_ParseTuple()}: it takes a format string and an arbitrary
number of C values, and returns a new Python object. More info on number of \C{} values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later. \code{Py_BuildValue()} is given later.
\bcode\begin{verbatim} \bcode\begin{verbatim}
@ -326,7 +321,7 @@ number of C values, and returns a new Python object. More info on
In this case, it will return an integer object. (Yes, even integers In this case, it will return an integer object. (Yes, even integers
are objects on the heap in Python!) are objects on the heap in Python!)
If you have a C function that returns no useful argument (a function If you have a \C{} function that returns no useful argument (a function
returning \code{void}), the corresponding Python function must return returning \code{void}), the corresponding Python function must return
\code{None}. You need this idiom to do so: \code{None}. You need this idiom to do so:
@ -335,8 +330,8 @@ returning \code{void}), the corresponding Python function must return
return Py_None; return Py_None;
\end{verbatim}\ecode \end{verbatim}\ecode
% %
\code{Py_None} is the C name for the special Python object \code{Py_None} is the \C{} name for the special Python object
\code{None}. It is a genuine Python object (not a \code{NULL} \code{None}. It is a genuine Python object (not a \NULL{}
pointer, which means ``error'' in most contexts, as we have seen). pointer, which means ``error'' in most contexts, as we have seen).
@ -349,17 +344,26 @@ table'':
\bcode\begin{verbatim} \bcode\begin{verbatim}
static PyMethodDef SpamMethods[] = { static PyMethodDef SpamMethods[] = {
... ...
{"system", spam_system, 1}, {"system", spam_system, METH_VARARGS},
... ...
{NULL, NULL} /* Sentinel */ {NULL, NULL} /* Sentinel */
}; };
\end{verbatim}\ecode \end{verbatim}\ecode
% %
Note the third entry (\samp{1}). This is a flag telling the Note the third entry (\samp{METH_VARARGS}). This is a flag telling
interpreter the calling convention to be used for the C function. It the interpreter the calling convention to be used for the \C{}
should normally always be \samp{1}; a value of \samp{0} means that an function. It should normally always be \samp{METH_VARARGS} or
\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
obsolete variant of \code{PyArg_ParseTuple()} is used. obsolete variant of \code{PyArg_ParseTuple()} is used.
The \code{METH_KEYWORDS} bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the \C{}
function should accept a third \samp{PyObject *} parameter which will
be a dictionary of keywords. Use \code{PyArg_ParseTupleAndKeywords()}
to parse the arguemts to such a function.
XXX --- need to explain PyArg_ParseTupleAndKeywords() in detail.
The method table must be passed to the interpreter in the module's The method table must be passed to the interpreter in the module's
initialization function (which should be the only non-\code{static} initialization function (which should be the only non-\code{static}
item defined in the module file): item defined in the module file):
@ -416,15 +420,15 @@ be listed on the line in the \file{Setup} file as well, for instance:
spam spammodule.o -lX11 spam spammodule.o -lX11
\end{verbatim}\ecode \end{verbatim}\ecode
% %
\section{Calling Python Functions From C} \section{Calling Python Functions From \C{}}
So far we have concentrated on making C functions callable from So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from C. Python. The reverse is also useful: calling Python functions from \C{}.
This is especially the case for libraries that support so-called This is especially the case for libraries that support so-called
``callback'' functions. If a C interface makes use of callbacks, the ``callback'' functions. If a \C{} interface makes use of callbacks, the
equivalent Python often needs to provide a callback mechanism to the equivalent Python often needs to provide a callback mechanism to the
Python programmer; the implementation will require calling the Python Python programmer; the implementation will require calling the Python
callback functions from a C callback. Other uses are also imaginable. callback functions from a \C{} callback. Other uses are also imaginable.
Fortunately, the Python interpreter is easily called recursively, and Fortunately, the Python interpreter is easily called recursively, and
there is a standard interface to call a Python function. (I won't there is a standard interface to call a Python function. (I won't
@ -458,10 +462,10 @@ definition:
% %
The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
the reference count of an object and are safe in the presence of the reference count of an object and are safe in the presence of
\code{NULL} pointers. More info on them in the section on Reference \NULL{} pointers. More info on them in the section on Reference
Counts below. Counts below.
Later, when it is time to call the function, you call the C function Later, when it is time to call the function, you call the \C{} function
\code{PyEval_CallObject()}. This function has two arguments, both \code{PyEval_CallObject()}. This function has two arguments, both
pointers to arbitrary Python objects: the Python function, and the pointers to arbitrary Python objects: the Python function, and the
argument list. The argument list must always be a tuple object, whose argument list. The argument list must always be a tuple object, whose
@ -497,8 +501,8 @@ global variable, you should somehow \code{Py_DECREF()} the result,
even (especially!) if you are not interested in its value. even (especially!) if you are not interested in its value.
Before you do this, however, it is important to check that the return Before you do this, however, it is important to check that the return
value isn't \code{NULL}. If it is, the Python function terminated by raising value isn't \NULL{}. If it is, the Python function terminated by raising
an exception. If the C code that called \code{PyEval_CallObject()} is an exception. If the \C{} code that called \code{PyEval_CallObject()} is
called from Python, it should now return an error indication to its called from Python, it should now return an error indication to its
Python caller, so the interpreter can print a stack trace, or the Python caller, so the interpreter can print a stack trace, or the
calling Python code can handle the exception. If this is not possible calling Python code can handle the exception. If this is not possible
@ -549,7 +553,7 @@ The \code{PyArg_ParseTuple()} function is declared as follows:
\end{verbatim}\ecode \end{verbatim}\ecode
% %
The \var{arg} argument must be a tuple object containing an argument The \var{arg} argument must be a tuple object containing an argument
list passed from Python to a C function. The \var{format} argument list passed from Python to a \C{} function. The \var{format} argument
must be a format string, whose syntax is explained below. The must be a format string, whose syntax is explained below. The
remaining arguments must be addresses of variables whose type is remaining arguments must be addresses of variables whose type is
determined by the format string. For the conversion to succeed, the determined by the format string. For the conversion to succeed, the
@ -558,7 +562,7 @@ exhausted.
Note that while \code{PyArg_ParseTuple()} checks that the Python Note that while \code{PyArg_ParseTuple()} checks that the Python
arguments have the required types, it cannot check the validity of the arguments have the required types, it cannot check the validity of the
addresses of C variables passed to the call: if you make mistakes addresses of \C{} variables passed to the call: if you make mistakes
there, your code will probably crash or at least overwrite random bits there, your code will probably crash or at least overwrite random bits
in memory. So be careful! in memory. So be careful!
@ -569,72 +573,72 @@ format unit that is not a parenthesized sequence normally corresponds
to a single address argument to \code{PyArg_ParseTuple()}. In the to a single address argument to \code{PyArg_ParseTuple()}. In the
following description, the quoted form is the format unit; the entry following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that matches the in (round) parentheses is the Python object type that matches the
format unit; and the entry in [square] brackets is the type of the C format unit; and the entry in [square] brackets is the type of the \C{}
variable(s) whose address should be passed. (Use the \samp{\&} variable(s) whose address should be passed. (Use the \samp{\&}
operator to pass a variable's address.) operator to pass a variable's address.)
\begin{description} \begin{description}
\item[\samp{s} (string) [char *]] \item[\samp{s} (string) [char *]]
Convert a Python string to a C pointer to a character string. You Convert a Python string to a \C{} pointer to a character string. You
must not provide storage for the string itself; a pointer to an must not provide storage for the string itself; a pointer to an
existing string is stored into the character pointer variable whose existing string is stored into the character pointer variable whose
address you pass. The C string is null-terminated. The Python string address you pass. The \C{} string is null-terminated. The Python string
must not contain embedded null bytes; if it does, a \code{TypeError} must not contain embedded null bytes; if it does, a \code{TypeError}
exception is raised. exception is raised.
\item[\samp{s\#} (string) {[char *, int]}] \item[\samp{s\#} (string) {[char *, int]}]
This variant on \code{'s'} stores into two C variables, the first one This variant on \code{'s'} stores into two \C{} variables, the first one
a pointer to a character string, the second one its length. In this a pointer to a character string, the second one its length. In this
case the Python string may contain embedded null bytes. case the Python string may contain embedded null bytes.
\item[\samp{z} (string or \code{None}) {[char *]}] \item[\samp{z} (string or \code{None}) {[char *]}]
Like \samp{s}, but the Python object may also be \code{None}, in which Like \samp{s}, but the Python object may also be \code{None}, in which
case the C pointer is set to \code{NULL}. case the \C{} pointer is set to \NULL{}.
\item[\samp{z\#} (string or \code{None}) {[char *, int]}] \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
This is to \code{'s\#'} as \code{'z'} is to \code{'s'}. This is to \code{'s\#'} as \code{'z'} is to \code{'s'}.
\item[\samp{b} (integer) {[char]}] \item[\samp{b} (integer) {[char]}]
Convert a Python integer to a tiny int, stored in a C \code{char}. Convert a Python integer to a tiny int, stored in a \C{} \code{char}.
\item[\samp{h} (integer) {[short int]}] \item[\samp{h} (integer) {[short int]}]
Convert a Python integer to a C \code{short int}. Convert a Python integer to a \C{} \code{short int}.
\item[\samp{i} (integer) {[int]}] \item[\samp{i} (integer) {[int]}]
Convert a Python integer to a plain C \code{int}. Convert a Python integer to a plain \C{} \code{int}.
\item[\samp{l} (integer) {[long int]}] \item[\samp{l} (integer) {[long int]}]
Convert a Python integer to a C \code{long int}. Convert a Python integer to a \C{} \code{long int}.
\item[\samp{c} (string of length 1) {[char]}] \item[\samp{c} (string of length 1) {[char]}]
Convert a Python character, represented as a string of length 1, to a Convert a Python character, represented as a string of length 1, to a
C \code{char}. \C{} \code{char}.
\item[\samp{f} (float) {[float]}] \item[\samp{f} (float) {[float]}]
Convert a Python floating point number to a C \code{float}. Convert a Python floating point number to a \C{} \code{float}.
\item[\samp{d} (float) {[double]}] \item[\samp{d} (float) {[double]}]
Convert a Python floating point number to a C \code{double}. Convert a Python floating point number to a \C{} \code{double}.
\item[\samp{O} (object) {[PyObject *]}] \item[\samp{O} (object) {[PyObject *]}]
Store a Python object (without any conversion) in a C object pointer. Store a Python object (without any conversion) in a \C{} object pointer.
The C program thus receives the actual object that was passed. The The \C{} program thus receives the actual object that was passed. The
object's reference count is not increased. The pointer stored is not object's reference count is not increased. The pointer stored is not
\code{NULL}. \NULL{}.
\item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}] \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
Store a Python object in a C object pointer. This is similar to Store a Python object in a \C{} object pointer. This is similar to
\samp{O}, but takes two C arguments: the first is the address of a \samp{O}, but takes two \C{} arguments: the first is the address of a
Python type object, the second is the address of the C variable (of Python type object, the second is the address of the \C{} variable (of
type \code{PyObject *}) into which the object pointer is stored. type \code{PyObject *}) into which the object pointer is stored.
If the Python object does not have the required type, a If the Python object does not have the required type, a
\code{TypeError} exception is raised. \code{TypeError} exception is raised.
\item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}] \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
Convert a Python object to a C variable through a \var{converter} Convert a Python object to a \C{} variable through a \var{converter}
function. This takes two arguments: the first is a function, the function. This takes two arguments: the first is a function, the
second is the address of a C variable (of arbitrary type), converted second is the address of a \C{} variable (of arbitrary type), converted
to \code{void *}. The \var{converter} function in turn is called as to \code{void *}. The \var{converter} function in turn is called as
follows: follows:
@ -649,12 +653,12 @@ should raise an exception.
\item[\samp{S} (string) {[PyStringObject *]}] \item[\samp{S} (string) {[PyStringObject *]}]
Like \samp{O} but raises a \code{TypeError} exception that the object Like \samp{O} but raises a \code{TypeError} exception that the object
is a string object. The C variable may also be declared as is a string object. The \C{} variable may also be declared as
\code{PyObject *}. \code{PyObject *}.
\item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}] \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
The object must be a Python tuple whose length is the number of format The object must be a Python tuple whose length is the number of format
units in \var{items}. The C arguments must correspond to the units in \var{items}. The \C{} arguments must correspond to the
individual format units in \var{items}. Format units for tuples may individual format units in \var{items}. Format units for tuples may
be nested. be nested.
@ -664,7 +668,7 @@ It is possible to pass Python long integers where integers are
requested; however no proper range checking is done -- the most requested; however no proper range checking is done -- the most
significant bits are silently truncated when the receiving field is significant bits are silently truncated when the receiving field is
too small to receive the value (actually, the semantics are inherited too small to receive the value (actually, the semantics are inherited
from downcasts in C --- your milage may vary). from downcasts in \C{} --- your milage may vary).
A few other characters have a meaning in a format string. These may A few other characters have a meaning in a format string. These may
not occur inside nested parentheses. They are: not occur inside nested parentheses. They are:
@ -673,10 +677,10 @@ not occur inside nested parentheses. They are:
\item[\samp{|}] \item[\samp{|}]
Indicates that the remaining arguments in the Python argument list are Indicates that the remaining arguments in the Python argument list are
optional. The C variables corresponding to optional arguments should optional. The \C{} variables corresponding to optional arguments should
be initialized to their default value --- when an optional argument is be initialized to their default value --- when an optional argument is
not specified, the \code{PyArg_ParseTuple} does not touch the contents not specified, the \code{PyArg_ParseTuple} does not touch the contents
of the corresponding C variable(s). of the corresponding \C{} variable(s).
\item[\samp{:}] \item[\samp{:}]
The list of format units ends here; the string after the colon is used The list of format units ends here; the string after the colon is used
@ -692,7 +696,7 @@ Clearly, \samp{:} and \samp{;} mutually exclude each other.
Some example calls: Some example calls:
\bcode\begin{verbatim} \begin{verbatim}
int ok; int ok;
int i, j; int i, j;
long k, l; long k, l;
@ -701,13 +705,13 @@ Some example calls:
ok = PyArg_ParseTuple(args, ""); /* No arguments */ ok = PyArg_ParseTuple(args, ""); /* No arguments */
/* Python call: f() */ /* Python call: f() */
ok = PyArg_ParseTuple(args, "s", &s); /* A string */ ok = PyArg_ParseTuple(args, "s", &s); /* A string */
/* Possible Python call: f('whoops!') */ /* Possible Python call: f('whoops!') */
ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */ ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
/* Possible Python call: f(1, 2, 'three') */ /* Possible Python call: f(1, 2, 'three') */
ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size); ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
/* A pair of ints and a string, whose size is also returned */ /* A pair of ints and a string, whose size is also returned */
/* Possible Python call: f((1, 2), 'three') */ /* Possible Python call: f((1, 2), 'three') */
@ -732,7 +736,7 @@ Some example calls:
/* Possible Python call: /* Possible Python call:
f(((0, 0), (400, 300)), (10, 10)) */ f(((0, 0), (400, 300)), (10, 10)) */
} }
\end{verbatim}\ecode \end{verbatim}
% %
\section{The {\tt Py_BuildValue()} Function} \section{The {\tt Py_BuildValue()} Function}
@ -746,7 +750,7 @@ declared as follows:
It recognizes a set of format units similar to the ones recognized by It recognizes a set of format units similar to the ones recognized by
\code{PyArg_ParseTuple()}, but the arguments (which are input to the \code{PyArg_ParseTuple()}, but the arguments (which are input to the
function, not output) must not be pointers, just values. It returns a function, not output) must not be pointers, just values. It returns a
new Python object, suitable for returning from a C function called new Python object, suitable for returning from a \C{} function called
from Python. from Python.
One difference with \code{PyArg_ParseTuple()}: while the latter One difference with \code{PyArg_ParseTuple()}: while the latter
@ -761,7 +765,7 @@ to return a tuple of size 0 or one, parenthesize the format string.
In the following description, the quoted form is the format unit; the In the following description, the quoted form is the format unit; the
entry in (round) parentheses is the Python object type that the format entry in (round) parentheses is the Python object type that the format
unit will return; and the entry in [square] brackets is the type of unit will return; and the entry in [square] brackets is the type of
the C value(s) to be passed. the \C{} value(s) to be passed.
The characters space, tab, colon and comma are ignored in format The characters space, tab, colon and comma are ignored in format
strings (but not within format units such as \samp{s\#}). This can be strings (but not within format units such as \samp{s\#}). This can be
@ -770,12 +774,12 @@ used to make long format strings a tad more readable.
\begin{description} \begin{description}
\item[\samp{s} (string) {[char *]}] \item[\samp{s} (string) {[char *]}]
Convert a null-terminated C string to a Python object. If the C Convert a null-terminated \C{} string to a Python object. If the \C{}
string pointer is \code{NULL}, \code{None} is returned. string pointer is \NULL{}, \code{None} is returned.
\item[\samp{s\#} (string) {[char *, int]}] \item[\samp{s\#} (string) {[char *, int]}]
Convert a C string and its length to a Python object. If the C string Convert a \C{} string and its length to a Python object. If the \C{} string
pointer is \code{NULL}, the length is ignored and \code{None} is pointer is \NULL{}, the length is ignored and \code{None} is
returned. returned.
\item[\samp{z} (string or \code{None}) {[char *]}] \item[\samp{z} (string or \code{None}) {[char *]}]
@ -785,7 +789,7 @@ Same as \samp{s}.
Same as \samp{s\#}. Same as \samp{s\#}.
\item[\samp{i} (integer) {[int]}] \item[\samp{i} (integer) {[int]}]
Convert a plain C \code{int} to a Python integer object. Convert a plain \C{} \code{int} to a Python integer object.
\item[\samp{b} (integer) {[char]}] \item[\samp{b} (integer) {[char]}]
Same as \samp{i}. Same as \samp{i}.
@ -794,24 +798,24 @@ Same as \samp{i}.
Same as \samp{i}. Same as \samp{i}.
\item[\samp{l} (integer) {[long int]}] \item[\samp{l} (integer) {[long int]}]
Convert a C \code{long int} to a Python integer object. Convert a \C{} \code{long int} to a Python integer object.
\item[\samp{c} (string of length 1) {[char]}] \item[\samp{c} (string of length 1) {[char]}]
Convert a C \code{int} representing a character to a Python string of Convert a \C{} \code{int} representing a character to a Python string of
length 1. length 1.
\item[\samp{d} (float) {[double]}] \item[\samp{d} (float) {[double]}]
Convert a C \code{double} to a Python floating point number. Convert a \C{} \code{double} to a Python floating point number.
\item[\samp{f} (float) {[float]}] \item[\samp{f} (float) {[float]}]
Same as \samp{d}. Same as \samp{d}.
\item[\samp{O} (object) {[PyObject *]}] \item[\samp{O} (object) {[PyObject *]}]
Pass a Python object untouched (except for its reference count, which Pass a Python object untouched (except for its reference count, which
is incremented by one). If the object passed in is a \code{NULL} is incremented by one). If the object passed in is a \NULL{}
pointer, it is assumed that this was caused because the call producing pointer, it is assumed that this was caused because the call producing
the argument found an error and set an exception. Therefore, the argument found an error and set an exception. Therefore,
\code{Py_BuildValue()} will return \code{NULL} but won't raise an \code{Py_BuildValue()} will return \NULL{} but won't raise an
exception. If no exception has been raised yet, exception. If no exception has been raised yet,
\code{PyExc_SystemError} is set. \code{PyExc_SystemError} is set.
@ -822,25 +826,25 @@ Same as \samp{O}.
Convert \var{anything} to a Python object through a \var{converter} Convert \var{anything} to a Python object through a \var{converter}
function. The function is called with \var{anything} (which should be function. The function is called with \var{anything} (which should be
compatible with \code{void *}) as its argument and should return a compatible with \code{void *}) as its argument and should return a
``new'' Python object, or \code{NULL} if an error occurred. ``new'' Python object, or \NULL{} if an error occurred.
\item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}] \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
Convert a sequence of C values to a Python tuple with the same number Convert a sequence of \C{} values to a Python tuple with the same number
of items. of items.
\item[\samp{[\var{items}]} (list) {[\var{matching-items}]}] \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
Convert a sequence of C values to a Python list with the same number Convert a sequence of \C{} values to a Python list with the same number
of items. of items.
\item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}] \item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
Convert a sequence of C values to a Python dictionary. Each pair of Convert a sequence of \C{} values to a Python dictionary. Each pair of
consecutive C values adds one item to the dictionary, serving as key consecutive \C{} values adds one item to the dictionary, serving as key
and value, respectively. and value, respectively.
\end{description} \end{description}
If there is an error in the format string, the If there is an error in the format string, the
\code{PyExc_SystemError} exception is raised and \code{NULL} returned. \code{PyExc_SystemError} exception is raised and \NULL{} returned.
Examples (to the left the call, to the right the resulting Python value): Examples (to the left the call, to the right the resulting Python value):
@ -866,8 +870,8 @@ Examples (to the left the call, to the right the resulting Python value):
\subsection{Introduction} \subsection{Introduction}
In languages like C or \Cpp{}, the programmer is responsible for In languages like \C{} or \Cpp{}, the programmer is responsible for
dynamic allocation and deallocation of memory on the heap. In C, this dynamic allocation and deallocation of memory on the heap. In \C{}, this
is done using the functions \code{malloc()} and \code{free()}. In is done using the functions \code{malloc()} and \code{free()}. In
\Cpp{}, the operators \code{new} and \code{delete} are used with \Cpp{}, the operators \code{new} and \code{delete} are used with
essentially the same meaning; they are actually implemented using essentially the same meaning; they are actually implemented using
@ -916,12 +920,12 @@ collection strategy, hence my use of ``automatic'' to distinguish the
two.) The big advantage of automatic garbage collection is that the two.) The big advantage of automatic garbage collection is that the
user doesn't need to call \code{free()} explicitly. (Another claimed user doesn't need to call \code{free()} explicitly. (Another claimed
advantage is an improvement in speed or memory usage --- this is no advantage is an improvement in speed or memory usage --- this is no
hard fact however.) The disadvantage is that for C, there is no hard fact however.) The disadvantage is that for \C{}, there is no
truly portable automatic garbage collector, while reference counting truly portable automatic garbage collector, while reference counting
can be implemented portably (as long as the functions \code{malloc()} can be implemented portably (as long as the functions \code{malloc()}
and \code{free()} are available --- which the C Standard guarantees). and \code{free()} are available --- which the \C{} Standard guarantees).
Maybe some day a sufficiently portable automatic garbage collector Maybe some day a sufficiently portable automatic garbage collector
will be available for C. Until then, we'll have to live with will be available for \C{}. Until then, we'll have to live with
reference counts. reference counts.
\subsection{Reference Counting in Python} \subsection{Reference Counting in Python}
@ -1008,14 +1012,14 @@ take over ownership of the item passed to them --- even if they fail!
(Note that \code{PyDict_SetItem()} and friends don't take over (Note that \code{PyDict_SetItem()} and friends don't take over
ownership --- they are ``normal''.) ownership --- they are ``normal''.)
When a C function is called from Python, it borrows references to its When a \C{} function is called from Python, it borrows references to its
arguments from the caller. The caller owns a reference to the object, arguments from the caller. The caller owns a reference to the object,
so the borrowed reference's lifetime is guaranteed until the function so the borrowed reference's lifetime is guaranteed until the function
returns. Only when such a borrowed reference must be stored or passed returns. Only when such a borrowed reference must be stored or passed
on, it must be turned into an owned reference by calling on, it must be turned into an owned reference by calling
\code{Py_INCREF()}. \code{Py_INCREF()}.
The object reference returned from a C function that is called from The object reference returned from a \C{} function that is called from
Python must be an owned reference --- ownership is tranferred from the Python must be an owned reference --- ownership is tranferred from the
function to its caller. function to its caller.
@ -1074,7 +1078,7 @@ no_bug(PyObject *list) {
\end{verbatim}\ecode \end{verbatim}\ecode
% %
This is a true story. An older version of Python contained variants 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 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... debugger to figure out why his \code{__del__()} methods would fail...
The second case of problems with a borrowed reference is a variant The second case of problems with a borrowed reference is a variant
@ -1101,36 +1105,36 @@ bug(PyObject *list) {
\subsection{NULL Pointers} \subsection{NULL Pointers}
In general, functions that take object references as arguments don't In general, functions that take object references as arguments don't
expect you to pass them \code{NULL} pointers, and will dump core (or expect you to pass them \NULL{} pointers, and will dump core (or
cause later core dumps) if you do so. Functions that return object cause later core dumps) if you do so. Functions that return object
references generally return \code{NULL} only to indicate that an references generally return \NULL{} only to indicate that an
exception occurred. The reason for not testing for \code{NULL} exception occurred. The reason for not testing for \NULL{}
arguments is that functions often pass the objects they receive on to arguments is that functions often pass the objects they receive on to
other function --- if each function were to test for \code{NULL}, other function --- if each function were to test for \NULL{},
there would be a lot of redundant tests and the code would run slower. there would be a lot of redundant tests and the code would run slower.
It is better to test for \code{NULL} only at the ``source'', i.e.\ It is better to test for \NULL{} only at the ``source'', i.e.\
when a pointer that may be \code{NULL} is received, e.g.\ from when a pointer that may be \NULL{} is received, e.g.\ from
\code{malloc()} or from a function that may raise an exception. \code{malloc()} or from a function that may raise an exception.
The macros \code{Py_INCREF()} and \code{Py_DECREF()} The macros \code{Py_INCREF()} and \code{Py_DECREF()}
don't check for \code{NULL} pointers --- however, their variants don't check for \NULL{} pointers --- however, their variants
\code{Py_XINCREF()} and \code{Py_XDECREF()} do. \code{Py_XINCREF()} and \code{Py_XDECREF()} do.
The macros for checking for a particular object type The macros for checking for a particular object type
(\code{Py\var{type}_Check()}) don't check for \code{NULL} pointers --- (\code{Py\var{type}_Check()}) don't check for \NULL{} pointers ---
again, there is much code that calls several of these in a row to test again, there is much code that calls several of these in a row to test
an object against various different expected types, and this would an object against various different expected types, and this would
generate redundant tests. There are no variants with \code{NULL} generate redundant tests. There are no variants with \NULL{}
checking. checking.
The C function calling mechanism guarantees that the argument list The \C{} function calling mechanism guarantees that the argument list
passed to C functions (\code{args} in the examples) is never passed to \C{} functions (\code{args} in the examples) is never
\code{NULL} --- in fact it guarantees that it is always a tuple.% \NULL{} --- in fact it guarantees that it is always a tuple.%
\footnote{These guarantees don't hold when you use the ``old'' style \footnote{These guarantees don't hold when you use the ``old'' style
calling convention --- this is still found in much existing code.} calling convention --- this is still found in much existing code.}
It is a severe error to ever let a \code{NULL} pointer ``escape'' to It is a severe error to ever let a \NULL{} pointer ``escape'' to
the Python user. the Python user.
@ -1138,7 +1142,7 @@ the Python user.
It is possible to write extension modules in \Cpp{}. Some restrictions It is possible to write extension modules in \Cpp{}. Some restrictions
apply. If the main program (the Python interpreter) is compiled and apply. If the main program (the Python interpreter) is compiled and
linked by the C compiler, global or static objects with constructors linked by the \C{} compiler, global or static objects with constructors
cannot be used. This is not a problem if the main program is linked cannot be used. This is not a problem if the main program is linked
by the \Cpp{} compiler. All functions that will be called directly or by the \Cpp{} compiler. All functions that will be called directly or
indirectly (i.e. via function pointers) by the Python interpreter will indirectly (i.e. via function pointers) by the Python interpreter will
@ -1146,7 +1150,7 @@ have to be declared using \code{extern "C"}; this applies to all
``methods'' as well as to the module's initialization function. ``methods'' as well as to the module's initialization function.
It is unnecessary to enclose the Python header files in It is unnecessary to enclose the Python header files in
\code{extern "C" \{...\}} --- they use this form already if the symbol \code{extern "C" \{...\}} --- they use this form already if the symbol
\samp{__cplusplus} is defined (all recent C++ compilers define this \samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
symbol). symbol).
\chapter{Embedding Python in another application} \chapter{Embedding Python in another application}
@ -1188,7 +1192,7 @@ itself using \Cpp{}.
\chapter{Dynamic Loading} \chapter{Dynamic Loading}
On most modern systems it is possible to configure Python to support On most modern systems it is possible to configure Python to support
dynamic loading of extension modules implemented in C. When shared dynamic loading of extension modules implemented in \C{}. When shared
libraries are used dynamic loading is configured automatically; libraries are used dynamic loading is configured automatically;
otherwise you have to select it as a build option (see below). Once otherwise you have to select it as a build option (see below). Once
configured, dynamic loading is trivial to use: when a Python program configured, dynamic loading is trivial to use: when a Python program
@ -1200,7 +1204,7 @@ module acts just like a built-in extension module.
The advantages of dynamic loading are twofold: the ``core'' Python The advantages of dynamic loading are twofold: the ``core'' Python
binary gets smaller, and users can extend Python with their own binary gets smaller, and users can extend Python with their own
modules implemented in C without having to build and maintain their modules implemented in \C{} without having to build and maintain their
own copy of the Python interpreter. There are also disadvantages: own copy of the Python interpreter. There are also disadvantages:
dynamic loading isn't available on all systems (this just means that dynamic loading isn't available on all systems (this just means that
on some systems you have to use static loading), and dynamically on some systems you have to use static loading), and dynamically
@ -1289,7 +1293,7 @@ described earlier).
Note that in all cases you will have to create your own Makefile that Note that in all cases you will have to create your own Makefile that
compiles your module file(s). This Makefile will have to pass two compiles your module file(s). This Makefile will have to pass two
\samp{-I} arguments to the C compiler which will make it find the \samp{-I} arguments to the \C{} compiler which will make it find the
Python header files. If the Make variable \var{PYTHONTOP} points to Python header files. If the Make variable \var{PYTHONTOP} points to
the toplevel Python directory, your \var{CFLAGS} Make variable should the toplevel Python directory, your \var{CFLAGS} Make variable should
contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}. contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
@ -1333,7 +1337,7 @@ along the Python module search path.
\subsection{SGI IRIX 4 Dynamic Loading} \subsection{SGI IRIX 4 Dynamic Loading}
{\bf IMPORTANT:} You must compile your extension module with the {\bf IMPORTANT:} You must compile your extension module with the
additional C flag \samp{-G0} (or \samp{-G 0}). This instruct the additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instruct the
assembler to generate position-independent code. assembler to generate position-independent code.
You don't need to link the resulting \file{spammodule.o} file; just You don't need to link the resulting \file{spammodule.o} file; just

268
Doc/ext/ext.tex
View File

@ -1,4 +1,5 @@
\documentstyle[twoside,11pt,myformat]{report} \documentclass[twoside]{report}
\usepackage{myformat}
% XXX PM Modulator % XXX PM Modulator
@ -11,6 +12,7 @@
\begin{document} \begin{document}
\pagestyle{empty}
\pagenumbering{roman} \pagenumbering{roman}
\maketitle \maketitle
@ -21,7 +23,7 @@
\noindent \noindent
Python is an interpreted, object-oriented programming language. This Python is an interpreted, object-oriented programming language. This
document describes how to write modules in C or \Cpp{} to extend the document describes how to write modules in \C{} or \Cpp{} to extend the
Python interpreter with new modules. Those modules can define new Python interpreter with new modules. Those modules can define new
functions but also new object types and their methods. The document functions but also new object types and their methods. The document
also describes how to embed the Python interpreter in another also describes how to embed the Python interpreter in another
@ -37,8 +39,8 @@ Python Library Reference documents the existing object types,
functions and modules (both built-in and written in Python) that give functions and modules (both built-in and written in Python) that give
the language its wide application range. the language its wide application range.
For a detailed description of the whole Python/C API, see the separate For a detailed description of the whole Python/\C{} API, see the separate
Python/C API Reference Manual. \strong{Note:} While that manual is Python/\C{} API Reference Manual. \strong{Note:} While that manual is
still in a state of flux, it is safe to say that it is much more up to still in a state of flux, it is safe to say that it is much more up to
date than the manual you're reading currently (which has been in need date than the manual you're reading currently (which has been in need
for an upgrade for some time now). for an upgrade for some time now).
@ -46,32 +48,25 @@ for an upgrade for some time now).
\end{abstract} \end{abstract}
\pagebreak \mytableofcontents
{
\parskip = 0mm
\tableofcontents
}
\pagebreak
\pagenumbering{arabic} \pagenumbering{arabic}
\chapter{Extending Python with C or \Cpp{} code} \chapter{Extending Python with \C{} or \Cpp{} code}
\section{Introduction} \section{Introduction}
It is quite easy to add new built-in modules to Python, if you know It is quite easy to add new built-in modules to Python, if you know
how to program in C. Such \dfn{extension modules} can do two things how to program in \C{}. Such \dfn{extension modules} can do two things
that can't be done directly in Python: they can implement new built-in that can't be done directly in Python: they can implement new built-in
object types, and they can call C library functions and system calls. object types, and they can call \C{} library functions and system calls.
To support extensions, the Python API (Application Programmers To support extensions, the Python API (Application Programmers
Interface) defines a set of functions, macros and variables that Interface) defines a set of functions, macros and variables that
provide access to most aspects of the Python run-time system. The provide access to most aspects of the Python run-time system. The
Python API is incorporated in a C source file by including the header Python API is incorporated in a \C{} source file by including the header
\code{"Python.h"}. \code{"Python.h"}.
The compilation of an extension module depends on its intended use as The compilation of an extension module depends on its intended use as
@ -82,7 +77,7 @@ well as on your system setup; details are given in a later section.
Let's create an extension module called \samp{spam} (the favorite food Let's create an extension module called \samp{spam} (the favorite food
of Monty Python fans...) and let's say we want to create a Python of Monty Python fans...) and let's say we want to create a Python
interface to the C library function \code{system()}.\footnote{An interface to the \C{} library function \code{system()}.\footnote{An
interface for this function already exists in the standard module interface for this function already exists in the standard module
\code{os} --- it was chosen as a simple and straightfoward example.} \code{os} --- it was chosen as a simple and straightfoward example.}
This function takes a null-terminated character string as argument and This function takes a null-terminated character string as argument and
@ -95,7 +90,7 @@ as follows:
\end{verbatim}\ecode \end{verbatim}\ecode
% %
Begin by creating a file \samp{spammodule.c}. (In general, if a Begin by creating a file \samp{spammodule.c}. (In general, if a
module is called \samp{spam}, the C file containing its implementation module is called \samp{spam}, the \C{} file containing its implementation
is called \file{spammodule.c}; if the module name is very long, like is called \file{spammodule.c}; if the module name is very long, like
\samp{spammify}, the module name can be just \file{spammify.c}.) \samp{spammify}, the module name can be just \file{spammify.c}.)
@ -117,7 +112,7 @@ interpreter, \code{"Python.h"} includes a few standard header files:
system, it declares the functions \code{malloc()}, \code{free()} and system, it declares the functions \code{malloc()}, \code{free()} and
\code{realloc()} directly. \code{realloc()} directly.
The next thing we add to our module file is the C function that will The next thing we add to our module file is the \C{} function that will
be called when the Python expression \samp{spam.system(\var{string})} be called when the Python expression \samp{spam.system(\var{string})}
is evaluated (we'll see shortly how it ends up being called): is evaluated (we'll see shortly how it ends up being called):
@ -138,23 +133,23 @@ is evaluated (we'll see shortly how it ends up being called):
% %
There is a straightforward translation from the argument list in There is a straightforward translation from the argument list in
Python (e.g.\ the single expression \code{"ls -l"}) to the arguments Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
passed to the C function. The C function always has two arguments, passed to the \C{} function. The \C{} function always has two arguments,
conventionally named \var{self} and \var{args}. conventionally named \var{self} and \var{args}.
The \var{self} argument is only used when the C function implements a The \var{self} argument is only used when the \C{} function implements a
builtin method. This will be discussed later. In the example, builtin method. This will be discussed later. In the example,
\var{self} will always be a \code{NULL} pointer, since we are defining \var{self} will always be a \NULL{} pointer, since we are defining
a function, not a method. (This is done so that the interpreter a function, not a method. (This is done so that the interpreter
doesn't have to understand two different types of C functions.) doesn't have to understand two different types of \C{} functions.)
The \var{args} argument will be a pointer to a Python tuple object The \var{args} argument will be a pointer to a Python tuple object
containing the arguments. Each item of the tuple corresponds to an containing the arguments. Each item of the tuple corresponds to an
argument in the call's argument list. The arguments are Python argument in the call's argument list. The arguments are Python
objects -- in order to do anything with them in our C function we have objects -- in order to do anything with them in our \C{} function we have
to convert them to C values. The function \code{PyArg_ParseTuple()} to convert them to \C{} values. The function \code{PyArg_ParseTuple()}
in the Python API checks the argument types and converts them to C in the Python API checks the argument types and converts them to \C{}
values. It uses a template string to determine the required types of values. It uses a template string to determine the required types of
the arguments as well as the types of the C variables into which to the arguments as well as the types of the \C{} variables into which to
store the converted values. More about this later. store the converted values. More about this later.
\code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have \code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
@ -162,20 +157,20 @@ the right type and its components have been stored in the variables
whose addresses are passed. It returns false (zero) if an invalid whose addresses are passed. It returns false (zero) if an invalid
argument list was passed. In the latter case it also raises an argument list was passed. In the latter case it also raises an
appropriate exception by so the calling function can return appropriate exception by so the calling function can return
\code{NULL} immediately (as we saw in the example). \NULL{} immediately (as we saw in the example).
\section{Intermezzo: Errors and Exceptions} \section{Intermezzo: Errors and Exceptions}
An important convention throughout the Python interpreter is the An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition following: when a function fails, it should set an exception condition
and return an error value (usually a \code{NULL} pointer). Exceptions and return an error value (usually a \NULL{} pointer). Exceptions
are stored in a static global variable inside the interpreter; if this are stored in a static global variable inside the interpreter; if this
variable is \code{NULL} no exception has occurred. A second global variable is \NULL{} no exception has occurred. A second global
variable stores the ``associated value'' of the exception (the second variable stores the ``associated value'' of the exception (the second
argument to \code{raise}). A third variable contains the stack argument to \code{raise}). A third variable contains the stack
traceback in case the error originated in Python code. These three traceback in case the error originated in Python code. These three
variables are the C equivalents of the Python variables variables are the \C{} equivalents of the Python variables
\code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback} \code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback}
(see the section on module \code{sys} in the Library Reference (see the section on module \code{sys} in the Library Reference
Manual). It is important to know about them to understand how errors Manual). It is important to know about them to understand how errors
@ -185,8 +180,8 @@ The Python API defines a number of functions to set various types of
exceptions. exceptions.
The most common one is \code{PyErr_SetString()}. Its arguments are an The most common one is \code{PyErr_SetString()}. Its arguments are an
exception object and a C string. The exception object is usually a exception object and a \C{} string. The exception object is usually a
predefined object like \code{PyExc_ZeroDivisionError}. The C string predefined object like \code{PyExc_ZeroDivisionError}. The \C{} string
indicates the cause of the error and is converted to a Python string indicates the cause of the error and is converted to a Python string
object and stored as the ``associated value'' of the exception. object and stored as the ``associated value'' of the exception.
@ -199,13 +194,13 @@ arguments, the exception and its associated value. You don't need to
You can test non-destructively whether an exception has been set with You can test non-destructively whether an exception has been set with
\code{PyErr_Occurred()}. This returns the current exception object, \code{PyErr_Occurred()}. This returns the current exception object,
or \code{NULL} if no exception has occurred. You normally don't need or \NULL{} if no exception has occurred. You normally don't need
to call \code{PyErr_Occurred()} to see whether an error occurred in a to call \code{PyErr_Occurred()} to see whether an error occurred in a
function call, since you should be able to tell from the return value. function call, since you should be able to tell from the return value.
When a function \var{f} that calls another function \var{g} detects When a function \var{f} that calls another function \var{g} detects
that the latter fails, \var{f} should itself return an error value that the latter fails, \var{f} should itself return an error value
(e.g. \code{NULL} or \code{-1}). It should \emph{not} call one of the (e.g. \NULL{} or \code{-1}). It should \emph{not} call one of the
\code{PyErr_*()} functions --- one has already been called by \var{g}. \code{PyErr_*()} functions --- one has already been called by \var{g}.
\var{f}'s caller is then supposed to also return an error indication \var{f}'s caller is then supposed to also return an error indication
to \emph{its} caller, again \emph{without} calling \code{PyErr_*()}, to \emph{its} caller, again \emph{without} calling \code{PyErr_*()},
@ -223,7 +218,7 @@ to be lost: most operations can fail for a variety of reasons.)
To ignore an exception set by a function call that failed, the exception To ignore an exception set by a function call that failed, the exception
condition must be cleared explicitly by calling \code{PyErr_Clear()}. condition must be cleared explicitly by calling \code{PyErr_Clear()}.
The only time C code should call \code{PyErr_Clear()} is if it doesn't The only time \C{} code should call \code{PyErr_Clear()} is if it doesn't
want to pass the error on to the interpreter but wants to handle it want to pass the error on to the interpreter but wants to handle it
completely by itself (e.g. by trying something else or pretending completely by itself (e.g. by trying something else or pretending
nothing happened). nothing happened).
@ -245,7 +240,7 @@ or \code{Py_DECREF()} calls for objects you have already created) when
you return an error indicator! you return an error indicator!
The choice of which exception to raise is entirely yours. There are The choice of which exception to raise is entirely yours. There are
predeclared C objects corresponding to all built-in Python exceptions, predeclared \C{} objects corresponding to all built-in Python exceptions,
e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of
course, you should choose exceptions wisely --- don't use course, you should choose exceptions wisely --- don't use
\code{PyExc_TypeError} to mean that a file couldn't be opened (that \code{PyExc_TypeError} to mean that a file couldn't be opened (that
@ -296,12 +291,12 @@ understand this statement:
return NULL; return NULL;
\end{verbatim}\ecode \end{verbatim}\ecode
% %
It returns \code{NULL} (the error indicator for functions returning It returns \NULL{} (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying object pointers) if an error is detected in the argument list, relying
on the exception set by \code{PyArg_ParseTuple()}. Otherwise the on the exception set by \code{PyArg_ParseTuple()}. Otherwise the
string value of the argument has been copied to the local variable string value of the argument has been copied to the local variable
\code{command}. This is a pointer assignment and you are not supposed \code{command}. This is a pointer assignment and you are not supposed
to modify the string to which it points (so in Standard C, the variable to modify the string to which it points (so in Standard \C{}, the variable
\code{command} should properly be declared as \samp{const char \code{command} should properly be declared as \samp{const char
*command}). *command}).
@ -316,7 +311,7 @@ Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of \code{Py_BuildValue()}, which is something like the inverse of
\code{PyArg_ParseTuple()}: it takes a format string and an arbitrary \code{PyArg_ParseTuple()}: it takes a format string and an arbitrary
number of C values, and returns a new Python object. More info on number of \C{} values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later. \code{Py_BuildValue()} is given later.
\bcode\begin{verbatim} \bcode\begin{verbatim}
@ -326,7 +321,7 @@ number of C values, and returns a new Python object. More info on
In this case, it will return an integer object. (Yes, even integers In this case, it will return an integer object. (Yes, even integers
are objects on the heap in Python!) are objects on the heap in Python!)
If you have a C function that returns no useful argument (a function If you have a \C{} function that returns no useful argument (a function
returning \code{void}), the corresponding Python function must return returning \code{void}), the corresponding Python function must return
\code{None}. You need this idiom to do so: \code{None}. You need this idiom to do so:
@ -335,8 +330,8 @@ returning \code{void}), the corresponding Python function must return
return Py_None; return Py_None;
\end{verbatim}\ecode \end{verbatim}\ecode
% %
\code{Py_None} is the C name for the special Python object \code{Py_None} is the \C{} name for the special Python object
\code{None}. It is a genuine Python object (not a \code{NULL} \code{None}. It is a genuine Python object (not a \NULL{}
pointer, which means ``error'' in most contexts, as we have seen). pointer, which means ``error'' in most contexts, as we have seen).
@ -349,17 +344,26 @@ table'':
\bcode\begin{verbatim} \bcode\begin{verbatim}
static PyMethodDef SpamMethods[] = { static PyMethodDef SpamMethods[] = {
... ...
{"system", spam_system, 1}, {"system", spam_system, METH_VARARGS},
... ...
{NULL, NULL} /* Sentinel */ {NULL, NULL} /* Sentinel */
}; };
\end{verbatim}\ecode \end{verbatim}\ecode
% %
Note the third entry (\samp{1}). This is a flag telling the Note the third entry (\samp{METH_VARARGS}). This is a flag telling
interpreter the calling convention to be used for the C function. It the interpreter the calling convention to be used for the \C{}
should normally always be \samp{1}; a value of \samp{0} means that an function. It should normally always be \samp{METH_VARARGS} or
\samp{METH_VARARGS | METH_KEYWORDS}; a value of \samp{0} means that an
obsolete variant of \code{PyArg_ParseTuple()} is used. obsolete variant of \code{PyArg_ParseTuple()} is used.
The \code{METH_KEYWORDS} bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the \C{}
function should accept a third \samp{PyObject *} parameter which will
be a dictionary of keywords. Use \code{PyArg_ParseTupleAndKeywords()}
to parse the arguemts to such a function.
XXX --- need to explain PyArg_ParseTupleAndKeywords() in detail.
The method table must be passed to the interpreter in the module's The method table must be passed to the interpreter in the module's
initialization function (which should be the only non-\code{static} initialization function (which should be the only non-\code{static}
item defined in the module file): item defined in the module file):
@ -416,15 +420,15 @@ be listed on the line in the \file{Setup} file as well, for instance:
spam spammodule.o -lX11 spam spammodule.o -lX11
\end{verbatim}\ecode \end{verbatim}\ecode
% %
\section{Calling Python Functions From C} \section{Calling Python Functions From \C{}}
So far we have concentrated on making C functions callable from So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from C. Python. The reverse is also useful: calling Python functions from \C{}.
This is especially the case for libraries that support so-called This is especially the case for libraries that support so-called
``callback'' functions. If a C interface makes use of callbacks, the ``callback'' functions. If a \C{} interface makes use of callbacks, the
equivalent Python often needs to provide a callback mechanism to the equivalent Python often needs to provide a callback mechanism to the
Python programmer; the implementation will require calling the Python Python programmer; the implementation will require calling the Python
callback functions from a C callback. Other uses are also imaginable. callback functions from a \C{} callback. Other uses are also imaginable.
Fortunately, the Python interpreter is easily called recursively, and Fortunately, the Python interpreter is easily called recursively, and
there is a standard interface to call a Python function. (I won't there is a standard interface to call a Python function. (I won't
@ -458,10 +462,10 @@ definition:
% %
The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
the reference count of an object and are safe in the presence of the reference count of an object and are safe in the presence of
\code{NULL} pointers. More info on them in the section on Reference \NULL{} pointers. More info on them in the section on Reference
Counts below. Counts below.
Later, when it is time to call the function, you call the C function Later, when it is time to call the function, you call the \C{} function
\code{PyEval_CallObject()}. This function has two arguments, both \code{PyEval_CallObject()}. This function has two arguments, both
pointers to arbitrary Python objects: the Python function, and the pointers to arbitrary Python objects: the Python function, and the
argument list. The argument list must always be a tuple object, whose argument list. The argument list must always be a tuple object, whose
@ -497,8 +501,8 @@ global variable, you should somehow \code{Py_DECREF()} the result,
even (especially!) if you are not interested in its value. even (especially!) if you are not interested in its value.
Before you do this, however, it is important to check that the return Before you do this, however, it is important to check that the return
value isn't \code{NULL}. If it is, the Python function terminated by raising value isn't \NULL{}. If it is, the Python function terminated by raising
an exception. If the C code that called \code{PyEval_CallObject()} is an exception. If the \C{} code that called \code{PyEval_CallObject()} is
called from Python, it should now return an error indication to its called from Python, it should now return an error indication to its
Python caller, so the interpreter can print a stack trace, or the Python caller, so the interpreter can print a stack trace, or the
calling Python code can handle the exception. If this is not possible calling Python code can handle the exception. If this is not possible
@ -549,7 +553,7 @@ The \code{PyArg_ParseTuple()} function is declared as follows:
\end{verbatim}\ecode \end{verbatim}\ecode
% %
The \var{arg} argument must be a tuple object containing an argument The \var{arg} argument must be a tuple object containing an argument
list passed from Python to a C function. The \var{format} argument list passed from Python to a \C{} function. The \var{format} argument
must be a format string, whose syntax is explained below. The must be a format string, whose syntax is explained below. The
remaining arguments must be addresses of variables whose type is remaining arguments must be addresses of variables whose type is
determined by the format string. For the conversion to succeed, the determined by the format string. For the conversion to succeed, the
@ -558,7 +562,7 @@ exhausted.
Note that while \code{PyArg_ParseTuple()} checks that the Python Note that while \code{PyArg_ParseTuple()} checks that the Python
arguments have the required types, it cannot check the validity of the arguments have the required types, it cannot check the validity of the
addresses of C variables passed to the call: if you make mistakes addresses of \C{} variables passed to the call: if you make mistakes
there, your code will probably crash or at least overwrite random bits there, your code will probably crash or at least overwrite random bits
in memory. So be careful! in memory. So be careful!
@ -569,72 +573,72 @@ format unit that is not a parenthesized sequence normally corresponds
to a single address argument to \code{PyArg_ParseTuple()}. In the to a single address argument to \code{PyArg_ParseTuple()}. In the
following description, the quoted form is the format unit; the entry following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that matches the in (round) parentheses is the Python object type that matches the
format unit; and the entry in [square] brackets is the type of the C format unit; and the entry in [square] brackets is the type of the \C{}
variable(s) whose address should be passed. (Use the \samp{\&} variable(s) whose address should be passed. (Use the \samp{\&}
operator to pass a variable's address.) operator to pass a variable's address.)
\begin{description} \begin{description}
\item[\samp{s} (string) [char *]] \item[\samp{s} (string) [char *]]
Convert a Python string to a C pointer to a character string. You Convert a Python string to a \C{} pointer to a character string. You
must not provide storage for the string itself; a pointer to an must not provide storage for the string itself; a pointer to an
existing string is stored into the character pointer variable whose existing string is stored into the character pointer variable whose
address you pass. The C string is null-terminated. The Python string address you pass. The \C{} string is null-terminated. The Python string
must not contain embedded null bytes; if it does, a \code{TypeError} must not contain embedded null bytes; if it does, a \code{TypeError}
exception is raised. exception is raised.
\item[\samp{s\#} (string) {[char *, int]}] \item[\samp{s\#} (string) {[char *, int]}]
This variant on \code{'s'} stores into two C variables, the first one This variant on \code{'s'} stores into two \C{} variables, the first one
a pointer to a character string, the second one its length. In this a pointer to a character string, the second one its length. In this
case the Python string may contain embedded null bytes. case the Python string may contain embedded null bytes.
\item[\samp{z} (string or \code{None}) {[char *]}] \item[\samp{z} (string or \code{None}) {[char *]}]
Like \samp{s}, but the Python object may also be \code{None}, in which Like \samp{s}, but the Python object may also be \code{None}, in which
case the C pointer is set to \code{NULL}. case the \C{} pointer is set to \NULL{}.
\item[\samp{z\#} (string or \code{None}) {[char *, int]}] \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
This is to \code{'s\#'} as \code{'z'} is to \code{'s'}. This is to \code{'s\#'} as \code{'z'} is to \code{'s'}.
\item[\samp{b} (integer) {[char]}] \item[\samp{b} (integer) {[char]}]
Convert a Python integer to a tiny int, stored in a C \code{char}. Convert a Python integer to a tiny int, stored in a \C{} \code{char}.
\item[\samp{h} (integer) {[short int]}] \item[\samp{h} (integer) {[short int]}]
Convert a Python integer to a C \code{short int}. Convert a Python integer to a \C{} \code{short int}.
\item[\samp{i} (integer) {[int]}] \item[\samp{i} (integer) {[int]}]
Convert a Python integer to a plain C \code{int}. Convert a Python integer to a plain \C{} \code{int}.
\item[\samp{l} (integer) {[long int]}] \item[\samp{l} (integer) {[long int]}]
Convert a Python integer to a C \code{long int}. Convert a Python integer to a \C{} \code{long int}.
\item[\samp{c} (string of length 1) {[char]}] \item[\samp{c} (string of length 1) {[char]}]
Convert a Python character, represented as a string of length 1, to a Convert a Python character, represented as a string of length 1, to a
C \code{char}. \C{} \code{char}.
\item[\samp{f} (float) {[float]}] \item[\samp{f} (float) {[float]}]
Convert a Python floating point number to a C \code{float}. Convert a Python floating point number to a \C{} \code{float}.
\item[\samp{d} (float) {[double]}] \item[\samp{d} (float) {[double]}]
Convert a Python floating point number to a C \code{double}. Convert a Python floating point number to a \C{} \code{double}.
\item[\samp{O} (object) {[PyObject *]}] \item[\samp{O} (object) {[PyObject *]}]
Store a Python object (without any conversion) in a C object pointer. Store a Python object (without any conversion) in a \C{} object pointer.
The C program thus receives the actual object that was passed. The The \C{} program thus receives the actual object that was passed. The
object's reference count is not increased. The pointer stored is not object's reference count is not increased. The pointer stored is not
\code{NULL}. \NULL{}.
\item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}] \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
Store a Python object in a C object pointer. This is similar to Store a Python object in a \C{} object pointer. This is similar to
\samp{O}, but takes two C arguments: the first is the address of a \samp{O}, but takes two \C{} arguments: the first is the address of a
Python type object, the second is the address of the C variable (of Python type object, the second is the address of the \C{} variable (of
type \code{PyObject *}) into which the object pointer is stored. type \code{PyObject *}) into which the object pointer is stored.
If the Python object does not have the required type, a If the Python object does not have the required type, a
\code{TypeError} exception is raised. \code{TypeError} exception is raised.
\item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}] \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
Convert a Python object to a C variable through a \var{converter} Convert a Python object to a \C{} variable through a \var{converter}
function. This takes two arguments: the first is a function, the function. This takes two arguments: the first is a function, the
second is the address of a C variable (of arbitrary type), converted second is the address of a \C{} variable (of arbitrary type), converted
to \code{void *}. The \var{converter} function in turn is called as to \code{void *}. The \var{converter} function in turn is called as
follows: follows:
@ -649,12 +653,12 @@ should raise an exception.
\item[\samp{S} (string) {[PyStringObject *]}] \item[\samp{S} (string) {[PyStringObject *]}]
Like \samp{O} but raises a \code{TypeError} exception that the object Like \samp{O} but raises a \code{TypeError} exception that the object
is a string object. The C variable may also be declared as is a string object. The \C{} variable may also be declared as
\code{PyObject *}. \code{PyObject *}.
\item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}] \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
The object must be a Python tuple whose length is the number of format The object must be a Python tuple whose length is the number of format
units in \var{items}. The C arguments must correspond to the units in \var{items}. The \C{} arguments must correspond to the
individual format units in \var{items}. Format units for tuples may individual format units in \var{items}. Format units for tuples may
be nested. be nested.
@ -664,7 +668,7 @@ It is possible to pass Python long integers where integers are
requested; however no proper range checking is done -- the most requested; however no proper range checking is done -- the most
significant bits are silently truncated when the receiving field is significant bits are silently truncated when the receiving field is
too small to receive the value (actually, the semantics are inherited too small to receive the value (actually, the semantics are inherited
from downcasts in C --- your milage may vary). from downcasts in \C{} --- your milage may vary).
A few other characters have a meaning in a format string. These may A few other characters have a meaning in a format string. These may
not occur inside nested parentheses. They are: not occur inside nested parentheses. They are:
@ -673,10 +677,10 @@ not occur inside nested parentheses. They are:
\item[\samp{|}] \item[\samp{|}]
Indicates that the remaining arguments in the Python argument list are Indicates that the remaining arguments in the Python argument list are
optional. The C variables corresponding to optional arguments should optional. The \C{} variables corresponding to optional arguments should
be initialized to their default value --- when an optional argument is be initialized to their default value --- when an optional argument is
not specified, the \code{PyArg_ParseTuple} does not touch the contents not specified, the \code{PyArg_ParseTuple} does not touch the contents
of the corresponding C variable(s). of the corresponding \C{} variable(s).
\item[\samp{:}] \item[\samp{:}]
The list of format units ends here; the string after the colon is used The list of format units ends here; the string after the colon is used
@ -692,7 +696,7 @@ Clearly, \samp{:} and \samp{;} mutually exclude each other.
Some example calls: Some example calls:
\bcode\begin{verbatim} \begin{verbatim}
int ok; int ok;
int i, j; int i, j;
long k, l; long k, l;
@ -701,13 +705,13 @@ Some example calls:
ok = PyArg_ParseTuple(args, ""); /* No arguments */ ok = PyArg_ParseTuple(args, ""); /* No arguments */
/* Python call: f() */ /* Python call: f() */
ok = PyArg_ParseTuple(args, "s", &s); /* A string */ ok = PyArg_ParseTuple(args, "s", &s); /* A string */
/* Possible Python call: f('whoops!') */ /* Possible Python call: f('whoops!') */
ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */ ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
/* Possible Python call: f(1, 2, 'three') */ /* Possible Python call: f(1, 2, 'three') */
ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size); ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
/* A pair of ints and a string, whose size is also returned */ /* A pair of ints and a string, whose size is also returned */
/* Possible Python call: f((1, 2), 'three') */ /* Possible Python call: f((1, 2), 'three') */
@ -732,7 +736,7 @@ Some example calls:
/* Possible Python call: /* Possible Python call:
f(((0, 0), (400, 300)), (10, 10)) */ f(((0, 0), (400, 300)), (10, 10)) */
} }
\end{verbatim}\ecode \end{verbatim}
% %
\section{The {\tt Py_BuildValue()} Function} \section{The {\tt Py_BuildValue()} Function}
@ -746,7 +750,7 @@ declared as follows:
It recognizes a set of format units similar to the ones recognized by It recognizes a set of format units similar to the ones recognized by
\code{PyArg_ParseTuple()}, but the arguments (which are input to the \code{PyArg_ParseTuple()}, but the arguments (which are input to the
function, not output) must not be pointers, just values. It returns a function, not output) must not be pointers, just values. It returns a
new Python object, suitable for returning from a C function called new Python object, suitable for returning from a \C{} function called
from Python. from Python.
One difference with \code{PyArg_ParseTuple()}: while the latter One difference with \code{PyArg_ParseTuple()}: while the latter
@ -761,7 +765,7 @@ to return a tuple of size 0 or one, parenthesize the format string.
In the following description, the quoted form is the format unit; the In the following description, the quoted form is the format unit; the
entry in (round) parentheses is the Python object type that the format entry in (round) parentheses is the Python object type that the format
unit will return; and the entry in [square] brackets is the type of unit will return; and the entry in [square] brackets is the type of
the C value(s) to be passed. the \C{} value(s) to be passed.
The characters space, tab, colon and comma are ignored in format The characters space, tab, colon and comma are ignored in format
strings (but not within format units such as \samp{s\#}). This can be strings (but not within format units such as \samp{s\#}). This can be
@ -770,12 +774,12 @@ used to make long format strings a tad more readable.
\begin{description} \begin{description}
\item[\samp{s} (string) {[char *]}] \item[\samp{s} (string) {[char *]}]
Convert a null-terminated C string to a Python object. If the C Convert a null-terminated \C{} string to a Python object. If the \C{}
string pointer is \code{NULL}, \code{None} is returned. string pointer is \NULL{}, \code{None} is returned.
\item[\samp{s\#} (string) {[char *, int]}] \item[\samp{s\#} (string) {[char *, int]}]
Convert a C string and its length to a Python object. If the C string Convert a \C{} string and its length to a Python object. If the \C{} string
pointer is \code{NULL}, the length is ignored and \code{None} is pointer is \NULL{}, the length is ignored and \code{None} is
returned. returned.
\item[\samp{z} (string or \code{None}) {[char *]}] \item[\samp{z} (string or \code{None}) {[char *]}]
@ -785,7 +789,7 @@ Same as \samp{s}.
Same as \samp{s\#}. Same as \samp{s\#}.
\item[\samp{i} (integer) {[int]}] \item[\samp{i} (integer) {[int]}]
Convert a plain C \code{int} to a Python integer object. Convert a plain \C{} \code{int} to a Python integer object.
\item[\samp{b} (integer) {[char]}] \item[\samp{b} (integer) {[char]}]
Same as \samp{i}. Same as \samp{i}.
@ -794,24 +798,24 @@ Same as \samp{i}.
Same as \samp{i}. Same as \samp{i}.
\item[\samp{l} (integer) {[long int]}] \item[\samp{l} (integer) {[long int]}]
Convert a C \code{long int} to a Python integer object. Convert a \C{} \code{long int} to a Python integer object.
\item[\samp{c} (string of length 1) {[char]}] \item[\samp{c} (string of length 1) {[char]}]
Convert a C \code{int} representing a character to a Python string of Convert a \C{} \code{int} representing a character to a Python string of
length 1. length 1.
\item[\samp{d} (float) {[double]}] \item[\samp{d} (float) {[double]}]
Convert a C \code{double} to a Python floating point number. Convert a \C{} \code{double} to a Python floating point number.
\item[\samp{f} (float) {[float]}] \item[\samp{f} (float) {[float]}]
Same as \samp{d}. Same as \samp{d}.
\item[\samp{O} (object) {[PyObject *]}] \item[\samp{O} (object) {[PyObject *]}]
Pass a Python object untouched (except for its reference count, which Pass a Python object untouched (except for its reference count, which
is incremented by one). If the object passed in is a \code{NULL} is incremented by one). If the object passed in is a \NULL{}
pointer, it is assumed that this was caused because the call producing pointer, it is assumed that this was caused because the call producing
the argument found an error and set an exception. Therefore, the argument found an error and set an exception. Therefore,
\code{Py_BuildValue()} will return \code{NULL} but won't raise an \code{Py_BuildValue()} will return \NULL{} but won't raise an
exception. If no exception has been raised yet, exception. If no exception has been raised yet,
\code{PyExc_SystemError} is set. \code{PyExc_SystemError} is set.
@ -822,25 +826,25 @@ Same as \samp{O}.
Convert \var{anything} to a Python object through a \var{converter} Convert \var{anything} to a Python object through a \var{converter}
function. The function is called with \var{anything} (which should be function. The function is called with \var{anything} (which should be
compatible with \code{void *}) as its argument and should return a compatible with \code{void *}) as its argument and should return a
``new'' Python object, or \code{NULL} if an error occurred. ``new'' Python object, or \NULL{} if an error occurred.
\item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}] \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
Convert a sequence of C values to a Python tuple with the same number Convert a sequence of \C{} values to a Python tuple with the same number
of items. of items.
\item[\samp{[\var{items}]} (list) {[\var{matching-items}]}] \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
Convert a sequence of C values to a Python list with the same number Convert a sequence of \C{} values to a Python list with the same number
of items. of items.
\item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}] \item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
Convert a sequence of C values to a Python dictionary. Each pair of Convert a sequence of \C{} values to a Python dictionary. Each pair of
consecutive C values adds one item to the dictionary, serving as key consecutive \C{} values adds one item to the dictionary, serving as key
and value, respectively. and value, respectively.
\end{description} \end{description}
If there is an error in the format string, the If there is an error in the format string, the
\code{PyExc_SystemError} exception is raised and \code{NULL} returned. \code{PyExc_SystemError} exception is raised and \NULL{} returned.
Examples (to the left the call, to the right the resulting Python value): Examples (to the left the call, to the right the resulting Python value):
@ -866,8 +870,8 @@ Examples (to the left the call, to the right the resulting Python value):
\subsection{Introduction} \subsection{Introduction}
In languages like C or \Cpp{}, the programmer is responsible for In languages like \C{} or \Cpp{}, the programmer is responsible for
dynamic allocation and deallocation of memory on the heap. In C, this dynamic allocation and deallocation of memory on the heap. In \C{}, this
is done using the functions \code{malloc()} and \code{free()}. In is done using the functions \code{malloc()} and \code{free()}. In
\Cpp{}, the operators \code{new} and \code{delete} are used with \Cpp{}, the operators \code{new} and \code{delete} are used with
essentially the same meaning; they are actually implemented using essentially the same meaning; they are actually implemented using
@ -916,12 +920,12 @@ collection strategy, hence my use of ``automatic'' to distinguish the
two.) The big advantage of automatic garbage collection is that the two.) The big advantage of automatic garbage collection is that the
user doesn't need to call \code{free()} explicitly. (Another claimed user doesn't need to call \code{free()} explicitly. (Another claimed
advantage is an improvement in speed or memory usage --- this is no advantage is an improvement in speed or memory usage --- this is no
hard fact however.) The disadvantage is that for C, there is no hard fact however.) The disadvantage is that for \C{}, there is no
truly portable automatic garbage collector, while reference counting truly portable automatic garbage collector, while reference counting
can be implemented portably (as long as the functions \code{malloc()} can be implemented portably (as long as the functions \code{malloc()}
and \code{free()} are available --- which the C Standard guarantees). and \code{free()} are available --- which the \C{} Standard guarantees).
Maybe some day a sufficiently portable automatic garbage collector Maybe some day a sufficiently portable automatic garbage collector
will be available for C. Until then, we'll have to live with will be available for \C{}. Until then, we'll have to live with
reference counts. reference counts.
\subsection{Reference Counting in Python} \subsection{Reference Counting in Python}
@ -1008,14 +1012,14 @@ take over ownership of the item passed to them --- even if they fail!
(Note that \code{PyDict_SetItem()} and friends don't take over (Note that \code{PyDict_SetItem()} and friends don't take over
ownership --- they are ``normal''.) ownership --- they are ``normal''.)
When a C function is called from Python, it borrows references to its When a \C{} function is called from Python, it borrows references to its
arguments from the caller. The caller owns a reference to the object, arguments from the caller. The caller owns a reference to the object,
so the borrowed reference's lifetime is guaranteed until the function so the borrowed reference's lifetime is guaranteed until the function
returns. Only when such a borrowed reference must be stored or passed returns. Only when such a borrowed reference must be stored or passed
on, it must be turned into an owned reference by calling on, it must be turned into an owned reference by calling
\code{Py_INCREF()}. \code{Py_INCREF()}.
The object reference returned from a C function that is called from The object reference returned from a \C{} function that is called from
Python must be an owned reference --- ownership is tranferred from the Python must be an owned reference --- ownership is tranferred from the
function to its caller. function to its caller.
@ -1074,7 +1078,7 @@ no_bug(PyObject *list) {
\end{verbatim}\ecode \end{verbatim}\ecode
% %
This is a true story. An older version of Python contained variants 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 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... debugger to figure out why his \code{__del__()} methods would fail...
The second case of problems with a borrowed reference is a variant The second case of problems with a borrowed reference is a variant
@ -1101,36 +1105,36 @@ bug(PyObject *list) {
\subsection{NULL Pointers} \subsection{NULL Pointers}
In general, functions that take object references as arguments don't In general, functions that take object references as arguments don't
expect you to pass them \code{NULL} pointers, and will dump core (or expect you to pass them \NULL{} pointers, and will dump core (or
cause later core dumps) if you do so. Functions that return object cause later core dumps) if you do so. Functions that return object
references generally return \code{NULL} only to indicate that an references generally return \NULL{} only to indicate that an
exception occurred. The reason for not testing for \code{NULL} exception occurred. The reason for not testing for \NULL{}
arguments is that functions often pass the objects they receive on to arguments is that functions often pass the objects they receive on to
other function --- if each function were to test for \code{NULL}, other function --- if each function were to test for \NULL{},
there would be a lot of redundant tests and the code would run slower. there would be a lot of redundant tests and the code would run slower.
It is better to test for \code{NULL} only at the ``source'', i.e.\ It is better to test for \NULL{} only at the ``source'', i.e.\
when a pointer that may be \code{NULL} is received, e.g.\ from when a pointer that may be \NULL{} is received, e.g.\ from
\code{malloc()} or from a function that may raise an exception. \code{malloc()} or from a function that may raise an exception.
The macros \code{Py_INCREF()} and \code{Py_DECREF()} The macros \code{Py_INCREF()} and \code{Py_DECREF()}
don't check for \code{NULL} pointers --- however, their variants don't check for \NULL{} pointers --- however, their variants
\code{Py_XINCREF()} and \code{Py_XDECREF()} do. \code{Py_XINCREF()} and \code{Py_XDECREF()} do.
The macros for checking for a particular object type The macros for checking for a particular object type
(\code{Py\var{type}_Check()}) don't check for \code{NULL} pointers --- (\code{Py\var{type}_Check()}) don't check for \NULL{} pointers ---
again, there is much code that calls several of these in a row to test again, there is much code that calls several of these in a row to test
an object against various different expected types, and this would an object against various different expected types, and this would
generate redundant tests. There are no variants with \code{NULL} generate redundant tests. There are no variants with \NULL{}
checking. checking.
The C function calling mechanism guarantees that the argument list The \C{} function calling mechanism guarantees that the argument list
passed to C functions (\code{args} in the examples) is never passed to \C{} functions (\code{args} in the examples) is never
\code{NULL} --- in fact it guarantees that it is always a tuple.% \NULL{} --- in fact it guarantees that it is always a tuple.%
\footnote{These guarantees don't hold when you use the ``old'' style \footnote{These guarantees don't hold when you use the ``old'' style
calling convention --- this is still found in much existing code.} calling convention --- this is still found in much existing code.}
It is a severe error to ever let a \code{NULL} pointer ``escape'' to It is a severe error to ever let a \NULL{} pointer ``escape'' to
the Python user. the Python user.
@ -1138,7 +1142,7 @@ the Python user.
It is possible to write extension modules in \Cpp{}. Some restrictions It is possible to write extension modules in \Cpp{}. Some restrictions
apply. If the main program (the Python interpreter) is compiled and apply. If the main program (the Python interpreter) is compiled and
linked by the C compiler, global or static objects with constructors linked by the \C{} compiler, global or static objects with constructors
cannot be used. This is not a problem if the main program is linked cannot be used. This is not a problem if the main program is linked
by the \Cpp{} compiler. All functions that will be called directly or by the \Cpp{} compiler. All functions that will be called directly or
indirectly (i.e. via function pointers) by the Python interpreter will indirectly (i.e. via function pointers) by the Python interpreter will
@ -1146,7 +1150,7 @@ have to be declared using \code{extern "C"}; this applies to all
``methods'' as well as to the module's initialization function. ``methods'' as well as to the module's initialization function.
It is unnecessary to enclose the Python header files in It is unnecessary to enclose the Python header files in
\code{extern "C" \{...\}} --- they use this form already if the symbol \code{extern "C" \{...\}} --- they use this form already if the symbol
\samp{__cplusplus} is defined (all recent C++ compilers define this \samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
symbol). symbol).
\chapter{Embedding Python in another application} \chapter{Embedding Python in another application}
@ -1188,7 +1192,7 @@ itself using \Cpp{}.
\chapter{Dynamic Loading} \chapter{Dynamic Loading}
On most modern systems it is possible to configure Python to support On most modern systems it is possible to configure Python to support
dynamic loading of extension modules implemented in C. When shared dynamic loading of extension modules implemented in \C{}. When shared
libraries are used dynamic loading is configured automatically; libraries are used dynamic loading is configured automatically;
otherwise you have to select it as a build option (see below). Once otherwise you have to select it as a build option (see below). Once
configured, dynamic loading is trivial to use: when a Python program configured, dynamic loading is trivial to use: when a Python program
@ -1200,7 +1204,7 @@ module acts just like a built-in extension module.
The advantages of dynamic loading are twofold: the ``core'' Python The advantages of dynamic loading are twofold: the ``core'' Python
binary gets smaller, and users can extend Python with their own binary gets smaller, and users can extend Python with their own
modules implemented in C without having to build and maintain their modules implemented in \C{} without having to build and maintain their
own copy of the Python interpreter. There are also disadvantages: own copy of the Python interpreter. There are also disadvantages:
dynamic loading isn't available on all systems (this just means that dynamic loading isn't available on all systems (this just means that
on some systems you have to use static loading), and dynamically on some systems you have to use static loading), and dynamically
@ -1289,7 +1293,7 @@ described earlier).
Note that in all cases you will have to create your own Makefile that Note that in all cases you will have to create your own Makefile that
compiles your module file(s). This Makefile will have to pass two compiles your module file(s). This Makefile will have to pass two
\samp{-I} arguments to the C compiler which will make it find the \samp{-I} arguments to the \C{} compiler which will make it find the
Python header files. If the Make variable \var{PYTHONTOP} points to Python header files. If the Make variable \var{PYTHONTOP} points to
the toplevel Python directory, your \var{CFLAGS} Make variable should the toplevel Python directory, your \var{CFLAGS} Make variable should
contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}. contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
@ -1333,7 +1337,7 @@ along the Python module search path.
\subsection{SGI IRIX 4 Dynamic Loading} \subsection{SGI IRIX 4 Dynamic Loading}
{\bf IMPORTANT:} You must compile your extension module with the {\bf IMPORTANT:} You must compile your extension module with the
additional C flag \samp{-G0} (or \samp{-G 0}). This instruct the additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instruct the
assembler to generate position-independent code. assembler to generate position-independent code.
You don't need to link the resulting \file{spammodule.o} file; just You don't need to link the resulting \file{spammodule.o} file; just