intro.rst revision 11986
111986Sandreas.sandberg@arm.com.. image:: pybind11-logo.png 211986Sandreas.sandberg@arm.com 311986Sandreas.sandberg@arm.comAbout this project 411986Sandreas.sandberg@arm.com================== 511986Sandreas.sandberg@arm.com**pybind11** is a lightweight header-only library that exposes C++ types in Python 611986Sandreas.sandberg@arm.comand vice versa, mainly to create Python bindings of existing C++ code. Its 711986Sandreas.sandberg@arm.comgoals and syntax are similar to the excellent `Boost.Python`_ library by David 811986Sandreas.sandberg@arm.comAbrahams: to minimize boilerplate code in traditional extension modules by 911986Sandreas.sandberg@arm.cominferring type information using compile-time introspection. 1011986Sandreas.sandberg@arm.com 1111986Sandreas.sandberg@arm.com.. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html 1211986Sandreas.sandberg@arm.com 1311986Sandreas.sandberg@arm.comThe main issue with Boost.Python—and the reason for creating such a similar 1411986Sandreas.sandberg@arm.comproject—is Boost. Boost is an enormously large and complex suite of utility 1511986Sandreas.sandberg@arm.comlibraries that works with almost every C++ compiler in existence. This 1611986Sandreas.sandberg@arm.comcompatibility has its cost: arcane template tricks and workarounds are 1711986Sandreas.sandberg@arm.comnecessary to support the oldest and buggiest of compiler specimens. Now that 1811986Sandreas.sandberg@arm.comC++11-compatible compilers are widely available, this heavy machinery has 1911986Sandreas.sandberg@arm.combecome an excessively large and unnecessary dependency. 2011986Sandreas.sandberg@arm.com 2111986Sandreas.sandberg@arm.comThink of this library as a tiny self-contained version of Boost.Python with 2211986Sandreas.sandberg@arm.comeverything stripped away that isn't relevant for binding generation. Without 2311986Sandreas.sandberg@arm.comcomments, the core header files only require ~2.5K lines of code and depend on 2411986Sandreas.sandberg@arm.comPython (2.7 or 3.x) and the C++ standard library. This compact implementation 2511986Sandreas.sandberg@arm.comwas possible thanks to some of the new C++11 language features (specifically: 2611986Sandreas.sandberg@arm.comtuples, lambda functions and variadic templates). Since its creation, this 2711986Sandreas.sandberg@arm.comlibrary has grown beyond Boost.Python in many ways, leading to dramatically 2811986Sandreas.sandberg@arm.comsimpler binding code in many common situations. 2911986Sandreas.sandberg@arm.com 3011986Sandreas.sandberg@arm.comCore features 3111986Sandreas.sandberg@arm.com************* 3211986Sandreas.sandberg@arm.comThe following core C++ features can be mapped to Python 3311986Sandreas.sandberg@arm.com 3411986Sandreas.sandberg@arm.com- Functions accepting and returning custom data structures per value, reference, or pointer 3511986Sandreas.sandberg@arm.com- Instance methods and static methods 3611986Sandreas.sandberg@arm.com- Overloaded functions 3711986Sandreas.sandberg@arm.com- Instance attributes and static attributes 3811986Sandreas.sandberg@arm.com- Arbitrary exception types 3911986Sandreas.sandberg@arm.com- Enumerations 4011986Sandreas.sandberg@arm.com- Callbacks 4111986Sandreas.sandberg@arm.com- Iterators and ranges 4211986Sandreas.sandberg@arm.com- Custom operators 4311986Sandreas.sandberg@arm.com- Single and multiple inheritance 4411986Sandreas.sandberg@arm.com- STL data structures 4511986Sandreas.sandberg@arm.com- Iterators and ranges 4611986Sandreas.sandberg@arm.com- Smart pointers with reference counting like ``std::shared_ptr`` 4711986Sandreas.sandberg@arm.com- Internal references with correct reference counting 4811986Sandreas.sandberg@arm.com- C++ classes with virtual (and pure virtual) methods can be extended in Python 4911986Sandreas.sandberg@arm.com 5011986Sandreas.sandberg@arm.comGoodies 5111986Sandreas.sandberg@arm.com******* 5211986Sandreas.sandberg@arm.comIn addition to the core functionality, pybind11 provides some extra goodies: 5311986Sandreas.sandberg@arm.com 5411986Sandreas.sandberg@arm.com- It is possible to bind C++11 lambda functions with captured variables. The 5511986Sandreas.sandberg@arm.com lambda capture data is stored inside the resulting Python function object. 5611986Sandreas.sandberg@arm.com 5711986Sandreas.sandberg@arm.com- pybind11 uses C++11 move constructors and move assignment operators whenever 5811986Sandreas.sandberg@arm.com possible to efficiently transfer custom data types. 5911986Sandreas.sandberg@arm.com 6011986Sandreas.sandberg@arm.com- It's easy to expose the internal storage of custom data types through 6111986Sandreas.sandberg@arm.com Pythons' buffer protocols. This is handy e.g. for fast conversion between 6211986Sandreas.sandberg@arm.com C++ matrix classes like Eigen and NumPy without expensive copy operations. 6311986Sandreas.sandberg@arm.com 6411986Sandreas.sandberg@arm.com- pybind11 can automatically vectorize functions so that they are transparently 6511986Sandreas.sandberg@arm.com applied to all entries of one or more NumPy array arguments. 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.com- Python's slice-based access and assignment operations can be supported with 6811986Sandreas.sandberg@arm.com just a few lines of code. 6911986Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.com- Everything is contained in just a few header files; there is no need to link 7111986Sandreas.sandberg@arm.com against any additional libraries. 7211986Sandreas.sandberg@arm.com 7311986Sandreas.sandberg@arm.com- Binaries are generally smaller by a factor of at least 2 compared to 7411986Sandreas.sandberg@arm.com equivalent bindings generated by Boost.Python. A recent pybind11 conversion 7511986Sandreas.sandberg@arm.com of `PyRosetta`_, an enormous Boost.Python binding project, reported a binary 7611986Sandreas.sandberg@arm.com size reduction of **5.4x** and compile time reduction by **5.8x**. 7711986Sandreas.sandberg@arm.com 7811986Sandreas.sandberg@arm.com- When supported by the compiler, two new C++14 features (relaxed constexpr and 7911986Sandreas.sandberg@arm.com return value deduction) are used to precompute function signatures at compile 8011986Sandreas.sandberg@arm.com time, leading to smaller binaries. 8111986Sandreas.sandberg@arm.com 8211986Sandreas.sandberg@arm.com- With little extra effort, C++ types can be pickled and unpickled similar to 8311986Sandreas.sandberg@arm.com regular Python objects. 8411986Sandreas.sandberg@arm.com 8511986Sandreas.sandberg@arm.com.. _PyRosetta: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf 8611986Sandreas.sandberg@arm.com 8711986Sandreas.sandberg@arm.comSupported compilers 8811986Sandreas.sandberg@arm.com******************* 8911986Sandreas.sandberg@arm.com 9011986Sandreas.sandberg@arm.com1. Clang/LLVM (any non-ancient version with C++11 support) 9111986Sandreas.sandberg@arm.com2. GCC (any non-ancient version with C++11 support) 9211986Sandreas.sandberg@arm.com3. Microsoft Visual Studio 2015 or newer 9311986Sandreas.sandberg@arm.com4. Intel C++ compiler v15 or newer 94
