Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="ext.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='last' href='about.html' title='About this document...' /> | |
10 | <link rel='help' href='about.html' title='About this document...' /> | |
11 | <link rel="next" href="compilation.html" /> | |
12 | <link rel="prev" href="backToExample.html" /> | |
13 | <link rel="parent" href="intro.html" /> | |
14 | <link rel="next" href="compilation.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>1.4 The Module's Method Table and Initialization Function | |
17 | </title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="1.3 Back to the" | |
25 | href="backToExample.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="1. Extending Python with" | |
28 | href="intro.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage" | |
31 | href="compilation.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><img src='../icons/blank.png' | |
38 | border='0' height='32' alt='' width='32' /></td> | |
39 | <td class='online-navigation'><img src='../icons/blank.png' | |
40 | border='0' height='32' alt='' width='32' /></td> | |
41 | </tr></table> | |
42 | <div class='online-navigation'> | |
43 | <b class="navlabel">Previous:</b> | |
44 | <a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A> | |
45 | <b class="navlabel">Up:</b> | |
46 | <a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A> | |
47 | <b class="navlabel">Next:</b> | |
48 | <a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A> | |
49 | </div> | |
50 | <hr /></div> | |
51 | </DIV> | |
52 | <!--End of Navigation Panel--> | |
53 | ||
54 | <H1><A NAME="SECTION003400000000000000000"></A><A NAME="methodTable"></A> | |
55 | <BR> | |
56 | 1.4 The Module's Method Table and Initialization Function | |
57 | ||
58 | </H1> | |
59 | ||
60 | <P> | |
61 | I promised to show how <tt class="cfunction">spam_system()</tt> is called from Python | |
62 | programs. First, we need to list its name and address in a ``method | |
63 | table'': | |
64 | ||
65 | <P> | |
66 | <div class="verbatim"><pre> | |
67 | static PyMethodDef SpamMethods[] = { | |
68 | ... | |
69 | {"system", spam_system, METH_VARARGS, | |
70 | "Execute a shell command."}, | |
71 | ... | |
72 | {NULL, NULL, 0, NULL} /* Sentinel */ | |
73 | }; | |
74 | </pre></div> | |
75 | ||
76 | <P> | |
77 | Note the third entry ("<tt class="samp">METH_VARARGS</tt>"). This is a flag telling | |
78 | the interpreter the calling convention to be used for the C | |
79 | function. It should normally always be "<tt class="samp">METH_VARARGS</tt>" or | |
80 | "<tt class="samp">METH_VARARGS | METH_KEYWORDS</tt>"; a value of <code>0</code> means that an | |
81 | obsolete variant of <tt class="cfunction">PyArg_ParseTuple()</tt> is used. | |
82 | ||
83 | <P> | |
84 | When using only "<tt class="samp">METH_VARARGS</tt>", the function should expect | |
85 | the Python-level parameters to be passed in as a tuple acceptable for | |
86 | parsing via <tt class="cfunction">PyArg_ParseTuple()</tt>; more information on this | |
87 | function is provided below. | |
88 | ||
89 | <P> | |
90 | The <tt class="constant">METH_KEYWORDS</tt> bit may be set in the third field if | |
91 | keyword arguments should be passed to the function. In this case, the | |
92 | C function should accept a third "<tt class="samp">PyObject *</tt>" parameter which | |
93 | will be a dictionary of keywords. Use | |
94 | <tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt> to parse the arguments to | |
95 | such a function. | |
96 | ||
97 | <P> | |
98 | The method table must be passed to the interpreter in the module's | |
99 | initialization function. The initialization function must be named | |
100 | <tt class="cfunction">init<var>name</var>()</tt>, where <var>name</var> is the name of the | |
101 | module, and should be the only non-<tt class="keyword">static</tt> item defined in | |
102 | the module file: | |
103 | ||
104 | <P> | |
105 | <div class="verbatim"><pre> | |
106 | PyMODINIT_FUNC | |
107 | initspam(void) | |
108 | { | |
109 | (void) Py_InitModule("spam", SpamMethods); | |
110 | } | |
111 | </pre></div> | |
112 | ||
113 | <P> | |
114 | Note that PyMODINIT_FUNC declares the function as <code>void</code> return type, | |
115 | declares any special linkage declarations required by the platform, and for | |
116 | C++ declares the function as <code>extern "C"</code>. | |
117 | ||
118 | <P> | |
119 | When the Python program imports module <tt class="module">spam</tt> for the first | |
120 | time, <tt class="cfunction">initspam()</tt> is called. (See below for comments about | |
121 | embedding Python.) It calls | |
122 | <tt class="cfunction">Py_InitModule()</tt>, which creates a ``module object'' (which | |
123 | is inserted in the dictionary <code>sys.modules</code> under the key | |
124 | <code>"spam"</code>), and inserts built-in function objects into the newly | |
125 | created module based upon the table (an array of <tt class="ctype">PyMethodDef</tt> | |
126 | structures) that was passed as its second argument. | |
127 | <tt class="cfunction">Py_InitModule()</tt> returns a pointer to the module object | |
128 | that it creates (which is unused here). It aborts with a fatal error | |
129 | if the module could not be initialized satisfactorily, so the caller | |
130 | doesn't need to check for errors. | |
131 | ||
132 | <P> | |
133 | When embedding Python, the <tt class="cfunction">initspam()</tt> function is not | |
134 | called automatically unless there's an entry in the | |
135 | <tt class="cdata">_PyImport_Inittab</tt> table. The easiest way to handle this is to | |
136 | statically initialize your statically-linked modules by directly | |
137 | calling <tt class="cfunction">initspam()</tt> after the call to | |
138 | <tt class="cfunction">Py_Initialize()</tt>: | |
139 | ||
140 | <P> | |
141 | <div class="verbatim"><pre> | |
142 | int | |
143 | main(int argc, char *argv[]) | |
144 | { | |
145 | /* Pass argv[0] to the Python interpreter */ | |
146 | Py_SetProgramName(argv[0]); | |
147 | ||
148 | /* Initialize the Python interpreter. Required. */ | |
149 | Py_Initialize(); | |
150 | ||
151 | /* Add a static module */ | |
152 | initspam(); | |
153 | </pre></div> | |
154 | ||
155 | <P> | |
156 | An example may be found in the file <span class="file">Demo/embed/demo.c</span> in the | |
157 | Python source distribution. | |
158 | ||
159 | <P> | |
160 | <span class="note"><b class="label">Note:</b> | |
161 | Removing entries from <code>sys.modules</code> or importing | |
162 | compiled modules into multiple interpreters within a process (or | |
163 | following a <tt class="cfunction">fork()</tt> without an intervening | |
164 | <tt class="cfunction">exec()</tt>) can create problems for some extension modules. | |
165 | Extension module authors should exercise caution when initializing | |
166 | internal data structures. | |
167 | Note also that the <tt class="function">reload()</tt> function can be used with | |
168 | extension modules, and will call the module initialization function | |
169 | (<tt class="cfunction">initspam()</tt> in the example), but will not load the module | |
170 | again if it was loaded from a dynamically loadable object file | |
171 | (<span class="file">.so</span> on <span class="Unix">Unix</span>, <span class="file">.dll</span> on Windows).</span> | |
172 | ||
173 | <P> | |
174 | A more substantial example module is included in the Python source | |
175 | distribution as <span class="file">Modules/xxmodule.c</span>. This file may be used as a | |
176 | template or simply read as an example. The <b class="program">modulator.py</b> | |
177 | script included in the source distribution or Windows install provides | |
178 | a simple graphical user interface for declaring the functions and | |
179 | objects which a module should implement, and can generate a template | |
180 | which can be filled in. The script lives in the | |
181 | <span class="file">Tools/modulator/</span> directory; see the <span class="file">README</span> file there | |
182 | for more information. | |
183 | ||
184 | <P> | |
185 | ||
186 | <DIV CLASS="navigation"> | |
187 | <div class='online-navigation'> | |
188 | <p></p><hr /> | |
189 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
190 | <tr> | |
191 | <td class='online-navigation'><a rel="prev" title="1.3 Back to the" | |
192 | href="backToExample.html"><img src='../icons/previous.png' | |
193 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
194 | <td class='online-navigation'><a rel="parent" title="1. Extending Python with" | |
195 | href="intro.html"><img src='../icons/up.png' | |
196 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
197 | <td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage" | |
198 | href="compilation.html"><img src='../icons/next.png' | |
199 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
200 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> | |
201 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
202 | href="contents.html"><img src='../icons/contents.png' | |
203 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
204 | <td class='online-navigation'><img src='../icons/blank.png' | |
205 | border='0' height='32' alt='' width='32' /></td> | |
206 | <td class='online-navigation'><img src='../icons/blank.png' | |
207 | border='0' height='32' alt='' width='32' /></td> | |
208 | </tr></table> | |
209 | <div class='online-navigation'> | |
210 | <b class="navlabel">Previous:</b> | |
211 | <a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A> | |
212 | <b class="navlabel">Up:</b> | |
213 | <a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A> | |
214 | <b class="navlabel">Next:</b> | |
215 | <a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A> | |
216 | </div> | |
217 | </div> | |
218 | <hr /> | |
219 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
220 | </DIV> | |
221 | <!--End of Navigation Panel--> | |
222 | <ADDRESS> | |
223 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
224 | </ADDRESS> | |
225 | </BODY> | |
226 | </HTML> |