Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5e8aa54

Browse files
freddrakefreddrake
committed
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 <[email protected]>.
1 parent c46973c commit 5e8aa54

1 file changed

Lines changed: 80 additions & 61 deletions

File tree

‎Doc/ext/ext.tex‎

Lines changed: 80 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ \chapter{Extending Python with \C{} or \Cpp{} code}
7272
well as on your system setup; details are given in a later section.
7373

7474

75-
\section{A Simple Example}
76-
\label{simpleExample}
75+
\section{A Simple Example
76+
\label{simpleExample}}
7777

7878
Let's create an extension module called \samp{spam} (the favorite food
7979
of Monty Python fans...) and let's say we want to create a Python
@@ -161,8 +161,8 @@ \section{A Simple Example}
161161
\NULL{} immediately (as we saw in the example).
162162

163163

164-
\section{Intermezzo: Errors and Exceptions}
165-
\label{errors}
164+
\section{Intermezzo: Errors and Exceptions
165+
\label{errors}}
166166

167167
An important convention throughout the Python interpreter is the
168168
following: when a function fails, it should set an exception condition
@@ -288,8 +288,8 @@ \section{Intermezzo: Errors and Exceptions}
288288
Exceptions.''
289289

290290

291-
\section{Back to the Example}
292-
\label{backToExample}
291+
\section{Back to the Example
292+
\label{backToExample}}
293293

294294
Going back to our example function, you should now be able to
295295
understand this statement:
@@ -344,8 +344,8 @@ \section{Back to the Example}
344344
pointer, which means ``error'' in most contexts, as we have seen.
345345

346346

347-
\section{The Module's Method Table and Initialization Function}
348-
\label{methodTable}
347+
\section{The Module's Method Table and Initialization Function
348+
\label{methodTable}}
349349

350350
I promised to show how \cfunction{spam_system()} is called from Python
351351
programs. First, we need to list its name and address in a ``method
@@ -402,8 +402,8 @@ \section{The Module's Method Table and Initialization Function}
402402
doesn't need to check for errors.
403403

404404

405-
\section{Compilation and Linkage}
406-
\label{compilation}
405+
\section{Compilation and Linkage
406+
\label{compilation}}
407407

408408
There are two more things to do before you can use your new extension:
409409
compiling and linking it with the Python system. If you use dynamic
@@ -435,8 +435,8 @@ \section{Compilation and Linkage}
435435
spam spammodule.o -lX11
436436
\end{verbatim}
437437

438-
\section{Calling Python Functions From \C{}}
439-
\label{callingPython}
438+
\section{Calling Python Functions from \C{}
439+
\label{callingPython}}
440440

441441
So far we have concentrated on making \C{} functions callable from
442442
Python. The reverse is also useful: calling Python functions from \C{}.
@@ -450,7 +450,8 @@ \section{Calling Python Functions From \C{}}
450450
there is a standard interface to call a Python function. (I won't
451451
dwell on how to call the Python parser with a particular string as
452452
input --- if you're interested, have a look at the implementation of
453-
the \samp{-c} command line option in \file{Python/pythonmain.c}.)
453+
the \samp{-c} command line option in \file{Python/pythonmain.c} from
454+
the Python source code.)
454455

455456
Calling a Python function is easy. First, the Python program must
456457
somehow pass you the Python function object. You should provide a
@@ -467,19 +468,37 @@ \section{Calling Python Functions From \C{}}
467468
my_set_callback(dummy, arg)
468469
PyObject *dummy, *arg;
469470
{
470-
Py_XDECREF(my_callback); /* Dispose of previous callback */
471-
Py_XINCREF(arg); /* Add a reference to new callback */
472-
my_callback = arg; /* Remember new callback */
473-
/* Boilerplate to return "None" */
474-
Py_INCREF(Py_None);
475-
return Py_None;
471+
PyObject *result = NULL;
472+
PyObject *temp;
473+
474+
if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
475+
if (!PyCallable_Check(temp)) {
476+
PyErr_SetString(PyExc_TypeError, "parameter must be callable");
477+
return NULL;
478+
}
479+
Py_XINCREF(temp); /* Add a reference to new callback */
480+
Py_XDECREF(my_callback); /* Dispose of previous callback */
481+
my_callback = temp; /* Remember new callback */
482+
/* Boilerplate to return "None" */
483+
Py_INCREF(Py_None);
484+
result = Py_None;
485+
}
486+
return result;
476487
}
477488
\end{verbatim}
478489

490+
This function must be registered with the interpreter using the
491+
\constant{METH_VARARGS} flag; this is described in Section
492+
\ref{methodTable}, ``The Module's Method Table and Initialization
493+
Function.'' The \cfunction{PyArg_ParseTuple()} function and its
494+
arguments are documented in Section \ref{parseTuple}, ``Format Strings
495+
for \cfunction{PyArg_ParseTuple()}.''
496+
479497
The macros \cfunction{Py_XINCREF()} and \cfunction{Py_XDECREF()}
480498
increment/decrement the reference count of an object and are safe in
481-
the presence of \NULL{} pointers. More info on them in the section on
482-
Reference Counts below.
499+
the presence of \NULL{} pointers (but note that \var{temp} will not be
500+
\NULL{} in this context). More info on them in Section
501+
\ref{refcounts}, ``Reference Counts.''
483502

