in a future version, it may become unnecessary to touch the Python/C API at

all. So stay tuned... <span class="inlinemediaobject"><img src="../images/smiley.png"></span></p>

<a name="embedding.building_embedded_programs"></a><h2>

To be able to use embedding in your programs, they have to be linked to

both Boost.Python's and Python's static link library.</p>

In a Jamfile, all the above boils down to:</p>

<pre class="programlisting"><tt class="literal">projectroot c:\projects\embedded_program ; # location of the program

<a name="embedding.getting_started"></a><h2>

Being able to build is nice, but there is nothing to build yet. Embedding

the Python interpreter into one of your C++ programs requires these 4

Fortunately Boost.Python provides the <a href="../../../../v2/handle.html" target="_top">handle</a> and

<a href="../../../../v2/object.html" target="_top">object</a> class templates to automate the process.</p>

<a name="using_the_interpreter.reference_counting_handles_and_objects"></a><h2>

There are two ways in which a function in the Python/C API can return a

<tt class="literal">PyObject*</tt>: as a <span class="emphasis"><em>borrowed reference</em></span> or as a <span class="emphasis"><em>new reference</em></span>. Which of

<a name="using_the_interpreter.running_python_code"></a><h2>

To run Python code from C++ there is a family of functions in the API

starting with the PyRun prefix. You can find the full list of these

for interpreting the code. The possible values are:</p>

<div class="informaltable">

<table class="table">

<a name="using_the_interpreter.beyond_handles"></a><h2>

It's nice that <tt class="literal">handle</tt> manages the reference counting details for us, but

other than that it doesn't do much. Often we'd like to have a more useful

<a name="using_the_interpreter.exception_handling"></a><h2>

If an exception occurs in the execution of some Python code, the <a href="http://www.python.org/doc/current/api/veryhigh.html#l2h-55" target="_top">PyRun_String</a>

function returns a null pointer. Constructing a <tt class="literal">handle</tt> out of this null

<div class="titlepage"><div><div><h3 class="title">

<a name="python.class_operators_special_functions"></a>Class Operators/Special Functions</h3></div></div></div>

<a name="class_operators_special_functions.python_operators"></a><h2>

C is well known for the abundance of operators. C++ extends this to the

extremes by allowing operator overloading. Boost.Python takes advantage of

default-constructible. You can use <tt class="literal">other&lt;T&gt;()</tt> in place of an actual

<tt class="literal">T</tt> instance when writing "self expressions".</p>

<a name="class_operators_special_functions.special_methods"></a><h2>

Python has a few more <span class="emphasis"><em>Special Methods</em></span>. Boost.Python supports all of the

standard special method names supported by real Python class instances. A

But before you do, you might want to fire up Python 2.2 or later and type

<tt class="literal">&gt;&gt;&gt; import this</tt>.</p>

<pre class="programlisting"><tt class="literal">&gt;&gt;&gt; import this

<div class="section" lang="en">

<div class="titlepage"><div><div><h3 class="title">

<li><span class="bold"><b>BOOM!</b></span></li>

<a name="call_policies.call_policies"></a><h2>

Call Policies may be used in situations such as the example detailed above.

In our example, <tt class="literal">return_internal_reference</tt> and <tt class="literal">with_custodian_and_ward</tt>

<a name="default_arguments.boost_python_function_overloads"></a><h2>

Boost.Python now has a way to make it easier. For instance, given a function:</p>

<pre class="programlisting"><tt class="literal"><span class="keyword">int</span><span class="identifier"> foo</span><span class="special">(</span><span class="keyword">int</span><span class="identifier"> a</span><span class="special">,</span><span class="keyword"> char</span><span class="identifier"> b</span><span class="special"> =</span><span class="number"> 1</span><span class="special">,</span><span class="keyword"> unsigned</span><span class="identifier"> c</span><span class="special"> =</span><span class="number"> 2</span><span class="special">,</span><span class="keyword"> double</span><span class="identifier"> d</span><span class="special"> =</span><span class="number"> 3</span><span class="special">)</span><span class="special">

automatically add all the foo variants for us:</p>

<pre class="programlisting"><tt class="literal"><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span><span class="identifier"> foo</span><span class="special">,</span><span class="identifier"> foo_overloads</span><span class="special">());</span></tt></pre>

<a name="default_arguments.boost_python_member_function_overloads"></a><h2>

Objects here, objects there, objects here there everywhere. More frequently

than anything else, we need to expose member functions of our classes to

See the <a href="../../../../v2/overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec" target="_top">overloads reference</a>

for details.</p>

<a name="default_arguments.init_and_optional"></a><h2>

A similar facility is provided for class constructors, again, with

default arguments or a sequence of overloads. Remember <tt class="literal">init&lt;...&gt;</tt>? For example,

Notice though that we have a situation now where we have a minimum of zero

(0) arguments and a maximum of 3 arguments.</p>

<a name="auto_overloading.manual_wrapping"></a><h2>

It is important to emphasize however that <span class="bold"><b>the overloaded functions must

have a common sequence of initial arguments</b></span>. Otherwise, our scheme above