| Embedding Python is similar to extending it, but not quite. The difference is |
| that when you extend Python, the main program of the application is still the |
| Python interpreter, while if you embed Python, the main program may have nothing |
| to do with Python --- instead, some parts of the application occasionally call |
| the Python interpreter to run some Python code. |
| |
| So if you are embedding Python, you are providing your own main program. One of |
| the things this main program has to do is initialize the Python interpreter. At |
n | the very least, you have to call the function :cfunc:`Py_Initialize` (on Mac OS, |
n | the very least, you have to call the function :cfunc:`Py_Initialize`. There are |
| call :cfunc:`PyMac_Initialize` instead). There are optional calls to pass |
| optional calls to pass command line arguments to Python. Then later you can |
| command line arguments to Python. Then later you can call the interpreter from |
| call the interpreter from any part of the application. |
| any part of the application. |
| |
| There are several different ways to call the interpreter: you can pass a string |
| containing Python statements to :cfunc:`PyRun_SimpleString`, or you can pass a |
| stdio file pointer and a file name (for identification in error messages only) |
| to :cfunc:`PyRun_SimpleFile`. You can also call the lower-level operations |
| described in the previous chapters to construct and use Python objects. |
| |
| A simple demo of embedding Python can be found in the directory |
| :file:`Demo/embed/` of the source distribution. |
| |
| |
| .. seealso:: |
| |
n | `Python/C API Reference Manual <../api/api.html>`_ |
n | :ref:`c-api-index` |
| The details of Python's C interface are given in this manual. A great deal of |
| necessary information can be found here. |
| |
| |
| .. _high-level-embedding: |
| |
| Very High Level Embedding |
| ========================= |
| |
| The first program aims to execute a function in a Python script. Like in the |
| section about the very high level interface, the Python interpreter does not |
| directly interact with the application (but that will change in the next |
| section). |
| |
| The code to run a function defined in a Python script is: |
| |
n | |
| .. include:: ../includes/run-func.c |
| .. literalinclude:: ../includes/run-func.c |
| :literal: |
| |
| |
| This code loads a Python script using ``argv[1]``, and calls the function named |
| in ``argv[2]``. Its integer arguments are the other values of the ``argv`` |
| array. If you compile and link this program (let's call the finished executable |
| :program:`call`), and use it to execute a Python script, such as:: |
| |
| def multiply(a,b): |
| print "Will compute", a, "times", b |
| then the result should be:: |
| |
| $ call multiply multiply 3 2 |
| Will compute 3 times 2 |
| Result of call: 6 |
| |
| Although the program is quite large for its functionality, most of the code is |
| for data conversion between Python and C, and for error reporting. The |
n | interesting part with respect to embedding Python starts with |
n | interesting part with respect to embedding Python starts with :: |
| |
| .. % $ |
| |
| :: |
| |
| Py_Initialize(); |
| pName = PyString_FromString(argv[1]); |
| /* Error checking of pName left out */ |
| pModule = PyImport_Import(pName); |
| |
| After initializing the interpreter, the script is loaded using |
| :cfunc:`PyImport_Import`. This routine needs a Python string as its argument, |
| With these extensions, the Python script can do things like :: |
| |
| import emb |
| print "Number of arguments", emb.numargs() |
| |
| In a real application, the methods will expose an API of the application to |
| Python. |
| |
t | .. % \section{For the future} |
| .. % |
| .. % You don't happen to have a nice library to get textual |
| .. % equivalents of numeric values do you :-) ? |
| .. % Callbacks here ? (I may be using information from that section |
| .. % ?!) |
| .. % threads |
| .. % code examples do not really behave well if errors happen |
| .. TODO: threads, code examples do not really behave well if errors happen |
| .. % (what to watch out for) |
| (what to watch out for) |
| |
| |
| .. _embeddingincplusplus: |
| |
| Embedding Python in C++ |
| ======================= |
| |
| It is also possible to embed Python in a C++ program; precisely how this is done |