| Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 1 | About this project |
| 2 | ================== |
| 3 | **pybind11** is a lightweight header library that exposes C++ types in Python |
| 4 | and vice versa, mainly to create Python bindings of existing C++ code. Its |
| 5 | goals and syntax are similar to the excellent `Boost.Python`_ library by David |
| 6 | Abrahams: to minimize boilerplate code in traditional extension modules by |
| Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 7 | inferring type information using compile-time introspection. |
| Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 8 | |
| 9 | .. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html |
| 10 | |
| 11 | The main issue with Boost.Python—and the reason for creating such a similar |
| 12 | project—is Boost. Boost is an enormously large and complex suite of utility |
| 13 | libraries that works with almost every C++ compiler in existence. This |
| 14 | compatibility has its cost: arcane template tricks and workarounds are |
| 15 | necessary to support the oldest and buggiest of compiler specimens. Now that |
| 16 | C++11-compatible compilers are widely available, this heavy machinery has |
| 17 | become an excessively large and unnecessary dependency. |
| 18 | |
| 19 | Think of this library as a tiny self-contained version of Boost.Python with |
| 20 | everything stripped away that isn't relevant for binding generation. The whole |
| 21 | codebase requires less than 3000 lines of code and only depends on Python (2.7 |
| 22 | or 3.x) and the C++ standard library. This compact implementation was possible |
| 23 | thanks to some of the new C++11 language features (tuples, lambda functions and |
| Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 24 | variadic templates). Since its creation, this library has grown beyond |
| 25 | Boost.Python in many ways, leading to dramatically simpler binding code in many |
| 26 | common situations. |
| Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 27 | |
| 28 | Core features |
| 29 | ************* |
| 30 | The following core C++ features can be mapped to Python |
| 31 | |
| 32 | - Functions accepting and returning custom data structures per value, reference, or pointer |
| 33 | - Instance methods and static methods |
| 34 | - Overloaded functions |
| 35 | - Instance attributes and static attributes |
| 36 | - Exceptions |
| 37 | - Enumerations |
| 38 | - Callbacks |
| 39 | - Custom operators |
| 40 | - STL data structures |
| 41 | - Smart pointers with reference counting like ``std::shared_ptr`` |
| 42 | - Internal references with correct reference counting |
| 43 | - C++ classes with virtual (and pure virtual) methods can be extended in Python |
| 44 | |
| 45 | Goodies |
| 46 | ******* |
| 47 | In addition to the core functionality, pybind11 provides some extra goodies: |
| 48 | |
| 49 | - It is possible to bind C++11 lambda functions with captured variables. The |
| 50 | lambda capture data is stored inside the resulting Python function object. |
| 51 | |
| 52 | - pybind11 uses C++11 move constructors and move assignment operators whenever |
| 53 | possible to efficiently transfer custom data types. |
| 54 | |
| 55 | - It's easy to expose the internal storage of custom data types through |
| 56 | Pythons' buffer protocols. This is handy e.g. for fast conversion between |
| 57 | C++ matrix classes like Eigen and NumPy without expensive copy operations. |
| 58 | |
| 59 | - pybind11 can automatically vectorize functions so that they are transparently |
| 60 | applied to all entries of one or more NumPy array arguments. |
| 61 | |
| 62 | - Python's slice-based access and assignment operations can be supported with |
| 63 | just a few lines of code. |
| 64 | |