diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md diff --git a/MANIFEST.in b/MANIFEST.in index 6e57baeee..6fe84ced8 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,2 @@ recursive-include include/pybind11 *.h -include LICENSE README.md CONTRIBUTING.md +include LICENSE README.md .github/CONTRIBUTING.md diff --git a/README.md b/README.md index 5eee2dc9f..7634972cb 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,11 @@ [![CI](https://github.com/pybind/pybind11/workflows/CI/badge.svg)](https://github.com/pybind/pybind11/actions) [![Build status](https://ci.appveyor.com/api/projects/status/riaj54pn4h08xy40?svg=true)](https://ci.appveyor.com/project/wjakob/pybind11) -**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. +**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][] 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 @@ -26,19 +25,18 @@ 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.x, or PyPy2.7 >= 5.7) 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. +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 -[http://pybind11.readthedocs.org/en/master](http://pybind11.readthedocs.org/en/master). -A PDF version of the manual is available -[here](https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf). +[pybind11.readthedocs.org][]. A PDF version of the manual is available +[here][docs-pdf]. ## Core features -pybind11 can map the following core C++ features to Python +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 @@ -51,15 +49,15 @@ pybind11 can map the following core C++ features to Python - Custom operators - Single and multiple inheritance - STL data structures -- Smart pointers with reference counting like ``std::shared_ptr`` +- 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.x, and PyPy (PyPy2.7 >= 5.7) are supported with an - implementation-agnostic interface. +- Python 2.7, 3.5+, and PyPy (tested on 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. @@ -83,10 +81,10 @@ In addition to the core functionality, pybind11 provides some extra goodies: - 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**. + [reported][pyrosetta-report] a binary size reduction of **5.4x** and compile + time reduction by **5.8x**. -- Function signatures are precomputed at compile time (using ``constexpr``), +- 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 @@ -97,7 +95,8 @@ In addition to the core functionality, pybind11 provides some extra goodies: 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 17 or newer (16 with pybind11 v2.0 and 15 with pybind11 v2.0 and a [workaround](https://github.com/pybind/pybind11/issues/276)) +4. Intel C++ compiler 17 or newer (16 with pybind11 v2.0 and 15 with pybind11 + v2.0 and a [workaround][intel-15-workaround]) 5. Cygwin/GCC (tested on 2.5.1) ## About @@ -122,8 +121,23 @@ Henry Schreiner, Ivan Smirnov, and Patrick Stewart. +### Contributing + +See the [contributing guide][] for information on building and contributing to +pybind11. + + ### 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, +[`LICENSE`][] file. By using, distributing, or contributing to this project, you agree to the terms and conditions of this license. + + +[pybind11.readthedocs.org]: http://pybind11.readthedocs.org/en/master +[docs-pdf]: https://media.readthedocs.org/pdf/pybind11/master/pybind11.pdf +[Boost.Python]: http://www.boost.org/doc/libs/1_58_0/libs/python/doc/ +[pyrosetta-report]: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf +[contributing guide]: https://github.com/pybind/pybind11/blob/master/CONTRIBUTING.md +[`LICENSE`]: https://github.com/pybind/pybind11/blob/master/LICENSE +[intel-15-workaround]: https://github.com/pybind/pybind11/issues/276