README.md revision 14299
113511Sgabeblack@google.com![pybind11 logo](https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png)
213511Sgabeblack@google.com
313511Sgabeblack@google.com# pybind11 — Seamless operability between C++11 and Python
413511Sgabeblack@google.com
513511Sgabeblack@google.com[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=master)](http://pybind11.readthedocs.org/en/master/?badge=master)
613511Sgabeblack@google.com[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=stable)](http://pybind11.readthedocs.org/en/stable/?badge=stable)
713511Sgabeblack@google.com[![Gitter chat](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/pybind/Lobby)
813511Sgabeblack@google.com[![Build Status](https://travis-ci.org/pybind/pybind11.svg?branch=master)](https://travis-ci.org/pybind/pybind11)
913511Sgabeblack@google.com[![Build status](https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true)](https://ci.appveyor.com/project/wjakob/pybind11)
1013511Sgabeblack@google.com
1113511Sgabeblack@google.com**pybind11** is a lightweight header-only library that exposes C++ types in Python
1213511Sgabeblack@google.comand vice versa, mainly to create Python bindings of existing C++ code. Its
1313511Sgabeblack@google.comgoals and syntax are similar to the excellent
1413511Sgabeblack@google.com[Boost.Python](http://www.boost.org/doc/libs/1_58_0/libs/python/doc/) library
1513511Sgabeblack@google.comby David Abrahams: to minimize boilerplate code in traditional extension
1613511Sgabeblack@google.commodules by inferring type information using compile-time introspection.
1713511Sgabeblack@google.com
1813511Sgabeblack@google.comThe main issue with Boost.Python—and the reason for creating such a similar
1913511Sgabeblack@google.comproject—is Boost. Boost is an enormously large and complex suite of utility
2013511Sgabeblack@google.comlibraries that works with almost every C++ compiler in existence. This
2113511Sgabeblack@google.comcompatibility has its cost: arcane template tricks and workarounds are
2213511Sgabeblack@google.comnecessary to support the oldest and buggiest of compiler specimens. Now that
2313511Sgabeblack@google.comC++11-compatible compilers are widely available, this heavy machinery has
2413511Sgabeblack@google.combecome an excessively large and unnecessary dependency.
2513511Sgabeblack@google.com
2613511Sgabeblack@google.comThink of this library as a tiny self-contained version of Boost.Python with
2713511Sgabeblack@google.comeverything stripped away that isn't relevant for binding generation. Without
2813511Sgabeblack@google.comcomments, the core header files only require ~4K lines of code and depend on
2913511Sgabeblack@google.comPython (2.7 or 3.x, or PyPy2.7 >= 5.7) and the C++ standard library. This
3013511Sgabeblack@google.comcompact implementation was possible thanks to some of the new C++11 language
3113511Sgabeblack@google.comfeatures (specifically: tuples, lambda functions and variadic templates). Since
3213511Sgabeblack@google.comits creation, this library has grown beyond Boost.Python in many ways, leading
3313511Sgabeblack@google.comto dramatically simpler binding code in many common situations.
3413511Sgabeblack@google.com
3513511Sgabeblack@google.comTutorial and reference documentation is provided at
3613511Sgabeblack@google.com[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master).
3713511Sgabeblack@google.comA PDF version of the manual is available
3813511Sgabeblack@google.com[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf).
3913511Sgabeblack@google.com
4013511Sgabeblack@google.com## Core features
4113511Sgabeblack@google.compybind11 can map the following core C++ features to Python
4213511Sgabeblack@google.com
4313511Sgabeblack@google.com- Functions accepting and returning custom data structures per value, reference, or pointer
4413511Sgabeblack@google.com- Instance methods and static methods
4513511Sgabeblack@google.com- Overloaded functions
4613511Sgabeblack@google.com- Instance attributes and static attributes
4713511Sgabeblack@google.com- Arbitrary exception types
4813511Sgabeblack@google.com- Enumerations
4913511Sgabeblack@google.com- Callbacks
5013511Sgabeblack@google.com- Iterators and ranges
5113511Sgabeblack@google.com- Custom operators
5213511Sgabeblack@google.com- Single and multiple inheritance
5313511Sgabeblack@google.com- STL data structures
5413511Sgabeblack@google.com- Smart pointers with reference counting like ``std::shared_ptr``
5513511Sgabeblack@google.com- Internal references with correct reference counting
5613511Sgabeblack@google.com- C++ classes with virtual (and pure virtual) methods can be extended in Python
5713511Sgabeblack@google.com
5813511Sgabeblack@google.com## Goodies
5913511Sgabeblack@google.comIn addition to the core functionality, pybind11 provides some extra goodies:
6013511Sgabeblack@google.com
6113511Sgabeblack@google.com- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an
6213511Sgabeblack@google.com  implementation-agnostic interface.
6313511Sgabeblack@google.com
6413511Sgabeblack@google.com- It is possible to bind C++11 lambda functions with captured variables. The
6513511Sgabeblack@google.com  lambda capture data is stored inside the resulting Python function object.
6613511Sgabeblack@google.com
6713511Sgabeblack@google.com- pybind11 uses C++11 move constructors and move assignment operators whenever
6813511Sgabeblack@google.com  possible to efficiently transfer custom data types.
6913511Sgabeblack@google.com
7013511Sgabeblack@google.com- It's easy to expose the internal storage of custom data types through
7113511Sgabeblack@google.com  Pythons' buffer protocols. This is handy e.g. for fast conversion between
7213511Sgabeblack@google.com  C++ matrix classes like Eigen and NumPy without expensive copy operations.
7313511Sgabeblack@google.com
7413511Sgabeblack@google.com- pybind11 can automatically vectorize functions so that they are transparently
7513511Sgabeblack@google.com  applied to all entries of one or more NumPy array arguments.
7613511Sgabeblack@google.com
7713511Sgabeblack@google.com- Python's slice-based access and assignment operations can be supported with
78  just a few lines of code.
79
80- Everything is contained in just a few header files; there is no need to link
81  against any additional libraries.
82
83- Binaries are generally smaller by a factor of at least 2 compared to
84  equivalent bindings generated by Boost.Python. A recent pybind11 conversion
85  of PyRosetta, an enormous Boost.Python binding project,
86  [reported](http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf) a binary
87  size reduction of **5.4x** and compile time reduction by **5.8x**.
88
89- Function signatures are precomputed at compile time (using ``constexpr``),
90  leading to smaller binaries.
91
92- With little extra effort, C++ types can be pickled and unpickled similar to
93  regular Python objects.
94
95## Supported compilers
96
971. Clang/LLVM 3.3 or newer (for Apple Xcode's clang, this is 5.0.0 or newer)
982. GCC 4.8 or newer
993. Microsoft Visual Studio 2015 Update 3 or newer
1004. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with pybind11 v2.0 and a [workaround](https://github.com/pybind/pybind11/issues/276))
1015. Cygwin/GCC (tested on 2.5.1)
102
103## About
104
105This project was created by [Wenzel Jakob](http://rgl.epfl.ch/people/wjakob).
106Significant features and/or improvements to the code were contributed by
107Jonas Adler,
108Lori A. Burns,
109Sylvain Corlay,
110Trent Houliston,
111Axel Huebl,
112@hulucc,
113Sergey Lyskov
114Johan Mabille,
115Tomasz Miąsko,
116Dean Moldovan,
117Ben Pritchard,
118Jason Rhinelander,
119Boris Schäling,
120Pim Schellart,
121Henry Schreiner,
122Ivan Smirnov, and
123Patrick Stewart.
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.
130