diff options
Diffstat (limited to '3rdparty/pybind11/README.rst')
-rw-r--r-- | 3rdparty/pybind11/README.rst | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/3rdparty/pybind11/README.rst b/3rdparty/pybind11/README.rst new file mode 100644 index 00000000..1474cb95 --- /dev/null +++ b/3rdparty/pybind11/README.rst @@ -0,0 +1,175 @@ +.. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png + :alt: pybind11 logo + +**pybind11 — Seamless operability between C++11 and Python** + +|Latest Documentation Status| |Stable Documentation Status| |Gitter chat| |CI| |Build status| + +.. warning:: + + Combining older versions of pybind11 (< 2.6.0) with the brand-new Python + 3.9.0 will trigger undefined behavior that typically manifests as crashes + during interpreter shutdown (but could also destroy your data. **You have been + warned.**) + + We recommend that you wait for Python 3.9.1 slated for release in December, + which will include a `fix <https://github.com/python/cpython/pull/22670>`_ + that resolves this problem. In the meantime, please update to the latest + version of pybind11 (2.6.0 or newer), which includes a temporary workaround + specifically when Python 3.9.0 is detected at runtime. + +**pybind11** is a lightweight header-only library that exposes C++ types +in Python and vice versa, mainly to create Python bindings of existing +C++ code. Its goals and syntax are similar to the excellent +`Boost.Python <http://www.boost.org/doc/libs/1_58_0/libs/python/doc/>`_ +library by David Abrahams: to minimize boilerplate code in traditional +extension modules by inferring type information using compile-time +introspection. + +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 ~4K +lines of code and depend on Python (2.7 or 3.5+, or PyPy) 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. + +Tutorial and reference documentation is provided at +`pybind11.readthedocs.io <https://pybind11.readthedocs.io/en/latest>`_. +A PDF version of the manual is available +`here <https://pybind11.readthedocs.io/_/downloads/en/latest/pdf/>`_. +And the source code is always available at +`github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_. + + +Core features +------------- + + +pybind11 can map the following core C++ features 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 +- Arbitrary exception types +- Enumerations +- Callbacks +- Iterators and ranges +- Custom operators +- Single and multiple inheritance +- STL data structures +- 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: + +- Python 2.7, 3.5+, and PyPy/PyPy3 7.3 are supported with an + implementation-agnostic interface. + +- 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. + +- Everything is contained in just a few header files; there is no need + to link against any additional libraries. + +- Binaries are generally smaller by a factor of at least 2 compared to + equivalent bindings generated by Boost.Python. A recent pybind11 + conversion of PyRosetta, an enormous Boost.Python binding project, + `reported <http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf>`_ + a binary size reduction of **5.4x** and compile time reduction by + **5.8x**. + +- Function signatures are precomputed at compile time (using + ``constexpr``), leading to smaller binaries. + +- With little extra effort, C++ types can be pickled and unpickled + similar to regular Python objects. + +Supported compilers +------------------- + +1. Clang/LLVM 3.3 or newer (for Apple Xcode’s clang, this is 5.0.0 or + newer) +2. GCC 4.8 or newer +3. Microsoft Visual Studio 2015 Update 3 or newer +4. Intel C++ compiler 18 or newer + (`possible issue <https://github.com/pybind/pybind11/pull/2573>`_ on 20.2) +5. Cygwin/GCC (tested on 2.5.1) +6. NVCC (CUDA 11.0 tested) +7. NVIDIA PGI (20.7 and 20.9 tested) + +About +----- + +This project was created by `Wenzel +Jakob <http://rgl.epfl.ch/people/wjakob>`_. Significant features and/or +improvements to the code were contributed by Jonas Adler, Lori A. Burns, +Sylvain Corlay, Eric Cousineau, Ralf Grosse-Kunstleve, Trent Houliston, Axel +Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov Johan Mabille, Tomasz Miąsko, +Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim +Schellart, Henry Schreiner, Ivan Smirnov, Boris Staletic, and Patrick Stewart. + +We thank Google for a generous financial contribution to the continuous +integration infrastructure used by this project. + + +Contributing +~~~~~~~~~~~~ + +See the `contributing +guide <https://github.com/pybind/pybind11/blob/master/.github/CONTRIBUTING.md>`_ +for information on building and contributing to pybind11. + +License +~~~~~~~ + +pybind11 is provided under a BSD-style license that can be found in the +`LICENSE <https://github.com/pybind/pybind11/blob/master/LICENSE>`_ +file. By using, distributing, or contributing to this project, you agree +to the terms and conditions of this license. + +.. |Latest Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge?version=latest + :target: http://pybind11.readthedocs.org/en/latest +.. |Stable Documentation Status| image:: https://img.shields.io/badge/docs-stable-blue + :target: http://pybind11.readthedocs.org/en/stable +.. |Gitter chat| image:: https://img.shields.io/gitter/room/gitterHQ/gitter.svg + :target: https://gitter.im/pybind/Lobby +.. |CI| image:: https://github.com/pybind/pybind11/workflows/CI/badge.svg + :target: https://github.com/pybind/pybind11/actions +.. |Build status| image:: https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true + :target: https://ci.appveyor.com/project/wjakob/pybind11 |