Update the example in "Calling Python Functions from C" to use
METH_VARARGS conventions and PyArg_ParseTuple(), and document the flag
and where to look for PyArg_ParseTuple() info.
Response to comment from Don Bashford <bashford@scripps.edu>.
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index a281a6d..23bbbd4 100644
--- a/Doc/ext/ext.tex
+++ b/Doc/ext/ext.tex
@@ -72,8 +72,8 @@
well as on your system setup; details are given in a later section.
-\section{A Simple Example}
-\label{simpleExample}
+\section{A Simple Example
+ \label{simpleExample}}
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
@@ -161,8 +161,8 @@
\NULL{} immediately (as we saw in the example).
-\section{Intermezzo: Errors and Exceptions}
-\label{errors}
+\section{Intermezzo: Errors and Exceptions
+ \label{errors}}
An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition
@@ -288,8 +288,8 @@
Exceptions.''
-\section{Back to the Example}
-\label{backToExample}
+\section{Back to the Example
+ \label{backToExample}}
Going back to our example function, you should now be able to
understand this statement:
@@ -344,8 +344,8 @@
pointer, which means ``error'' in most contexts, as we have seen.
-\section{The Module's Method Table and Initialization Function}
-\label{methodTable}
+\section{The Module's Method Table and Initialization Function
+ \label{methodTable}}
I promised to show how \cfunction{spam_system()} is called from Python
programs. First, we need to list its name and address in a ``method
@@ -402,8 +402,8 @@
doesn't need to check for errors.
-\section{Compilation and Linkage}
-\label{compilation}
+\section{Compilation and Linkage
+ \label{compilation}}
There are two more things to do before you can use your new extension:
compiling and linking it with the Python system. If you use dynamic
@@ -435,8 +435,8 @@
spam spammodule.o -lX11
\end{verbatim}
-\section{Calling Python Functions From \C{}}
-\label{callingPython}
+\section{Calling Python Functions from \C{}
+ \label{callingPython}}
So far we have concentrated on making \C{} functions callable from
Python. The reverse is also useful: calling Python functions from \C{}.
@@ -450,7 +450,8 @@
there is a standard interface to call a Python function. (I won't
dwell on how to call the Python parser with a particular string as
input --- if you're interested, have a look at the implementation of
-the \samp{-c} command line option in \file{Python/pythonmain.c}.)
+the \samp{-c} command line option in \file{Python/pythonmain.c} from
+the Python source code.)
Calling a Python function is easy. First, the Python program must
somehow pass you the Python function object. You should provide a
@@ -467,19 +468,37 @@
my_set_callback(dummy, arg)
PyObject *dummy, *arg;
{
- Py_XDECREF(my_callback); /* Dispose of previous callback */
- Py_XINCREF(arg); /* Add a reference to new callback */
- my_callback = arg; /* Remember new callback */
- /* Boilerplate to return "None" */
- Py_INCREF(Py_None);
- return Py_None;
+ PyObject *result = NULL;
+ PyObject *temp;
+
+ if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
+ if (!PyCallable_Check(temp)) {
+ PyErr_SetString(PyExc_TypeError, "parameter must be callable");
+ return NULL;
+ }
+ Py_XINCREF(temp); /* Add a reference to new callback */
+ Py_XDECREF(my_callback); /* Dispose of previous callback */
+ my_callback = temp; /* Remember new callback */
+ /* Boilerplate to return "None" */
+ Py_INCREF(Py_None);
+ result = Py_None;
+ }
+ return result;
}
\end{verbatim}
+This function must be registered with the interpreter using the
+\constant{METH_VARARGS} flag; this is described in Section
+\ref{methodTable}, ``The Module's Method Table and Initialization
+Function.'' The \cfunction{PyArg_ParseTuple()} function and its
+arguments are documented in Section \ref{parseTuple}, ``Format Strings
+for \cfunction{PyArg_ParseTuple()}.''
+
The macros \cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()}
increment/decrement the reference count of an object and are safe in
-the presence of \NULL{} pointers. More info on them in the section on
-Reference Counts below.
+the presence of \NULL{} pointers (but note that \var{temp} will not be
+\NULL{} in this context). More info on them in Section
+\ref{refcounts}, ``Reference Counts.''
Later, when it is time to call the function, you call the \C{} function
\cfunction{PyEval_CallObject()}. This function has two arguments, both
@@ -561,8 +580,8 @@
memory, and this should be checked.
-\section{Format Strings for \cfunction{PyArg_ParseTuple()}}
-\label{parseTuple}
+\section{Format Strings for \cfunction{PyArg_ParseTuple()}
+ \label{parseTuple}}
The \cfunction{PyArg_ParseTuple()} function is declared as follows:
@@ -767,8 +786,8 @@
\end{verbatim}
-\section{Keyword Parsing with \cfunction{PyArg_ParseTupleAndKeywords()}}
-\label{parseTupleAndKeywords}
+\section{Keyword Parsing with \cfunction{PyArg_ParseTupleAndKeywords()}
+ \label{parseTupleAndKeywords}}
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
follows:
@@ -837,8 +856,8 @@
\end{verbatim}
-\section{The \cfunction{Py_BuildValue()} Function}
-\label{buildValue}
+\section{The \cfunction{Py_BuildValue()} Function
+ \label{buildValue}}
This function is the counterpart to \cfunction{PyArg_ParseTuple()}. It is
declared as follows:
@@ -967,8 +986,8 @@
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
\end{verbatim}
-\section{Reference Counts}
-\label{refcounts}
+\section{Reference Counts
+ \label{refcounts}}
%\subsection{Introduction}
@@ -1032,8 +1051,8 @@
will be available for \C{}. Until then, we'll have to live with
reference counts.
-\subsection{Reference Counting in Python}
-\label{refcountsInPython}
+\subsection{Reference Counting in Python
+ \label{refcountsInPython}}
There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
which handle the incrementing and decrementing of the reference count.
@@ -1080,8 +1099,8 @@
and gives full owner responsibilities (i.e., the new owner must
dispose of the reference properly, as well as the previous owner).
-\subsection{Ownership Rules}
-\label{ownershipRules}
+\subsection{Ownership Rules
+ \label{ownershipRules}}
Whenever an object reference is passed into or out of a function, it
is part of the function's interface specification whether ownership is
@@ -1130,8 +1149,8 @@
Python must be an owned reference --- ownership is tranferred from the
function to its caller.
-\subsection{Thin Ice}
-\label{thinIce}
+\subsection{Thin Ice
+ \label{thinIce}}
There are a few situations where seemingly harmless use of a borrowed
reference can lead to problems. These all have to do with implicit
@@ -1212,8 +1231,8 @@
}
\end{verbatim}
-\subsection{NULL Pointers}
-\label{nullPointers}
+\subsection{NULL Pointers
+ \label{nullPointers}}
In general, functions that take object references as arguments do not
expect you to pass them \NULL{} pointers, and will dump core (or
@@ -1249,8 +1268,8 @@
the Python user.
-\section{Writing Extensions in \Cpp{}}
-\label{cplusplus}
+\section{Writing Extensions in \Cpp{}
+ \label{cplusplus}}
It is possible to write extension modules in \Cpp{}. Some restrictions
apply. If the main program (the Python interpreter) is compiled and
@@ -1264,8 +1283,8 @@
\samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
symbol).
-\chapter{Embedding Python in another application}
-\label{embedding}
+\chapter{Embedding Python in Another Application
+ \label{embedding}}
Embedding Python is similar to extending it, but not quite. The
difference is that when you extend Python, the main program of the
@@ -1293,8 +1312,8 @@
\file{Demo/embed}.
-\section{Embedding Python in \Cpp{}}
-\label{embeddingInCplusplus}
+\section{Embedding Python in \Cpp{}
+ \label{embeddingInCplusplus}}
It is also possible to embed Python in a \Cpp{} program; precisely how this
is done will depend on the details of the \Cpp{} system used; in general you
@@ -1303,8 +1322,8 @@
itself using \Cpp{}.
-\chapter{Dynamic Loading}
-\label{dynload}
+\chapter{Dynamic Loading
+ \label{dynload}}
On most modern systems it is possible to configure Python to support
dynamic loading of extension modules implemented in \C{}. When shared
@@ -1329,15 +1348,15 @@
(e.g. with a different representation of objects) may dump core.
-\section{Configuring and Building the Interpreter for Dynamic Loading}
-\label{dynloadConfig}
+\section{Configuring and Building the Interpreter for Dynamic Loading
+ \label{dynloadConfig}}
There are three styles of dynamic loading: one using shared libraries,
one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
loading.
-\subsection{Shared Libraries}
-\label{sharedlibs}
+\subsection{Shared Libraries
+ \label{sharedlibs}}
The following systems support dynamic loading using shared libraries:
SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!), Linux, FreeBSD,
@@ -1350,8 +1369,8 @@
\code{<dlfcn.h>} header file and automatically configures dynamic
loading.
-\subsection{SGI IRIX 4 Dynamic Loading}
-\label{irixDynload}
+\subsection{SGI IRIX 4 Dynamic Loading
+ \label{irixDynload}}
Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic
loading. (SGI IRIX 5 might also support it but it is inferior to
@@ -1372,8 +1391,8 @@
Now build and install Python as you normally would (see the
\file{README} file in the toplevel Python directory.)
-\subsection{GNU Dynamic Loading}
-\label{gnuDynload}
+\subsection{GNU Dynamic Loading
+ \label{gnuDynload}}
GNU dynamic loading supports (according to its \file{README} file) the
following hardware and software combinations: VAX (Ultrix), Sun 3
@@ -1403,8 +1422,8 @@
will support GNU dynamic loading.
-\section{Building a Dynamically Loadable Module}
-\label{makedynload}
+\section{Building a Dynamically Loadable Module
+ \label{makedynload}}
Since there are three styles of dynamic loading, there are also three
groups of instructions for building a dynamically loadable module.
@@ -1424,8 +1443,8 @@
\file{config.h} header lives in the toplevel directory.)
-\subsection{Shared Libraries}
-\label{linking}
+\subsection{Shared Libraries
+ \label{linking}}
You must link the \file{.o} file to produce a shared library. This is
done using a special invocation of the \UNIX{} loader/linker,
@@ -1459,8 +1478,8 @@
along the Python module search path.
-\subsection{SGI IRIX 4 Dynamic Loading}
-\label{irixLinking}
+\subsection{SGI IRIX 4 Dynamic Loading
+ \label{irixLinking}}
\strong{IMPORTANT:} You must compile your extension module with the
additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instructs the
@@ -1489,8 +1508,8 @@
(\samp{.a} files) should be used.
-\subsection{GNU Dynamic Loading}
-\label{gnuLinking}
+\subsection{GNU Dynamic Loading
+ \label{gnuLinking}}
Just copy \file{spammodule.o} into a directory along the Python module
search path.%