rest25/extending/embedding.rst => rest262/extending/embedding.rst
20Embedding Python is similar to extending it, but not quite.  The difference is
21that when you extend Python, the main program of the application is still the
22Python interpreter, while if you embed Python, the main program may have nothing
23to do with Python --- instead, some parts of the application occasionally call
24the Python interpreter to run some Python code.
25
26So if you are embedding Python, you are providing your own main program.  One of
27the things this main program has to do is initialize the Python interpreter.  At
n28-the very least, you have to call the function :cfunc:`Py_Initialize` (on Mac OS,
n28+the very least, you have to call the function :cfunc:`Py_Initialize`.  There are
29-call :cfunc:`PyMac_Initialize` instead).  There are optional calls to pass
29+optional calls to pass command line arguments to Python.  Then later you can
30-command line arguments to Python.  Then later you can call the interpreter from
30+call the interpreter from any part of the application.
31-any part of the application.
32
33There are several different ways to call the interpreter: you can pass a string
34containing Python statements to :cfunc:`PyRun_SimpleString`, or you can pass a
35stdio file pointer and a file name (for identification in error messages only)
36to :cfunc:`PyRun_SimpleFile`.  You can also call the lower-level operations
37described in the previous chapters to construct and use Python objects.
38
39A simple demo of embedding Python can be found in the directory
40:file:`Demo/embed/` of the source distribution.
41
42
43.. seealso::
44
n45-   `Python/C API Reference Manual <../api/api.html>`_
n44+   :ref:`c-api-index`
46      The details of Python's C interface are given in this manual. A great deal of
47      necessary information can be found here.
48
49
50.. _high-level-embedding:
51
52Very High Level Embedding
53=========================
127
128The first program aims to execute a function in a Python script. Like in the
129section about the very high level interface, the Python interpreter does not
130directly interact with the application (but that will change in the next
131section).
132
133The code to run a function defined in a Python script is:
134
n135- 
136-.. include:: ../includes/run-func.c
134+.. literalinclude:: ../includes/run-func.c
137-   :literal:
135+ 
138
139This code loads a Python script using ``argv[1]``, and calls the function named
140in ``argv[2]``.  Its integer arguments are the other values of the ``argv``
141array.  If you compile and link this program (let's call the finished executable
142:program:`call`), and use it to execute a Python script, such as::
143
144   def multiply(a,b):
145       print "Will compute", a, "times", b
151then the result should be::
152
153   $ call multiply multiply 3 2
154   Will compute 3 times 2
155   Result of call: 6
156
157Although the program is quite large for its functionality, most of the code is
158for data conversion between Python and C, and for error reporting.  The
n159-interesting part with respect to embedding Python starts with
n157+interesting part with respect to embedding Python starts with ::
160- 
161-.. % $
162- 
163-::
164
165   Py_Initialize();
166   pName = PyString_FromString(argv[1]);
167   /* Error checking of pName left out */
168   pModule = PyImport_Import(pName);
169
170After initializing the interpreter, the script is loaded using
171:cfunc:`PyImport_Import`.  This routine needs a Python string as its argument,
235With these extensions, the Python script can do things like ::
236
237   import emb
238   print "Number of arguments", emb.numargs()
239
240In a real application, the methods will expose an API of the application to
241Python.
242
t243-.. % \section{For the future}
244-.. % 
245-.. % You don't happen to have a nice library to get textual
246-.. % equivalents of numeric values do you :-) ?
247-.. % Callbacks here ? (I may be using information from that section
248-.. % ?!)
249-.. % threads
250-.. % code examples do not really behave well if errors happen
237+.. TODO: threads, code examples do not really behave well if errors happen
251-.. % (what to watch out for)
238+   (what to watch out for)
252
253
254.. _embeddingincplusplus:
255
256Embedding Python in C++
257=======================
258
259It is also possible to embed Python in a C++ program; precisely how this is done
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op