Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-22 13:15:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation improvements

Browse Source
This commit is contained in:
Wenzel Jakob 2016-04-07 18:00:41 +02:00
parent 1e1f3675cd
commit 978e376e57
1 changed files with 52 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/advanced.rst
View File

@ -373,10 +373,10 @@ Passing STL data structures
=========================== ===========================
When including the additional header file :file:`pybind11/stl.h`, conversions When including the additional header file :file:`pybind11/stl.h`, conversions
between ``std::vector<>``, ``std::set<>``, and ``std::map<>`` and the Python between ``std::vector<>``, ``std::list<>``, ``std::set<>``, and ``std::map<>``
``list``, ``set`` and ``dict`` data structures are automatically enabled. The and the Python ``list``, ``set`` and ``dict`` data structures are automatically
types ``std::pair<>`` and ``std::tuple<>`` are already supported out of the box enabled. The types ``std::pair<>`` and ``std::tuple<>`` are already supported
with just the core :file:`pybind11/pybind11.h` header. out of the box with just the core :file:`pybind11/pybind11.h` header.
.. note:: .. note::
@ -457,7 +457,7 @@ See below for an example that uses the
py::class_<Example>(m, "Example") py::class_<Example>(m, "Example")
.def(py::init<>()) .def(py::init<>())
.def("get_internal", &Example::get_internal, "Return the internal data", py::return_value_policy::reference_internal) .def("get_internal", &Example::get_internal, "Return the internal data", py::return_value_policy::reference_internal);
return m.ptr(); return m.ptr();
} }
@ -705,23 +705,35 @@ automatically converted into a Python ``Exception``. pybind11 defines multiple
special exception classes that will map to different types of Python special exception classes that will map to different types of Python
exceptions: exceptions:
+----------------------------+------------------------------+ +--------------------------------------+------------------------------+
| C++ exception type | Python exception type | | C++ exception type | Python exception type |
+============================+==============================+ +======================================+==============================+
| :class:`std::exception` | ``Exception`` | | :class:`std::exception` | ``RuntimeError`` |
+----------------------------+------------------------------+ +--------------------------------------+------------------------------+
| :class:`stop_iteration` | ``StopIteration`` (used to | | :class:`std::bad_alloc` | ``MemoryError`` |
| | implement custom iterators) | +--------------------------------------+------------------------------+
+----------------------------+------------------------------+ | :class:`std::domain_error` | ``ValueError`` |
| :class:`index_error` | ``IndexError`` (used to | +--------------------------------------+------------------------------+
| | indicate out of bounds | | :class:`std::invalid_argument` | ``ValueError`` |
| | accesses in ``__getitem__``, | +--------------------------------------+------------------------------+
| | ``__setitem__``, etc.) | | :class:`std::length_error` | ``ValueError`` |
+----------------------------+------------------------------+ +--------------------------------------+------------------------------+
| :class:`error_already_set` | Indicates that the Python | | :class:`std::out_of_range` | ``ValueError`` |
| | exception flag has already | +--------------------------------------+------------------------------+
| | been initialized. | | :class:`std::range_error` | ``ValueError`` |
+----------------------------+------------------------------+ +--------------------------------------+------------------------------+
| :class:`pybind11::stop_iteration` | ``StopIteration`` (used to |
| | implement custom iterators) |
+--------------------------------------+------------------------------+
| :class:`pybind11::index_error` | ``IndexError`` (used to |
| | indicate out of bounds |
| | accesses in ``__getitem__``, |
| | ``__setitem__``, etc.) |
+--------------------------------------+------------------------------+
| :class:`pybind11::error_already_set` | Indicates that the Python |
| | exception flag has already |
| | been initialized |
+--------------------------------------+------------------------------+
When a Python function invoked from C++ throws an exception, it is converted When a Python function invoked from C++ throws an exception, it is converted
into a C++ exception of type :class:`error_already_set` whose string payload into a C++ exception of type :class:`error_already_set` whose string payload
@ -735,9 +747,9 @@ Buffer protocol
=============== ===============
Python supports an extremely general and convenient approach for exchanging Python supports an extremely general and convenient approach for exchanging
data between plugin libraries. Types can expose a buffer view which provides data between plugin libraries. Types can expose a buffer view [#f1]_,
fast direct access to the raw internal representation. Suppose we want to bind which provides fast direct access to the raw internal representation. Suppose
the following simplistic Matrix class: we want to bind the following simplistic Matrix class:
.. code-block:: cpp .. code-block:: cpp
@ -829,12 +841,14 @@ objects (e.g. a NumPy matrix).
The file :file:`example/example7.cpp` contains a complete example that The file :file:`example/example7.cpp` contains a complete example that
demonstrates using the buffer protocol with pybind11 in more detail. demonstrates using the buffer protocol with pybind11 in more detail.
.. [#f1] https://docs.python.org/3/c-api/buffer.html
NumPy support NumPy support
============= =============
By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can 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 restrict the function so that it only accepts NumPy arrays (rather than any
type of Python object satisfying the buffer object protocol). type of Python object satisfying the buffer protocol).
In many situations, we want to define a function which only accepts a NumPy 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_t<T>`` array of a certain data type. This is possible via the ``py::array_t<T>``
@ -846,8 +860,9 @@ dense array of doubles in C-style ordering.
void f(py::array_t<double> array); void f(py::array_t<double> array);
When it is invoked with a different type (e.g. an integer), the binding code 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. will attempt to cast the input into a NumPy array of the requested type. Note
Note that this feature requires the ``pybind11/numpy.h`` header to be included. that this feature requires the :file:``pybind11/numpy.h`` header to be
included.
Vectorizing functions Vectorizing functions
===================== =====================
@ -867,7 +882,10 @@ After including the ``pybind11/numpy.h`` header, this is extremely simple:
m.def("vectorized_func", py::vectorize(my_func)); m.def("vectorized_func", py::vectorize(my_func));
Invoking the function like below causes 4 calls to be made to ``my_func`` with 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 each of the the array elements. The significant advantage of this compared to
solutions like ``numpy.vectorize()`` is that the loop over the elements runs
entirely on the C++ side and can be crunched down into a tight, optimized loop
by the compiler. The result is returned as a NumPy array of type
``numpy.dtype.float64``. ``numpy.dtype.float64``.
.. code-block:: python .. code-block:: python
@ -1085,8 +1103,6 @@ lookup of the corresponding Python type. However, this also requires invoking
the ``import`` function once to ensure that the pybind11 binding code of the the ``import`` function once to ensure that the pybind11 binding code of the
module ``basic`` has been executed. module ``basic`` has been executed.
Naturally, both methods will fail when there are cyclic dependencies.
.. code-block:: cpp .. code-block:: cpp
py::module::import("basic"); py::module::import("basic");
@ -1095,6 +1111,8 @@ Naturally, both methods will fail when there are cyclic dependencies.
.def(py::init<const std::string &>()) .def(py::init<const std::string &>())
.def("bark", &Dog::bark); .def("bark", &Dog::bark);
Naturally, both methods will fail when there are cyclic dependencies.
Treating STL data structures as opaque objects Treating STL data structures as opaque objects
============================================== ==============================================
@ -1104,9 +1122,9 @@ linked lists, hash tables, etc. This even works in a recursive manner, for
instance to deal with lists of hash maps of pairs of elementary and custom instance to deal with lists of hash maps of pairs of elementary and custom
types, etc. types, etc.
The fundamental limitation of this approach is the internal conversion between A fundamental limitation of this approach is that the internal conversion
Python and C++ types involves a copy operation that prevents pass-by-reference between Python and C++ types involves a copy operation that prevents
semantics. What does this mean? pass-by-reference semantics. What does this mean?
Suppose we bind the following function Suppose we bind the following function