<td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td>

<a name="embedding_basics"></a><h2>Embedding basics</h2><p>

The basics to embedding with the API are pretty simple. First you need to make sure that your program links with <tt>pythonXY.lib</tt> where X.Y is your Python version number. You'll typically find this library in the libs subdirectory of your Python installation. Now your program can follow these steps:</p>

<ol><li>#include <tt>&quot;Python.h&quot;</tt></li><li>Call <a href="http://www.python.org/doc/current/api/initialization.html#l2h-652">

Py_Initialize</a>() to start the Python interpreter.</li><li>Call other Python C API routines. </li><li>Call <a href="http://www.python.org/doc/current/api/initialization.html#l2h-656">

Now this looks pretty simple, but we'll see in the next section that step 3 can be tricky.</p>

<a name="manual_reference_counting"></a><h2>Manual reference counting</h2><p>

Most things in Python are objects. Therefore it is only natural that many of the Python C API functions operate on Python objects. Because C/C++ can't work with Python objects directly, the API defines a PyObject structure and a lot of functions to operate on PyObject pointers. </p>

An important property of Python objects, and therefore of PyObjects, is that they are reference counted. This has major advantages compared to 'dumb' copying: it requiring less memory and it avoids unnecessary copying overhead. However, there is a downside as well. Although the reference counting is transparent from the Python-side, it is quite explicit in the C API. In other words you must increase and decrease the reference counts of PyObjects <b>manually</b> using the <a href="http://www.python.org/doc/current/api/countingRefs.html#l2h-65">

Py_XINCREF</a> and <a href="http://www.python.org/doc/current/api/countingRefs.html#l2h-67">

Py_XDECREF</a> macros. This is cumbersome, and if you don't do it properly some objects might be released when you still need them, or not be released at all. </p>

I will briefly explain how to update the reference counts correctly, but I'll soon show a better way to do things.</p>

The API functions that return PyObject pointers are listed in the Python C API documentation as either returning a <i>borrowed</i> or a <i>new</i> reference. The difference is in <i>reference ownership</i>. </p>

When a <i>new</i> reference is returned, you own that reference. Therefore you don't need to worry about the object being deallocated while you still need it. You do need to decrease the reference count when you are done with it however, otherwise the object will never be deallocated. In other words, you'll have a resource leak. </p>

Here's a simple example:</p>

<blockquote><p><b>TODO:</b> <tt>need different examples because the current ones can be done very naturally with python::tuple which makes them rather unsuitable for explaining python::<a href="../../v2/handle.html">

handle</a> </tt></p></blockquote><code><pre>

<span class=comment>// Create a new tuple of 3 elements long

</span><span class=identifier>PyObject</span><span class=special>* </span><span class=identifier>my_tuple </span><span class=special>= </span><span class=identifier>PyTuple_New</span><span class=special>(</span><span class=number>3</span><span class=special>);

</span><span class=special>... </span><span class=comment>// Use my_tuple here

// We're done with the tuple

</span><span class=identifier>Py_XDECREF</span><span class=special>(</span><span class=identifier>my_tuple</span><span class=special>);

When a <i>borrowed</i> reference is returned, you do not have ownership of the reference. So if you just want to discard the return value, there is nothing you have to do: you didn't own it anyway. If want to use it however, you'll first have to increase its reference count (to prevent the objects deletion). Then later on when you are done with itm you'll need to decrease the reference count again. Here's another example:</p>

<span class=comment>// Retrieve the first item in the tuple

</span><span class=identifier>PyObject</span><span class=special>* </span><span class=identifier>first </span><span class=special>= </span><span class=identifier>PyTuple_GetItem</span><span class=special>(</span><span class=identifier>my_tuple</span><span class=special>, </span><span class=number>0</span><span class=special>);

</span><span class=identifier>Py_XINCREF</span><span class=special>(</span><span class=identifier>first</span><span class=special>);

</span><span class=special>... </span><span class=comment>// Use first here

// We're done with the first tuple item

</span><span class=identifier>Py_XDECREF</span><span class=special>(</span><span class=identifier>first</span><span class=special>);

While this certainly works, it's hardly elegant and it's easy to make mistakes, especially when there are multiple execution paths.</p>

<a name="boost_python_to_the_rescue"></a><h2>Boost.Python to the rescue</h2><p>

Now we get to the good news. If you don't want to do all the error prone reference counting yourself, you can let Boost.Python do all the work. First include <tt>&lt;boost/python.hpp&gt;</tt> instead of <tt>&quot;Python.h&quot;</tt> and link to <tt>boost_python.lib</tt> (or <tt>boost_python_debug.lib</tt>) instead of <tt>pythonXY.lib</tt>. Then all we really need to do is replace every PyObject* with <a href="../../v2/handle.html">

