pybind11/docs/intro.rst

94 lines
4.1 KiB
ReStructuredText
Raw Normal View History

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