mirror of https://github.com/pybind/pybind11
Wenzel Jakob
10 years ago
10 changed files with 1694 additions and 197 deletions
@ -0,0 +1,192 @@
@@ -0,0 +1,192 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS = |
||||
SPHINXBUILD = sphinx-build |
||||
PAPER = |
||||
BUILDDIR = .build |
||||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) |
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) |
||||
endif |
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4 |
||||
PAPEROPT_letter = -D latex_paper_size=letter |
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . |
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . |
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext |
||||
|
||||
help: |
||||
@echo "Please use \`make <target>' where <target> is one of" |
||||
@echo " html to make standalone HTML files" |
||||
@echo " dirhtml to make HTML files named index.html in directories" |
||||
@echo " singlehtml to make a single large HTML file" |
||||
@echo " pickle to make pickle files" |
||||
@echo " json to make JSON files" |
||||
@echo " htmlhelp to make HTML files and a HTML help project" |
||||
@echo " qthelp to make HTML files and a qthelp project" |
||||
@echo " applehelp to make an Apple Help Book" |
||||
@echo " devhelp to make HTML files and a Devhelp project" |
||||
@echo " epub to make an epub" |
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex" |
||||
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" |
||||
@echo " text to make text files" |
||||
@echo " man to make manual pages" |
||||
@echo " texinfo to make Texinfo files" |
||||
@echo " info to make Texinfo files and run them through makeinfo" |
||||
@echo " gettext to make PO message catalogs" |
||||
@echo " changes to make an overview of all changed/added/deprecated items" |
||||
@echo " xml to make Docutils-native XML files" |
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes" |
||||
@echo " linkcheck to check all external links for integrity" |
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)" |
||||
@echo " coverage to run coverage check of the documentation (if enabled)" |
||||
|
||||
clean: |
||||
rm -rf $(BUILDDIR)/* |
||||
|
||||
html: |
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html |
||||
@echo |
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html." |
||||
|
||||
dirhtml: |
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml |
||||
@echo |
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." |
||||
|
||||
singlehtml: |
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml |
||||
@echo |
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." |
||||
|
||||
pickle: |
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle |
||||
@echo |
||||
@echo "Build finished; now you can process the pickle files." |
||||
|
||||
json: |
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json |
||||
@echo |
||||
@echo "Build finished; now you can process the JSON files." |
||||
|
||||
htmlhelp: |
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp |
||||
@echo |
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp." |
||||
|
||||
qthelp: |
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp |
||||
@echo |
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:" |
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pybind11.qhcp" |
||||
@echo "To view the help file:" |
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pybind11.qhc" |
||||
|
||||
applehelp: |
||||
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp |
||||
@echo |
||||
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp." |
||||
@echo "N.B. You won't be able to view it unless you put it in" \
|
||||
"~/Library/Documentation/Help or install it in your application" \
|
||||
"bundle." |
||||
|
||||
devhelp: |
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp |
||||
@echo |
||||
@echo "Build finished." |
||||
@echo "To view the help file:" |
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/pybind11" |
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pybind11" |
||||
@echo "# devhelp" |
||||
|
||||
epub: |
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub |
||||
@echo |
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub." |
||||
|
||||
latex: |
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
||||
@echo |
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." |
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)." |
||||
|
||||
latexpdf: |
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
||||
@echo "Running LaTeX files through pdflatex..." |
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf |
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." |
||||
|
||||
latexpdfja: |
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
||||
@echo "Running LaTeX files through platex and dvipdfmx..." |
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja |
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." |
||||
|
||||
text: |
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text |
||||
@echo |
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text." |
||||
|
||||
man: |
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man |
||||
@echo |
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man." |
||||
|
||||
texinfo: |
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo |
||||
@echo |
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." |
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)." |
||||
|
||||
info: |
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo |
||||
@echo "Running Texinfo files through makeinfo..." |
||||
make -C $(BUILDDIR)/texinfo info |
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." |
||||
|
||||
gettext: |
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale |
||||
@echo |
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." |
||||
|
||||
changes: |
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes |
||||
@echo |
||||
@echo "The overview file is in $(BUILDDIR)/changes." |
||||
|
||||
linkcheck: |
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck |
||||
@echo |
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt." |
||||
|
||||
doctest: |
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest |
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt." |
||||
|
||||
coverage: |
||||
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage |
||||
@echo "Testing of coverage in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/coverage/python.txt." |
||||
|
||||
xml: |
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml |
||||
@echo |
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml." |
||||
|
||||
pseudoxml: |
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml |
||||
@echo |
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." |
||||
@ -0,0 +1,202 @@
@@ -0,0 +1,202 @@
|
||||
.. _advanced: |
||||
|
||||
Advanced topics |
||||
############### |
||||
|
||||
Operator overloading |
||||
==================== |
||||
|
||||
Overriding virtual functions in Python |
||||
====================================== |
||||
|
||||
Passing anonymous functions |
||||
=========================== |
||||
|
||||
Return value policies |
||||
===================== |
||||
|
||||
Functions taking Python objects as arguments |
||||
============================================ |
||||
|
||||
Callbacks |
||||
========= |
||||
|
||||
Buffer protocol |
||||
=============== |
||||
|
||||
Python supports an extremely general and convenient approach for exchanging |
||||
data between plugin libraries. Types can expose a buffer view which provides |
||||
fast direct access to the raw internal representation. Suppose we want to bind |
||||
the following simplistic Matrix class: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
class Matrix { |
||||
public: |
||||
Matrix(size_t rows, size_t cols) : m_rows(rows), m_cols(cols) { |
||||
m_data = new float[rows*cols]; |
||||
} |
||||
float *data() { return m_data; } |
||||
size_t rows() const { return m_rows; } |
||||
size_t cols() const { return m_cols; } |
||||
private: |
||||
size_t m_rows, m_cols; |
||||
float *m_data; |
||||
}; |
||||
|
||||
The following binding code exposes the ``Matrix`` contents as a buffer object, |
||||
making it possible to cast Matrixes into NumPy arrays. It is even possible to |
||||
completely avoid copy operations with Python expressions like |
||||
``np.array(matrix_instance, copy = False)``. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Matrix>(m, "Matrix") |
||||
.def_buffer([](Matrix &m) -> py::buffer_info { |
||||
return py::buffer_info( |
||||
m.data(), /* Pointer to buffer */ |
||||
sizeof(float), /* Size of one scalar */ |
||||
py::format_descriptor<float>::value(), /* Python struct-style format descriptor */ |
||||
2, /* Number of dimensions */ |
||||
{ m.rows(), m.cols() }, /* Buffer dimensions */ |
||||
{ sizeof(float) * m.rows(), /* Strides (in bytes) for each index */ |
||||
sizeof(float) } |
||||
); |
||||
}); |
||||
|
||||
The snippet above binds a lambda function, which can create ``py::buffer_info`` |
||||
description records on demand describing a given matrix. The contents of |
||||
``py::buffer_info`` mirror the Python buffer protocol specification. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
struct buffer_info { |
||||
void *ptr; |
||||
size_t itemsize; |
||||
std::string format; |
||||
int ndim; |
||||
std::vector<size_t> shape; |
||||
std::vector<size_t> strides; |
||||
}; |
||||
|
||||
To create a C++ function that can take a Python buffer object as an argument, |
||||
simply use the type ``py::buffer`` as one of its arguments. Buffers can exist |
||||
in a great variety of configurations, hence some safety checks are usually |
||||
necessary in the function body. Below, you can see an basic example on how to |
||||
define a custom constructor for the Eigen double precision matrix |
||||
(``Eigen::MatrixXd``) type, which supports initialization from compatible |
||||
buffer |
||||
objects (e.g. a NumPy matrix). |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Eigen::MatrixXd>(m, "MatrixXd") |
||||
.def("__init__", [](Eigen::MatrixXd &m, py::buffer b) { |
||||
/* Request a buffer descriptor from Python */ |
||||
py::buffer_info info = b.request(); |
||||
|
||||
/* Some sanity checks ... */ |
||||
if (info.format != py::format_descriptor<double>::value()) |
||||
throw std::runtime_error("Incompatible format: expected a double array!"); |
||||
|
||||
if (info.ndim != 2) |
||||
throw std::runtime_error("Incompatible buffer dimension!"); |
||||
|
||||
if (info.strides[0] == sizeof(double)) { |
||||
/* Buffer has the right layout -- directly copy. */ |
||||
new (&m) Eigen::MatrixXd(info.shape[0], info.shape[1]); |
||||
memcpy(m.data(), info.ptr, sizeof(double) * m.size()); |
||||
} else { |
||||
/* Oops -- the buffer is transposed */ |
||||
new (&m) Eigen::MatrixXd(info.shape[1], info.shape[0]); |
||||
memcpy(m.data(), info.ptr, sizeof(double) * m.size()); |
||||
m.transposeInPlace(); |
||||
} |
||||
}); |
||||
|
||||
NumPy support |
||||
============= |
||||
|
||||
By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can |
||||
restrict the function so that it only accepts NumPy arrays (rather than any |
||||
type of Python object satisfying the buffer object protocol). |
||||
|
||||
In many situations, we want to define a function which only accepts a NumPy |
||||
array of a certain data type. This is possible via the ``py::array_dtype<T>`` |
||||
template. For instance, the following function requires the argument to be a |
||||
dense array of doubles in C-style ordering. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
void f(py::array_dtype<double> array); |
||||
|
||||
When it is invoked with a different type (e.g. an integer), the binding code |
||||
will attempt to cast the input into a NumPy array of the requested type. |
||||
Note that this feature requires the ``pybind/numpy.h`` header to be included. |
||||
|
||||
Vectorizing functions |
||||
===================== |
||||
|
||||
Suppose we want to bind a function with the following signature to Python so |
||||
that it can process arbitrary NumPy array arguments (vectors, matrices, general |
||||
N-D arrays) in addition to its normal arguments: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
double my_func(int x, float y, double z); |
||||
|
||||
After including the ``pybind/numpy.h`` header, this is extremely simple: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
m.def("vectorized_func", py::vectorize(my_func)); |
||||
|
||||
Invoking the function like below causes 4 calls to be made to ``my_func`` with |
||||
each of the the array elements. The result is returned as a NumPy array of type |
||||
``numpy.dtype.float64``. |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> x = np.array([[1, 3],[5, 7]]) |
||||
>>> y = np.array([[2, 4],[6, 8]]) |
||||
>>> z = 3 |
||||
>>> result = vectorized_func(x, y, z) |
||||
|
||||
The scalar argument ``z`` is transparently replicated 4 times. The input |
||||
arrays ``x`` and ``y`` are automatically converted into the right types (they |
||||
are of type ``numpy.dtype.int64`` but need to be ``numpy.dtype.int32`` and |
||||
``numpy.dtype.float32``, respectively) |
||||
|
||||
Sometimes we might want to explitly exclude an argument from the vectorization |
||||
because it makes little sense to wrap it in a NumPy array. For instance, |
||||
suppose the function signature was |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
double my_func(int x, float y, my_custom_type *z); |
||||
|
||||
This can be done with a stateful Lambda closure: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
// Vectorize a lambda function with a capture object (e.g. to exclude some arguments from the vectorization) |
||||
m.def("vectorized_func", |
||||
[](py::array_dtype<int> x, py::array_dtype<float> y, my_custom_type *z) { |
||||
auto stateful_closure = [z](int x, float y) { return my_func(x, y, z); }; |
||||
return py::vectorize(stateful_closure)(x, y); |
||||
} |
||||
); |
||||
|
||||
Throwing exceptions |
||||
=================== |
||||
|
||||
STL data structures |
||||
=================== |
||||
|
||||
Smart pointers |
||||
============== |
||||
|
||||
.. _custom_constructors: |
||||
|
||||
Custom constructors |
||||
=================== |
||||
@ -0,0 +1,263 @@
@@ -0,0 +1,263 @@
|
||||
.. _basics: |
||||
|
||||
First steps |
||||
########### |
||||
|
||||
This sections demonstrates the basic features of pybind11. Before getting |
||||
started, make sure that development environment is set up to compile the |
||||
included set of examples, which also double as test cases. |
||||
|
||||
|
||||
Compiling the test cases |
||||
======================== |
||||
|
||||
Linux/MacOS |
||||
----------- |
||||
|
||||
On Linux you'll need to install the **python-dev** or **python3-dev** packages as |
||||
well as **cmake**. On Mac OS, the included python version works out of the box, |
||||
but **cmake** must still be installed. |
||||
|
||||
After installing the prerequisites, run |
||||
|
||||
.. code-block:: bash |
||||
|
||||
cmake . |
||||
make -j 4 |
||||
|
||||
followed by |
||||
|
||||
.. code-block:: bash |
||||
|
||||
make test |
||||
|
||||
Windows |
||||
------- |
||||
|
||||
On Windows, use the `CMake GUI`_ to create a Visual Studio project. Note that |
||||
only the 2015 release and newer versions are supported since pybind11 relies on |
||||
various C++11 language features that break older versions of Visual Studio. |
||||
After running CMake, open the created :file:`pybind.sln` file and perform a |
||||
release build, which will will produce a file named |
||||
:file:`Release\\example.pyd`. Copy this file to the :file:`example` directory |
||||
and run :file:`example\\run_test.py` using the targeted Python version. |
||||
|
||||
.. _`CMake GUI`: https://cmake.org/runningcmake |
||||
|
||||
.. Note:: |
||||
|
||||
When all tests fail, make sure that |
||||
|
||||
1. The Python binary and the testcases are compiled for the same processor |
||||
type and bitness (i.e. either **i386** or **x86_64**) |
||||
|
||||
2. The Python binary used to run :file:`example\\run_test.py` matches the |
||||
Python version specified in the CMake GUI. This is controlled via |
||||
the ``PYTHON_EXECUTABLE`` ``PYTHON_INCLUDE_DIR``, and |
||||
``PYTHON_LIBRARY`` variables. |
||||
|
||||
.. seealso:: |
||||
|
||||
Advanced users who are already familiar with Boost.Python may want to skip |
||||
the tutorial and look at the test cases in the :file:`example` directory, |
||||
which exercise all features of pybind11. |
||||
|
||||
Creating bindings for a simple function |
||||
======================================= |
||||
|
||||
Let's start by creating Python bindings for an extremely simple function, which |
||||
adds two numbers and returns their result: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
int add(int i, int j) { |
||||
return i + j; |
||||
} |
||||
|
||||
For simplicity [#f1]_, we'll put both this function and the binding code into |
||||
a file named :file:`example.cpp` with the following contents: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
#include <pybind/pybind.h> |
||||
|
||||
int add(int i, int j) { |
||||
return i + j; |
||||
} |
||||
|
||||
namespace py = pybind; |
||||
|
||||
PYTHON_PLUGIN(example) { |
||||
py::module m("example", "pybind example plugin"); |
||||
|
||||
m.def("add", &add, "A function which adds two numbers"); |
||||
|
||||
return m.ptr(); |
||||
} |
||||
|
||||
The :func:`PYTHON_PLUGIN` macro creates a function that will be called when an |
||||
``import`` statement is issued from within Python. The next line creates a |
||||
module named ``example`` (with the supplied docstring). The method |
||||
:func:`module::def` generates binding code that exposes the |
||||
``add()`` function to Python. The last line returns the internal Python object |
||||
associated with ``m`` to the Python interpreter. |
||||
|
||||
.. note:: |
||||
|
||||
Notice how little code was needed to expose our function to Python: all |
||||
details regarding the function's parameters and return value were |
||||
automatically inferred using template metaprogramming. This overall |
||||
approach and the used syntax are borrowed from Boost.Python, though the |
||||
underlying implementation is very different. |
||||
|
||||
pybind11 is a header-only-library, hence it is not necessary to link against |
||||
any special libraries (other than Python itself). On Windows, use the CMake |
||||
build file discussed in section :ref:`cmake`. On Linux and Mac OS, the above |
||||
example can be compiled using the following command |
||||
|
||||
.. code-block:: bash |
||||
|
||||
$ c++ -O3 -shared -std=c++11 -I <path-to-pybind>/include `python-config --cflags --libs` example.cpp -o example.so |
||||
|
||||
In general, it is advisable to include several additional build parameters |
||||
that can considerably reduce the size of the created binary. Refer to section |
||||
:ref:`cmake` for a detailed example of a suitable cross-platform CMake-based |
||||
build system. |
||||
|
||||
Assuming that the created file :file:`example.so` (:file:`example.pyd` on Windows) |
||||
is located in the current directory, the following interactive Python session |
||||
shows how to load and execute the example. |
||||
|
||||
.. code-block:: python |
||||
|
||||
% python |
||||
Python 2.7.10 (default, Aug 22 2015, 20:33:39) |
||||
[GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin |
||||
Type "help", "copyright", "credits" or "license" for more information. |
||||
>>> import example |
||||
>>> example.add(1, 2) |
||||
3L |
||||
|
||||
.. _keyword_args: |
||||
|
||||
Keyword arguments |
||||
================= |
||||
|
||||
With a simple modification code, it is possible to inform Python about the |
||||
names of the arguments ("i" and "j" in this case). |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
m.def("add", &add, "A function which adds two numbers", |
||||
py::arg("i"), py::arg("j")); |
||||
|
||||
:class:`arg` is one of several special tag classes which can be used to pass |
||||
metadata into :func:`module::def`. With this modified binding code, we can now |
||||
call the function using keyword arguments, which is a more readable alternative |
||||
particularly for functions taking many parameters: |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> import example |
||||
>>> example.add(i=1, j=2) |
||||
3L |
||||
|
||||
The keyword names also appear in the function signatures within the documentation. |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> help(example) |
||||
|
||||
.... |
||||
|
||||
FUNCTIONS |
||||
add(...) |
||||
Signature : (i: int32_t, j: int32_t) -> int32_t |
||||
|
||||
A function which adds two numbers |
||||
|
||||
.. _default_args: |
||||
|
||||
Default arguments |
||||
================= |
||||
|
||||
Suppose now that the function to be bound has default arguments, e.g.: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
int add(int i = 1, int j = 2) { |
||||
return i + j; |
||||
} |
||||
|
||||
Unfortunately, pybind11 cannot automatically extract these parameters, since they |
||||
are not part of the function's type information. However, they are simple to specify |
||||
using an extension of :class:`arg`: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
m.def("add", &add, "A function which adds two numbers", |
||||
py::arg("i") = 1, py::arg("j") = 2); |
||||
|
||||
The default values also appear within the documentation. |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> help(example) |
||||
|
||||
.... |
||||
|
||||
FUNCTIONS |
||||
add(...) |
||||
Signature : (i: int32_t = 1L, j: int32_t = 2L) -> int32_t |
||||
|
||||
A function which adds two numbers |
||||
|
||||
.. _supported_types: |
||||
|
||||
Supported data types |
||||
==================== |
||||
|
||||
The following basic data types are supported out of the box (some may require |
||||
an additional extension header to be included). To pass other data structures |
||||
as arguments and return values, refer to the section on :ref:`classes`. |
||||
|
||||
+------------------------+--------------------------+---------------------+ |
||||
| Data type | Description | Header file | |
||||
+========================+==========================+=====================+ |
||||
| int8_t, uint8_t | 8-bit integers | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| int16_t, uint16_t | 16-bit integers | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| int32_t, uint32_t | 32-bit integers | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| int64_t, uint64_t | 64-bit integers | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| ssize_t, size_t | Platform-dependent size | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| float, double | Floating point types | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| bool | Two-state Boolean type | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| char | Character literal | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| const char * | UTF-8 string literal | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::string | STL dynamic UTF-8 string | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::pair<T1, T2> | Pair of two custom types | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::tuple<....> | Arbitrary tuple of types | pybind/pybind.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::complex<T> | Complex numbers | pybind/complex.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::vector<T> | STL dynamic array | pybind/stl.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::map<T1, T2> | STL dynamic maps | pybind/stl.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
| std::function<...> | STL polymorphic function | pybind/functional.h | |
||||
+------------------------+--------------------------+---------------------+ |
||||
|
||||
|
||||
.. [#f1] In practice, implementation and binding code will generally be located |
||||
in separate files. |
||||
|
||||
@ -0,0 +1,304 @@
@@ -0,0 +1,304 @@
|
||||
.. _classes: |
||||
|
||||
Object-oriented code |
||||
#################### |
||||
|
||||
Creating bindings for a custom type |
||||
=================================== |
||||
|
||||
Let's now look at a more complex example where we'll create bindings for a |
||||
custom C++ data structure named ``Pet``. Its definition is given below: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
struct Pet { |
||||
Pet(const std::string &name) : name(name) { } |
||||
void setName(const std::string &name_) { name = name_; } |
||||
const std::string &getName() const { return name; } |
||||
|
||||
std::string name; |
||||
}; |
||||
|
||||
The binding code for ``Pet`` looks as follows: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
#include <pybind/pybind.h> |
||||
|
||||
namespace py = pybind; |
||||
|
||||
PYTHON_PLUGIN(example) { |
||||
py::module m("example", "pybind example plugin"); |
||||
|
||||
py::class_<Pet>(m, "Pet") |
||||
.def(py::init<const std::string &>()) |
||||
.def("setName", &Pet::setName) |
||||
.def("getName", &Pet::getName); |
||||
|
||||
return m.ptr(); |
||||
} |
||||
|
||||
:class:`class_` creates bindings for a C++ `class` or `struct`-style data |
||||
structure. :func:`init` is a convenience function that takes the types of a |
||||
constructor's parameters as template arguments and wraps the corresponding |
||||
constructor (see the :ref:`custom_constructors` section for details). An |
||||
interactive Python session demonstrating this example is shown below: |
||||
|
||||
.. code-block:: python |
||||
|
||||
% python |
||||
>>> import example |
||||
>>> p = example.Pet('Molly') |
||||
>>> print(p) |
||||
<example.Pet object at 0x10cd98060> |
||||
>>> p.getName() |
||||
u'Molly' |
||||
>>> p.setName('Charly') |
||||
>>> p.getName() |
||||
u'Charly' |
||||
|
||||
Keyword and default arguments |
||||
============================= |
||||
It is possible to specify keyword and default arguments using the syntax |
||||
discussed in the previous chapter. Refer to the sections :ref:`keyword_args` |
||||
and :ref:`default_args` for details. |
||||
|
||||
Binding lambda functions |
||||
======================== |
||||
|
||||
Note how ``print(p)`` produced a rather useless summary of our data structure in the example above: |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> print(p) |
||||
<example.Pet object at 0x10cd98060> |
||||
|
||||
To address this, we could bind an utility function that returns a human-readable |
||||
summary to the special method slot named ``__repr__``. Unfortunately, there is no |
||||
suitable functionality in the ``Pet`` data structure, and it would be nice if |
||||
we did not have to change it. This can easily be accomplished by binding a |
||||
Lambda function instead: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Pet>(m, "Pet") |
||||
.def(py::init<const std::string &>()) |
||||
.def("setName", &Pet::setName) |
||||
.def("getName", &Pet::getName) |
||||
.def("__repr__", |
||||
[](const Pet &a) { |
||||
return "<example.Pet named '" + a.name + "'>"; |
||||
} |
||||
); |
||||
|
||||
Both stateless [#f1]_ and stateful lambda closures are supported by pybind11. |
||||
With the above change, the same Python code now produces the following output: |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> print(p) |
||||
<example.Pet named 'Molly'> |
||||
|
||||
Instance and static fields |
||||
========================== |
||||
|
||||
We can also directly expose the ``name`` field using the |
||||
:func:`class_::def_readwrite` method. A similar :func:`class_::def_readonly` |
||||
method also exists for ``const`` fields. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Pet>(m, "Pet") |
||||
.def(py::init<const std::string &>()) |
||||
.def_readwrite("name", &Pet::name) |
||||
// ... remainder ... |
||||
|
||||
This makes it possible to write |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> p = example.Pet('Molly') |
||||
>>> p.name |
||||
u'Molly' |
||||
>>> p.name = 'Charly' |
||||
>>> p.name |
||||
u'Charly' |
||||
|
||||
Now suppose that ``Pet::name`` was a private internal variable |
||||
that can only be accessed via setters and getters. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
class Pet { |
||||
public: |
||||
Pet(const std::string &name) : name(name) { } |
||||
void setName(const std::string &name_) { name = name_; } |
||||
const std::string &getName() const { return name; } |
||||
private: |
||||
std::string name; |
||||
}; |
||||
|
||||
In this case, the method :func:`class_::def_property` |
||||
(:func:`class_::def_property_readonly` for read-only data) can be used to |
||||
provide an interface that is indistinguishable from within Python: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Pet>(m, "Pet") |
||||
.def(py::init<const std::string &>()) |
||||
.def_property("name", &Pet::getName, &Pet::setName) |
||||
// ... remainder ... |
||||
|
||||
.. seealso:: |
||||
|
||||
Similar functions :func:`class_::def_readwrite_static`, |
||||
:func:`class_::def_readonly_static` :func:`class_::def_property_static`, |
||||
and :func:`class_::def_property_readonly_static` are provided for binding |
||||
static variables and properties. |
||||
|
||||
Inheritance |
||||
=========== |
||||
|
||||
Suppose now that the example consists of two data structures with an |
||||
inheritance relationship: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
struct Pet { |
||||
Pet(const std::string &name) : name(name) { } |
||||
std::string name; |
||||
}; |
||||
|
||||
struct Dog : Pet { |
||||
Dog(const std::string &name) : Pet(name) { } |
||||
std::string bark() const { return "woof!"; } |
||||
}; |
||||
|
||||
To capture the hierarchical relationship in pybind11, we must assign a name to |
||||
the ``Pet`` :class:`class_` instance and reference it when binding the ``Dog`` |
||||
class. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Pet> pet(m, "Pet"); |
||||
pet.def(py::init<const std::string &>()) |
||||
.def_readwrite("name", &Pet::name); |
||||
|
||||
py::class_<Dog>(m, "Dog", pet /* <- specify parent */) |
||||
.def(py::init<const std::string &>()) |
||||
.def("bark", &Dog::bark); |
||||
|
||||
Instances then expose fields and methods of both types: |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> p = example.Dog('Molly') |
||||
>>> p.name |
||||
u'Molly' |
||||
>>> p.bark() |
||||
u'woof!' |
||||
|
||||
Overloaded methods |
||||
================== |
||||
|
||||
Sometimes there are several overloaded C++ methods with the same name taking |
||||
different kinds of input arguments: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
struct Pet { |
||||
Pet(const std::string &name, int age) : name(name), age(age) { } |
||||
|
||||
void set(int age) { age = age; } |
||||
void set(const std::string &name) { name = name; } |
||||
|
||||
std::string name; |
||||
int age; |
||||
}; |
||||
|
||||
Attempting to bind ``Pet::set`` will cause an error since the compiler does not |
||||
know which method the user intended to select. We can disambiguate by casting |
||||
them to function pointers. Binding multiple functions to the same Python name |
||||
automatically creates a chain of fucnction overloads that will be tried in |
||||
sequence. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Pet>(m, "Pet") |
||||
.def(py::init<const std::string &, int>()) |
||||
.def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age") |
||||
.def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name"); |
||||
|
||||
The overload signatures are also visible in the method's docstring: |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> help(example.Pet) |
||||
|
||||
class Pet(__builtin__.object) |
||||
| Methods defined here: |
||||
| |
||||
| __init__(...) |
||||
| Signature : (Pet, str, int32_t) -> None |
||||
| |
||||
| set(...) |
||||
| 1. Signature : (Pet, int32_t) -> None |
||||
| |
||||
| Set the pet's age |
||||
| |
||||
| 2. Signature : (Pet, str) -> None |
||||
| |
||||
| Set the pet's name |
||||
| |
||||
|
||||
Enumerations and internal types |
||||
=============================== |
||||
|
||||
Let's now suppose that the example class also contains an internal enumeration |
||||
type. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
struct Pet { |
||||
enum Kind { |
||||
Dog = 0, |
||||
Cat |
||||
}; |
||||
|
||||
Pet(const std::string &name, Kind type) : name(name), type(type) { } |
||||
|
||||
std::string name; |
||||
Kind type; |
||||
}; |
||||
|
||||
The binding code for this example looks as follows: |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
py::class_<Pet> pet(m, "Pet"); |
||||
|
||||
pet.def(py::init<const std::string &, Pet::Kind>()) |
||||
.def_readwrite("name", &Pet::name) |
||||
.def_readwrite("type", &Pet::type); |
||||
|
||||
py::enum_<Pet::Kind>(pet, "Kind") |
||||
.value("Dog", Pet::Kind::Dog) |
||||
.value("Cat", Pet::Kind::Cat) |
||||
.export_values(); |
||||
|
||||
To ensure that the ``Kind`` type is created within the scope of ``Pet``, the |
||||
``pet`` :class:`class_` instance must be supplied to the :class:`enum_`. |
||||
constructor. The :func:`enum_::export_values` function ensures that the enum |
||||
entries are exported into the parent scope; skip this call for new C++11-style |
||||
strongly typed enums. |
||||
|
||||
.. code-block:: python |
||||
|
||||
>>> p = Pet('Lucy', Pet.Cat) |
||||
>>> p.type |
||||
Kind.Cat |
||||
>>> int(p.type) |
||||
1L |
||||
|
||||
|
||||
.. [#f1] (those with an empty pair of brackets ``[]`` as the capture object) |
||||
@ -0,0 +1,102 @@
@@ -0,0 +1,102 @@
|
||||
.. _cmake: |
||||
|
||||
Building with CMake |
||||
=================== |
||||
|
||||
The following snippet should be a good starting point to create bindings across |
||||
platforms. It assumes that the code is located in a file named :file:`example.cpp`, |
||||
and that the pybind11 repository is located in a subdirectory named :file:`pybind11`. |
||||
|
||||
.. code-block:: cmake |
||||
|
||||
cmake_minimum_required(VERSION 2.8) |
||||
|
||||
project(example) |
||||
|
||||
# Add a CMake parameter for choosing a desired Python version |
||||
set(EXAMPLE_PYTHON_VERSION "" CACHE STRING "Python version to use for compiling the example library") |
||||
|
||||
# Set a default build configuration if none is specified. 'MinSizeRel' produces the smallest binaries |
||||
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) |
||||
message(STATUS "Setting build type to 'MinSizeRel' as none was specified.") |
||||
set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Choose the type of build." FORCE) |
||||
set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" |
||||
"MinSizeRel" "RelWithDebInfo") |
||||
endif() |
||||
string(TOUPPER "${CMAKE_BUILD_TYPE}" U_CMAKE_BUILD_TYPE) |
||||
|
||||
# Try to autodetect Python (can be overridden manually if needed) |
||||
set(Python_ADDITIONAL_VERSIONS 3.4 3.5 3.6) |
||||
find_package(PythonLibs ${EXAMPLE_PYTHON_VERSION} REQUIRED) |
||||
|
||||
if (UNIX) |
||||
# Enable C++11 mode |
||||
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11") |
||||
|
||||
# Enable link time optimization and set the default symbol |
||||
# visibility to hidden (very important to obtain small binaries) |
||||
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) |
||||
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility=hidden -flto") |
||||
endif() |
||||
endif() |
||||
|
||||
# Include path for Python header files |
||||
include_directories(${PYTHON_INCLUDE_DIR}) |
||||
|
||||
# Include path for pybind11 header files -- this may need to be changed depending on your setup |
||||
include_directories(${PROJECT_SOURCE_DIR}/pybind11/include) |
||||
|
||||
# Create the binding library |
||||
add_library(example SHARED |
||||
example.cpp |
||||
# ... extra files go here ... |
||||
) |
||||
|
||||
# Don't add a 'lib' prefix to the shared library |
||||
set_target_properties(example PROPERTIES PREFIX "") |
||||
|
||||
if (WIN32) |
||||
if (MSVC) |
||||
# Enforce size-based optimization and link time code generation |
||||
# on MSVC (~30% smaller binaries in experiments). /bigobj is needed |
||||
# for bigger binding projects due to the limit to 64k addressable sections |
||||
# /MP enables multithreaded builds (relevant when there are many files). |
||||
set_target_properties(example PROPERTIES COMPILE_FLAGS "/Os /GL /MP /bigobj") |
||||
set_target_properties(example PROPERTIES LINK_FLAGS "/LTCG") |
||||
endif() |
||||
|
||||
# .PYD file extension on Windows |
||||
set_target_properties(example PROPERTIES SUFFIX ".pyd") |
||||
|
||||
# Link against the Python shared library |
||||
target_link_libraries(example ${PYTHON_LIBRARY}) |
||||
elseif (UNIX) |
||||
# It's quite common to have multiple copies of the same Python version |
||||
# installed on one's system. E.g.: one copy from the OS and another copy |
||||
# that's statically linked into an application like Blender or Maya. |
||||
# If we link our plugin library against the OS Python here and import it |
||||
# into Blender or Maya later on, this will cause segfaults when multiple |
||||
# conflicting Python instances are active at the same time. |
||||
|
||||
# Windows is not affected by this issue since it handles DLL imports |
||||
# differently. The solution for Linux and Mac OS is simple: we just don't |
||||
# link against the Python library. The resulting shared library will have |
||||
# missing symbols, but that's perfectly fine -- they will be resolved at |
||||
# import time. |
||||
|
||||
# .SO file extension on Linux/Mac OS |
||||
set_target_properties(example PROPERTIES SUFFIX ".so") |
||||
|
||||
# Strip unnecessary sections of the binary on Linux/Mac OS |
||||
if(APPLE) |
||||
set_target_properties(example PROPERTIES MACOSX_RPATH ".") |
||||
set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup -dead_strip") |
||||
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) |
||||
add_custom_command(TARGET example POST_BUILD COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so) |
||||
endif() |
||||
else() |
||||
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) |
||||
add_custom_command(TARGET example POST_BUILD COMMAND strip ${PROJECT_BINARY_DIR}/example.so) |
||||
endif() |
||||
endif() |
||||
endif() |
||||
@ -0,0 +1,308 @@
@@ -0,0 +1,308 @@
|
||||
#!/usr/bin/env python3 |
||||
# -*- coding: utf-8 -*- |
||||
# |
||||
# pybind11 documentation build configuration file, created by |
||||
# sphinx-quickstart on Sun Oct 11 19:23:48 2015. |
||||
# |
||||
# This file is execfile()d with the current directory set to its |
||||
# containing dir. |
||||
# |
||||
# Note that not all possible configuration values are present in this |
||||
# autogenerated file. |
||||
# |
||||
# All configuration values have a default; values that are commented out |
||||
# serve to show the default. |
||||
|
||||
import sys |
||||
import os |
||||
import shlex |
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory, |
||||
# add these directories to sys.path here. If the directory is relative to the |
||||
# documentation root, use os.path.abspath to make it absolute, like shown here. |
||||
#sys.path.insert(0, os.path.abspath('.')) |
||||
|
||||
# -- General configuration ------------------------------------------------ |
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here. |
||||
#needs_sphinx = '1.0' |
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be |
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom |
||||
# ones. |
||||
extensions = [] |
||||
|
||||
# Add any paths that contain templates here, relative to this directory. |
||||
templates_path = ['.templates'] |
||||
|
||||
# The suffix(es) of source filenames. |
||||
# You can specify multiple suffix as a list of string: |
||||
# source_suffix = ['.rst', '.md'] |
||||
source_suffix = '.rst' |
||||
|
||||
# The encoding of source files. |
||||
#source_encoding = 'utf-8-sig' |
||||
|
||||
# The master toctree document. |
||||
master_doc = 'index' |
||||
|
||||
# General information about the project. |
||||
project = 'pybind11' |
||||
copyright = '2015, Wenzel Jakob' |
||||
author = 'Wenzel Jakob' |
||||
|
||||
# The version info for the project you're documenting, acts as replacement for |
||||
# |version| and |release|, also used in various other places throughout the |
||||
# built documents. |
||||
# |
||||
# The short X.Y version. |
||||
version = '1.0' |
||||
# The full version, including alpha/beta/rc tags. |
||||
release = '1.0' |
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation |
||||
# for a list of supported languages. |
||||
# |
||||
# This is also used if you do content translation via gettext catalogs. |
||||
# Usually you set "language" from the command line for these cases. |
||||
language = None |
||||
|
||||
# There are two options for replacing |today|: either, you set today to some |
||||
# non-false value, then it is used: |
||||
#today = '' |
||||
# Else, today_fmt is used as the format for a strftime call. |
||||
#today_fmt = '%B %d, %Y' |
||||
|
||||
# List of patterns, relative to source directory, that match files and |
||||
# directories to ignore when looking for source files. |
||||
exclude_patterns = ['.build'] |
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all |
||||
# documents. |
||||
#default_role = None |
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text. |
||||
#add_function_parentheses = True |
||||
|
||||
# If true, the current module name will be prepended to all description |
||||
# unit titles (such as .. function::). |
||||
#add_module_names = True |
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the |
||||
# output. They are ignored by default. |
||||
#show_authors = False |
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use. |
||||
#pygments_style = 'monokai' |
||||
|
||||
# A list of ignored prefixes for module index sorting. |
||||
#modindex_common_prefix = [] |
||||
|
||||
# If true, keep warnings as "system message" paragraphs in the built documents. |
||||
#keep_warnings = False |
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing. |
||||
todo_include_todos = False |
||||
|
||||
|
||||
# -- Options for HTML output ---------------------------------------------- |
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for |
||||
# a list of builtin themes. |
||||
|
||||
on_rtd = os.environ.get('READTHEDOCS', None) == 'True' |
||||
|
||||
if not on_rtd: # only import and set the theme if we're building docs locally |
||||
import sphinx_rtd_theme |
||||
html_theme = 'sphinx_rtd_theme' |
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] |
||||
|
||||
#import alabaster |
||||
|
||||
#html_theme_path = [alabaster.get_path()] |
||||
#extensions = ['alabaster'] |
||||
#html_theme = 'alabaster' |
||||
#html_sidebars = { |
||||
#'**': [ |
||||
#'about.html', |
||||
#'navigation.html', |
||||
#'relations.html', |
||||
#'searchbox.html' |
||||
#] |
||||
#} |
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme |
||||
# further. For a list of options available for each theme, see the |
||||
# documentation. |
||||
#html_theme_options = {} |
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory. |
||||
#html_theme_path = [] |
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to |
||||
# "<project> v<release> documentation". |
||||
#html_title = None |
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title. |
||||
#html_short_title = None |
||||
|
||||
# The name of an image file (relative to this directory) to place at the top |
||||
# of the sidebar. |
||||
#html_logo = None |
||||
|
||||
# The name of an image file (within the static path) to use as favicon of the |
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
||||
# pixels large. |
||||
#html_favicon = None |
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here, |
||||
# relative to this directory. They are copied after the builtin static files, |
||||
# so a file named "default.css" will overwrite the builtin "default.css". |
||||
html_static_path = ['.static'] |
||||
|
||||
# Add any extra paths that contain custom files (such as robots.txt or |
||||
# .htaccess) here, relative to this directory. These files are copied |
||||
# directly to the root of the documentation. |
||||
#html_extra_path = [] |
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
||||
# using the given strftime format. |
||||
#html_last_updated_fmt = '%b %d, %Y' |
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to |
||||
# typographically correct entities. |
||||
#html_use_smartypants = True |
||||
|
||||
# Custom sidebar templates, maps document names to template names. |
||||
#html_sidebars = {} |
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to |
||||
# template names. |
||||
#html_additional_pages = {} |
||||
|
||||
# If false, no module index is generated. |
||||
#html_domain_indices = True |
||||
|
||||
# If false, no index is generated. |
||||
#html_use_index = True |
||||
|
||||
# If true, the index is split into individual pages for each letter. |
||||
#html_split_index = False |
||||
|
||||
# If true, links to the reST sources are added to the pages. |
||||
#html_show_sourcelink = True |
||||
|
||||
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. |
||||
#html_show_sphinx = True |
||||
|
||||
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. |
||||
#html_show_copyright = True |
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will |
||||
# contain a <link> tag referring to it. The value of this option must be the |
||||
# base URL from which the finished HTML is served. |
||||
#html_use_opensearch = '' |
||||
|
||||
# This is the file name suffix for HTML files (e.g. ".xhtml"). |
||||
#html_file_suffix = None |
||||
|
||||
# Language to be used for generating the HTML full-text search index. |
||||
# Sphinx supports the following languages: |
||||
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' |
||||
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' |
||||
#html_search_language = 'en' |
||||
|
||||
# A dictionary with options for the search language support, empty by default. |
||||
# Now only 'ja' uses this config value |
||||
#html_search_options = {'type': 'default'} |
||||
|
||||
# The name of a javascript file (relative to the configuration directory) that |
||||
# implements a search results scorer. If empty, the default will be used. |
||||
#html_search_scorer = 'scorer.js' |
||||
|
||||
# Output file base name for HTML help builder. |
||||
htmlhelp_basename = 'pybind11doc' |
||||
|
||||
# -- Options for LaTeX output --------------------------------------------- |
||||
|
||||
latex_elements = { |
||||
# The paper size ('letterpaper' or 'a4paper'). |
||||
#'papersize': 'letterpaper', |
||||
|
||||
# The font size ('10pt', '11pt' or '12pt'). |
||||
#'pointsize': '10pt', |
||||
|
||||
# Additional stuff for the LaTeX preamble. |
||||
#'preamble': '', |
||||
|
||||
# Latex figure (float) alignment |
||||
#'figure_align': 'htbp', |
||||
} |
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples |
||||
# (source start file, target name, title, |
||||
# author, documentclass [howto, manual, or own class]). |
||||
latex_documents = [ |
||||
(master_doc, 'pybind11.tex', 'pybind11 Documentation', |
||||
'Wenzel Jakob', 'manual'), |
||||
] |
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of |
||||
# the title page. |
||||
#latex_logo = None |
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts, |
||||
# not chapters. |
||||
#latex_use_parts = False |
||||
|
||||
# If true, show page references after internal links. |
||||
#latex_show_pagerefs = False |
||||
|
||||
# If true, show URL addresses after external links. |
||||
#latex_show_urls = False |
||||
|
||||
# Documents to append as an appendix to all manuals. |
||||
#latex_appendices = [] |
||||
|
||||
# If false, no module index is generated. |
||||
#latex_domain_indices = True |
||||
|
||||
|
||||
# -- Options for manual page output --------------------------------------- |
||||
|
||||
# One entry per manual page. List of tuples |
||||
# (source start file, name, description, authors, manual section). |
||||
man_pages = [ |
||||
(master_doc, 'pybind11', 'pybind11 Documentation', |
||||
[author], 1) |
||||
] |
||||
|
||||
# If true, show URL addresses after external links. |
||||
#man_show_urls = False |
||||
|
||||
|
||||
# -- Options for Texinfo output ------------------------------------------- |
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples |
||||
# (source start file, target name, title, author, |
||||
# dir menu entry, description, category) |
||||
texinfo_documents = [ |
||||
(master_doc, 'pybind11', 'pybind11 Documentation', |
||||
author, 'pybind11', 'One line description of project.', |
||||
'Miscellaneous'), |
||||
] |
||||
|
||||
# Documents to append as an appendix to all manuals. |
||||
#texinfo_appendices = [] |
||||
|
||||
# If false, no module index is generated. |
||||
#texinfo_domain_indices = True |
||||
|
||||
# How to display URL addresses: 'footnote', 'no', or 'inline'. |
||||
#texinfo_show_urls = 'footnote' |
||||
|
||||
# If true, do not generate a @detailmenu in the "Top" node's menu. |
||||
#texinfo_no_detailmenu = False |
||||
|
||||
primary_domain = 'cpp' |
||||
highlight_language = 'cpp' |
||||
@ -0,0 +1,15 @@
@@ -0,0 +1,15 @@
|
||||
Welcome to pybind11's documentation! |
||||
==================================== |
||||
|
||||
|
||||
Contents: |
||||
|
||||
.. toctree:: |
||||
:maxdepth: 2 |
||||
|
||||
intro |
||||
basics |
||||
classes |
||||
advanced |
||||
cmake |
||||
reference |
||||
@ -0,0 +1,62 @@
@@ -0,0 +1,62 @@
|
||||
About this project |
||||
================== |
||||
**pybind11** is a lightweight header 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. The whole |
||||
codebase requires less than 3000 lines of code and only depends 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 (tuples, lambda functions and |
||||
variadic templates). |
||||
|
||||
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 |
||||
- Exceptions |
||||
- Enumerations |
||||
- Callbacks |
||||
- Custom operators |
||||
- 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: |
||||
|
||||
- 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. |
||||
|
||||
@ -0,0 +1,232 @@
@@ -0,0 +1,232 @@
|
||||
.. _reference: |
||||
|
||||
Reference |
||||
######### |
||||
|
||||
Macros |
||||
====== |
||||
|
||||
.. function:: PYTHON_PLUGIN(const char *name) |
||||
|
||||
This macro creates the entry point that will be invoked when the Python |
||||
interpreter imports a plugin library. Please create a |
||||
:class:`module` in the function body and return the pointer to its |
||||
underlying Python object at the end. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
PYTHON_PLUGIN(example) { |
||||
pybind::module m("example", "pybind example plugin"); |
||||
/// Set up bindings here |
||||
return m.ptr(); |
||||
} |
||||
|
||||
.. _core_types: |
||||
|
||||
Convenience classes for arbitrary Python types |
||||
============================================== |
||||
|
||||
Without reference counting |
||||
-------------------------- |
||||
|
||||
.. class:: handle |
||||
|
||||
The :class:`handle` class is a thin wrapper around an arbitrary Python |
||||
object (i.e. a ``PyObject *`` in Python's C API). It does not perform any |
||||
automatic reference counting and merely provides a basic C++ interface to |
||||
various Python API functions. |
||||
|
||||
.. seealso:: |
||||
|
||||
The :class:`object` class inherits from :class:`handle` and adds automatic |
||||
reference counting features. |
||||
|
||||
.. function:: handle::handle() |
||||
|
||||
The default constructor creates a handle with a ``nullptr``-valued pointer. |
||||
|
||||
.. function:: handle::handle(const handle&) |
||||
|
||||
Copy constructor |
||||
|
||||
.. function:: handle::handle(PyObject *) |
||||
|
||||
Creates a :class:`handle` from the given raw Python object pointer. |
||||
|
||||
.. function:: PyObject * handle::ptr() |
||||
|
||||
Return the ``PyObject *`` underlying a :class:`handle`. |
||||
|
||||
.. function:: void handle::inc_ref() |
||||
|
||||
Manually increase the reference count of the Python object. Usually, it is |
||||
preferable to use the :class:`object` class which derives from |
||||
:class:`handle` and calls this function automatically. |
||||
|
||||
.. function:: void handle::dec_ref() |
||||
|
||||
Manually decrease the reference count of the Python object. Usually, it is |
||||
preferable to use the :class:`object` class which derives from |
||||
:class:`handle` and calls this function automatically. |
||||
|
||||
.. function:: void handle::ref_count() |
||||
|
||||
Return the object's current reference count |
||||
|
||||
.. function:: handle handle::get_type() |
||||
|
||||
Return a handle to the Python type object underlying the instance |
||||
|
||||
.. function detail::accessor handle::operator[](handle key) |
||||
|
||||
Return an internal functor to invoke the object's sequence protocol. |
||||
Casting the returned ``detail::accessor`` instance to a :class:`handle` or |
||||
:class:`object` subclass causes a corresponding call to ``__getitem__``. |
||||
Assigning a :class:`handle` or :class:`object` subclass causes a call to |
||||
``__setitem__``. |
||||
|
||||
.. function detail::accessor handle::operator[](const char *key) |
||||
|
||||
See the above function (the only difference is that they key is provided as |
||||
a string literal). |
||||
|
||||
.. function detail::accessor handle::attr(handle key) |
||||
|
||||
Return an internal functor to access the object's attributes. |
||||
Casting the returned ``detail::accessor`` instance to a :class:`handle` or |
||||
:class:`object` subclass causes a corresponding call to ``__getattr``. |
||||
Assigning a :class:`handle` or :class:`object` subclass causes a call to |
||||
``__setattr``. |
||||
|
||||
.. function detail::accessor handle::attr(const char *key) |
||||
|
||||
See the above function (the only difference is that they key is provided as |
||||
a string literal). |
||||
|
||||
.. function operator handle::bool() const |
||||
|
||||
Return ``true`` when the :class:`handle` wraps a valid Python object. |
||||
|
||||
.. function str handle::str() const |
||||
|
||||
Return a string representation of the object. This is analogous to |
||||
the ``str()`` function in Python. |
||||
|
||||
.. function:: template <typename T> T handle::cast() |
||||
|
||||
Attempt to cast the Python object into the given C++ type. A |
||||
:class:`cast_error` will be throw upon failure. |
||||
|
||||
.. function:: template <typename ... Args> object handle::call(Args&&... args) |
||||
|
||||
Assuming the Python object is a function or implements the ``__call__`` |
||||
protocol, ``call()`` invokes the underlying function, passing an arbitrary |
||||
set of parameters. The result is returned as a :class:`object` and may need |
||||
to be converted back into a Python object using :func:`template <typename T> handle::cast`. |
||||
|
||||
When some of the arguments cannot be converted to Python objects, the |
||||
function will throw a :class:`cast_error` exception. When the Python |
||||
function call fails, a :class:`error_already_set` exception is thrown. |
||||
|
||||
With reference counting |
||||
----------------------- |
||||
|
||||
.. class:: object : public handle |
||||
|
||||
Like :class:`handle`, the object class is a thin wrapper around an |
||||
arbitrary Python object (i.e. a ``PyObject *`` in Python's C API). In |
||||
contrast to :class:`handle`, it optionally increases the object's reference |
||||
count upon construction, and it *always* decreases the reference count when |
||||
the :class:`object` instance goes out of scope and is destructed. When |
||||
using :class:`object` instances consistently, it is much easier to get |
||||
reference counting right at the first attempt. |
||||
|
||||
.. function:: object::object(const object &o) |
||||
|
||||
Copy constructor; always increases the reference count |
||||
|
||||
.. function:: object::object(const handle &h, bool borrowed) |
||||
|
||||
Creates a :class:`object` from the given :class:`handle`. The reference |
||||
count is only increased if the ``borrowed`` parameter is set to ``true``. |
||||
|
||||
.. function:: object::object(PyObject *ptr, bool borrowed) |
||||
|
||||
Creates a :class:`object` from the given raw Python object pointer. The |
||||
reference count is only increased if the ``borrowed`` parameter is set to |
||||
``true``. |
||||
|
||||
.. function:: object::object(object &&other) |
||||
|
||||
Move constructor; steals the object from ``other`` and preserves its |
||||
reference count. |
||||
|
||||
.. function:: object::~object() |
||||
|
||||
Constructor, which automatically calls :func:`handle::dec_ref()`. |
||||
|
||||
Convenience classes for specific Python types |
||||
============================================= |
||||
|
||||
|
||||
.. class:: module : public object |
||||
|
||||
.. function:: module::module(const char *name, const char *doc = nullptr) |
||||
|
||||
Create a new top-level Python module with the given name and docstring |
||||
|
||||
.. function:: module module::def_submodule(const char *name, const char *doc = nullptr) |
||||
|
||||
Create and return a new Python submodule with the given name and docstring. |
||||
This also works recursively, i.e. |
||||
|
||||
.. code-block:: cpp |
||||
|
||||
pybind::module m("example", "pybind example plugin"); |
||||
pybind::module m2 = m.def_submodule("sub", "A submodule of 'example'"); |
||||
pybind::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'"); |
||||
|
||||
.. cpp:function:: template <typename Func, typename ... Extra> module& module::def(const char *name, Func && f, Extra && ... extra) |
||||
|
||||
Create Python binding for a new function within the module scope. ``Func`` |
||||
can be a plain C++ function, a function pointer, or a lambda function. For |
||||
details on the ``Extra&& ... extra`` argument, see section :ref:`extras`. |
||||
|
||||
.. _extras: |
||||
|
||||
Passing extra arguments to the def function |
||||
=========================================== |
||||
|
||||
.. class:: arg |
||||
|
||||
.. function:: arg::arg(const char *name) |
||||
|
||||
.. function:: template <typename T> arg_t<T> arg::operator=(const T &value) |
||||
|
||||
.. class:: template <typename T> arg_t<T> : public arg |
||||
|
||||
Represents a named argument with a default value |
||||
|
||||
.. class:: sibling |
||||
|
||||
Used to specify a handle to an existing sibling function; used internally |
||||
to implement function overloading in :func:`module::def` and |
||||
:func:`class_::def`. |
||||
|
||||
.. function:: sibling::sibling(handle handle) |
||||
|
||||
.. class doc |
||||
|
||||
This is class is internally used by pybind11. |
||||
|
||||
.. function:: doc::doc(const char *value) |
||||
|
||||
Create a new docstring with the specified value |
||||
|
||||
.. class name |
||||
|
||||
This is class is internally used by pybind11. |
||||
|
||||
.. function:: name::name(const char *value) |
||||
|
||||
Used to specify the function name |
||||
Loading…
Reference in new issue