From 28f98aa298db65b781935bc5ead13c3558ee5aaf Mon Sep 17 00:00:00 2001 From: Wenzel Jakob Date: Tue, 13 Oct 2015 02:57:16 +0200 Subject: [PATCH] took a stab at some documentation --- README.md | 211 +++---------------------------- docs/Makefile | 192 ++++++++++++++++++++++++++++ docs/advanced.rst | 202 +++++++++++++++++++++++++++++ docs/basics.rst | 263 ++++++++++++++++++++++++++++++++++++++ docs/classes.rst | 304 ++++++++++++++++++++++++++++++++++++++++++++ docs/cmake.rst | 102 +++++++++++++++ docs/conf.py | 308 +++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 15 +++ docs/intro.rst | 62 +++++++++ docs/reference.rst | 232 ++++++++++++++++++++++++++++++++++ 10 files changed, 1694 insertions(+), 197 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/advanced.rst create mode 100644 docs/basics.rst create mode 100644 docs/classes.rst create mode 100644 docs/cmake.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/intro.rst create mode 100644 docs/reference.rst diff --git a/README.md b/README.md index 0bdc1a05b..21bdfc3fc 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ # pybind11 — Seamless operability between C++11 and Python [![Build Status](https://travis-ci.org/wjakob/pybind11.svg?branch=master)](https://travis-ci.org/wjakob/pybind11) +[![Documentation Status](https://readthedocs.org/projects/pybind11/badge/?version=latest)](http://pybind11.readthedocs.org/en/latest/?badge=latest) **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 @@ -24,10 +25,15 @@ 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). +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/latest](http://pybind11.readthedocs.org/en/latest). ## Core features -The following core C++ features can be mapped 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 @@ -45,6 +51,12 @@ The following core C++ features can be mapped to Python ## Goodies In addition to the core functionality, pybind11 provides some extra goodies: +- pybind11 uses C++11 move constructors and move assignment operators whenever + possible to efficiently transfer custom data types. + +- It is possible to bind C++11 lambda functions with captured variables. The + lambda capture data is stored inside the resulting Python function object. + - 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. @@ -55,199 +67,4 @@ In addition to the core functionality, pybind11 provides some extra goodies: - Python's slice-based access and assignment operations can be supported with just a few lines of code. -- pybind11 uses C++11 move constructors and move assignment operators whenever - possible to efficiently transfer custom data types. -- It is possible to bind C++11 lambda functions with captured variables. The - lambda capture data is stored inside the resulting Python function object. - -## What does the binding code look like? -Here is a simple example. The directory `example` contains many more. -```C++ -#include -#include - -namespace py = pybind; - -/// Example C++ class which should be bound to Python -class Test { -public: - Test(); - Test(int value); - std::string toString(); - Test operator+(const Test &e) const; - - void print_dict(py::dict dict) { - /* Easily interact with Python types */ - for (auto item : dict) - std::cout << "key=" << item.first << ", " - << "value=" << item.second << std::endl; - } - - int value = 0; -}; - - -PYTHON_PLUGIN(example) { - py::module m("example", "pybind example plugin"); - - py::class_(m, "Test", "docstring for the Test class") - .def(py::init<>(), "docstring for constructor 1") - .def(py::init(), "docstring for constructor 2") - .def(py::self + py::self, "Addition operator") - .def("__str__", &Test::toString, "Convert to a string representation") - .def("print_dict", &Test::print_dict, "Print a Python dictionary") - .def_readwrite("value", &Test::value, "An instance attribute"); - - return m.ptr(); -} -``` - -## A collection of specific use cases (mostly buffer-related for now) -For brevity, let's set -```C++ -namespace py = pybind; -``` -### Exposing buffer views -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: - -```C++ -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)``. -```C++ -py::class_(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::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. -```C++ -struct buffer_info { - void *ptr; - size_t itemsize; - std::string format; - int ndim; - std::vector shape; - std::vector strides; -}; -``` -### Taking Python buffer objects as arguments -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). -```C++ -py::class_(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::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(); - } - }); -``` - -### Taking NumPy arrays as arguments - -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`` -template. For instance, the following function requires the argument to be a -dense array of doubles in C-style ordering. -```C++ -void f(py::array_dtype 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. - -### Auto-vectorizing a function over NumPy array arguments -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: -```C++ -double my_func(int x, float y, double z); -``` -This is extremely simple to do! -```C++ -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``. -```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 -```C++ -double my_func(int x, float y, my_custom_type *z); -``` -This can be done with a stateful Lambda closure: -```C++ -// Vectorize a lambda function with a capture object (e.g. to exclude some arguments from the vectorization) -m.def("vectorized_func", - [](py::array_dtype x, py::array_dtype 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); - } -); -``` diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..511b47c2d --- /dev/null +++ b/docs/Makefile @@ -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 ' where 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." diff --git a/docs/advanced.rst b/docs/advanced.rst new file mode 100644 index 000000000..6b7cc1ea3 --- /dev/null +++ b/docs/advanced.rst @@ -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_(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::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 shape; + std::vector 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_(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::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`` +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 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 x, py::array_dtype 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 +=================== diff --git a/docs/basics.rst b/docs/basics.rst new file mode 100644 index 000000000..eb37da54f --- /dev/null +++ b/docs/basics.rst @@ -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 + + 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 /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 | Pair of two custom types | pybind/pybind.h | ++------------------------+--------------------------+---------------------+ +| std::tuple<....> | Arbitrary tuple of types | pybind/pybind.h | ++------------------------+--------------------------+---------------------+ +| std::complex | Complex numbers | pybind/complex.h | ++------------------------+--------------------------+---------------------+ +| std::vector | STL dynamic array | pybind/stl.h | ++------------------------+--------------------------+---------------------+ +| std::map | 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. + diff --git a/docs/classes.rst b/docs/classes.rst new file mode 100644 index 000000000..c141c1610 --- /dev/null +++ b/docs/classes.rst @@ -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 + + namespace py = pybind; + + PYTHON_PLUGIN(example) { + py::module m("example", "pybind example plugin"); + + py::class_(m, "Pet") + .def(py::init()) + .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) + + >>> 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) + + +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_(m, "Pet") + .def(py::init()) + .def("setName", &Pet::setName) + .def("getName", &Pet::getName) + .def("__repr__", + [](const Pet &a) { + return ""; + } + ); + +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) + + +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_(m, "Pet") + .def(py::init()) + .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_(m, "Pet") + .def(py::init()) + .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(m, "Pet"); + pet.def(py::init()) + .def_readwrite("name", &Pet::name); + + py::class_(m, "Dog", pet /* <- specify parent */) + .def(py::init()) + .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_(m, "Pet") + .def(py::init()) + .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(m, "Pet"); + + pet.def(py::init()) + .def_readwrite("name", &Pet::name) + .def_readwrite("type", &Pet::type); + + py::enum_(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) diff --git a/docs/cmake.rst b/docs/cmake.rst new file mode 100644 index 000000000..a5d074011 --- /dev/null +++ b/docs/cmake.rst @@ -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() diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..f883fef6e --- /dev/null +++ b/docs/conf.py @@ -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 +# " v 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 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' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..253c2c20f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,15 @@ +Welcome to pybind11's documentation! +==================================== + + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + basics + classes + advanced + cmake + reference diff --git a/docs/intro.rst b/docs/intro.rst new file mode 100644 index 000000000..3fa362676 --- /dev/null +++ b/docs/intro.rst @@ -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. + diff --git a/docs/reference.rst b/docs/reference.rst new file mode 100644 index 000000000..8fbb39624 --- /dev/null +++ b/docs/reference.rst @@ -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 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 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 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 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 arg_t arg::operator=(const T &value) + +.. class:: template arg_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