484503
Later, when it is time to call the function, you call the \C{} function
485504
\cfunction{PyEval_CallObject()}. This function has two arguments, both
@@ -561,8 +580,8 @@ \section{Calling Python Functions From \C{}}
561580
memory, and this should be checked.
562581

563582

564-
\section{Format Strings for \cfunction{PyArg_ParseTuple()}}
565-
\label{parseTuple}
583+
\section{Format Strings for \cfunction{PyArg_ParseTuple()}
584+
\label{parseTuple}}
566585

567586
The \cfunction{PyArg_ParseTuple()} function is declared as follows:
568587

@@ -767,8 +786,8 @@ \section{Format Strings for \cfunction{PyArg_ParseTuple()}}
767786
\end{verbatim}
768787

769788

770-
\section{Keyword Parsing with \cfunction{PyArg_ParseTupleAndKeywords()}}
771-
\label{parseTupleAndKeywords}
789+
\section{Keyword Parsing with \cfunction{PyArg_ParseTupleAndKeywords()}
790+
\label{parseTupleAndKeywords}}
772791

773792
The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as
774793
follows:
@@ -837,8 +856,8 @@ \section{Keyword Parsing with \cfunction{PyArg_ParseTupleAndKeywords()}}
837856
\end{verbatim}
838857

839858

840-
\section{The \cfunction{Py_BuildValue()} Function}
841-
\label{buildValue}
859+
\section{The \cfunction{Py_BuildValue()} Function
860+
\label{buildValue}}
842861

843862
This function is the counterpart to \cfunction{PyArg_ParseTuple()}. It is
844863
declared as follows:
@@ -967,8 +986,8 @@ \section{The \cfunction{Py_BuildValue()} Function}
967986
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
968987
\end{verbatim}
969988

970-
\section{Reference Counts}
971-
\label{refcounts}
989+
\section{Reference Counts
990+
\label{refcounts}}
972991

973992
%\subsection{Introduction}
974993

@@ -1032,8 +1051,8 @@ \section{Reference Counts}
10321051
will be available for \C{}. Until then, we'll have to live with
10331052
reference counts.
10341053

1035-
\subsection{Reference Counting in Python}
1036-
\label{refcountsInPython}
1054+
\subsection{Reference Counting in Python
1055+
\label{refcountsInPython}}
10371056

10381057
There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
10391058
which handle the incrementing and decrementing of the reference count.
@@ -1080,8 +1099,8 @@ \subsection{Reference Counting in Python}
10801099
and gives full owner responsibilities (i.e., the new owner must
10811100
dispose of the reference properly, as well as the previous owner).
10821101

1083-
\subsection{Ownership Rules}
1084-
\label{ownershipRules}
1102+
\subsection{Ownership Rules
1103+
\label{ownershipRules}}
10851104

10861105
Whenever an object reference is passed into or out of a function, it
10871106
is part of the function's interface specification whether ownership is
@@ -1130,8 +1149,8 @@ \subsection{Ownership Rules}
11301149
Python must be an owned reference --- ownership is tranferred from the
11311150
function to its caller.
11321151

1133-
\subsection{Thin Ice}
1134-
\label{thinIce}
1152+
\subsection{Thin Ice
1153+
\label{thinIce}}
11351154

11361155
There are a few situations where seemingly harmless use of a borrowed
11371156
reference can lead to problems. These all have to do with implicit
@@ -1212,8 +1231,8 @@ \subsection{Thin Ice}
12121231
}
12131232
\end{verbatim}
12141233

1215-
\subsection{NULL Pointers}
1216-
\label{nullPointers}
1234+
\subsection{NULL Pointers
1235+
\label{nullPointers}}
12171236

12181237
In general, functions that take object references as arguments do not
12191238
expect you to pass them \NULL{} pointers, and will dump core (or
@@ -1249,8 +1268,8 @@ \subsection{NULL Pointers}
12491268
the Python user.
12501269

12511270

1252-
\section{Writing Extensions in \Cpp{}}
1253-
\label{cplusplus}
1271+
\section{Writing Extensions in \Cpp{}
1272+
\label{cplusplus}}
12541273

12551274
It is possible to write extension modules in \Cpp{}. Some restrictions
12561275
apply. If the main program (the Python interpreter) is compiled and
@@ -1264,8 +1283,8 @@ \section{Writing Extensions in \Cpp{}}
12641283
\samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
12651284
symbol).
12661285

1267-
\chapter{Embedding Python in another application}
1268-
\label{embedding}
1286+
\chapter{Embedding Python in Another Application
1287+
\label{embedding}}
12691288

