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:
parent
1f8449af4e
commit
0fd8268189
264
Doc/ext.tex
264
Doc/ext.tex
|
@ -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;
|
||||||
|
@ -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
|
||||||
|
|
264
Doc/ext/ext.tex
264
Doc/ext/ext.tex
|
@ -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;
|
||||||
|
@ -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
|
||||||
|
|
Loading…
Reference in New Issue