Wenzel Jakob | 6eb11da | 2016-01-17 22:36:36 +0100 | [diff] [blame] | 1 | .. image:: pybind11-logo.png |
| 2 | |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 3 | About this project |
| 4 | ================== |
Wenzel Jakob | 7641c1d | 2015-10-18 14:48:24 +0200 | [diff] [blame] | 5 | **pybind11** is a lightweight header-only library that exposes C++ types in Python |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 6 | and vice versa, mainly to create Python bindings of existing C++ code. Its |
| 7 | goals and syntax are similar to the excellent `Boost.Python`_ library by David |
| 8 | Abrahams: to minimize boilerplate code in traditional extension modules by |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 9 | inferring type information using compile-time introspection. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 10 | |
| 11 | .. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html |
| 12 | |
| 13 | The main issue with Boost.Python—and the reason for creating such a similar |
| 14 | project—is Boost. Boost is an enormously large and complex suite of utility |
| 15 | libraries that works with almost every C++ compiler in existence. This |
| 16 | compatibility has its cost: arcane template tricks and workarounds are |
| 17 | necessary to support the oldest and buggiest of compiler specimens. Now that |
| 18 | C++11-compatible compilers are widely available, this heavy machinery has |
| 19 | become an excessively large and unnecessary dependency. |
| 20 | |
| 21 | Think of this library as a tiny self-contained version of Boost.Python with |
Wenzel Jakob | 678d787 | 2016-01-17 22:36:41 +0100 | [diff] [blame] | 22 | everything stripped away that isn't relevant for binding generation. Without |
| 23 | comments, the core header files only require ~2.5K lines of code and depend on |
| 24 | Python (2.7 or 3.x) and the C++ standard library. This compact implementation |
| 25 | was possible thanks to some of the new C++11 language features (specifically: |
| 26 | tuples, lambda functions and variadic templates). Since its creation, this |
| 27 | library has grown beyond Boost.Python in many ways, leading to dramatically |
| 28 | simpler binding code in many common situations. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 29 | |
| 30 | Core features |
| 31 | ************* |
| 32 | The following core C++ features can be mapped to Python |
| 33 | |
| 34 | - Functions accepting and returning custom data structures per value, reference, or pointer |
| 35 | - Instance methods and static methods |
| 36 | - Overloaded functions |
| 37 | - Instance attributes and static attributes |
Wenzel Jakob | 8e5dceb | 2016-09-11 20:00:40 +0900 | [diff] [blame^] | 38 | - Arbitrary exception types |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 39 | - Enumerations |
| 40 | - Callbacks |
Wenzel Jakob | 8e5dceb | 2016-09-11 20:00:40 +0900 | [diff] [blame^] | 41 | - Iterators and ranges |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 42 | - Custom operators |
Wenzel Jakob | 8e5dceb | 2016-09-11 20:00:40 +0900 | [diff] [blame^] | 43 | - Single and multiple inheritance |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 44 | - STL data structures |
Wenzel Jakob | 8e5dceb | 2016-09-11 20:00:40 +0900 | [diff] [blame^] | 45 | - Iterators and ranges |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 46 | - Smart pointers with reference counting like ``std::shared_ptr`` |
| 47 | - Internal references with correct reference counting |
| 48 | - C++ classes with virtual (and pure virtual) methods can be extended in Python |
| 49 | |
| 50 | Goodies |
| 51 | ******* |
| 52 | In addition to the core functionality, pybind11 provides some extra goodies: |
| 53 | |
| 54 | - It is possible to bind C++11 lambda functions with captured variables. The |
| 55 | lambda capture data is stored inside the resulting Python function object. |
| 56 | |
| 57 | - pybind11 uses C++11 move constructors and move assignment operators whenever |
| 58 | possible to efficiently transfer custom data types. |
| 59 | |
| 60 | - It's easy to expose the internal storage of custom data types through |
| 61 | Pythons' buffer protocols. This is handy e.g. for fast conversion between |
| 62 | C++ matrix classes like Eigen and NumPy without expensive copy operations. |
| 63 | |
| 64 | - pybind11 can automatically vectorize functions so that they are transparently |
| 65 | applied to all entries of one or more NumPy array arguments. |
| 66 | |
| 67 | - Python's slice-based access and assignment operations can be supported with |
| 68 | just a few lines of code. |
| 69 | |
Wenzel Jakob | 40584ce | 2015-12-04 23:58:23 +0100 | [diff] [blame] | 70 | - Everything is contained in just a few header files; there is no need to link |
Wenzel Jakob | 7641c1d | 2015-10-18 14:48:24 +0200 | [diff] [blame] | 71 | against any additional libraries. |
Wenzel Jakob | 66c9a40 | 2016-01-17 22:36:36 +0100 | [diff] [blame] | 72 | |
Wenzel Jakob | 68b193e | 2016-08-19 09:32:58 +0200 | [diff] [blame] | 73 | - Binaries are generally smaller by a factor of at least 2 compared to |
| 74 | equivalent bindings generated by Boost.Python. A recent pybind11 conversion |
| 75 | of `PyRosetta`_, an enourmous Boot.Python binding project, reported a binary |
| 76 | size reduction of **5.4x** and compile time reduction by **5.8x**. |
| 77 | |
Wenzel Jakob | 6eb11da | 2016-01-17 22:36:36 +0100 | [diff] [blame] | 78 | - When supported by the compiler, two new C++14 features (relaxed constexpr and |
Wenzel Jakob | 240e404 | 2016-02-20 21:00:45 +0100 | [diff] [blame] | 79 | return value deduction) are used to precompute function signatures at compile |
Wenzel Jakob | 66c9a40 | 2016-01-17 22:36:36 +0100 | [diff] [blame] | 80 | time, leading to smaller binaries. |
Wenzel Jakob | 240e404 | 2016-02-20 21:00:45 +0100 | [diff] [blame] | 81 | |
Wenzel Jakob | b282595 | 2016-04-13 23:33:00 +0200 | [diff] [blame] | 82 | - With little extra effort, C++ types can be pickled and unpickled similar to |
| 83 | regular Python objects. |
| 84 | |
Wenzel Jakob | 192eb88 | 2016-08-19 09:38:14 +0200 | [diff] [blame] | 85 | .. _PyRosetta: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf |
| 86 | |
Wenzel Jakob | 240e404 | 2016-02-20 21:00:45 +0100 | [diff] [blame] | 87 | Supported compilers |
| 88 | ******************* |
| 89 | |
| 90 | 1. Clang/LLVM (any non-ancient version with C++11 support) |
| 91 | 2. GCC (any non-ancient version with C++11 support) |
| 92 | 3. Microsoft Visual Studio 2015 or newer |
| 93 | 4. Intel C++ compiler v15 or newer |