12701289
Embedding Python is similar to extending it, but not quite. The
12711290
difference is that when you extend Python, the main program of the
@@ -1293,8 +1312,8 @@ \chapter{Embedding Python in another application}
12931312
\file{Demo/embed}.
12941313

12951314

1296-
\section{Embedding Python in \Cpp{}}
1297-
\label{embeddingInCplusplus}
1315+
\section{Embedding Python in \Cpp{}
1316+
\label{embeddingInCplusplus}}
12981317

12991318
It is also possible to embed Python in a \Cpp{} program; precisely how this
13001319
is done will depend on the details of the \Cpp{} system used; in general you
@@ -1303,8 +1322,8 @@ \section{Embedding Python in \Cpp{}}
13031322
itself using \Cpp{}.
13041323

13051324

1306-
\chapter{Dynamic Loading}
1307-
\label{dynload}
1325+
\chapter{Dynamic Loading
1326+
\label{dynload}}
13081327

13091328
On most modern systems it is possible to configure Python to support
13101329
dynamic loading of extension modules implemented in \C{}. When shared
@@ -1329,15 +1348,15 @@ \chapter{Dynamic Loading}
13291348
(e.g. with a different representation of objects) may dump core.
13301349

13311350

1332-
\section{Configuring and Building the Interpreter for Dynamic Loading}
1333-
\label{dynloadConfig}
1351+
\section{Configuring and Building the Interpreter for Dynamic Loading
1352+
\label{dynloadConfig}}
13341353

13351354
There are three styles of dynamic loading: one using shared libraries,
13361355
one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
13371356
loading.
13381357

1339-
\subsection{Shared Libraries}
1340-
\label{sharedlibs}
1358+
\subsection{Shared Libraries
1359+
\label{sharedlibs}}
13411360

13421361
The following systems support dynamic loading using shared libraries:
13431362
SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!), Linux, FreeBSD,
@@ -1350,8 +1369,8 @@ \subsection{Shared Libraries}
13501369
\code{<dlfcn.h>} header file and automatically configures dynamic
13511370
loading.
13521371

1353-
\subsection{SGI IRIX 4 Dynamic Loading}
1354-
\label{irixDynload}
1372+
\subsection{SGI IRIX 4 Dynamic Loading
1373+
\label{irixDynload}}
13551374

13561375
Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic
13571376
loading. (SGI IRIX 5 might also support it but it is inferior to
@@ -1372,8 +1391,8 @@ \subsection{SGI IRIX 4 Dynamic Loading}
13721391
Now build and install Python as you normally would (see the
13731392
\file{README} file in the toplevel Python directory.)
13741393

1375-
\subsection{GNU Dynamic Loading}
1376-
\label{gnuDynload}
1394+
\subsection{GNU Dynamic Loading
1395+
\label{gnuDynload}}
13771396

13781397
GNU dynamic loading supports (according to its \file{README} file) the
13791398
following hardware and software combinations: VAX (Ultrix), Sun 3
@@ -1403,8 +1422,8 @@ \subsection{GNU Dynamic Loading}
14031422
will support GNU dynamic loading.
14041423

14051424

1406-
\section{Building a Dynamically Loadable Module}
1407-
\label{makedynload}
1425+
\section{Building a Dynamically Loadable Module
1426+
\label{makedynload}}
14081427

14091428
Since there are three styles of dynamic loading, there are also three
14101429
groups of instructions for building a dynamically loadable module.
@@ -1424,8 +1443,8 @@ \section{Building a Dynamically Loadable Module}
14241443
\file{config.h} header lives in the toplevel directory.)
14251444

14261445

1427-
\subsection{Shared Libraries}
1428-
\label{linking}
1446+
\subsection{Shared Libraries
1447+
\label{linking}}
14291448

14301449
You must link the \file{.o} file to produce a shared library. This is
14311450
done using a special invocation of the \UNIX{} loader/linker,
@@ -1459,8 +1478,8 @@ \subsection{Shared Libraries}
14591478
along the Python module search path.
14601479

14611480

1462-
\subsection{SGI IRIX 4 Dynamic Loading}
1463-
\label{irixLinking}
1481+
\subsection{SGI IRIX 4 Dynamic Loading
1482+
\label{irixLinking}}
14641483

14651484
\strong{IMPORTANT:} You must compile your extension module with the
14661485
additional \C{} flag \samp{-G0} (or \samp{-G 0}). This instructs the
@@ -1489,8 +1508,8 @@ \subsection{SGI IRIX 4 Dynamic Loading}
14891508
(\samp{.a} files) should be used.
14901509

14911510

1492-
\subsection{GNU Dynamic Loading}
1493-
\label{gnuLinking}
1511+
\subsection{GNU Dynamic Loading
1512+
\label{gnuLinking}}
14941513

14951514
Just copy \file{spammodule.o} into a directory along the Python module
14961515
search path.%

0 commit comments

Comments
 (0)