pybind11/README.md

115 lines
5.0 KiB
Markdown
Raw Normal View History

2016-03-01 14:41:02 +00:00
![pybind11 logo](https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png)
2015-08-04 11:59:51 +00:00
# pybind11 — Seamless operability between C++11 and Python
2015-07-05 18:05:44 +00:00
2015-10-13 00:57:16 +00:00
[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=latest)](http://pybind11.readthedocs.org/en/latest/?badge=latest)
2016-03-01 14:41:02 +00:00
[![Build Status](https://travis-ci.org/pybind/pybind11.svg?branch=master)](https://travis-ci.org/pybind/pybind11)
[![Build status](https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true)](https://ci.appveyor.com/project/wjakob/pybind11)
2015-10-18 12:48:24 +00:00
**pybind11** is a lightweight header-only library that exposes C++ types in Python
2015-07-05 18:05:44 +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](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 ~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
Tutorial and reference documentation is provided at
[http://pybind11.readthedocs.org/en/latest](http://pybind11.readthedocs.org/en/latest).
2016-04-28 14:25:24 +00:00
A PDF version of the manual is available
[here](https://media.readthedocs.org/pdf/pybind11/latest/pybind11.pdf).
2015-07-05 18:05:44 +00:00
## Core features
2015-10-13 00:57:16 +00:00
pybind11 can map the following core C++ features to Python
2015-07-05 18:05:44 +00:00
- Functions accepting and returning custom data structures per value, reference, or pointer
- Instance methods and static methods
- Overloaded functions
- Instance attributes and static attributes
- Exceptions
- Enumerations
- Callbacks
- Custom operators
- STL data structures
- Iterators and ranges
2015-07-05 18:05:44 +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
2015-07-05 18:05:44 +00:00
## Goodies
In addition to the core functionality, pybind11 provides some extra goodies:
2015-10-13 00:57:16 +00:00
- pybind11 uses C++11 move constructors and move assignment operators whenever
possible to efficiently transfer custom data types.
- It is possible to bind C++11 lambda functions with captured variables. The
lambda capture data is stored inside the resulting Python function object.
2015-07-05 18:05:44 +00:00
- 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.
2015-07-26 14:33:49 +00:00
- pybind11 can automatically vectorize functions so that they are transparently
applied to all entries of one or more NumPy array arguments.
2015-07-05 18:05:44 +00:00
- Python's slice-based access and assignment operations can be supported with
just a few lines of code.
2015-12-04 22:51:42 +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.
2015-12-05 13:41:25 +00:00
- Binaries are generally smaller by a factor of 2 or more compared to
equivalent bindings generated by Boost.Python.
- 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.
## 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
2016-06-02 18:31:17 +00:00
5. Cygwin/GCC (tested on 2.5.1)
2016-03-01 11:45:08 +00:00
## About
This project was created by [Wenzel Jakob](https://www.mitsuba-renderer.org/~wenzel/).
Significant features and/or improvements to the code were contributed by
Jonas Adler,
Sylvain Corlay,
Axel Huebl,
@hulucc,
2016-05-15 18:50:38 +00:00
Sergey Lyskov
Johan Mabille,
2016-05-29 10:37:11 +00:00
Tomasz Miąsko,
Dean Moldovan,
Ben Pritchard, and
Boris Schäling.
2016-03-01 11:45:08 +00:00
2015-12-05 13:41:25 +00:00
### License
pybind11 is provided under a BSD-style license that can be found in the
``LICENSE`` file. By using, distributing, or contributing to this project,
2015-12-05 13:41:25 +00:00
you agree to the terms and conditions of this license.