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="errors.html" /> | |
12 | <link rel="prev" href="intro.html" /> | |
13 | <link rel="parent" href="intro.html" /> | |
14 | <link rel="next" href="errors.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>1.1 A Simple Example | |
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. Extending Python with" | |
25 | href="intro.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.2 Intermezzo: Errors and" | |
31 | href="errors.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="intro.html">1. Extending Python with</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="errors.html">1.2 Intermezzo: Errors and</A> | |
49 | </div> | |
50 | <hr /></div> | |
51 | </DIV> | |
52 | <!--End of Navigation Panel--> | |
53 | ||
54 | <H1><A NAME="SECTION003100000000000000000"></A><A NAME="simpleExample"></A> | |
55 | <BR> | |
56 | 1.1 A Simple Example | |
57 | ||
58 | </H1> | |
59 | ||
60 | <P> | |
61 | Let's create an extension module called "<tt class="samp">spam</tt>" (the favorite food | |
62 | of Monty Python fans...) and let's say we want to create a Python | |
63 | interface to the C library function <tt class="cfunction">system()</tt>.<A NAME="tex2html1" | |
64 | HREF="#foot519"><SUP>1.1</SUP></A>This function takes a null-terminated character string as argument and | |
65 | returns an integer. We want this function to be callable from Python | |
66 | as follows: | |
67 | ||
68 | <P> | |
69 | <div class="verbatim"><pre> | |
70 | >>> import spam | |
71 | >>> status = spam.system("ls -l") | |
72 | </pre></div> | |
73 | ||
74 | <P> | |
75 | Begin by creating a file <span class="file">spammodule.c</span>. (Historically, if a | |
76 | module is called "<tt class="samp">spam</tt>", the C file containing its implementation | |
77 | is called <span class="file">spammodule.c</span>; if the module name is very long, like | |
78 | "<tt class="samp">spammify</tt>", the module name can be just <span class="file">spammify.c</span>.) | |
79 | ||
80 | <P> | |
81 | The first line of our file can be: | |
82 | ||
83 | <P> | |
84 | <div class="verbatim"><pre> | |
85 | #include <Python.h> | |
86 | </pre></div> | |
87 | ||
88 | <P> | |
89 | which pulls in the Python API (you can add a comment describing the | |
90 | purpose of the module and a copyright notice if you like). | |
91 | ||
92 | <P> | |
93 | <div class="warning"><b class="label">Warning:</b> | |
94 | ||
95 | Since Python may define some pre-processor definitions which affect | |
96 | the standard headers on some systems, you <em>must</em> include | |
97 | <span class="file">Python.h</span> before any standard headers are included. | |
98 | </div> | |
99 | ||
100 | <P> | |
101 | All user-visible symbols defined by <span class="file">Python.h</span> have a prefix of | |
102 | "<tt class="samp">Py</tt>" or "<tt class="samp">PY</tt>", except those defined in standard header files. | |
103 | For convenience, and since they are used extensively by the Python | |
104 | interpreter, <code>"Python.h"</code> includes a few standard header files: | |
105 | <code><stdio.h></code>, <code><string.h></code>, <code><errno.h></code>, and | |
106 | <code><stdlib.h></code>. If the latter header file does not exist on your | |
107 | system, it declares the functions <tt class="cfunction">malloc()</tt>, | |
108 | <tt class="cfunction">free()</tt> and <tt class="cfunction">realloc()</tt> directly. | |
109 | ||
110 | <P> | |
111 | The next thing we add to our module file is the C function that will | |
112 | be called when the Python expression "<tt class="samp">spam.system(<var>string</var>)</tt>"is evaluated (we'll see shortly how it ends up being called): | |
113 | ||
114 | <P> | |
115 | <div class="verbatim"><pre> | |
116 | static PyObject * | |
117 | spam_system(PyObject *self, PyObject *args) | |
118 | { | |
119 | const char *command; | |
120 | int sts; | |
121 | ||
122 | if (!PyArg_ParseTuple(args, "s", &command)) | |
123 | return NULL; | |
124 | sts = system(command); | |
125 | return Py_BuildValue("i", sts); | |
126 | } | |
127 | </pre></div> | |
128 | ||
129 | <P> | |
130 | There is a straightforward translation from the argument list in | |
131 | Python (for example, the single expression <code>"ls -l"</code>) to the | |
132 | arguments passed to the C function. The C function always has two | |
133 | arguments, conventionally named <var>self</var> and <var>args</var>. | |
134 | ||
135 | <P> | |
136 | The <var>self</var> argument is only used when the C function implements a | |
137 | built-in method, not a function. In the example, <var>self</var> will | |
138 | always be a <tt class="constant">NULL</tt> pointer, since we are defining a function, not a | |
139 | method. (This is done so that the interpreter doesn't have to | |
140 | understand two different types of C functions.) | |
141 | ||
142 | <P> | |
143 | The <var>args</var> argument will be a pointer to a Python tuple object | |
144 | containing the arguments. Each item of the tuple corresponds to an | |
145 | argument in the call's argument list. The arguments are Python | |
146 | objects -- in order to do anything with them in our C function we have | |
147 | to convert them to C values. The function <tt class="cfunction">PyArg_ParseTuple()</tt> | |
148 | in the Python API checks the argument types and converts them to C | |
149 | values. It uses a template string to determine the required types of | |
150 | the arguments as well as the types of the C variables into which to | |
151 | store the converted values. More about this later. | |
152 | ||
153 | <P> | |
154 | <tt class="cfunction">PyArg_ParseTuple()</tt> returns true (nonzero) if all arguments have | |
155 | the right type and its components have been stored in the variables | |
156 | whose addresses are passed. It returns false (zero) if an invalid | |
157 | argument list was passed. In the latter case it also raises an | |
158 | appropriate exception so the calling function can return | |
159 | <tt class="constant">NULL</tt> immediately (as we saw in the example). | |
160 | ||
161 | <P> | |
162 | <BR><HR><H4>Footnotes</H4> | |
163 | <DL> | |
164 | <DT><A NAME="foot519">...system().</A><A | |
165 | href="simpleExample.html#tex2html1"><SUP>1.1</SUP></A></DT> | |
166 | <DD>An | |
167 | interface for this function already exists in the standard module | |
168 | <tt class="module">os</tt> -- it was chosen as a simple and straightforward example. | |
169 | ||
170 | </DD> | |
171 | </DL> | |
172 | <DIV CLASS="navigation"> | |
173 | <div class='online-navigation'> | |
174 | <p></p><hr /> | |
175 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
176 | <tr> | |
177 | <td class='online-navigation'><a rel="prev" title="1. Extending Python with" | |
178 | href="intro.html"><img src='../icons/previous.png' | |
179 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
180 | <td class='online-navigation'><a rel="parent" title="1. Extending Python with" | |
181 | href="intro.html"><img src='../icons/up.png' | |
182 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
183 | <td class='online-navigation'><a rel="next" title="1.2 Intermezzo: Errors and" | |
184 | href="errors.html"><img src='../icons/next.png' | |
185 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
186 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> | |
187 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
188 | href="contents.html"><img src='../icons/contents.png' | |
189 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
190 | <td class='online-navigation'><img src='../icons/blank.png' | |
191 | border='0' height='32' alt='' width='32' /></td> | |
192 | <td class='online-navigation'><img src='../icons/blank.png' | |
193 | border='0' height='32' alt='' width='32' /></td> | |
194 | </tr></table> | |
195 | <div class='online-navigation'> | |
196 | <b class="navlabel">Previous:</b> | |
197 | <a class="sectref" rel="prev" href="intro.html">1. Extending Python with</A> | |
198 | <b class="navlabel">Up:</b> | |
199 | <a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A> | |
200 | <b class="navlabel">Next:</b> | |
201 | <a class="sectref" rel="next" href="errors.html">1.2 Intermezzo: Errors and</A> | |
202 | </div> | |
203 | </div> | |
204 | <hr /> | |
205 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
206 | </DIV> | |
207 | <!--End of Navigation Panel--> | |
208 | <ADDRESS> | |
209 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
210 | </ADDRESS> | |
211 | </BODY> | |
212 | </HTML> |