handle</a>&lt;PyObject&gt; and we can remove all the <a href="http://www.python.org/doc/current/api/countingRefs.html#l2h-65">

Py_XINCREF</a>s and <a href="http://www.python.org/doc/current/api/countingRefs.html#l2h-67">

Py_XDECREF</a>s! All the reference counting will be done automagically through the power of the <a href="http://sourceforge.net/docman/display_doc.php?docid=8673&amp;group_id=9028">

Resource Acquisition Is Initialization</a> idiom. </p>

We still need a way to differentiate between new and borrowed references though. Luckily, this is pretty straightforward using the <a href="../../v2/handle.html#borrowed-spec">

borrowed</a> function. Here is an example using <a href="../../v2/handle.html">

handle</a> that combines the functionality of the above two PyObject* examples. Notice how it is both shorter and cleaner:</p>

<span class=comment>// Create a new tuple of 3 elements long

</span><span class=identifier>handle</span><span class=special>&lt;</span><span class=identifier>PyObject</span><span class=special>&gt; </span><span class=identifier>my_tuple</span><span class=special>( </span><span class=identifier>PyTuple_New</span><span class=special>(</span><span class=number>3</span><span class=special>) </span><span class=special>);

</span><span class=comment>// Retrieve the first item in the tuple

</span><span class=identifier>handle</span><span class=special>&lt;</span><span class=identifier>PyObject</span><span class=special>&gt; </span><span class=identifier>first</span><span class=special>( </span><span class=identifier>borrowed</span><span class=special>(</span><span class=identifier>PyTuple_GetItem</span><span class=special>(</span><span class=identifier>my_tuple</span><span class=special>.</span><span class=identifier>get</span><span class=special>(), </span><span class=number>0</span><span class=special>)) </span><span class=special>);

</span><span class=special>... </span><span class=comment>// Use first here

Note that the <a href="../../v2/handle.html">

handle</a> member function get() returns the raw PyObject* that is held by the <a href="../../v2/handle.html">

handle</a>. </p>

<blockquote><p><b>TODO:</b> <tt>Explain PyRun_... basics, somewhere. Perhaps these functions can be used in the examples?</tt></p></blockquote><a name="boost_python_modules_in_an_embedded_program"></a><h2>Boost.Python modules in an embedded program</h2><p>

Now that we know how to call Python code from C++ and C++ code from Python, how about doing it both at the same time? Sometimes you might want to call Python code from C++ and have that Python code call C++ code again. If you built your Boost.Python module then you can just use it in your embedded Python code as you would in a standalone Python program: no further changes necessary.</p>

However, you can also define the Boost.Python module in the same program that embeds the Python code which will be using the module. Then you won't have to build the module and place it in the proper directory, and this also prevents others from using it in their own Python code. (Unless they start taking your executable apart that is. <img src="theme/smiley.gif"></img>) </p>

Doing this is relatively straightforward. You just define your Boost.Python module as usual and use the basic embedding steps described above. However, before calling <a href="http://www.python.org/doc/current/api/initialization.html#l2h-652">

Py_Initialize</a> you call <a href="http://www.python.org/doc/current/api/importing.html#l2h-137">

PyImport_AppendInittab</a> first. This function takes the name and initialization function of your module as parameters and adds the module to the interpreters list of builtin modules. So when the Python interpreter comes across an import statement, it will find the module in its list of builtin modules instead of (unsuccessfully) searching for it in the Python directory.</p>

Your program will look something like this:</p>

<span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>my_module</span><span class=special>)

</span><span class=special>{

</span><span class=special>...

</span><span class=special>}

</span><span class=special>...

</span><span class=identifier>PyImport_AppendInittab</span><span class=special>(</span><span class=string>&quot;my_module&quot;</span><span class=special>, </span><span class=identifier>initmy_module</span><span class=special>);

</span><span class=identifier>Py_Initialize</span><span class=special>();

</span><span class=special>...

There is one catch at the moment though. You must <b>not</b> call <a href="http://www.python.org/doc/current/api/initialization.html#l2h-656">

Py_Finalize</a>. Boost.Python keeps some PyObject references alive in global data structures, and when those go out of scope after interpreter finalization, Python crashes. This will be fixed in the future. </p>

<a name="additional_reading"></a><h2>Additional reading</h2><p>

A more elaborate example showing these techniques is located at <a href="../../../test/embedding.cpp">

libs/python/test/embedding.cpp</a>. </p>

<table border="0">

<td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td>