Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 1 | .. _basics: |
| 2 | |
| 3 | First steps |
| 4 | ########### |
| 5 | |
| 6 | This sections demonstrates the basic features of pybind11. Before getting |
| 7 | started, make sure that development environment is set up to compile the |
| 8 | included set of examples, which also double as test cases. |
| 9 | |
| 10 | |
| 11 | Compiling the test cases |
| 12 | ======================== |
| 13 | |
| 14 | Linux/MacOS |
| 15 | ----------- |
| 16 | |
| 17 | On Linux you'll need to install the **python-dev** or **python3-dev** packages as |
| 18 | well as **cmake**. On Mac OS, the included python version works out of the box, |
| 19 | but **cmake** must still be installed. |
| 20 | |
| 21 | After installing the prerequisites, run |
| 22 | |
| 23 | .. code-block:: bash |
| 24 | |
| 25 | cmake . |
| 26 | make -j 4 |
| 27 | |
| 28 | followed by |
| 29 | |
| 30 | .. code-block:: bash |
| 31 | |
| 32 | make test |
| 33 | |
| 34 | Windows |
| 35 | ------- |
| 36 | |
| 37 | On Windows, use the `CMake GUI`_ to create a Visual Studio project. Note that |
| 38 | only the 2015 release and newer versions are supported since pybind11 relies on |
| 39 | various C++11 language features that break older versions of Visual Studio. |
Wenzel Jakob | 8f4eb00 | 2015-10-15 18:13:33 +0200 | [diff] [blame] | 40 | After running CMake, open the created :file:`pybind11.sln` file and perform a |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 41 | release build, which will will produce a file named |
| 42 | :file:`Release\\example.pyd`. Copy this file to the :file:`example` directory |
| 43 | and run :file:`example\\run_test.py` using the targeted Python version. |
| 44 | |
| 45 | .. _`CMake GUI`: https://cmake.org/runningcmake |
| 46 | |
| 47 | .. Note:: |
| 48 | |
| 49 | When all tests fail, make sure that |
| 50 | |
| 51 | 1. The Python binary and the testcases are compiled for the same processor |
| 52 | type and bitness (i.e. either **i386** or **x86_64**) |
| 53 | |
| 54 | 2. The Python binary used to run :file:`example\\run_test.py` matches the |
| 55 | Python version specified in the CMake GUI. This is controlled via |
| 56 | the ``PYTHON_EXECUTABLE`` ``PYTHON_INCLUDE_DIR``, and |
| 57 | ``PYTHON_LIBRARY`` variables. |
| 58 | |
| 59 | .. seealso:: |
| 60 | |
| 61 | Advanced users who are already familiar with Boost.Python may want to skip |
| 62 | the tutorial and look at the test cases in the :file:`example` directory, |
| 63 | which exercise all features of pybind11. |
| 64 | |
| 65 | Creating bindings for a simple function |
| 66 | ======================================= |
| 67 | |
| 68 | Let's start by creating Python bindings for an extremely simple function, which |
| 69 | adds two numbers and returns their result: |
| 70 | |
| 71 | .. code-block:: cpp |
| 72 | |
| 73 | int add(int i, int j) { |
| 74 | return i + j; |
| 75 | } |
| 76 | |
| 77 | For simplicity [#f1]_, we'll put both this function and the binding code into |
| 78 | a file named :file:`example.cpp` with the following contents: |
| 79 | |
| 80 | .. code-block:: cpp |
| 81 | |
Wenzel Jakob | 8f4eb00 | 2015-10-15 18:13:33 +0200 | [diff] [blame] | 82 | #include <pybind11/pybind11.h> |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 83 | |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 84 | int add(int i, int j) { |
| 85 | return i + j; |
| 86 | } |
| 87 | |
Wenzel Jakob | 10e62e1 | 2015-10-15 22:46:07 +0200 | [diff] [blame] | 88 | namespace py = pybind11; |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 89 | |
Wenzel Jakob | b1b7140 | 2015-10-18 16:48:30 +0200 | [diff] [blame^] | 90 | PYBIND11_PLUGIN(example) { |
Wenzel Jakob | 8f4eb00 | 2015-10-15 18:13:33 +0200 | [diff] [blame] | 91 | py::module m("example", "pybind11 example plugin"); |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 92 | |
| 93 | m.def("add", &add, "A function which adds two numbers"); |
| 94 | |
| 95 | return m.ptr(); |
| 96 | } |
| 97 | |
Wenzel Jakob | b1b7140 | 2015-10-18 16:48:30 +0200 | [diff] [blame^] | 98 | The :func:`PYBIND11_PLUGIN` macro creates a function that will be called when an |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 99 | ``import`` statement is issued from within Python. The next line creates a |
| 100 | module named ``example`` (with the supplied docstring). The method |
| 101 | :func:`module::def` generates binding code that exposes the |
| 102 | ``add()`` function to Python. The last line returns the internal Python object |
| 103 | associated with ``m`` to the Python interpreter. |
| 104 | |
| 105 | .. note:: |
| 106 | |
| 107 | Notice how little code was needed to expose our function to Python: all |
| 108 | details regarding the function's parameters and return value were |
| 109 | automatically inferred using template metaprogramming. This overall |
| 110 | approach and the used syntax are borrowed from Boost.Python, though the |
| 111 | underlying implementation is very different. |
| 112 | |
| 113 | pybind11 is a header-only-library, hence it is not necessary to link against |
| 114 | any special libraries (other than Python itself). On Windows, use the CMake |
| 115 | build file discussed in section :ref:`cmake`. On Linux and Mac OS, the above |
| 116 | example can be compiled using the following command |
| 117 | |
| 118 | .. code-block:: bash |
| 119 | |
Wenzel Jakob | 8f4eb00 | 2015-10-15 18:13:33 +0200 | [diff] [blame] | 120 | $ c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --libs` example.cpp -o example.so |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 121 | |
| 122 | In general, it is advisable to include several additional build parameters |
| 123 | that can considerably reduce the size of the created binary. Refer to section |
| 124 | :ref:`cmake` for a detailed example of a suitable cross-platform CMake-based |
| 125 | build system. |
| 126 | |
| 127 | Assuming that the created file :file:`example.so` (:file:`example.pyd` on Windows) |
| 128 | is located in the current directory, the following interactive Python session |
| 129 | shows how to load and execute the example. |
| 130 | |
| 131 | .. code-block:: python |
| 132 | |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 133 | $ python |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 134 | Python 2.7.10 (default, Aug 22 2015, 20:33:39) |
| 135 | [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin |
| 136 | Type "help", "copyright", "credits" or "license" for more information. |
| 137 | >>> import example |
| 138 | >>> example.add(1, 2) |
| 139 | 3L |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 140 | >>> |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 141 | |
| 142 | .. _keyword_args: |
| 143 | |
| 144 | Keyword arguments |
| 145 | ================= |
| 146 | |
| 147 | With a simple modification code, it is possible to inform Python about the |
| 148 | names of the arguments ("i" and "j" in this case). |
| 149 | |
| 150 | .. code-block:: cpp |
| 151 | |
| 152 | m.def("add", &add, "A function which adds two numbers", |
| 153 | py::arg("i"), py::arg("j")); |
| 154 | |
| 155 | :class:`arg` is one of several special tag classes which can be used to pass |
| 156 | metadata into :func:`module::def`. With this modified binding code, we can now |
| 157 | call the function using keyword arguments, which is a more readable alternative |
| 158 | particularly for functions taking many parameters: |
| 159 | |
| 160 | .. code-block:: python |
| 161 | |
| 162 | >>> import example |
| 163 | >>> example.add(i=1, j=2) |
| 164 | 3L |
| 165 | |
| 166 | The keyword names also appear in the function signatures within the documentation. |
| 167 | |
| 168 | .. code-block:: python |
| 169 | |
| 170 | >>> help(example) |
| 171 | |
| 172 | .... |
| 173 | |
| 174 | FUNCTIONS |
| 175 | add(...) |
| 176 | Signature : (i: int32_t, j: int32_t) -> int32_t |
| 177 | |
| 178 | A function which adds two numbers |
| 179 | |
| 180 | .. _default_args: |
| 181 | |
| 182 | Default arguments |
| 183 | ================= |
| 184 | |
| 185 | Suppose now that the function to be bound has default arguments, e.g.: |
| 186 | |
| 187 | .. code-block:: cpp |
| 188 | |
| 189 | int add(int i = 1, int j = 2) { |
| 190 | return i + j; |
| 191 | } |
| 192 | |
| 193 | Unfortunately, pybind11 cannot automatically extract these parameters, since they |
| 194 | are not part of the function's type information. However, they are simple to specify |
| 195 | using an extension of :class:`arg`: |
| 196 | |
| 197 | .. code-block:: cpp |
| 198 | |
| 199 | m.def("add", &add, "A function which adds two numbers", |
| 200 | py::arg("i") = 1, py::arg("j") = 2); |
| 201 | |
| 202 | The default values also appear within the documentation. |
| 203 | |
| 204 | .. code-block:: python |
| 205 | |
| 206 | >>> help(example) |
| 207 | |
| 208 | .... |
| 209 | |
| 210 | FUNCTIONS |
| 211 | add(...) |
| 212 | Signature : (i: int32_t = 1L, j: int32_t = 2L) -> int32_t |
| 213 | |
| 214 | A function which adds two numbers |
| 215 | |
| 216 | .. _supported_types: |
| 217 | |
| 218 | Supported data types |
| 219 | ==================== |
| 220 | |
| 221 | The following basic data types are supported out of the box (some may require |
| 222 | an additional extension header to be included). To pass other data structures |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 223 | as arguments and return values, refer to the section on binding :ref:`classes`. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 224 | |
Wenzel Jakob | 8f4eb00 | 2015-10-15 18:13:33 +0200 | [diff] [blame] | 225 | +------------------------+--------------------------+-----------------------+ |
| 226 | | Data type | Description | Header file | |
| 227 | +========================+==========================+=======================+ |
| 228 | | int8_t, uint8_t | 8-bit integers | pybind11/pybind11.h | |
| 229 | +------------------------+--------------------------+-----------------------+ |
| 230 | | int16_t, uint16_t | 16-bit integers | pybind11/pybind11.h | |
| 231 | +------------------------+--------------------------+-----------------------+ |
| 232 | | int32_t, uint32_t | 32-bit integers | pybind11/pybind11.h | |
| 233 | +------------------------+--------------------------+-----------------------+ |
| 234 | | int64_t, uint64_t | 64-bit integers | pybind11/pybind11.h | |
| 235 | +------------------------+--------------------------+-----------------------+ |
| 236 | | ssize_t, size_t | Platform-dependent size | pybind11/pybind11.h | |
| 237 | +------------------------+--------------------------+-----------------------+ |
| 238 | | float, double | Floating point types | pybind11/pybind11.h | |
| 239 | +------------------------+--------------------------+-----------------------+ |
| 240 | | bool | Two-state Boolean type | pybind11/pybind11.h | |
| 241 | +------------------------+--------------------------+-----------------------+ |
| 242 | | char | Character literal | pybind11/pybind11.h | |
| 243 | +------------------------+--------------------------+-----------------------+ |
| 244 | | const char * | UTF-8 string literal | pybind11/pybind11.h | |
| 245 | +------------------------+--------------------------+-----------------------+ |
| 246 | | std::string | STL dynamic UTF-8 string | pybind11/pybind11.h | |
| 247 | +------------------------+--------------------------+-----------------------+ |
| 248 | | std::pair<T1, T2> | Pair of two custom types | pybind11/pybind11.h | |
| 249 | +------------------------+--------------------------+-----------------------+ |
| 250 | | std::tuple<....> | Arbitrary tuple of types | pybind11/pybind11.h | |
| 251 | +------------------------+--------------------------+-----------------------+ |
| 252 | | std::complex<T> | Complex numbers | pybind11/complex.h | |
| 253 | +------------------------+--------------------------+-----------------------+ |
| 254 | | std::vector<T> | STL dynamic array | pybind11/stl.h | |
| 255 | +------------------------+--------------------------+-----------------------+ |
| 256 | | std::map<T1, T2> | STL dynamic maps | pybind11/stl.h | |
| 257 | +------------------------+--------------------------+-----------------------+ |
| 258 | | std::function<...> | STL polymorphic function | pybind11/functional.h | |
| 259 | +------------------------+--------------------------+-----------------------+ |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 260 | |
| 261 | |
| 262 | .. [#f1] In practice, implementation and binding code will generally be located |
| 263 | in separate files. |
| 264 | |