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