Skip to content

Latest commit

 

History

History
138 lines (92 loc) · 4 KB

README.md

File metadata and controls

138 lines (92 loc) · 4 KB
Raw

Build Status

cythonwrapper

Automatically generates a Cython wrapper for C++ code

Example

Suppose you have a C++ header myheader.hpp

class A
{
public:
    double plus2(double d)
    {
        return d + 2.0;
    }
};

... and you would be able to use it in Python just like

from myheader import A
a = A()
b = 3.213
c = a.plus2(b)

This is a tool that can do this for you! It will automatically parse the C++ header and generate a wrapper based on Cython for the C++ header. It will even manage all the type conversions between C++ and Python for you.

At least that is the goal. ;)

There are more examples in the subdirectory examples.

Unsupported Features of C++

Many things are not implemented yet, e.g.

  • default values
  • linking to other libraries (you can modify the setup.py though)
  • integrating other Cython extensions (you can modify the setup.py though)

Feel free to work on any of these features. :)

Why?

I think Cython is a great tool to wrap C++ code in Python. However, it requires a lot of manual work to wrap C++ code: you have to write a file that lists all the classes and functions that you want to use and you must convert custom types manually. A lot of this work can be done automatically. A pitfall is the naming of classes and functions. It is hard to have consistent names while you write a wrapper manually. With this tool you do not rely on every developer on the project to follow the same naming scheme because the names of classes and functions in the wrapper are determined automatically from their C++ decleration.

Install

Install the package with:

python setup.py install

The following dependencies are required (installation instructions for Ubuntu 14.04):

  • NumPy, Cython, Jinja2 (install e.g. with sudo pip install numpy cython Jinja2)
  • libclang and libclang Python API (install e.g. with sudo apt-get install libclang-3.5-dev python-clang-3.5)

Instead of libclang 3.5 you can use newer versions (currently up to 6.0). It is important that you have matching versions of libclang and its Python bindings.

Usage

Command Line Tool

We can generate a Python extension that wraps a library defined in C++ header with:

pywrap <headers> --sources <sources> --modulename <name> --outdir <directory>

The result is located in the directory and can be build with:

python setup.py build_ext -i

If this is a header only library we can now simply do the following in Python:

from <name> import *

If we must link against a library or we have to compile C++ source files, we will have to add that to the setup.py that has been generated.

Python Library

Note that you can use this as a Pyhon library that you can use in your setup.py as well. For now, take a look at the code to understand how you can do that. You can take a look at the main function or at the test code which should give you a good impression of how to use the library.

Import Hook

A third option to generate a Python wrapper is to use the import hook:

import pywrap.import_hook
import myheader
a = myheader.A()
b = 3.213
c = a.plus2(b)

The first import statement will add a module finder that searches for a C++ header file that corresponds to the name of modules in import statements, e.g., myheader.hpp, and compiles them before they are actually imported.

Documentation

The docmentation of this project can be found in the directory doc. To build the documentation, run e.g. (on unix):

cd doc
make html

Development

Git

You can get the latest sources with:

git clone https://github.com/AlexanderFabisch/cythonwrapper.git

Testing

You can use nosetests to run the tests of this project in the root directory:

nosetests