tlemo / nwcpp_pybind11

A toy example of how to create Python bindings using pybind11

Pybind11 Demo

This is a toy example intended to illustrate how to use pybind11 to create Python bindings around a C++ library. A goal of this exercise is to create a Pythonic extension without requiring modifications to the C++ library.

Directory	Component
bindings	Source code for the Python bindings (including a demo notebook)
cpp	A toy C++ dataflow graph library
docs	Doxygen documentation definition for the C++ library
tests	C++ test cases
tests/python	Python test cases

Prerequisites

• A C++17 compiler
• Python 3.6+
• CMake 3.17+
• miniconda (optional)
• Doxygen for generating the API documentation (optional)

Getting the Source Code

This project uses [Git submodules][3] for third party libraries, so --recursive is required when cloning:

git clone --recursive <repository>

Or, the submodules can be initialized after a regular clone:

git submodule init
git submodule update

Submodules may change. To avoid having to repeatedly run git submodule update:

• Use git pull --recurse-submodules when updating the local repository.
• Or, you can make it automatic: git config submodule.recurse true

Building

Tip: The use of a virtual Python environment (ex. venv or conda) is highly recommended

The easiest way to build & install the Python extension is:

python setup.py install

Or, in order to use the CMake project directly (note this will not automatically install the built Python extension library):

# from the project's root directory
mkdir build && cd build
cmake .. # defaults to debug build
make -j8 # normally, use the number of cores

Running the Python tests

python setup.py test

Running the C++ tests

cd build/tests
ctest

Or, to directly run a test binary:

cd build
tests/tests

References

• Slide deck
• pybind11 documentation
• Python Data (Object) Model
• Extending and Embedding the Python Interpreter
• Packaging binary extensions
• Packaging Python Projects
• PyPI · The Python Package Index