==========================
Wrap C++ with Boost.Python
==========================

`Boost <http://www.boost.org/>`_ is a high-quality, widely-used, open-source
C++ library.  `Boost.Python
<http://www.boost.org/doc/libs/1_55_0/libs/python/doc/index.html>`_ is one
component project that provides a comprehensive wrapping capabilities between
C++ and Python.  By using Boost.Python, one can easily create a `Python
extension module <https://docs.python.org/2/extending/index.html>`__ with C++.

.. inter_bpy_sec1

Create a Python Extension
=========================

The basic and the most important feature of Boost.Python is to help writing
Python extension modules by using C++.

This is our first Python extension module by Boost.Python; call it ``zoo.cpp``:

.. literalinclude:: sec1/zoo.cpp
  :language: c++
  :linenos:

It simply return a string from C++ to Python.  Boost.Python will do all the
conversion and interfacing for us:

.. literalinclude:: sec1/visit_zoo.py
  :language: python
  :linenos:

Running the above script (call it ``visit_zoo.py``) will get::

  hello, zoo

The following makefile will help us build the module (and run it):

.. literalinclude:: sec1/Makefile
  :language: makefile
  :linenos:

Wrap a Class
============

Expose a class ``Animal`` from C++ to Python:

.. literalinclude:: sec2/zoo.cpp
  :language: c++
  :linenos:

The script changes to:

.. literalinclude:: sec2/visit_zoo.py
  :language: python
  :linenos:

The output is::

  hello, zoo
  <zoo.Animal object at 0x102437890>
  The C++ object is at 0x00007fb0c860ac20
  I see a "dog"
  I see a "cat"

Provide Docstrings
==================

Share Instances between C++ and Python
======================================

Method Overloading
==================

Irregular Arguments
===================

- http://www.boost.org/doc/libs/1_55_0/libs/python/doc/v2/args.html
- http://www.boost.org/doc/libs/1_55_0/libs/python/doc/v2/def.html

Call Back to Python
===================

.. vim: set spell ft=rst ff=unix fenc=utf8 ai et sw=4 ts=4 tw=79