111986Sandreas.sandberg@arm.com.. _basics: 211986Sandreas.sandberg@arm.com 311986Sandreas.sandberg@arm.comFirst steps 411986Sandreas.sandberg@arm.com########### 511986Sandreas.sandberg@arm.com 611986Sandreas.sandberg@arm.comThis sections demonstrates the basic features of pybind11. Before getting 711986Sandreas.sandberg@arm.comstarted, make sure that development environment is set up to compile the 811986Sandreas.sandberg@arm.comincluded set of test cases. 911986Sandreas.sandberg@arm.com 1011986Sandreas.sandberg@arm.com 1111986Sandreas.sandberg@arm.comCompiling the test cases 1211986Sandreas.sandberg@arm.com======================== 1311986Sandreas.sandberg@arm.com 1411986Sandreas.sandberg@arm.comLinux/MacOS 1511986Sandreas.sandberg@arm.com----------- 1611986Sandreas.sandberg@arm.com 1711986Sandreas.sandberg@arm.comOn Linux you'll need to install the **python-dev** or **python3-dev** packages as 1811986Sandreas.sandberg@arm.comwell as **cmake**. On Mac OS, the included python version works out of the box, 1911986Sandreas.sandberg@arm.combut **cmake** must still be installed. 2011986Sandreas.sandberg@arm.com 2111986Sandreas.sandberg@arm.comAfter installing the prerequisites, run 2211986Sandreas.sandberg@arm.com 2311986Sandreas.sandberg@arm.com.. code-block:: bash 2411986Sandreas.sandberg@arm.com 2511986Sandreas.sandberg@arm.com mkdir build 2611986Sandreas.sandberg@arm.com cd build 2711986Sandreas.sandberg@arm.com cmake .. 2812037Sandreas.sandberg@arm.com make check -j 4 2911986Sandreas.sandberg@arm.com 3011986Sandreas.sandberg@arm.comThe last line will both compile and run the tests. 3111986Sandreas.sandberg@arm.com 3211986Sandreas.sandberg@arm.comWindows 3311986Sandreas.sandberg@arm.com------- 3411986Sandreas.sandberg@arm.com 3511986Sandreas.sandberg@arm.comOn Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies 3611986Sandreas.sandberg@arm.comon various C++11 language features that break older versions of Visual Studio. 3711986Sandreas.sandberg@arm.com 3811986Sandreas.sandberg@arm.comTo compile and run the tests: 3911986Sandreas.sandberg@arm.com 4011986Sandreas.sandberg@arm.com.. code-block:: batch 4111986Sandreas.sandberg@arm.com 4211986Sandreas.sandberg@arm.com mkdir build 4311986Sandreas.sandberg@arm.com cd build 4411986Sandreas.sandberg@arm.com cmake .. 4512037Sandreas.sandberg@arm.com cmake --build . --config Release --target check 4611986Sandreas.sandberg@arm.com 4711986Sandreas.sandberg@arm.comThis will create a Visual Studio project, compile and run the target, all from the 4811986Sandreas.sandberg@arm.comcommand line. 4911986Sandreas.sandberg@arm.com 5011986Sandreas.sandberg@arm.com.. Note:: 5111986Sandreas.sandberg@arm.com 5211986Sandreas.sandberg@arm.com If all tests fail, make sure that the Python binary and the testcases are compiled 5311986Sandreas.sandberg@arm.com for the same processor type and bitness (i.e. either **i386** or **x86_64**). You 5411986Sandreas.sandberg@arm.com can specify **x86_64** as the target architecture for the generated Visual Studio 5511986Sandreas.sandberg@arm.com project using ``cmake -A x64 ..``. 5611986Sandreas.sandberg@arm.com 5711986Sandreas.sandberg@arm.com.. seealso:: 5811986Sandreas.sandberg@arm.com 5911986Sandreas.sandberg@arm.com Advanced users who are already familiar with Boost.Python may want to skip 6011986Sandreas.sandberg@arm.com the tutorial and look at the test cases in the :file:`tests` directory, 6111986Sandreas.sandberg@arm.com which exercise all features of pybind11. 6211986Sandreas.sandberg@arm.com 6311986Sandreas.sandberg@arm.comHeader and namespace conventions 6411986Sandreas.sandberg@arm.com================================ 6511986Sandreas.sandberg@arm.com 6611986Sandreas.sandberg@arm.comFor brevity, all code examples assume that the following two lines are present: 6711986Sandreas.sandberg@arm.com 6811986Sandreas.sandberg@arm.com.. code-block:: cpp 6911986Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.com #include <pybind11/pybind11.h> 7111986Sandreas.sandberg@arm.com 7211986Sandreas.sandberg@arm.com namespace py = pybind11; 7311986Sandreas.sandberg@arm.com 7411986Sandreas.sandberg@arm.comSome features may require additional headers, but those will be specified as needed. 7511986Sandreas.sandberg@arm.com 7612391Sjason@lowepower.com.. _simple_example: 7712391Sjason@lowepower.com 7811986Sandreas.sandberg@arm.comCreating bindings for a simple function 7911986Sandreas.sandberg@arm.com======================================= 8011986Sandreas.sandberg@arm.com 8111986Sandreas.sandberg@arm.comLet's start by creating Python bindings for an extremely simple function, which 8211986Sandreas.sandberg@arm.comadds two numbers and returns their result: 8311986Sandreas.sandberg@arm.com 8411986Sandreas.sandberg@arm.com.. code-block:: cpp 8511986Sandreas.sandberg@arm.com 8611986Sandreas.sandberg@arm.com int add(int i, int j) { 8711986Sandreas.sandberg@arm.com return i + j; 8811986Sandreas.sandberg@arm.com } 8911986Sandreas.sandberg@arm.com 9011986Sandreas.sandberg@arm.comFor simplicity [#f1]_, we'll put both this function and the binding code into 9111986Sandreas.sandberg@arm.coma file named :file:`example.cpp` with the following contents: 9211986Sandreas.sandberg@arm.com 9311986Sandreas.sandberg@arm.com.. code-block:: cpp 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.com #include <pybind11/pybind11.h> 9611986Sandreas.sandberg@arm.com 9711986Sandreas.sandberg@arm.com int add(int i, int j) { 9811986Sandreas.sandberg@arm.com return i + j; 9911986Sandreas.sandberg@arm.com } 10011986Sandreas.sandberg@arm.com 10112391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 10212391Sjason@lowepower.com m.doc() = "pybind11 example plugin"; // optional module docstring 10311986Sandreas.sandberg@arm.com 10411986Sandreas.sandberg@arm.com m.def("add", &add, "A function which adds two numbers"); 10511986Sandreas.sandberg@arm.com } 10611986Sandreas.sandberg@arm.com 10711986Sandreas.sandberg@arm.com.. [#f1] In practice, implementation and binding code will generally be located 10811986Sandreas.sandberg@arm.com in separate files. 10911986Sandreas.sandberg@arm.com 11012391Sjason@lowepower.comThe :func:`PYBIND11_MODULE` macro creates a function that will be called when an 11112391Sjason@lowepower.com``import`` statement is issued from within Python. The module name (``example``) 11212391Sjason@lowepower.comis given as the first macro argument (it should not be in quotes). The second 11312391Sjason@lowepower.comargument (``m``) defines a variable of type :class:`py::module <module>` which 11412391Sjason@lowepower.comis the main interface for creating bindings. The method :func:`module::def` 11512391Sjason@lowepower.comgenerates binding code that exposes the ``add()`` function to Python. 11611986Sandreas.sandberg@arm.com 11711986Sandreas.sandberg@arm.com.. note:: 11811986Sandreas.sandberg@arm.com 11911986Sandreas.sandberg@arm.com Notice how little code was needed to expose our function to Python: all 12011986Sandreas.sandberg@arm.com details regarding the function's parameters and return value were 12111986Sandreas.sandberg@arm.com automatically inferred using template metaprogramming. This overall 12211986Sandreas.sandberg@arm.com approach and the used syntax are borrowed from Boost.Python, though the 12311986Sandreas.sandberg@arm.com underlying implementation is very different. 12411986Sandreas.sandberg@arm.com 12512391Sjason@lowepower.compybind11 is a header-only library, hence it is not necessary to link against 12612391Sjason@lowepower.comany special libraries and there are no intermediate (magic) translation steps. 12712391Sjason@lowepower.comOn Linux, the above example can be compiled using the following command: 12811986Sandreas.sandberg@arm.com 12911986Sandreas.sandberg@arm.com.. code-block:: bash 13011986Sandreas.sandberg@arm.com 13112391Sjason@lowepower.com $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` 13211986Sandreas.sandberg@arm.com 13312391Sjason@lowepower.comFor more details on the required compiler flags on Linux and MacOS, see 13412391Sjason@lowepower.com:ref:`building_manually`. For complete cross-platform compilation instructions, 13512391Sjason@lowepower.comrefer to the :ref:`compiling` page. 13611986Sandreas.sandberg@arm.com 13712391Sjason@lowepower.comThe `python_example`_ and `cmake_example`_ repositories are also a good place 13812391Sjason@lowepower.comto start. They are both complete project examples with cross-platform build 13912391Sjason@lowepower.comsystems. The only difference between the two is that `python_example`_ uses 14012391Sjason@lowepower.comPython's ``setuptools`` to build the module, while `cmake_example`_ uses CMake 14112391Sjason@lowepower.com(which may be preferable for existing C++ projects). 14212391Sjason@lowepower.com 14312391Sjason@lowepower.com.. _python_example: https://github.com/pybind/python_example 14412391Sjason@lowepower.com.. _cmake_example: https://github.com/pybind/cmake_example 14512391Sjason@lowepower.com 14612391Sjason@lowepower.comBuilding the above C++ code will produce a binary module file that can be 14712391Sjason@lowepower.comimported to Python. Assuming that the compiled module is located in the 14812391Sjason@lowepower.comcurrent directory, the following interactive Python session shows how to 14912391Sjason@lowepower.comload and execute the example: 15011986Sandreas.sandberg@arm.com 15111986Sandreas.sandberg@arm.com.. code-block:: pycon 15211986Sandreas.sandberg@arm.com 15311986Sandreas.sandberg@arm.com $ python 15411986Sandreas.sandberg@arm.com Python 2.7.10 (default, Aug 22 2015, 20:33:39) 15511986Sandreas.sandberg@arm.com [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin 15611986Sandreas.sandberg@arm.com Type "help", "copyright", "credits" or "license" for more information. 15711986Sandreas.sandberg@arm.com >>> import example 15811986Sandreas.sandberg@arm.com >>> example.add(1, 2) 15911986Sandreas.sandberg@arm.com 3L 16011986Sandreas.sandberg@arm.com >>> 16111986Sandreas.sandberg@arm.com 16211986Sandreas.sandberg@arm.com.. _keyword_args: 16311986Sandreas.sandberg@arm.com 16411986Sandreas.sandberg@arm.comKeyword arguments 16511986Sandreas.sandberg@arm.com================= 16611986Sandreas.sandberg@arm.com 16711986Sandreas.sandberg@arm.comWith a simple modification code, it is possible to inform Python about the 16811986Sandreas.sandberg@arm.comnames of the arguments ("i" and "j" in this case). 16911986Sandreas.sandberg@arm.com 17011986Sandreas.sandberg@arm.com.. code-block:: cpp 17111986Sandreas.sandberg@arm.com 17211986Sandreas.sandberg@arm.com m.def("add", &add, "A function which adds two numbers", 17311986Sandreas.sandberg@arm.com py::arg("i"), py::arg("j")); 17411986Sandreas.sandberg@arm.com 17511986Sandreas.sandberg@arm.com:class:`arg` is one of several special tag classes which can be used to pass 17611986Sandreas.sandberg@arm.commetadata into :func:`module::def`. With this modified binding code, we can now 17711986Sandreas.sandberg@arm.comcall the function using keyword arguments, which is a more readable alternative 17811986Sandreas.sandberg@arm.comparticularly for functions taking many parameters: 17911986Sandreas.sandberg@arm.com 18011986Sandreas.sandberg@arm.com.. code-block:: pycon 18111986Sandreas.sandberg@arm.com 18211986Sandreas.sandberg@arm.com >>> import example 18311986Sandreas.sandberg@arm.com >>> example.add(i=1, j=2) 18411986Sandreas.sandberg@arm.com 3L 18511986Sandreas.sandberg@arm.com 18611986Sandreas.sandberg@arm.comThe keyword names also appear in the function signatures within the documentation. 18711986Sandreas.sandberg@arm.com 18811986Sandreas.sandberg@arm.com.. code-block:: pycon 18911986Sandreas.sandberg@arm.com 19011986Sandreas.sandberg@arm.com >>> help(example) 19111986Sandreas.sandberg@arm.com 19211986Sandreas.sandberg@arm.com .... 19311986Sandreas.sandberg@arm.com 19411986Sandreas.sandberg@arm.com FUNCTIONS 19511986Sandreas.sandberg@arm.com add(...) 19611986Sandreas.sandberg@arm.com Signature : (i: int, j: int) -> int 19711986Sandreas.sandberg@arm.com 19811986Sandreas.sandberg@arm.com A function which adds two numbers 19911986Sandreas.sandberg@arm.com 20011986Sandreas.sandberg@arm.comA shorter notation for named arguments is also available: 20111986Sandreas.sandberg@arm.com 20211986Sandreas.sandberg@arm.com.. code-block:: cpp 20311986Sandreas.sandberg@arm.com 20411986Sandreas.sandberg@arm.com // regular notation 20511986Sandreas.sandberg@arm.com m.def("add1", &add, py::arg("i"), py::arg("j")); 20611986Sandreas.sandberg@arm.com // shorthand 20711986Sandreas.sandberg@arm.com using namespace pybind11::literals; 20811986Sandreas.sandberg@arm.com m.def("add2", &add, "i"_a, "j"_a); 20911986Sandreas.sandberg@arm.com 21011986Sandreas.sandberg@arm.comThe :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`. 21111986Sandreas.sandberg@arm.comNote that the literal operator must first be made visible with the directive 21211986Sandreas.sandberg@arm.com``using namespace pybind11::literals``. This does not bring in anything else 21311986Sandreas.sandberg@arm.comfrom the ``pybind11`` namespace except for literals. 21411986Sandreas.sandberg@arm.com 21511986Sandreas.sandberg@arm.com.. _default_args: 21611986Sandreas.sandberg@arm.com 21711986Sandreas.sandberg@arm.comDefault arguments 21811986Sandreas.sandberg@arm.com================= 21911986Sandreas.sandberg@arm.com 22011986Sandreas.sandberg@arm.comSuppose now that the function to be bound has default arguments, e.g.: 22111986Sandreas.sandberg@arm.com 22211986Sandreas.sandberg@arm.com.. code-block:: cpp 22311986Sandreas.sandberg@arm.com 22411986Sandreas.sandberg@arm.com int add(int i = 1, int j = 2) { 22511986Sandreas.sandberg@arm.com return i + j; 22611986Sandreas.sandberg@arm.com } 22711986Sandreas.sandberg@arm.com 22811986Sandreas.sandberg@arm.comUnfortunately, pybind11 cannot automatically extract these parameters, since they 22911986Sandreas.sandberg@arm.comare not part of the function's type information. However, they are simple to specify 23011986Sandreas.sandberg@arm.comusing an extension of :class:`arg`: 23111986Sandreas.sandberg@arm.com 23211986Sandreas.sandberg@arm.com.. code-block:: cpp 23311986Sandreas.sandberg@arm.com 23411986Sandreas.sandberg@arm.com m.def("add", &add, "A function which adds two numbers", 23511986Sandreas.sandberg@arm.com py::arg("i") = 1, py::arg("j") = 2); 23611986Sandreas.sandberg@arm.com 23711986Sandreas.sandberg@arm.comThe default values also appear within the documentation. 23811986Sandreas.sandberg@arm.com 23911986Sandreas.sandberg@arm.com.. code-block:: pycon 24011986Sandreas.sandberg@arm.com 24111986Sandreas.sandberg@arm.com >>> help(example) 24211986Sandreas.sandberg@arm.com 24311986Sandreas.sandberg@arm.com .... 24411986Sandreas.sandberg@arm.com 24511986Sandreas.sandberg@arm.com FUNCTIONS 24611986Sandreas.sandberg@arm.com add(...) 24711986Sandreas.sandberg@arm.com Signature : (i: int = 1, j: int = 2) -> int 24811986Sandreas.sandberg@arm.com 24911986Sandreas.sandberg@arm.com A function which adds two numbers 25011986Sandreas.sandberg@arm.com 25111986Sandreas.sandberg@arm.comThe shorthand notation is also available for default arguments: 25211986Sandreas.sandberg@arm.com 25311986Sandreas.sandberg@arm.com.. code-block:: cpp 25411986Sandreas.sandberg@arm.com 25511986Sandreas.sandberg@arm.com // regular notation 25611986Sandreas.sandberg@arm.com m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2); 25711986Sandreas.sandberg@arm.com // shorthand 25811986Sandreas.sandberg@arm.com m.def("add2", &add, "i"_a=1, "j"_a=2); 25911986Sandreas.sandberg@arm.com 26011986Sandreas.sandberg@arm.comExporting variables 26111986Sandreas.sandberg@arm.com=================== 26211986Sandreas.sandberg@arm.com 26311986Sandreas.sandberg@arm.comTo expose a value from C++, use the ``attr`` function to register it in a 26411986Sandreas.sandberg@arm.commodule as shown below. Built-in types and general objects (more on that later) 26511986Sandreas.sandberg@arm.comare automatically converted when assigned as attributes, and can be explicitly 26611986Sandreas.sandberg@arm.comconverted using the function ``py::cast``. 26711986Sandreas.sandberg@arm.com 26811986Sandreas.sandberg@arm.com.. code-block:: cpp 26911986Sandreas.sandberg@arm.com 27012391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 27111986Sandreas.sandberg@arm.com m.attr("the_answer") = 42; 27211986Sandreas.sandberg@arm.com py::object world = py::cast("World"); 27311986Sandreas.sandberg@arm.com m.attr("what") = world; 27411986Sandreas.sandberg@arm.com } 27511986Sandreas.sandberg@arm.com 27611986Sandreas.sandberg@arm.comThese are then accessible from Python: 27711986Sandreas.sandberg@arm.com 27811986Sandreas.sandberg@arm.com.. code-block:: pycon 27911986Sandreas.sandberg@arm.com 28011986Sandreas.sandberg@arm.com >>> import example 28111986Sandreas.sandberg@arm.com >>> example.the_answer 28211986Sandreas.sandberg@arm.com 42 28311986Sandreas.sandberg@arm.com >>> example.what 28411986Sandreas.sandberg@arm.com 'World' 28511986Sandreas.sandberg@arm.com 28611986Sandreas.sandberg@arm.com.. _supported_types: 28711986Sandreas.sandberg@arm.com 28811986Sandreas.sandberg@arm.comSupported data types 28911986Sandreas.sandberg@arm.com==================== 29011986Sandreas.sandberg@arm.com 29111986Sandreas.sandberg@arm.comA large number of data types are supported out of the box and can be used 29211986Sandreas.sandberg@arm.comseamlessly as functions arguments, return values or with ``py::cast`` in general. 29311986Sandreas.sandberg@arm.comFor a full overview, see the :doc:`advanced/cast/index` section. 294