mirror of
https://github.com/pybind/pybind11.git
synced 2024-11-22 05:05:11 +00:00
docs: Use README.rst in docs as home page (#2500)
This commit is contained in:
Henry Schreiner
GitHub
parent
99ef2b8467
commit
81555ce61f
@ -1,4 +1,4 @@
|
||||
recursive-include pybind11/include/pybind11 *.h
|
||||
recursive-include pybind11 *.py
|
||||
include pybind11/share/cmake/pybind11/*.cmake
|
||||
include LICENSE README.md pyproject.toml setup.py setup.cfg
|
||||
include LICENSE README.rst pyproject.toml setup.py setup.cfg
|
||||
|
||||
145
README.md
145
README.md
@ -1,145 +0,0 @@
|
||||
|
||||
|
||||
# pybind11 — Seamless operability between C++11 and Python
|
||||
|
||||
[](http://pybind11.readthedocs.org/en/master/?badge=master)
|
||||
[](http://pybind11.readthedocs.org/en/stable/?badge=stable)
|
||||
[](https://gitter.im/pybind/Lobby)
|
||||
[](https://github.com/pybind/pybind11/actions)
|
||||
[](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][] 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.org][]. A PDF version of the manual is available
|
||||
[here][docs-pdf].
|
||||
|
||||
## 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 (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.
|
||||
|
||||
- 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][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`),
|
||||
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 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)
|
||||
6. NVCC (CUDA 11 tested)
|
||||
7. NVIDIA PGI (20.7 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,
|
||||
Trent Houliston,
|
||||
Axel Huebl,
|
||||
@hulucc,
|
||||
Sergey Lyskov
|
||||
Johan Mabille,
|
||||
Tomasz Miąsko,
|
||||
Dean Moldovan,
|
||||
Ben Pritchard,
|
||||
Jason Rhinelander,
|
||||
Boris Schäling,
|
||||
Pim Schellart,
|
||||
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,
|
||||
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/.github/CONTRIBUTING.md
|
||||
[`LICENSE`]: https://github.com/pybind/pybind11/blob/master/LICENSE
|
||||
[intel-15-workaround]: https://github.com/pybind/pybind11/issues/276
|
||||
158
README.rst
Normal file
158
README.rst
Normal file
@ -0,0 +1,158 @@
|
||||
.. figure:: https://github.com/pybind/pybind11/raw/master/docs/pybind11-logo.png
|
||||
:alt: pybind11 logo
|
||||
|
||||
pybind11 — Seamless operability between C++11 and Python
|
||||
========================================================
|
||||
|
||||
|Documentation Status| |image1| |Gitter chat| |CI| |Build status|
|
||||
|
||||
**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.org <http://pybind11.readthedocs.org/en/master>`_.
|
||||
A PDF version of the manual is available
|
||||
`here <https://media.readthedocs.org/pdf/pybind11/master/pybind11.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 (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.
|
||||
|
||||
- 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 17 or newer (16 with pybind11 v2.0 and 15 with
|
||||
pybind11 v2.0 and a
|
||||
`workaround <https://github.com/pybind/pybind11/issues/276>`_)
|
||||
5. Cygwin/GCC (tested on 2.5.1)
|
||||
6. NVCC (CUDA 11 tested)
|
||||
7. NVIDIA PGI (20.7 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, Trent Houliston, Axel Huebl, @hulucc, Sergey Lyskov
|
||||
Johan Mabille, Tomasz Miąsko, Dean Moldovan, Ben Pritchard, Jason
|
||||
Rhinelander, Boris Schäling, Pim Schellart, Henry Schreiner, Ivan
|
||||
Smirnov, and Patrick Stewart.
|
||||
|
||||
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.
|
||||
|
||||
.. |Documentation Status| image:: https://readthedocs.org/projects/pybind11/badge/?version=master
|
||||
:target: http://pybind11.readthedocs.org/en/master/?badge=master
|
||||
.. |image1| image:: https://readthedocs.org/projects/pybind11/badge/?version=stable
|
||||
:target: http://pybind11.readthedocs.org/en/stable/?badge=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
|
||||
@ -31,7 +31,7 @@ import subprocess
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['breathe']
|
||||
extensions = ['breathe', 'sphinx.ext.imgconverter']
|
||||
|
||||
breathe_projects = {'pybind11': '.build/doxygenxml/'}
|
||||
breathe_default_project = 'pybind11'
|
||||
@ -242,7 +242,10 @@ latex_elements = {
|
||||
#'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
'preamble': r'\DeclareUnicodeCharacter{00A0}{}',
|
||||
'preamble': r'''
|
||||
\DeclareUnicodeCharacter{00A0}{}
|
||||
\DeclareUnicodeCharacter{2194}{<->}
|
||||
''',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#'figure_align': 'htbp',
|
||||
|
||||
@ -1,11 +1,4 @@
|
||||
.. only: not latex
|
||||
|
||||
.. image:: pybind11-logo.png
|
||||
|
||||
pybind11 --- Seamless operability between C++11 and Python
|
||||
==========================================================
|
||||
|
||||
Source code available at `github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_.
|
||||
.. include:: ../README.rst
|
||||
|
||||
.. only: not latex
|
||||
|
||||
@ -14,7 +7,6 @@ Source code available at `github.com/pybind/pybind11 <https://github.com/pybind/
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
intro
|
||||
changelog
|
||||
upgrade
|
||||
|
||||
|
||||
@ -1,93 +0,0 @@
|
||||
.. image:: pybind11-logo.png
|
||||
|
||||
About this project
|
||||
==================
|
||||
**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.
|
||||
|
||||
.. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html
|
||||
|
||||
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.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.
|
||||
|
||||
Core features
|
||||
*************
|
||||
The following core C++ features can be mapped 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.x, and PyPy (PyPy2.7 >= 5.7) 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 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.
|
||||
|
||||
.. _PyRosetta: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf
|
||||
|
||||
Supported compilers
|
||||
*******************
|
||||
|
||||
1. Clang/LLVM (any non-ancient version with C++11 support)
|
||||
2. GCC 4.8 or newer
|
||||
3. Microsoft Visual Studio 2015 or newer
|
||||
4. Intel C++ compiler v17 or newer (v16 with pybind11 v2.0 and v15 with pybind11 v2.0 and a `workaround <https://github.com/pybind/pybind11/issues/276>`_ )
|
||||
@ -1,6 +1,6 @@
|
||||
[metadata]
|
||||
long_description = file: README.md
|
||||
long_description_content_type = text/markdown
|
||||
long_description = file: README.rst
|
||||
long_description_content_type = text/x-rst
|
||||
description = Seamless operability between C++11 and Python
|
||||
author = Wenzel Jakob
|
||||
author_email = "wenzel.jakob@epfl.ch"
|
||||
|
||||
@ -80,7 +80,7 @@ sdist_files = {
|
||||
"setup.py",
|
||||
"LICENSE",
|
||||
"MANIFEST.in",
|
||||
"README.md",
|
||||
"README.rst",
|
||||
"PKG-INFO",
|
||||
}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user