1![pybind11 logo](https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png) 2 3# pybind11 — Seamless operability between C++11 and Python 4 5[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=master)](http://pybind11.readthedocs.org/en/master/?badge=master) 6[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=stable)](http://pybind11.readthedocs.org/en/stable/?badge=stable)
| 1![pybind11 logo](https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png) 2 3# pybind11 — Seamless operability between C++11 and Python 4 5[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=master)](http://pybind11.readthedocs.org/en/master/?badge=master) 6[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=stable)](http://pybind11.readthedocs.org/en/stable/?badge=stable)
|
| 7[![Gitter chat](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/pybind/Lobby)
|
7[![Build Status](https://travis-ci.org/pybind/pybind11.svg?branch=master)](https://travis-ci.org/pybind/pybind11) 8[![Build status](https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true)](https://ci.appveyor.com/project/wjakob/pybind11) 9 10**pybind11** is a lightweight header-only library that exposes C++ types in Python 11and vice versa, mainly to create Python bindings of existing C++ code. Its 12goals and syntax are similar to the excellent 13[Boost.Python](http://www.boost.org/doc/libs/1_58_0/libs/python/doc/) library 14by David Abrahams: to minimize boilerplate code in traditional extension 15modules by inferring type information using compile-time introspection. 16 17The main issue with Boost.Python—and the reason for creating such a similar 18project—is Boost. Boost is an enormously large and complex suite of utility 19libraries that works with almost every C++ compiler in existence. This 20compatibility has its cost: arcane template tricks and workarounds are 21necessary to support the oldest and buggiest of compiler specimens. Now that 22C++11-compatible compilers are widely available, this heavy machinery has 23become an excessively large and unnecessary dependency. 24 25Think of this library as a tiny self-contained version of Boost.Python with 26everything stripped away that isn't relevant for binding generation. Without
| 8[![Build Status](https://travis-ci.org/pybind/pybind11.svg?branch=master)](https://travis-ci.org/pybind/pybind11) 9[![Build status](https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true)](https://ci.appveyor.com/project/wjakob/pybind11) 10 11**pybind11** is a lightweight header-only library that exposes C++ types in Python 12and vice versa, mainly to create Python bindings of existing C++ code. Its 13goals and syntax are similar to the excellent 14[Boost.Python](http://www.boost.org/doc/libs/1_58_0/libs/python/doc/) library 15by David Abrahams: to minimize boilerplate code in traditional extension 16modules by inferring type information using compile-time introspection. 17 18The main issue with Boost.Python—and the reason for creating such a similar 19project—is Boost. Boost is an enormously large and complex suite of utility 20libraries that works with almost every C++ compiler in existence. This 21compatibility has its cost: arcane template tricks and workarounds are 22necessary to support the oldest and buggiest of compiler specimens. Now that 23C++11-compatible compilers are widely available, this heavy machinery has 24become an excessively large and unnecessary dependency. 25 26Think of this library as a tiny self-contained version of Boost.Python with 27everything stripped away that isn't relevant for binding generation. Without
|
27comments, the core header files only require ~2.5K lines of code and depend on 28Python (2.7 or 3.x) and the C++ standard library. This compact implementation 29was possible thanks to some of the new C++11 language features (specifically: 30tuples, lambda functions and variadic templates). Since its creation, this 31library has grown beyond Boost.Python in many ways, leading to dramatically 32simpler binding code in many common situations.
| 28comments, the core header files only require ~4K lines of code and depend on 29Python (2.7 or 3.x, or PyPy2.7 >= 5.7) and the C++ standard library. This 30compact implementation was possible thanks to some of the new C++11 language 31features (specifically: tuples, lambda functions and variadic templates). Since 32its creation, this library has grown beyond Boost.Python in many ways, leading 33to dramatically simpler binding code in many common situations.
|
33 34Tutorial and reference documentation is provided at 35[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master). 36A PDF version of the manual is available 37[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf). 38 39## Core features 40pybind11 can map the following core C++ features to Python 41 42- Functions accepting and returning custom data structures per value, reference, or pointer 43- Instance methods and static methods 44- Overloaded functions 45- Instance attributes and static attributes 46- Arbitrary exception types 47- Enumerations 48- Callbacks 49- Iterators and ranges 50- Custom operators 51- Single and multiple inheritance 52- STL data structures 53- Iterators and ranges 54- Smart pointers with reference counting like ``std::shared_ptr`` 55- Internal references with correct reference counting 56- C++ classes with virtual (and pure virtual) methods can be extended in Python 57 58## Goodies 59In addition to the core functionality, pybind11 provides some extra goodies: 60
| 34 35Tutorial and reference documentation is provided at 36[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master). 37A PDF version of the manual is available 38[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf). 39 40## Core features 41pybind11 can map the following core C++ features to Python 42 43- Functions accepting and returning custom data structures per value, reference, or pointer 44- Instance methods and static methods 45- Overloaded functions 46- Instance attributes and static attributes 47- Arbitrary exception types 48- Enumerations 49- Callbacks 50- Iterators and ranges 51- Custom operators 52- Single and multiple inheritance 53- STL data structures 54- Iterators and ranges 55- Smart pointers with reference counting like ``std::shared_ptr`` 56- Internal references with correct reference counting 57- C++ classes with virtual (and pure virtual) methods can be extended in Python 58 59## Goodies 60In addition to the core functionality, pybind11 provides some extra goodies: 61
|
61- pybind11 uses C++11 move constructors and move assignment operators whenever 62 possible to efficiently transfer custom data types.
| 62- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an 63 implementation-agnostic interface.
|
63 64- It is possible to bind C++11 lambda functions with captured variables. The 65 lambda capture data is stored inside the resulting Python function object. 66
| 64 65- It is possible to bind C++11 lambda functions with captured variables. The 66 lambda capture data is stored inside the resulting Python function object. 67
|
| 68- pybind11 uses C++11 move constructors and move assignment operators whenever 69 possible to efficiently transfer custom data types. 70
|
67- It's easy to expose the internal storage of custom data types through 68 Pythons' buffer protocols. This is handy e.g. for fast conversion between 69 C++ matrix classes like Eigen and NumPy without expensive copy operations. 70 71- pybind11 can automatically vectorize functions so that they are transparently 72 applied to all entries of one or more NumPy array arguments. 73 74- Python's slice-based access and assignment operations can be supported with 75 just a few lines of code. 76 77- Everything is contained in just a few header files; there is no need to link 78 against any additional libraries. 79 80- Binaries are generally smaller by a factor of at least 2 compared to 81 equivalent bindings generated by Boost.Python. A recent pybind11 conversion 82 of PyRosetta, an enormous Boost.Python binding project, 83 [reported](http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf) a binary 84 size reduction of **5.4x** and compile time reduction by **5.8x**. 85 86- When supported by the compiler, two new C++14 features (relaxed constexpr and 87 return value deduction) are used to precompute function signatures at compile 88 time, leading to smaller binaries. 89 90- With little extra effort, C++ types can be pickled and unpickled similar to 91 regular Python objects. 92 93## Supported compilers 94
| 71- It's easy to expose the internal storage of custom data types through 72 Pythons' buffer protocols. This is handy e.g. for fast conversion between 73 C++ matrix classes like Eigen and NumPy without expensive copy operations. 74 75- pybind11 can automatically vectorize functions so that they are transparently 76 applied to all entries of one or more NumPy array arguments. 77 78- Python's slice-based access and assignment operations can be supported with 79 just a few lines of code. 80 81- Everything is contained in just a few header files; there is no need to link 82 against any additional libraries. 83 84- Binaries are generally smaller by a factor of at least 2 compared to 85 equivalent bindings generated by Boost.Python. A recent pybind11 conversion 86 of PyRosetta, an enormous Boost.Python binding project, 87 [reported](http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf) a binary 88 size reduction of **5.4x** and compile time reduction by **5.8x**. 89 90- When supported by the compiler, two new C++14 features (relaxed constexpr and 91 return value deduction) are used to precompute function signatures at compile 92 time, leading to smaller binaries. 93 94- With little extra effort, C++ types can be pickled and unpickled similar to 95 regular Python objects. 96 97## Supported compilers 98
|
951. Clang/LLVM (any non-ancient version with C++11 support) 962. GCC (any non-ancient version with C++11 support) 973. Microsoft Visual Studio 2015 or newer
| 991. Clang/LLVM 3.3 or newer (for Apple Xcode's clang, this is 5.0.0 or newer) 1002. GCC 4.8 or newer 1013. Microsoft Visual Studio 2015 Update 3 or newer
|
984. Intel C++ compiler 16 or newer (15 with a [workaround](https://github.com/pybind/pybind11/issues/276)) 995. Cygwin/GCC (tested on 2.5.1) 100 101## About 102
| 1024. Intel C++ compiler 16 or newer (15 with a [workaround](https://github.com/pybind/pybind11/issues/276)) 1035. Cygwin/GCC (tested on 2.5.1) 104 105## About 106
|
103This project was created by [Wenzel Jakob](https://www.mitsuba-renderer.org/~wenzel/).
| 107This project was created by [Wenzel Jakob](http://rgl.epfl.ch/people/wjakob).
|
104Significant features and/or improvements to the code were contributed by 105Jonas Adler, 106Sylvain Corlay, 107Trent Houliston, 108Axel Huebl, 109@hulucc, 110Sergey Lyskov 111Johan Mabille, 112Tomasz Miąsko, 113Dean Moldovan, 114Ben Pritchard, 115Jason Rhinelander, 116Boris Schäling,
| 108Significant features and/or improvements to the code were contributed by 109Jonas Adler, 110Sylvain Corlay, 111Trent Houliston, 112Axel Huebl, 113@hulucc, 114Sergey Lyskov 115Johan Mabille, 116Tomasz Miąsko, 117Dean Moldovan, 118Ben Pritchard, 119Jason Rhinelander, 120Boris Schäling,
|
117Pim Schellart, and 118Ivan Smirnov.
| 121Pim Schellart, 122Ivan Smirnov, and 123Patrick Stewart.
|
119 120### License 121 122pybind11 is provided under a BSD-style license that can be found in the 123``LICENSE`` file. By using, distributing, or contributing to this project, 124you agree to the terms and conditions of this license.
| 124 125### License 126 127pybind11 is provided under a BSD-style license that can be found in the 128``LICENSE`` file. By using, distributing, or contributing to this project, 129you agree to the terms and conditions of this license.
|