Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 1 | .. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png |
| 2 | :alt: pybind11 logo |
| 3 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 4 | **pybind11 — Seamless operability between C++11 and Python** |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 5 | |
Henry Schreiner | d753b76 | 2020-09-17 17:53:35 -0400 | [diff] [blame] | 6 | |Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |CI| |Build status| |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 7 | |
Henry Schreiner | de78bdd | 2020-11-15 12:23:33 -0500 | [diff] [blame] | 8 | |Repology| |PyPI package| |Conda-forge| |Python Versions| |
| 9 | |
| 10 | `Setuptools example <https://github.com/pybind/python_example>`_ |
| 11 | • `Scikit-build example <https://github.com/pybind/scikit_build_example>`_ |
| 12 | • `CMake example <https://github.com/pybind/cmake_example>`_ |
| 13 | |
Henry Schreiner | 79b0e2c | 2020-12-22 08:50:45 -0500 | [diff] [blame] | 14 | .. start |
| 15 | |
Henry Schreiner | 2a263e0 | 2020-10-13 18:19:05 -0400 | [diff] [blame] | 16 | .. warning:: |
| 17 | |
Yannick Jadoul | 91a6972 | 2020-12-09 00:08:19 +0100 | [diff] [blame] | 18 | Combining older versions of pybind11 (< 2.6.0) with Python 3.9.0 will |
| 19 | trigger undefined behavior that typically manifests as crashes during |
| 20 | interpreter shutdown (but could also destroy your data. **You have been |
Henry Schreiner | 2a263e0 | 2020-10-13 18:19:05 -0400 | [diff] [blame] | 21 | warned.**) |
| 22 | |
Yannick Jadoul | 91a6972 | 2020-12-09 00:08:19 +0100 | [diff] [blame] | 23 | We recommend that you update to the latest patch release of Python (3.9.1), |
| 24 | which includes a `fix <https://github.com/python/cpython/pull/22670>`_ |
| 25 | that resolves this problem. If you do use Python 3.9.0, please update to |
| 26 | the latest version of pybind11 (2.6.0 or newer), which includes a temporary |
| 27 | workaround specifically when Python 3.9.0 is detected at runtime. |
Henry Schreiner | 2a263e0 | 2020-10-13 18:19:05 -0400 | [diff] [blame] | 28 | |
Henry Schreiner | 79b0e2c | 2020-12-22 08:50:45 -0500 | [diff] [blame] | 29 | |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 30 | **pybind11** is a lightweight header-only library that exposes C++ types |
| 31 | in Python and vice versa, mainly to create Python bindings of existing |
| 32 | C++ code. Its goals and syntax are similar to the excellent |
| 33 | `Boost.Python <http://www.boost.org/doc/libs/1_58_0/libs/python/doc/>`_ |
| 34 | library by David Abrahams: to minimize boilerplate code in traditional |
| 35 | extension modules by inferring type information using compile-time |
| 36 | introspection. |
| 37 | |
| 38 | The main issue with Boost.Python—and the reason for creating such a |
| 39 | similar project—is Boost. Boost is an enormously large and complex suite |
| 40 | of utility libraries that works with almost every C++ compiler in |
| 41 | existence. This compatibility has its cost: arcane template tricks and |
| 42 | workarounds are necessary to support the oldest and buggiest of compiler |
| 43 | specimens. Now that C++11-compatible compilers are widely available, |
| 44 | this heavy machinery has become an excessively large and unnecessary |
| 45 | dependency. |
| 46 | |
| 47 | Think of this library as a tiny self-contained version of Boost.Python |
| 48 | with everything stripped away that isn’t relevant for binding |
| 49 | generation. Without comments, the core header files only require ~4K |
| 50 | lines of code and depend on Python (2.7 or 3.5+, or PyPy) and the C++ |
| 51 | standard library. This compact implementation was possible thanks to |
| 52 | some of the new C++11 language features (specifically: tuples, lambda |
| 53 | functions and variadic templates). Since its creation, this library has |
| 54 | grown beyond Boost.Python in many ways, leading to dramatically simpler |
| 55 | binding code in many common situations. |
| 56 | |
| 57 | Tutorial and reference documentation is provided at |
Henry Schreiner | 993495c | 2020-10-12 16:31:44 -0400 | [diff] [blame] | 58 | `pybind11.readthedocs.io <https://pybind11.readthedocs.io/en/latest>`_. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 59 | A PDF version of the manual is available |
Dariusz Suchojad | bed9080 | 2020-10-18 12:51:36 +0200 | [diff] [blame] | 60 | `here <https://pybind11.readthedocs.io/_/downloads/en/latest/pdf/>`_. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 61 | And the source code is always available at |
| 62 | `github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_. |
| 63 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 64 | |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 65 | Core features |
| 66 | ------------- |
| 67 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 68 | |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 69 | pybind11 can map the following core C++ features to Python: |
| 70 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 71 | - Functions accepting and returning custom data structures per value, |
| 72 | reference, or pointer |
| 73 | - Instance methods and static methods |
| 74 | - Overloaded functions |
| 75 | - Instance attributes and static attributes |
| 76 | - Arbitrary exception types |
| 77 | - Enumerations |
| 78 | - Callbacks |
| 79 | - Iterators and ranges |
| 80 | - Custom operators |
| 81 | - Single and multiple inheritance |
| 82 | - STL data structures |
| 83 | - Smart pointers with reference counting like ``std::shared_ptr`` |
| 84 | - Internal references with correct reference counting |
| 85 | - C++ classes with virtual (and pure virtual) methods can be extended |
| 86 | in Python |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 87 | |
| 88 | Goodies |
| 89 | ------- |
| 90 | |
| 91 | In addition to the core functionality, pybind11 provides some extra |
| 92 | goodies: |
| 93 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 94 | - Python 2.7, 3.5+, and PyPy/PyPy3 7.3 are supported with an |
| 95 | implementation-agnostic interface. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 96 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 97 | - It is possible to bind C++11 lambda functions with captured |
| 98 | variables. The lambda capture data is stored inside the resulting |
| 99 | Python function object. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 100 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 101 | - pybind11 uses C++11 move constructors and move assignment operators |
| 102 | whenever possible to efficiently transfer custom data types. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 103 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 104 | - It’s easy to expose the internal storage of custom data types through |
| 105 | Pythons’ buffer protocols. This is handy e.g. for fast conversion |
| 106 | between C++ matrix classes like Eigen and NumPy without expensive |
| 107 | copy operations. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 108 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 109 | - pybind11 can automatically vectorize functions so that they are |
| 110 | transparently applied to all entries of one or more NumPy array |
| 111 | arguments. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 112 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 113 | - Python’s slice-based access and assignment operations can be |
| 114 | supported with just a few lines of code. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 115 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 116 | - Everything is contained in just a few header files; there is no need |
| 117 | to link against any additional libraries. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 118 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 119 | - Binaries are generally smaller by a factor of at least 2 compared to |
| 120 | equivalent bindings generated by Boost.Python. A recent pybind11 |
| 121 | conversion of PyRosetta, an enormous Boost.Python binding project, |
| 122 | `reported <http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf>`_ |
| 123 | a binary size reduction of **5.4x** and compile time reduction by |
| 124 | **5.8x**. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 125 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 126 | - Function signatures are precomputed at compile time (using |
| 127 | ``constexpr``), leading to smaller binaries. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 128 | |
Henry Schreiner | 0b9acc4 | 2020-10-18 14:31:28 -0400 | [diff] [blame] | 129 | - With little extra effort, C++ types can be pickled and unpickled |
| 130 | similar to regular Python objects. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 131 | |
| 132 | Supported compilers |
| 133 | ------------------- |
| 134 | |
| 135 | 1. Clang/LLVM 3.3 or newer (for Apple Xcode’s clang, this is 5.0.0 or |
| 136 | newer) |
| 137 | 2. GCC 4.8 or newer |
| 138 | 3. Microsoft Visual Studio 2015 Update 3 or newer |
Michael Kuron | 4853408 | 2021-01-18 01:53:07 +0100 | [diff] [blame] | 139 | 4. Intel classic C++ compiler 18 or newer (ICC 20.2 tested in CI) |
Henry Schreiner | 499fcd5 | 2020-12-15 21:07:41 -0500 | [diff] [blame] | 140 | 5. Cygwin/GCC (previously tested on 2.5.1) |
Michael Kuron | 4853408 | 2021-01-18 01:53:07 +0100 | [diff] [blame] | 141 | 6. NVCC (CUDA 11.0 tested in CI) |
| 142 | 7. NVIDIA PGI (20.9 tested in CI) |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 143 | |
| 144 | About |
| 145 | ----- |
| 146 | |
| 147 | This project was created by `Wenzel |
| 148 | Jakob <http://rgl.epfl.ch/people/wjakob>`_. Significant features and/or |
| 149 | improvements to the code were contributed by Jonas Adler, Lori A. Burns, |
Wenzel Jakob | 2bc62dc | 2020-10-20 16:56:02 +0200 | [diff] [blame] | 150 | Sylvain Corlay, Eric Cousineau, Ralf Grosse-Kunstleve, Trent Houliston, Axel |
| 151 | Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov Johan Mabille, Tomasz Miąsko, |
| 152 | Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim |
| 153 | Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic, and Patrick Stewart. |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 154 | |
Wenzel Jakob | 7f9445a | 2020-10-20 21:14:40 +0200 | [diff] [blame] | 155 | We thank Google for a generous financial contribution to the continuous |
| 156 | integration infrastructure used by this project. |
| 157 | |
| 158 | |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 159 | Contributing |
| 160 | ~~~~~~~~~~~~ |
| 161 | |
| 162 | See the `contributing |
| 163 | guide <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_ |
| 164 | for information on building and contributing to pybind11. |
| 165 | |
| 166 | License |
| 167 | ~~~~~~~ |
| 168 | |
| 169 | pybind11 is provided under a BSD-style license that can be found in the |
| 170 | `LICENSE <https://github.com/pybind/pybind11/blob/master/LICENSE>`_ |
| 171 | file. By using, distributing, or contributing to this project, you agree |
| 172 | to the terms and conditions of this license. |
| 173 | |
Henry Schreiner | d753b76 | 2020-09-17 17:53:35 -0400 | [diff] [blame] | 174 | .. |Latest Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge?version=latest |
Henry Schreiner | 8fa70e7 | 2020-09-17 21:18:15 -0400 | [diff] [blame] | 175 | :target: http://pybind11.readthedocs.org/en/latest |
Henry Schreiner | 79b0e2c | 2020-12-22 08:50:45 -0500 | [diff] [blame] | 176 | .. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue.svg |
Henry Schreiner | 8fa70e7 | 2020-09-17 21:18:15 -0400 | [diff] [blame] | 177 | :target: http://pybind11.readthedocs.org/en/stable |
Henry Schreiner | 81555ce | 2020-09-17 15:40:09 -0400 | [diff] [blame] | 178 | .. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg |
| 179 | :target: https://gitter.im/pybind/Lobby |
| 180 | .. |CI| image:: https://github.com/pybind/pybind11/workflows/CI/badge.svg |
| 181 | :target: https://github.com/pybind/pybind11/actions |
| 182 | .. |Build status| image:: https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true |
| 183 | :target: https://ci.appveyor.com/project/wjakob/pybind11 |
Henry Schreiner | 79b0e2c | 2020-12-22 08:50:45 -0500 | [diff] [blame] | 184 | .. |PyPI package| image:: https://img.shields.io/pypi/v/pybind11.svg |
Henry Schreiner | de78bdd | 2020-11-15 12:23:33 -0500 | [diff] [blame] | 185 | :target: https://pypi.org/project/pybind11/ |
Henry Schreiner | 79b0e2c | 2020-12-22 08:50:45 -0500 | [diff] [blame] | 186 | .. |Conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pybind11.svg |
Henry Schreiner | de78bdd | 2020-11-15 12:23:33 -0500 | [diff] [blame] | 187 | :target: https://github.com/conda-forge/pybind11-feedstock |
| 188 | .. |Repology| image:: https://repology.org/badge/latest-versions/python:pybind11.svg |
| 189 | :target: https://repology.org/project/python:pybind11/versions |
Henry Schreiner | 79b0e2c | 2020-12-22 08:50:45 -0500 | [diff] [blame] | 190 | .. |Python Versions| image:: https://img.shields.io/pypi/pyversions/pybind11.svg |
Henry Schreiner | de78bdd | 2020-11-15 12:23:33 -0500 | [diff] [blame] | 191 | :target: https://pypi.org/project/pybind11/ |