Issue #5262: Improved fix.
[python.git] / Doc / extending / extending.rst
blobd052ec24c65d8fa102b149a73e0b6a312f09d84e
1 .. highlightlang:: c
4 .. _extending-intro:
6 ******************************
7 Extending Python with C or C++
8 ******************************
10 It is quite easy to add new built-in modules to Python, if you know how to
11 program in C.  Such :dfn:`extension modules` can do two things that can't be
12 done directly in Python: they can implement new built-in object types, and they
13 can call C library functions and system calls.
15 To support extensions, the Python API (Application Programmers Interface)
16 defines a set of functions, macros and variables that provide access to most
17 aspects of the Python run-time system.  The Python API is incorporated in a C
18 source file by including the header ``"Python.h"``.
20 The compilation of an extension module depends on its intended use as well as on
21 your system setup; details are given in later chapters.
24 .. _extending-simpleexample:
26 A Simple Example
27 ================
29 Let's create an extension module called ``spam`` (the favorite food of Monty
30 Python fans...) and let's say we want to create a Python interface to the C
31 library function :cfunc:`system`. [#]_ This function takes a null-terminated
32 character string as argument and returns an integer.  We want this function to
33 be callable from Python as follows::
35    >>> import spam
36    >>> status = spam.system("ls -l")
38 Begin by creating a file :file:`spammodule.c`.  (Historically, if a module is
39 called ``spam``, the C file containing its implementation is called
40 :file:`spammodule.c`; if the module name is very long, like ``spammify``, the
41 module name can be just :file:`spammify.c`.)
43 The first line of our file can be::
45    #include <Python.h>
47 which pulls in the Python API (you can add a comment describing the purpose of
48 the module and a copyright notice if you like).
50 .. note::
52    Since Python may define some pre-processor definitions which affect the standard
53    headers on some systems, you *must* include :file:`Python.h` before any standard
54    headers are included.
56 All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
57 ``PY``, except those defined in standard header files. For convenience, and
58 since they are used extensively by the Python interpreter, ``"Python.h"``
59 includes a few standard header files: ``<stdio.h>``, ``<string.h>``,
60 ``<errno.h>``, and ``<stdlib.h>``.  If the latter header file does not exist on
61 your system, it declares the functions :cfunc:`malloc`, :cfunc:`free` and
62 :cfunc:`realloc` directly.
64 The next thing we add to our module file is the C function that will be called
65 when the Python expression ``spam.system(string)`` is evaluated (we'll see
66 shortly how it ends up being called)::
68    static PyObject *
69    spam_system(PyObject *self, PyObject *args)
70    {
71        const char *command;
72        int sts;
74        if (!PyArg_ParseTuple(args, "s", &command))
75            return NULL;
76        sts = system(command);
77        return Py_BuildValue("i", sts);
78    }
80 There is a straightforward translation from the argument list in Python (for
81 example, the single expression ``"ls -l"``) to the arguments passed to the C
82 function.  The C function always has two arguments, conventionally named *self*
83 and *args*.
85 The *self* argument is only used when the C function implements a built-in
86 method, not a function. In the example, *self* will always be a *NULL* pointer,
87 since we are defining a function, not a method.  (This is done so that the
88 interpreter doesn't have to understand two different types of C functions.)
90 The *args* argument will be a pointer to a Python tuple object containing the
91 arguments.  Each item of the tuple corresponds to an argument in the call's
92 argument list.  The arguments are Python objects --- in order to do anything
93 with them in our C function we have to convert them to C values.  The function
94 :cfunc:`PyArg_ParseTuple` in the Python API checks the argument types and
95 converts them to C values.  It uses a template string to determine the required
96 types of the arguments as well as the types of the C variables into which to
97 store the converted values.  More about this later.
99 :cfunc:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right
100 type and its components have been stored in the variables whose addresses are
101 passed.  It returns false (zero) if an invalid argument list was passed.  In the
102 latter case it also raises an appropriate exception so the calling function can
103 return *NULL* immediately (as we saw in the example).
106 .. _extending-errors:
108 Intermezzo: Errors and Exceptions
109 =================================
111 An important convention throughout the Python interpreter is the following: when
112 a function fails, it should set an exception condition and return an error value
113 (usually a *NULL* pointer).  Exceptions are stored in a static global variable
114 inside the interpreter; if this variable is *NULL* no exception has occurred.  A
115 second global variable stores the "associated value" of the exception (the
116 second argument to :keyword:`raise`).  A third variable contains the stack
117 traceback in case the error originated in Python code.  These three variables
118 are the C equivalents of the Python variables ``sys.exc_type``,
119 ``sys.exc_value`` and ``sys.exc_traceback`` (see the section on module
120 :mod:`sys` in the Python Library Reference).  It is important to know about them
121 to understand how errors are passed around.
123 The Python API defines a number of functions to set various types of exceptions.
125 The most common one is :cfunc:`PyErr_SetString`.  Its arguments are an exception
126 object and a C string.  The exception object is usually a predefined object like
127 :cdata:`PyExc_ZeroDivisionError`.  The C string indicates the cause of the error
128 and is converted to a Python string object and stored as the "associated value"
129 of the exception.
131 Another useful function is :cfunc:`PyErr_SetFromErrno`, which only takes an
132 exception argument and constructs the associated value by inspection of the
133 global variable :cdata:`errno`.  The most general function is
134 :cfunc:`PyErr_SetObject`, which takes two object arguments, the exception and
135 its associated value.  You don't need to :cfunc:`Py_INCREF` the objects passed
136 to any of these functions.
138 You can test non-destructively whether an exception has been set with
139 :cfunc:`PyErr_Occurred`.  This returns the current exception object, or *NULL*
140 if no exception has occurred.  You normally don't need to call
141 :cfunc:`PyErr_Occurred` to see whether an error occurred in a function call,
142 since you should be able to tell from the return value.
144 When a function *f* that calls another function *g* detects that the latter
145 fails, *f* should itself return an error value (usually *NULL* or ``-1``).  It
146 should *not* call one of the :cfunc:`PyErr_\*` functions --- one has already
147 been called by *g*. *f*'s caller is then supposed to also return an error
148 indication to *its* caller, again *without* calling :cfunc:`PyErr_\*`, and so on
149 --- the most detailed cause of the error was already reported by the function
150 that first detected it.  Once the error reaches the Python interpreter's main
151 loop, this aborts the currently executing Python code and tries to find an
152 exception handler specified by the Python programmer.
154 (There are situations where a module can actually give a more detailed error
155 message by calling another :cfunc:`PyErr_\*` function, and in such cases it is
156 fine to do so.  As a general rule, however, this is not necessary, and can cause
157 information about the cause of the error to be lost: most operations can fail
158 for a variety of reasons.)
160 To ignore an exception set by a function call that failed, the exception
161 condition must be cleared explicitly by calling :cfunc:`PyErr_Clear`.  The only
162 time C code should call :cfunc:`PyErr_Clear` is if it doesn't want to pass the
163 error on to the interpreter but wants to handle it completely by itself
164 (possibly by trying something else, or pretending nothing went wrong).
166 Every failing :cfunc:`malloc` call must be turned into an exception --- the
167 direct caller of :cfunc:`malloc` (or :cfunc:`realloc`) must call
168 :cfunc:`PyErr_NoMemory` and return a failure indicator itself.  All the
169 object-creating functions (for example, :cfunc:`PyInt_FromLong`) already do
170 this, so this note is only relevant to those who call :cfunc:`malloc` directly.
172 Also note that, with the important exception of :cfunc:`PyArg_ParseTuple` and
173 friends, functions that return an integer status usually return a positive value
174 or zero for success and ``-1`` for failure, like Unix system calls.
176 Finally, be careful to clean up garbage (by making :cfunc:`Py_XDECREF` or
177 :cfunc:`Py_DECREF` calls for objects you have already created) when you return
178 an error indicator!
180 The choice of which exception to raise is entirely yours.  There are predeclared
181 C objects corresponding to all built-in Python exceptions, such as
182 :cdata:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
183 should choose exceptions wisely --- don't use :cdata:`PyExc_TypeError` to mean
184 that a file couldn't be opened (that should probably be :cdata:`PyExc_IOError`).
185 If something's wrong with the argument list, the :cfunc:`PyArg_ParseTuple`
186 function usually raises :cdata:`PyExc_TypeError`.  If you have an argument whose
187 value must be in a particular range or must satisfy other conditions,
188 :cdata:`PyExc_ValueError` is appropriate.
190 You can also define a new exception that is unique to your module. For this, you
191 usually declare a static object variable at the beginning of your file::
193    static PyObject *SpamError;
195 and initialize it in your module's initialization function (:cfunc:`initspam`)
196 with an exception object (leaving out the error checking for now)::
198    PyMODINIT_FUNC
199    initspam(void)
200    {
201        PyObject *m;
203        m = Py_InitModule("spam", SpamMethods);
204        if (m == NULL)
205            return;
207        SpamError = PyErr_NewException("spam.error", NULL, NULL);
208        Py_INCREF(SpamError);
209        PyModule_AddObject(m, "error", SpamError);
210    }
212 Note that the Python name for the exception object is :exc:`spam.error`.  The
213 :cfunc:`PyErr_NewException` function may create a class with the base class
214 being :exc:`Exception` (unless another class is passed in instead of *NULL*),
215 described in :ref:`bltin-exceptions`.
217 Note also that the :cdata:`SpamError` variable retains a reference to the newly
218 created exception class; this is intentional!  Since the exception could be
219 removed from the module by external code, an owned reference to the class is
220 needed to ensure that it will not be discarded, causing :cdata:`SpamError` to
221 become a dangling pointer. Should it become a dangling pointer, C code which
222 raises the exception could cause a core dump or other unintended side effects.
224 We discuss the use of PyMODINIT_FUNC as a function return type later in this
225 sample.
228 .. _backtoexample:
230 Back to the Example
231 ===================
233 Going back to our example function, you should now be able to understand this
234 statement::
236    if (!PyArg_ParseTuple(args, "s", &command))
237        return NULL;
239 It returns *NULL* (the error indicator for functions returning object pointers)
240 if an error is detected in the argument list, relying on the exception set by
241 :cfunc:`PyArg_ParseTuple`.  Otherwise the string value of the argument has been
242 copied to the local variable :cdata:`command`.  This is a pointer assignment and
243 you are not supposed to modify the string to which it points (so in Standard C,
244 the variable :cdata:`command` should properly be declared as ``const char
245 *command``).
247 The next statement is a call to the Unix function :cfunc:`system`, passing it
248 the string we just got from :cfunc:`PyArg_ParseTuple`::
250    sts = system(command);
252 Our :func:`spam.system` function must return the value of :cdata:`sts` as a
253 Python object.  This is done using the function :cfunc:`Py_BuildValue`, which is
254 something like the inverse of :cfunc:`PyArg_ParseTuple`: it takes a format
255 string and an arbitrary number of C values, and returns a new Python object.
256 More info on :cfunc:`Py_BuildValue` is given later. ::
258    return Py_BuildValue("i", sts);
260 In this case, it will return an integer object.  (Yes, even integers are objects
261 on the heap in Python!)
263 If you have a C function that returns no useful argument (a function returning
264 :ctype:`void`), the corresponding Python function must return ``None``.   You
265 need this idiom to do so (which is implemented by the :cmacro:`Py_RETURN_NONE`
266 macro)::
268    Py_INCREF(Py_None);
269    return Py_None;
271 :cdata:`Py_None` is the C name for the special Python object ``None``.  It is a
272 genuine Python object rather than a *NULL* pointer, which means "error" in most
273 contexts, as we have seen.
276 .. _methodtable:
278 The Module's Method Table and Initialization Function
279 =====================================================
281 I promised to show how :cfunc:`spam_system` is called from Python programs.
282 First, we need to list its name and address in a "method table"::
284    static PyMethodDef SpamMethods[] = {
285        ...
286        {"system",  spam_system, METH_VARARGS,
287         "Execute a shell command."},
288        ...
289        {NULL, NULL, 0, NULL}        /* Sentinel */
290    };
292 Note the third entry (``METH_VARARGS``).  This is a flag telling the interpreter
293 the calling convention to be used for the C function.  It should normally always
294 be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a value of ``0`` means
295 that an obsolete variant of :cfunc:`PyArg_ParseTuple` is used.
297 When using only ``METH_VARARGS``, the function should expect the Python-level
298 parameters to be passed in as a tuple acceptable for parsing via
299 :cfunc:`PyArg_ParseTuple`; more information on this function is provided below.
301 The :const:`METH_KEYWORDS` bit may be set in the third field if keyword
302 arguments should be passed to the function.  In this case, the C function should
303 accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
304 Use :cfunc:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
305 function.
307 The method table must be passed to the interpreter in the module's
308 initialization function.  The initialization function must be named
309 :cfunc:`initname`, where *name* is the name of the module, and should be the
310 only non-\ ``static`` item defined in the module file::
312    PyMODINIT_FUNC
313    initspam(void)
314    {
315        (void) Py_InitModule("spam", SpamMethods);
316    }
318 Note that PyMODINIT_FUNC declares the function as ``void`` return type,
319 declares any special linkage declarations required by the platform, and for  C++
320 declares the function as ``extern "C"``.
322 When the Python program imports module :mod:`spam` for the first time,
323 :cfunc:`initspam` is called. (See below for comments about embedding Python.)
324 It calls :cfunc:`Py_InitModule`, which creates a "module object" (which is
325 inserted in the dictionary ``sys.modules`` under the key ``"spam"``), and
326 inserts built-in function objects into the newly created module based upon the
327 table (an array of :ctype:`PyMethodDef` structures) that was passed as its
328 second argument. :cfunc:`Py_InitModule` returns a pointer to the module object
329 that it creates (which is unused here).  It may abort with a fatal error for
330 certain errors, or return *NULL* if the module could not be initialized
331 satisfactorily.
333 When embedding Python, the :cfunc:`initspam` function is not called
334 automatically unless there's an entry in the :cdata:`_PyImport_Inittab` table.
335 The easiest way to handle this is to statically initialize your
336 statically-linked modules by directly calling :cfunc:`initspam` after the call
337 to :cfunc:`Py_Initialize`::
339    int
340    main(int argc, char *argv[])
341    {
342        /* Pass argv[0] to the Python interpreter */
343        Py_SetProgramName(argv[0]);
345        /* Initialize the Python interpreter.  Required. */
346        Py_Initialize();
348        /* Add a static module */
349        initspam();
351 An example may be found in the file :file:`Demo/embed/demo.c` in the Python
352 source distribution.
354 .. note::
356    Removing entries from ``sys.modules`` or importing compiled modules into
357    multiple interpreters within a process (or following a :cfunc:`fork` without an
358    intervening :cfunc:`exec`) can create problems for some extension modules.
359    Extension module authors should exercise caution when initializing internal data
360    structures. Note also that the :func:`reload` function can be used with
361    extension modules, and will call the module initialization function
362    (:cfunc:`initspam` in the example), but will not load the module again if it was
363    loaded from a dynamically loadable object file (:file:`.so` on Unix,
364    :file:`.dll` on Windows).
366 A more substantial example module is included in the Python source distribution
367 as :file:`Modules/xxmodule.c`.  This file may be used as a  template or simply
368 read as an example.  The :program:`modulator.py` script included in the source
369 distribution or Windows install provides  a simple graphical user interface for
370 declaring the functions and objects which a module should implement, and can
371 generate a template which can be filled in.  The script lives in the
372 :file:`Tools/modulator/` directory; see the :file:`README` file there for more
373 information.
376 .. _compilation:
378 Compilation and Linkage
379 =======================
381 There are two more things to do before you can use your new extension: compiling
382 and linking it with the Python system.  If you use dynamic loading, the details
383 may depend on the style of dynamic loading your system uses; see the chapters
384 about building extension modules (chapter :ref:`building`) and additional
385 information that pertains only to building on Windows (chapter
386 :ref:`building-on-windows`) for more information about this.
388 If you can't use dynamic loading, or if you want to make your module a permanent
389 part of the Python interpreter, you will have to change the configuration setup
390 and rebuild the interpreter.  Luckily, this is very simple on Unix: just place
391 your file (:file:`spammodule.c` for example) in the :file:`Modules/` directory
392 of an unpacked source distribution, add a line to the file
393 :file:`Modules/Setup.local` describing your file::
395    spam spammodule.o
397 and rebuild the interpreter by running :program:`make` in the toplevel
398 directory.  You can also run :program:`make` in the :file:`Modules/`
399 subdirectory, but then you must first rebuild :file:`Makefile` there by running
400 ':program:`make` Makefile'.  (This is necessary each time you change the
401 :file:`Setup` file.)
403 If your module requires additional libraries to link with, these can be listed
404 on the line in the configuration file as well, for instance::
406    spam spammodule.o -lX11
409 .. _callingpython:
411 Calling Python Functions from C
412 ===============================
414 So far we have concentrated on making C functions callable from Python.  The
415 reverse is also useful: calling Python functions from C. This is especially the
416 case for libraries that support so-called "callback" functions.  If a C
417 interface makes use of callbacks, the equivalent Python often needs to provide a
418 callback mechanism to the Python programmer; the implementation will require
419 calling the Python callback functions from a C callback.  Other uses are also
420 imaginable.
422 Fortunately, the Python interpreter is easily called recursively, and there is a
423 standard interface to call a Python function.  (I won't dwell on how to call the
424 Python parser with a particular string as input --- if you're interested, have a
425 look at the implementation of the :option:`-c` command line option in
426 :file:`Modules/main.c` from the Python source code.)
428 Calling a Python function is easy.  First, the Python program must somehow pass
429 you the Python function object.  You should provide a function (or some other
430 interface) to do this.  When this function is called, save a pointer to the
431 Python function object (be careful to :cfunc:`Py_INCREF` it!) in a global
432 variable --- or wherever you see fit. For example, the following function might
433 be part of a module definition::
435    static PyObject *my_callback = NULL;
437    static PyObject *
438    my_set_callback(PyObject *dummy, PyObject *args)
439    {
440        PyObject *result = NULL;
441        PyObject *temp;
443        if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
444            if (!PyCallable_Check(temp)) {
445                PyErr_SetString(PyExc_TypeError, "parameter must be callable");
446                return NULL;
447            }
448            Py_XINCREF(temp);         /* Add a reference to new callback */
449            Py_XDECREF(my_callback);  /* Dispose of previous callback */
450            my_callback = temp;       /* Remember new callback */
451            /* Boilerplate to return "None" */
452            Py_INCREF(Py_None);
453            result = Py_None;
454        }
455        return result;
456    }
458 This function must be registered with the interpreter using the
459 :const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`.  The
460 :cfunc:`PyArg_ParseTuple` function and its arguments are documented in section
461 :ref:`parsetuple`.
463 The macros :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF` increment/decrement the
464 reference count of an object and are safe in the presence of *NULL* pointers
465 (but note that *temp* will not be  *NULL* in this context).  More info on them
466 in section :ref:`refcounts`.
468 .. index:: single: PyObject_CallObject()
470 Later, when it is time to call the function, you call the C function
471 :cfunc:`PyObject_CallObject`.  This function has two arguments, both pointers to
472 arbitrary Python objects: the Python function, and the argument list.  The
473 argument list must always be a tuple object, whose length is the number of
474 arguments.  To call the Python function with no arguments, pass in NULL, or
475 an empty tuple; to call it with one argument, pass a singleton tuple.
476 :cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
477 or more format codes between parentheses.  For example::
479    int arg;
480    PyObject *arglist;
481    PyObject *result;
482    ...
483    arg = 123;
484    ...
485    /* Time to call the callback */
486    arglist = Py_BuildValue("(i)", arg);
487    result = PyObject_CallObject(my_callback, arglist);
488    Py_DECREF(arglist);
490 :cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return
491 value of the Python function.  :cfunc:`PyObject_CallObject` is
492 "reference-count-neutral" with respect to its arguments.  In the example a new
493 tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
494 -ed immediately after the call.
496 The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand
497 new object, or it is an existing object whose reference count has been
498 incremented.  So, unless you want to save it in a global variable, you should
499 somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not
500 interested in its value.
502 Before you do this, however, it is important to check that the return value
503 isn't *NULL*.  If it is, the Python function terminated by raising an exception.
504 If the C code that called :cfunc:`PyObject_CallObject` is called from Python, it
505 should now return an error indication to its Python caller, so the interpreter
506 can print a stack trace, or the calling Python code can handle the exception.
507 If this is not possible or desirable, the exception should be cleared by calling
508 :cfunc:`PyErr_Clear`.  For example::
510    if (result == NULL)
511        return NULL; /* Pass error back */
512    ...use result...
513    Py_DECREF(result);
515 Depending on the desired interface to the Python callback function, you may also
516 have to provide an argument list to :cfunc:`PyObject_CallObject`.  In some cases
517 the argument list is also provided by the Python program, through the same
518 interface that specified the callback function.  It can then be saved and used
519 in the same manner as the function object.  In other cases, you may have to
520 construct a new tuple to pass as the argument list.  The simplest way to do this
521 is to call :cfunc:`Py_BuildValue`.  For example, if you want to pass an integral
522 event code, you might use the following code::
524    PyObject *arglist;
525    ...
526    arglist = Py_BuildValue("(l)", eventcode);
527    result = PyObject_CallObject(my_callback, arglist);
528    Py_DECREF(arglist);
529    if (result == NULL)
530        return NULL; /* Pass error back */
531    /* Here maybe use the result */
532    Py_DECREF(result);
534 Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
535 the error check!  Also note that strictly speaking this code is not complete:
536 :cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
538 You may also call a function with keyword arguments by using
539 :cfunc:`PyObject_Call`, which supports arguments and keyword arguments.  As in
540 the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::
542    PyObject *dict;
543    ...
544    dict = Py_BuildValue("{s:i}", "name", val);
545    result = PyObject_Call(my_callback, NULL, dict);
546    Py_DECREF(dict);
547    if (result == NULL)
548        return NULL; /* Pass error back */
549    /* Here maybe use the result */
550    Py_DECREF(result);
553 .. _parsetuple:
555 Extracting Parameters in Extension Functions
556 ============================================
558 .. index:: single: PyArg_ParseTuple()
560 The :cfunc:`PyArg_ParseTuple` function is declared as follows::
562    int PyArg_ParseTuple(PyObject *arg, char *format, ...);
564 The *arg* argument must be a tuple object containing an argument list passed
565 from Python to a C function.  The *format* argument must be a format string,
566 whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference
567 Manual.  The remaining arguments must be addresses of variables whose type is
568 determined by the format string.
570 Note that while :cfunc:`PyArg_ParseTuple` checks that the Python arguments have
571 the required types, it cannot check the validity of the addresses of C variables
572 passed to the call: if you make mistakes there, your code will probably crash or
573 at least overwrite random bits in memory.  So be careful!
575 Note that any Python object references which are provided to the caller are
576 *borrowed* references; do not decrement their reference count!
578 Some example calls::
580    int ok;
581    int i, j;
582    long k, l;
583    const char *s;
584    int size;
586    ok = PyArg_ParseTuple(args, ""); /* No arguments */
587        /* Python call: f() */
591    ok = PyArg_ParseTuple(args, "s", &s); /* A string */
592        /* Possible Python call: f('whoops!') */
596    ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
597        /* Possible Python call: f(1, 2, 'three') */
601    ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
602        /* A pair of ints and a string, whose size is also returned */
603        /* Possible Python call: f((1, 2), 'three') */
607    {
608        const char *file;
609        const char *mode = "r";
610        int bufsize = 0;
611        ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
612        /* A string, and optionally another string and an integer */
613        /* Possible Python calls:
614           f('spam')
615           f('spam', 'w')
616           f('spam', 'wb', 100000) */
617    }
621    {
622        int left, top, right, bottom, h, v;
623        ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
624                 &left, &top, &right, &bottom, &h, &v);
625        /* A rectangle and a point */
626        /* Possible Python call:
627           f(((0, 0), (400, 300)), (10, 10)) */
628    }
632    {
633        Py_complex c;
634        ok = PyArg_ParseTuple(args, "D:myfunction", &c);
635        /* a complex, also providing a function name for errors */
636        /* Possible Python call: myfunction(1+2j) */
637    }
640 .. _parsetupleandkeywords:
642 Keyword Parameters for Extension Functions
643 ==========================================
645 .. index:: single: PyArg_ParseTupleAndKeywords()
647 The :cfunc:`PyArg_ParseTupleAndKeywords` function is declared as follows::
649    int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
650                                    char *format, char *kwlist[], ...);
652 The *arg* and *format* parameters are identical to those of the
653 :cfunc:`PyArg_ParseTuple` function.  The *kwdict* parameter is the dictionary of
654 keywords received as the third parameter from the Python runtime.  The *kwlist*
655 parameter is a *NULL*-terminated list of strings which identify the parameters;
656 the names are matched with the type information from *format* from left to
657 right.  On success, :cfunc:`PyArg_ParseTupleAndKeywords` returns true, otherwise
658 it returns false and raises an appropriate exception.
660 .. note::
662    Nested tuples cannot be parsed when using keyword arguments!  Keyword parameters
663    passed in which are not present in the *kwlist* will cause :exc:`TypeError` to
664    be raised.
666 .. index:: single: Philbrick, Geoff
668 Here is an example module which uses keywords, based on an example by Geoff
669 Philbrick (philbrick@hks.com)::
671    #include "Python.h"
673    static PyObject *
674    keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
675    {
676        int voltage;
677        char *state = "a stiff";
678        char *action = "voom";
679        char *type = "Norwegian Blue";
681        static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
683        if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
684                                         &voltage, &state, &action, &type))
685            return NULL;
687        printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
688               action, voltage);
689        printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
691        Py_INCREF(Py_None);
693        return Py_None;
694    }
696    static PyMethodDef keywdarg_methods[] = {
697        /* The cast of the function is necessary since PyCFunction values
698         * only take two PyObject* parameters, and keywdarg_parrot() takes
699         * three.
700         */
701        {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
702         "Print a lovely skit to standard output."},
703        {NULL, NULL, 0, NULL}   /* sentinel */
704    };
708    void
709    initkeywdarg(void)
710    {
711      /* Create the module and add the functions */
712      Py_InitModule("keywdarg", keywdarg_methods);
713    }
716 .. _buildvalue:
718 Building Arbitrary Values
719 =========================
721 This function is the counterpart to :cfunc:`PyArg_ParseTuple`.  It is declared
722 as follows::
724    PyObject *Py_BuildValue(char *format, ...);
726 It recognizes a set of format units similar to the ones recognized by
727 :cfunc:`PyArg_ParseTuple`, but the arguments (which are input to the function,
728 not output) must not be pointers, just values.  It returns a new Python object,
729 suitable for returning from a C function called from Python.
731 One difference with :cfunc:`PyArg_ParseTuple`: while the latter requires its
732 first argument to be a tuple (since Python argument lists are always represented
733 as tuples internally), :cfunc:`Py_BuildValue` does not always build a tuple.  It
734 builds a tuple only if its format string contains two or more format units. If
735 the format string is empty, it returns ``None``; if it contains exactly one
736 format unit, it returns whatever object is described by that format unit.  To
737 force it to return a tuple of size 0 or one, parenthesize the format string.
739 Examples (to the left the call, to the right the resulting Python value)::
741    Py_BuildValue("")                        None
742    Py_BuildValue("i", 123)                  123
743    Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
744    Py_BuildValue("s", "hello")              'hello'
745    Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
746    Py_BuildValue("s#", "hello", 4)          'hell'
747    Py_BuildValue("()")                      ()
748    Py_BuildValue("(i)", 123)                (123,)
749    Py_BuildValue("(ii)", 123, 456)          (123, 456)
750    Py_BuildValue("(i,i)", 123, 456)         (123, 456)
751    Py_BuildValue("[i,i]", 123, 456)         [123, 456]
752    Py_BuildValue("{s:i,s:i}",
753                  "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
754    Py_BuildValue("((ii)(ii)) (ii)",
755                  1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))
758 .. _refcounts:
760 Reference Counts
761 ================
763 In languages like C or C++, the programmer is responsible for dynamic allocation
764 and deallocation of memory on the heap.  In C, this is done using the functions
765 :cfunc:`malloc` and :cfunc:`free`.  In C++, the operators ``new`` and
766 ``delete`` are used with essentially the same meaning and we'll restrict
767 the following discussion to the C case.
769 Every block of memory allocated with :cfunc:`malloc` should eventually be
770 returned to the pool of available memory by exactly one call to :cfunc:`free`.
771 It is important to call :cfunc:`free` at the right time.  If a block's address
772 is forgotten but :cfunc:`free` is not called for it, the memory it occupies
773 cannot be reused until the program terminates.  This is called a :dfn:`memory
774 leak`.  On the other hand, if a program calls :cfunc:`free` for a block and then
775 continues to use the block, it creates a conflict with re-use of the block
776 through another :cfunc:`malloc` call.  This is called :dfn:`using freed memory`.
777 It has the same bad consequences as referencing uninitialized data --- core
778 dumps, wrong results, mysterious crashes.
780 Common causes of memory leaks are unusual paths through the code.  For instance,
781 a function may allocate a block of memory, do some calculation, and then free
782 the block again.  Now a change in the requirements for the function may add a
783 test to the calculation that detects an error condition and can return
784 prematurely from the function.  It's easy to forget to free the allocated memory
785 block when taking this premature exit, especially when it is added later to the
786 code.  Such leaks, once introduced, often go undetected for a long time: the
787 error exit is taken only in a small fraction of all calls, and most modern
788 machines have plenty of virtual memory, so the leak only becomes apparent in a
789 long-running process that uses the leaking function frequently.  Therefore, it's
790 important to prevent leaks from happening by having a coding convention or
791 strategy that minimizes this kind of errors.
793 Since Python makes heavy use of :cfunc:`malloc` and :cfunc:`free`, it needs a
794 strategy to avoid memory leaks as well as the use of freed memory.  The chosen
795 method is called :dfn:`reference counting`.  The principle is simple: every
796 object contains a counter, which is incremented when a reference to the object
797 is stored somewhere, and which is decremented when a reference to it is deleted.
798 When the counter reaches zero, the last reference to the object has been deleted
799 and the object is freed.
801 An alternative strategy is called :dfn:`automatic garbage collection`.
802 (Sometimes, reference counting is also referred to as a garbage collection
803 strategy, hence my use of "automatic" to distinguish the two.)  The big
804 advantage of automatic garbage collection is that the user doesn't need to call
805 :cfunc:`free` explicitly.  (Another claimed advantage is an improvement in speed
806 or memory usage --- this is no hard fact however.)  The disadvantage is that for
807 C, there is no truly portable automatic garbage collector, while reference
808 counting can be implemented portably (as long as the functions :cfunc:`malloc`
809 and :cfunc:`free` are available --- which the C Standard guarantees). Maybe some
810 day a sufficiently portable automatic garbage collector will be available for C.
811 Until then, we'll have to live with reference counts.
813 While Python uses the traditional reference counting implementation, it also
814 offers a cycle detector that works to detect reference cycles.  This allows
815 applications to not worry about creating direct or indirect circular references;
816 these are the weakness of garbage collection implemented using only reference
817 counting.  Reference cycles consist of objects which contain (possibly indirect)
818 references to themselves, so that each object in the cycle has a reference count
819 which is non-zero.  Typical reference counting implementations are not able to
820 reclaim the memory belonging to any objects in a reference cycle, or referenced
821 from the objects in the cycle, even though there are no further references to
822 the cycle itself.
824 The cycle detector is able to detect garbage cycles and can reclaim them so long
825 as there are no finalizers implemented in Python (:meth:`__del__` methods).
826 When there are such finalizers, the detector exposes the cycles through the
827 :mod:`gc` module (specifically, the
828 ``garbage`` variable in that module).  The :mod:`gc` module also exposes a way
829 to run the detector (the :func:`collect` function), as well as configuration
830 interfaces and the ability to disable the detector at runtime.  The cycle
831 detector is considered an optional component; though it is included by default,
832 it can be disabled at build time using the :option:`--without-cycle-gc` option
833 to the :program:`configure` script on Unix platforms (including Mac OS X) or by
834 removing the definition of ``WITH_CYCLE_GC`` in the :file:`pyconfig.h` header on
835 other platforms.  If the cycle detector is disabled in this way, the :mod:`gc`
836 module will not be available.
839 .. _refcountsinpython:
841 Reference Counting in Python
842 ----------------------------
844 There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle the
845 incrementing and decrementing of the reference count. :cfunc:`Py_DECREF` also
846 frees the object when the count reaches zero. For flexibility, it doesn't call
847 :cfunc:`free` directly --- rather, it makes a call through a function pointer in
848 the object's :dfn:`type object`.  For this purpose (and others), every object
849 also contains a pointer to its type object.
851 The big question now remains: when to use ``Py_INCREF(x)`` and ``Py_DECREF(x)``?
852 Let's first introduce some terms.  Nobody "owns" an object; however, you can
853 :dfn:`own a reference` to an object.  An object's reference count is now defined
854 as the number of owned references to it.  The owner of a reference is
855 responsible for calling :cfunc:`Py_DECREF` when the reference is no longer
856 needed.  Ownership of a reference can be transferred.  There are three ways to
857 dispose of an owned reference: pass it on, store it, or call :cfunc:`Py_DECREF`.
858 Forgetting to dispose of an owned reference creates a memory leak.
860 It is also possible to :dfn:`borrow` [#]_ a reference to an object.  The
861 borrower of a reference should not call :cfunc:`Py_DECREF`.  The borrower must
862 not hold on to the object longer than the owner from which it was borrowed.
863 Using a borrowed reference after the owner has disposed of it risks using freed
864 memory and should be avoided completely. [#]_
866 The advantage of borrowing over owning a reference is that you don't need to
867 take care of disposing of the reference on all possible paths through the code
868 --- in other words, with a borrowed reference you don't run the risk of leaking
869 when a premature exit is taken.  The disadvantage of borrowing over owning is
870 that there are some subtle situations where in seemingly correct code a borrowed
871 reference can be used after the owner from which it was borrowed has in fact
872 disposed of it.
874 A borrowed reference can be changed into an owned reference by calling
875 :cfunc:`Py_INCREF`.  This does not affect the status of the owner from which the
876 reference was borrowed --- it creates a new owned reference, and gives full
877 owner responsibilities (the new owner must dispose of the reference properly, as
878 well as the previous owner).
881 .. _ownershiprules:
883 Ownership Rules
884 ---------------
886 Whenever an object reference is passed into or out of a function, it is part of
887 the function's interface specification whether ownership is transferred with the
888 reference or not.
890 Most functions that return a reference to an object pass on ownership with the
891 reference.  In particular, all functions whose function it is to create a new
892 object, such as :cfunc:`PyInt_FromLong` and :cfunc:`Py_BuildValue`, pass
893 ownership to the receiver.  Even if the object is not actually new, you still
894 receive ownership of a new reference to that object.  For instance,
895 :cfunc:`PyInt_FromLong` maintains a cache of popular values and can return a
896 reference to a cached item.
898 Many functions that extract objects from other objects also transfer ownership
899 with the reference, for instance :cfunc:`PyObject_GetAttrString`.  The picture
900 is less clear, here, however, since a few common routines are exceptions:
901 :cfunc:`PyTuple_GetItem`, :cfunc:`PyList_GetItem`, :cfunc:`PyDict_GetItem`, and
902 :cfunc:`PyDict_GetItemString` all return references that you borrow from the
903 tuple, list or dictionary.
905 The function :cfunc:`PyImport_AddModule` also returns a borrowed reference, even
906 though it may actually create the object it returns: this is possible because an
907 owned reference to the object is stored in ``sys.modules``.
909 When you pass an object reference into another function, in general, the
910 function borrows the reference from you --- if it needs to store it, it will use
911 :cfunc:`Py_INCREF` to become an independent owner.  There are exactly two
912 important exceptions to this rule: :cfunc:`PyTuple_SetItem` and
913 :cfunc:`PyList_SetItem`.  These functions take over ownership of the item passed
914 to them --- even if they fail!  (Note that :cfunc:`PyDict_SetItem` and friends
915 don't take over ownership --- they are "normal.")
917 When a C function is called from Python, it borrows references to its arguments
918 from the caller.  The caller owns a reference to the object, so the borrowed
919 reference's lifetime is guaranteed until the function returns.  Only when such a
920 borrowed reference must be stored or passed on, it must be turned into an owned
921 reference by calling :cfunc:`Py_INCREF`.
923 The object reference returned from a C function that is called from Python must
924 be an owned reference --- ownership is transferred from the function to its
925 caller.
928 .. _thinice:
930 Thin Ice
931 --------
933 There are a few situations where seemingly harmless use of a borrowed reference
934 can lead to problems.  These all have to do with implicit invocations of the
935 interpreter, which can cause the owner of a reference to dispose of it.
937 The first and most important case to know about is using :cfunc:`Py_DECREF` on
938 an unrelated object while borrowing a reference to a list item.  For instance::
940    void
941    bug(PyObject *list)
942    {
943        PyObject *item = PyList_GetItem(list, 0);
945        PyList_SetItem(list, 1, PyInt_FromLong(0L));
946        PyObject_Print(item, stdout, 0); /* BUG! */
947    }
949 This function first borrows a reference to ``list[0]``, then replaces
950 ``list[1]`` with the value ``0``, and finally prints the borrowed reference.
951 Looks harmless, right?  But it's not!
953 Let's follow the control flow into :cfunc:`PyList_SetItem`.  The list owns
954 references to all its items, so when item 1 is replaced, it has to dispose of
955 the original item 1.  Now let's suppose the original item 1 was an instance of a
956 user-defined class, and let's further suppose that the class defined a
957 :meth:`__del__` method.  If this class instance has a reference count of 1,
958 disposing of it will call its :meth:`__del__` method.
960 Since it is written in Python, the :meth:`__del__` method can execute arbitrary
961 Python code.  Could it perhaps do something to invalidate the reference to
962 ``item`` in :cfunc:`bug`?  You bet!  Assuming that the list passed into
963 :cfunc:`bug` is accessible to the :meth:`__del__` method, it could execute a
964 statement to the effect of ``del list[0]``, and assuming this was the last
965 reference to that object, it would free the memory associated with it, thereby
966 invalidating ``item``.
968 The solution, once you know the source of the problem, is easy: temporarily
969 increment the reference count.  The correct version of the function reads::
971    void
972    no_bug(PyObject *list)
973    {
974        PyObject *item = PyList_GetItem(list, 0);
976        Py_INCREF(item);
977        PyList_SetItem(list, 1, PyInt_FromLong(0L));
978        PyObject_Print(item, stdout, 0);
979        Py_DECREF(item);
980    }
982 This is a true story.  An older version of Python contained variants of this bug
983 and someone spent a considerable amount of time in a C debugger to figure out
984 why his :meth:`__del__` methods would fail...
986 The second case of problems with a borrowed reference is a variant involving
987 threads.  Normally, multiple threads in the Python interpreter can't get in each
988 other's way, because there is a global lock protecting Python's entire object
989 space.  However, it is possible to temporarily release this lock using the macro
990 :cmacro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
991 :cmacro:`Py_END_ALLOW_THREADS`.  This is common around blocking I/O calls, to
992 let other threads use the processor while waiting for the I/O to complete.
993 Obviously, the following function has the same problem as the previous one::
995    void
996    bug(PyObject *list)
997    {
998        PyObject *item = PyList_GetItem(list, 0);
999        Py_BEGIN_ALLOW_THREADS
1000        ...some blocking I/O call...
1001        Py_END_ALLOW_THREADS
1002        PyObject_Print(item, stdout, 0); /* BUG! */
1003    }
1006 .. _nullpointers:
1008 NULL Pointers
1009 -------------
1011 In general, functions that take object references as arguments do not expect you
1012 to pass them *NULL* pointers, and will dump core (or cause later core dumps) if
1013 you do so.  Functions that return object references generally return *NULL* only
1014 to indicate that an exception occurred.  The reason for not testing for *NULL*
1015 arguments is that functions often pass the objects they receive on to other
1016 function --- if each function were to test for *NULL*, there would be a lot of
1017 redundant tests and the code would run more slowly.
1019 It is better to test for *NULL* only at the "source:" when a pointer that may be
1020 *NULL* is received, for example, from :cfunc:`malloc` or from a function that
1021 may raise an exception.
1023 The macros :cfunc:`Py_INCREF` and :cfunc:`Py_DECREF` do not check for *NULL*
1024 pointers --- however, their variants :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF`
1027 The macros for checking for a particular object type (``Pytype_Check()``) don't
1028 check for *NULL* pointers --- again, there is much code that calls several of
1029 these in a row to test an object against various different expected types, and
1030 this would generate redundant tests.  There are no variants with *NULL*
1031 checking.
1033 The C function calling mechanism guarantees that the argument list passed to C
1034 functions (``args`` in the examples) is never *NULL* --- in fact it guarantees
1035 that it is always a tuple. [#]_
1037 It is a severe error to ever let a *NULL* pointer "escape" to the Python user.
1039 .. Frank Stajano:
1040    A pedagogically buggy example, along the lines of the previous listing, would
1041    be helpful here -- showing in more concrete terms what sort of actions could
1042    cause the problem. I can't very well imagine it from the description.
1045 .. _cplusplus:
1047 Writing Extensions in C++
1048 =========================
1050 It is possible to write extension modules in C++.  Some restrictions apply.  If
1051 the main program (the Python interpreter) is compiled and linked by the C
1052 compiler, global or static objects with constructors cannot be used.  This is
1053 not a problem if the main program is linked by the C++ compiler.  Functions that
1054 will be called by the Python interpreter (in particular, module initialization
1055 functions) have to be declared using ``extern "C"``. It is unnecessary to
1056 enclose the Python header files in ``extern "C" {...}`` --- they use this form
1057 already if the symbol ``__cplusplus`` is defined (all recent C++ compilers
1058 define this symbol).
1061 .. _using-cobjects:
1063 Providing a C API for an Extension Module
1064 =========================================
1066 .. sectionauthor:: Konrad Hinsen <hinsen@cnrs-orleans.fr>
1069 Many extension modules just provide new functions and types to be used from
1070 Python, but sometimes the code in an extension module can be useful for other
1071 extension modules. For example, an extension module could implement a type
1072 "collection" which works like lists without order. Just like the standard Python
1073 list type has a C API which permits extension modules to create and manipulate
1074 lists, this new collection type should have a set of C functions for direct
1075 manipulation from other extension modules.
1077 At first sight this seems easy: just write the functions (without declaring them
1078 ``static``, of course), provide an appropriate header file, and document
1079 the C API. And in fact this would work if all extension modules were always
1080 linked statically with the Python interpreter. When modules are used as shared
1081 libraries, however, the symbols defined in one module may not be visible to
1082 another module. The details of visibility depend on the operating system; some
1083 systems use one global namespace for the Python interpreter and all extension
1084 modules (Windows, for example), whereas others require an explicit list of
1085 imported symbols at module link time (AIX is one example), or offer a choice of
1086 different strategies (most Unices). And even if symbols are globally visible,
1087 the module whose functions one wishes to call might not have been loaded yet!
1089 Portability therefore requires not to make any assumptions about symbol
1090 visibility. This means that all symbols in extension modules should be declared
1091 ``static``, except for the module's initialization function, in order to
1092 avoid name clashes with other extension modules (as discussed in section
1093 :ref:`methodtable`). And it means that symbols that *should* be accessible from
1094 other extension modules must be exported in a different way.
1096 Python provides a special mechanism to pass C-level information (pointers) from
1097 one extension module to another one: CObjects. A CObject is a Python data type
1098 which stores a pointer (:ctype:`void \*`).  CObjects can only be created and
1099 accessed via their C API, but they can be passed around like any other Python
1100 object. In particular,  they can be assigned to a name in an extension module's
1101 namespace. Other extension modules can then import this module, retrieve the
1102 value of this name, and then retrieve the pointer from the CObject.
1104 There are many ways in which CObjects can be used to export the C API of an
1105 extension module. Each name could get its own CObject, or all C API pointers
1106 could be stored in an array whose address is published in a CObject. And the
1107 various tasks of storing and retrieving the pointers can be distributed in
1108 different ways between the module providing the code and the client modules.
1110 The following example demonstrates an approach that puts most of the burden on
1111 the writer of the exporting module, which is appropriate for commonly used
1112 library modules. It stores all C API pointers (just one in the example!) in an
1113 array of :ctype:`void` pointers which becomes the value of a CObject. The header
1114 file corresponding to the module provides a macro that takes care of importing
1115 the module and retrieving its C API pointers; client modules only have to call
1116 this macro before accessing the C API.
1118 The exporting module is a modification of the :mod:`spam` module from section
1119 :ref:`extending-simpleexample`. The function :func:`spam.system` does not call
1120 the C library function :cfunc:`system` directly, but a function
1121 :cfunc:`PySpam_System`, which would of course do something more complicated in
1122 reality (such as adding "spam" to every command). This function
1123 :cfunc:`PySpam_System` is also exported to other extension modules.
1125 The function :cfunc:`PySpam_System` is a plain C function, declared
1126 ``static`` like everything else::
1128    static int
1129    PySpam_System(const char *command)
1130    {
1131        return system(command);
1132    }
1134 The function :cfunc:`spam_system` is modified in a trivial way::
1136    static PyObject *
1137    spam_system(PyObject *self, PyObject *args)
1138    {
1139        const char *command;
1140        int sts;
1142        if (!PyArg_ParseTuple(args, "s", &command))
1143            return NULL;
1144        sts = PySpam_System(command);
1145        return Py_BuildValue("i", sts);
1146    }
1148 In the beginning of the module, right after the line ::
1150    #include "Python.h"
1152 two more lines must be added::
1154    #define SPAM_MODULE
1155    #include "spammodule.h"
1157 The ``#define`` is used to tell the header file that it is being included in the
1158 exporting module, not a client module. Finally, the module's initialization
1159 function must take care of initializing the C API pointer array::
1161    PyMODINIT_FUNC
1162    initspam(void)
1163    {
1164        PyObject *m;
1165        static void *PySpam_API[PySpam_API_pointers];
1166        PyObject *c_api_object;
1168        m = Py_InitModule("spam", SpamMethods);
1169        if (m == NULL)
1170            return;
1172        /* Initialize the C API pointer array */
1173        PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
1175        /* Create a CObject containing the API pointer array's address */
1176        c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
1178        if (c_api_object != NULL)
1179            PyModule_AddObject(m, "_C_API", c_api_object);
1180    }
1182 Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
1183 array would disappear when :func:`initspam` terminates!
1185 The bulk of the work is in the header file :file:`spammodule.h`, which looks
1186 like this::
1188    #ifndef Py_SPAMMODULE_H
1189    #define Py_SPAMMODULE_H
1190    #ifdef __cplusplus
1191    extern "C" {
1192    #endif
1194    /* Header file for spammodule */
1196    /* C API functions */
1197    #define PySpam_System_NUM 0
1198    #define PySpam_System_RETURN int
1199    #define PySpam_System_PROTO (const char *command)
1201    /* Total number of C API pointers */
1202    #define PySpam_API_pointers 1
1205    #ifdef SPAM_MODULE
1206    /* This section is used when compiling spammodule.c */
1208    static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;
1210    #else
1211    /* This section is used in modules that use spammodule's API */
1213    static void **PySpam_API;
1215    #define PySpam_System \
1216     (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
1218    /* Return -1 and set exception on error, 0 on success. */
1219    static int
1220    import_spam(void)
1221    {
1222        PyObject *module = PyImport_ImportModule("spam");
1224        if (module != NULL) {
1225            PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
1226            if (c_api_object == NULL)
1227                return -1;
1228            if (PyCObject_Check(c_api_object))
1229                PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
1230            Py_DECREF(c_api_object);
1231        }
1232        return 0;
1233    }
1235    #endif
1237    #ifdef __cplusplus
1238    }
1239    #endif
1241    #endif /* !defined(Py_SPAMMODULE_H) */
1243 All that a client module must do in order to have access to the function
1244 :cfunc:`PySpam_System` is to call the function (or rather macro)
1245 :cfunc:`import_spam` in its initialization function::
1247    PyMODINIT_FUNC
1248    initclient(void)
1249    {
1250        PyObject *m;
1252        m = Py_InitModule("client", ClientMethods);
1253        if (m == NULL)
1254            return;
1255        if (import_spam() < 0)
1256            return;
1257        /* additional initialization can happen here */
1258    }
1260 The main disadvantage of this approach is that the file :file:`spammodule.h` is
1261 rather complicated. However, the basic structure is the same for each function
1262 that is exported, so it has to be learned only once.
1264 Finally it should be mentioned that CObjects offer additional functionality,
1265 which is especially useful for memory allocation and deallocation of the pointer
1266 stored in a CObject. The details are described in the Python/C API Reference
1267 Manual in the section :ref:`cobjects` and in the implementation of CObjects (files
1268 :file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source
1269 code distribution).
1271 .. rubric:: Footnotes
1273 .. [#] An interface for this function already exists in the standard module :mod:`os`
1274    --- it was chosen as a simple and straightforward example.
1276 .. [#] The metaphor of "borrowing" a reference is not completely correct: the owner
1277    still has a copy of the reference.
1279 .. [#] Checking that the reference count is at least 1 **does not work** --- the
1280    reference count itself could be in freed memory and may thus be reused for
1281    another object!
1283 .. [#] These guarantees don't hold when you use the "old" style calling convention ---
1284    this is still found in much existing code.