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 |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 8 | included set of test cases. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 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 | |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 25 | mkdir build |
| 26 | cd build |
| 27 | cmake .. |
Jason Rhinelander | 05920e3 | 2016-12-19 11:33:02 -0500 | [diff] [blame] | 28 | make check -j 4 |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 29 | |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 30 | The last line will both compile and run the tests. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 31 | |
| 32 | Windows |
| 33 | ------- |
| 34 | |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 35 | On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies |
| 36 | on various C++11 language features that break older versions of Visual Studio. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 37 | |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 38 | To compile and run the tests: |
| 39 | |
| 40 | .. code-block:: batch |
| 41 | |
| 42 | mkdir build |
| 43 | cd build |
| 44 | cmake .. |
Jason Rhinelander | 05920e3 | 2016-12-19 11:33:02 -0500 | [diff] [blame] | 45 | cmake --build . --config Release --target check |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 46 | |
| 47 | This will create a Visual Studio project, compile and run the target, all from the |
| 48 | command line. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 49 | |
| 50 | .. Note:: |
| 51 | |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 52 | If all tests fail, make sure that the Python binary and the testcases are compiled |
| 53 | for the same processor type and bitness (i.e. either **i386** or **x86_64**). You |
| 54 | can specify **x86_64** as the target architecture for the generated Visual Studio |
| 55 | project using ``cmake -A x64 ..``. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 56 | |
| 57 | .. seealso:: |
| 58 | |
| 59 | Advanced users who are already familiar with Boost.Python may want to skip |
Dean Moldovan | ec0d38e | 2016-08-13 03:09:52 +0200 | [diff] [blame] | 60 | the tutorial and look at the test cases in the :file:`tests` directory, |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 61 | which exercise all features of pybind11. |
| 62 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 63 | Header and namespace conventions |
| 64 | ================================ |
| 65 | |
| 66 | For brevity, all code examples assume that the following two lines are present: |
| 67 | |
| 68 | .. code-block:: cpp |
| 69 | |
| 70 | #include <pybind11/pybind11.h> |
| 71 | |
| 72 | namespace py = pybind11; |
| 73 | |
| 74 | Some features may require additional headers, but those will be specified as needed. |
| 75 | |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 76 | Creating bindings for a simple function |
| 77 | ======================================= |
| 78 | |
| 79 | Let's start by creating Python bindings for an extremely simple function, which |
| 80 | adds two numbers and returns their result: |
| 81 | |
| 82 | .. code-block:: cpp |
| 83 | |
| 84 | int add(int i, int j) { |
| 85 | return i + j; |
| 86 | } |
| 87 | |
| 88 | For simplicity [#f1]_, we'll put both this function and the binding code into |
| 89 | a file named :file:`example.cpp` with the following contents: |
| 90 | |
| 91 | .. code-block:: cpp |
| 92 | |
Wenzel Jakob | 8f4eb00 | 2015-10-15 18:13:33 +0200 | [diff] [blame] | 93 | #include <pybind11/pybind11.h> |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 94 | |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 95 | int add(int i, int j) { |
| 96 | return i + j; |
| 97 | } |
| 98 | |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 99 | PYBIND11_MODULE(example, m) { |
| 100 | m.doc() = "pybind11 example plugin"; // optional module docstring |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 101 | |
| 102 | m.def("add", &add, "A function which adds two numbers"); |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 103 | } |
| 104 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 105 | .. [#f1] In practice, implementation and binding code will generally be located |
| 106 | in separate files. |
| 107 | |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 108 | The :func:`PYBIND11_MODULE` macro creates a function that will be called when an |
| 109 | ``import`` statement is issued from within Python. The module name (``example``) |
Matthew Chan | 6223b18 | 2017-06-08 13:55:30 -0400 | [diff] [blame] | 110 | is given as the first macro argument (it should not be in quotes). The second |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 111 | argument (``m``) defines a variable of type :class:`py::module <module>` which |
| 112 | is the main interface for creating bindings. The method :func:`module::def` |
| 113 | generates binding code that exposes the ``add()`` function to Python. |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 114 | |
| 115 | .. note:: |
| 116 | |
| 117 | Notice how little code was needed to expose our function to Python: all |
| 118 | details regarding the function's parameters and return value were |
| 119 | automatically inferred using template metaprogramming. This overall |
| 120 | approach and the used syntax are borrowed from Boost.Python, though the |
| 121 | underlying implementation is very different. |
| 122 | |
| 123 | pybind11 is a header-only-library, hence it is not necessary to link against |
| 124 | any special libraries (other than Python itself). On Windows, use the CMake |
| 125 | build file discussed in section :ref:`cmake`. On Linux and Mac OS, the above |
| 126 | example can be compiled using the following command |
| 127 | |
| 128 | .. code-block:: bash |
| 129 | |
Wenzel Jakob | 06f56ee | 2016-04-28 16:25:24 +0200 | [diff] [blame] | 130 | $ c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` example.cpp -o example.so |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 131 | |
| 132 | In general, it is advisable to include several additional build parameters |
| 133 | that can considerably reduce the size of the created binary. Refer to section |
| 134 | :ref:`cmake` for a detailed example of a suitable cross-platform CMake-based |
| 135 | build system. |
| 136 | |
| 137 | Assuming that the created file :file:`example.so` (:file:`example.pyd` on Windows) |
| 138 | is located in the current directory, the following interactive Python session |
| 139 | shows how to load and execute the example. |
| 140 | |
Wenzel Jakob | 99279f7 | 2016-06-03 11:19:29 +0200 | [diff] [blame] | 141 | .. code-block:: pycon |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 142 | |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 143 | $ python |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 144 | Python 2.7.10 (default, Aug 22 2015, 20:33:39) |
| 145 | [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin |
| 146 | Type "help", "copyright", "credits" or "license" for more information. |
| 147 | >>> import example |
| 148 | >>> example.add(1, 2) |
| 149 | 3L |
Wenzel Jakob | 9329669 | 2015-10-13 23:21:54 +0200 | [diff] [blame] | 150 | >>> |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 151 | |
| 152 | .. _keyword_args: |
| 153 | |
| 154 | Keyword arguments |
| 155 | ================= |
| 156 | |
| 157 | With a simple modification code, it is possible to inform Python about the |
| 158 | names of the arguments ("i" and "j" in this case). |
| 159 | |
| 160 | .. code-block:: cpp |
| 161 | |
| 162 | m.def("add", &add, "A function which adds two numbers", |
| 163 | py::arg("i"), py::arg("j")); |
| 164 | |
| 165 | :class:`arg` is one of several special tag classes which can be used to pass |
| 166 | metadata into :func:`module::def`. With this modified binding code, we can now |
| 167 | call the function using keyword arguments, which is a more readable alternative |
| 168 | particularly for functions taking many parameters: |
| 169 | |
Wenzel Jakob | 99279f7 | 2016-06-03 11:19:29 +0200 | [diff] [blame] | 170 | .. code-block:: pycon |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 171 | |
| 172 | >>> import example |
| 173 | >>> example.add(i=1, j=2) |
| 174 | 3L |
| 175 | |
| 176 | The keyword names also appear in the function signatures within the documentation. |
| 177 | |
Wenzel Jakob | 99279f7 | 2016-06-03 11:19:29 +0200 | [diff] [blame] | 178 | .. code-block:: pycon |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 179 | |
| 180 | >>> help(example) |
| 181 | |
| 182 | .... |
| 183 | |
| 184 | FUNCTIONS |
| 185 | add(...) |
Wenzel Jakob | 6eb11da | 2016-01-17 22:36:36 +0100 | [diff] [blame] | 186 | Signature : (i: int, j: int) -> int |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 187 | |
| 188 | A function which adds two numbers |
| 189 | |
Dean Moldovan | b3eadfa | 2016-06-03 23:48:31 +0200 | [diff] [blame] | 190 | A shorter notation for named arguments is also available: |
| 191 | |
| 192 | .. code-block:: cpp |
Wenzel Jakob | fe34241 | 2016-09-06 13:02:29 +0900 | [diff] [blame] | 193 | |
Dean Moldovan | b3eadfa | 2016-06-03 23:48:31 +0200 | [diff] [blame] | 194 | // regular notation |
| 195 | m.def("add1", &add, py::arg("i"), py::arg("j")); |
| 196 | // shorthand |
| 197 | using namespace pybind11::literals; |
| 198 | m.def("add2", &add, "i"_a, "j"_a); |
| 199 | |
Wenzel Jakob | fe34241 | 2016-09-06 13:02:29 +0900 | [diff] [blame] | 200 | The :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`. |
| 201 | Note that the literal operator must first be made visible with the directive |
| 202 | ``using namespace pybind11::literals``. This does not bring in anything else |
Dean Moldovan | b3eadfa | 2016-06-03 23:48:31 +0200 | [diff] [blame] | 203 | from the ``pybind11`` namespace except for literals. |
| 204 | |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 205 | .. _default_args: |
| 206 | |
| 207 | Default arguments |
| 208 | ================= |
| 209 | |
| 210 | Suppose now that the function to be bound has default arguments, e.g.: |
| 211 | |
| 212 | .. code-block:: cpp |
| 213 | |
| 214 | int add(int i = 1, int j = 2) { |
| 215 | return i + j; |
| 216 | } |
| 217 | |
| 218 | Unfortunately, pybind11 cannot automatically extract these parameters, since they |
| 219 | are not part of the function's type information. However, they are simple to specify |
| 220 | using an extension of :class:`arg`: |
| 221 | |
| 222 | .. code-block:: cpp |
| 223 | |
| 224 | m.def("add", &add, "A function which adds two numbers", |
| 225 | py::arg("i") = 1, py::arg("j") = 2); |
| 226 | |
| 227 | The default values also appear within the documentation. |
| 228 | |
Wenzel Jakob | 99279f7 | 2016-06-03 11:19:29 +0200 | [diff] [blame] | 229 | .. code-block:: pycon |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 230 | |
| 231 | >>> help(example) |
| 232 | |
| 233 | .... |
| 234 | |
| 235 | FUNCTIONS |
| 236 | add(...) |
Wenzel Jakob | 6eb11da | 2016-01-17 22:36:36 +0100 | [diff] [blame] | 237 | Signature : (i: int = 1, j: int = 2) -> int |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 238 | |
| 239 | A function which adds two numbers |
| 240 | |
Dean Moldovan | b3eadfa | 2016-06-03 23:48:31 +0200 | [diff] [blame] | 241 | The shorthand notation is also available for default arguments: |
| 242 | |
| 243 | .. code-block:: cpp |
Wenzel Jakob | fe34241 | 2016-09-06 13:02:29 +0900 | [diff] [blame] | 244 | |
Dean Moldovan | b3eadfa | 2016-06-03 23:48:31 +0200 | [diff] [blame] | 245 | // regular notation |
| 246 | m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2); |
| 247 | // shorthand |
| 248 | m.def("add2", &add, "i"_a=1, "j"_a=2); |
| 249 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 250 | Exporting variables |
| 251 | =================== |
| 252 | |
Jason Rhinelander | 3f1ff3f | 2016-12-12 17:42:52 -0500 | [diff] [blame] | 253 | To expose a value from C++, use the ``attr`` function to register it in a |
| 254 | module as shown below. Built-in types and general objects (more on that later) |
| 255 | are automatically converted when assigned as attributes, and can be explicitly |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 256 | converted using the function ``py::cast``. |
| 257 | |
| 258 | .. code-block:: cpp |
| 259 | |
Dean Moldovan | 443ab59 | 2017-04-24 01:51:44 +0200 | [diff] [blame] | 260 | PYBIND11_MODULE(example, m) { |
Jason Rhinelander | 3f1ff3f | 2016-12-12 17:42:52 -0500 | [diff] [blame] | 261 | m.attr("the_answer") = 42; |
| 262 | py::object world = py::cast("World"); |
| 263 | m.attr("what") = world; |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 264 | } |
| 265 | |
| 266 | These are then accessible from Python: |
| 267 | |
| 268 | .. code-block:: pycon |
| 269 | |
| 270 | >>> import example |
| 271 | >>> example.the_answer |
| 272 | 42 |
| 273 | >>> example.what |
| 274 | 'World' |
| 275 | |
Wenzel Jakob | 28f98aa | 2015-10-13 02:57:16 +0200 | [diff] [blame] | 276 | .. _supported_types: |
| 277 | |
| 278 | Supported data types |
| 279 | ==================== |
| 280 | |
Dean Moldovan | 67b52d8 | 2016-10-16 19:12:43 +0200 | [diff] [blame] | 281 | A large number of data types are supported out of the box and can be used |
| 282 | seamlessly as functions arguments, return values or with ``py::cast`` in general. |
| 283 | For a full overview, see the :doc:`advanced/cast/index` section. |