sam-t2/devtools/v9/html/python/ext/methodTable.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ext.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="compilation.html" />
<link rel="prev" href="backToExample.html" />
<link rel="parent" href="intro.html" />
<link rel="next" href="compilation.html" />
<meta name='aesop' content='information' />
<title>1.4 The Module's Method Table and Initialization Function
</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="1.3 Back to the"
  href="backToExample.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
  href="intro.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage"
  href="compilation.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION003400000000000000000"></A><A NAME="methodTable"></A>
<BR>
1.4 The Module's Method Table and Initialization Function

</H1>

<P>
I promised to show how <tt class="cfunction">spam_system()</tt> is called from Python
programs.  First, we need to list its name and address in a ``method
table'':

<P>
<div class="verbatim"><pre>
static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Sentinel */
};
</pre></div>

<P>
Note the third entry ("<tt class="samp">METH_VARARGS</tt>").  This is a flag telling
the interpreter the calling convention to be used for the C
function.  It should normally always be "<tt class="samp">METH_VARARGS</tt>" or
"<tt class="samp">METH_VARARGS | METH_KEYWORDS</tt>"; a value of <code>0</code> means that an
obsolete variant of <tt class="cfunction">PyArg_ParseTuple()</tt> is used.

<P>
When using only "<tt class="samp">METH_VARARGS</tt>", the function should expect
the Python-level parameters to be passed in as a tuple acceptable for
parsing via <tt class="cfunction">PyArg_ParseTuple()</tt>; more information on this
function is provided below.

<P>
The <tt class="constant">METH_KEYWORDS</tt> 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 "<tt class="samp">PyObject *</tt>" parameter which
will be a dictionary of keywords.  Use
<tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt> to parse the arguments to
such a function.

<P>
The method table must be passed to the interpreter in the module's
initialization function.  The initialization function must be named
<tt class="cfunction">init<var>name</var>()</tt>, where <var>name</var> is the name of the
module, and should be the only non-<tt class="keyword">static</tt> item defined in
the module file:

<P>
<div class="verbatim"><pre>
PyMODINIT_FUNC
initspam(void)
{
    (void) Py_InitModule("spam", SpamMethods);
}
</pre></div>

<P>
Note that PyMODINIT_FUNC declares the function as <code>void</code> return type,
declares any special linkage declarations required by the platform, and for
C++ declares the function as <code>extern "C"</code>.

<P>
When the Python program imports module <tt class="module">spam</tt> for the first
time, <tt class="cfunction">initspam()</tt> is called. (See below for comments about
embedding Python.)  It calls
<tt class="cfunction">Py_InitModule()</tt>, which creates a ``module object'' (which
is inserted in the dictionary <code>sys.modules</code> under the key
<code>"spam"</code>), and inserts built-in function objects into the newly
created module based upon the table (an array of <tt class="ctype">PyMethodDef</tt>
structures) that was passed as its second argument.
<tt class="cfunction">Py_InitModule()</tt> returns a pointer to the module object
that it creates (which is unused here).  It aborts with a fatal error
if the module could not be initialized satisfactorily, so the caller
doesn't need to check for errors.

<P>
When embedding Python, the <tt class="cfunction">initspam()</tt> function is not
called automatically unless there's an entry in the
<tt class="cdata">_PyImport_Inittab</tt> table.  The easiest way to handle this is to
statically initialize your statically-linked modules by directly
calling <tt class="cfunction">initspam()</tt> after the call to
<tt class="cfunction">Py_Initialize()</tt>:

<P>
<div class="verbatim"><pre>
int
main(int argc, char *argv[])
{
    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(argv[0]);

    /* Initialize the Python interpreter.  Required. */
    Py_Initialize();

    /* Add a static module */
    initspam();
</pre></div>

<P>
An example may be found in the file <span class="file">Demo/embed/demo.c</span> in the
Python source distribution.

<P>
<span class="note"><b class="label">Note:</b>
Removing entries from <code>sys.modules</code> or importing
compiled modules into multiple interpreters within a process (or
following a <tt class="cfunction">fork()</tt> without an intervening
<tt class="cfunction">exec()</tt>) can create problems for some extension modules.
Extension module authors should exercise caution when initializing
internal data structures.
Note also that the <tt class="function">reload()</tt> function can be used with
extension modules, and will call the module initialization function
(<tt class="cfunction">initspam()</tt> in the example), but will not load the module
again if it was loaded from a dynamically loadable object file
(<span class="file">.so</span> on <span class="Unix">Unix</span>, <span class="file">.dll</span> on Windows).</span>

<P>
A more substantial example module is included in the Python source
distribution as <span class="file">Modules/xxmodule.c</span>.  This file may be used as a
template or simply read as an example.  The <b class="program">modulator.py</b>
script included in the source distribution or Windows install provides
a simple graphical user interface for declaring the functions and
objects which a module should implement, and can generate a template
which can be filled in.  The script lives in the
<span class="file">Tools/modulator/</span> directory; see the <span class="file">README</span> file there
for more information.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="1.3 Back to the"
  href="backToExample.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
  href="intro.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage"
  href="compilation.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>