basics.rst revision 11986
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 .. 2811986Sandreas.sandberg@arm.com make pytest -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 .. 4511986Sandreas.sandberg@arm.com cmake --build . --config Release --target pytest 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 7611986Sandreas.sandberg@arm.comCreating bindings for a simple function 7711986Sandreas.sandberg@arm.com======================================= 7811986Sandreas.sandberg@arm.com 7911986Sandreas.sandberg@arm.comLet's start by creating Python bindings for an extremely simple function, which 8011986Sandreas.sandberg@arm.comadds two numbers and returns their result: 8111986Sandreas.sandberg@arm.com 8211986Sandreas.sandberg@arm.com.. code-block:: cpp 8311986Sandreas.sandberg@arm.com 8411986Sandreas.sandberg@arm.com int add(int i, int j) { 8511986Sandreas.sandberg@arm.com return i + j; 8611986Sandreas.sandberg@arm.com } 8711986Sandreas.sandberg@arm.com 8811986Sandreas.sandberg@arm.comFor simplicity [#f1]_, we'll put both this function and the binding code into 8911986Sandreas.sandberg@arm.coma file named :file:`example.cpp` with the following contents: 9011986Sandreas.sandberg@arm.com 9111986Sandreas.sandberg@arm.com.. code-block:: cpp 9211986Sandreas.sandberg@arm.com 9311986Sandreas.sandberg@arm.com #include <pybind11/pybind11.h> 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.com int add(int i, int j) { 9611986Sandreas.sandberg@arm.com return i + j; 9711986Sandreas.sandberg@arm.com } 9811986Sandreas.sandberg@arm.com 9911986Sandreas.sandberg@arm.com namespace py = pybind11; 10011986Sandreas.sandberg@arm.com 10111986Sandreas.sandberg@arm.com PYBIND11_PLUGIN(example) { 10211986Sandreas.sandberg@arm.com py::module m("example", "pybind11 example plugin"); 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 return m.ptr(); 10711986Sandreas.sandberg@arm.com } 10811986Sandreas.sandberg@arm.com 10911986Sandreas.sandberg@arm.com.. [#f1] In practice, implementation and binding code will generally be located 11011986Sandreas.sandberg@arm.com in separate files. 11111986Sandreas.sandberg@arm.com 11211986Sandreas.sandberg@arm.comThe :func:`PYBIND11_PLUGIN` macro creates a function that will be called when an 11311986Sandreas.sandberg@arm.com``import`` statement is issued from within Python. The next line creates a 11411986Sandreas.sandberg@arm.commodule named ``example`` (with the supplied docstring). The method 11511986Sandreas.sandberg@arm.com:func:`module::def` generates binding code that exposes the 11611986Sandreas.sandberg@arm.com``add()`` function to Python. The last line returns the internal Python object 11711986Sandreas.sandberg@arm.comassociated with ``m`` to the Python interpreter. 11811986Sandreas.sandberg@arm.com 11911986Sandreas.sandberg@arm.com.. note:: 12011986Sandreas.sandberg@arm.com 12111986Sandreas.sandberg@arm.com Notice how little code was needed to expose our function to Python: all 12211986Sandreas.sandberg@arm.com details regarding the function's parameters and return value were 12311986Sandreas.sandberg@arm.com automatically inferred using template metaprogramming. This overall 12411986Sandreas.sandberg@arm.com approach and the used syntax are borrowed from Boost.Python, though the 12511986Sandreas.sandberg@arm.com underlying implementation is very different. 12611986Sandreas.sandberg@arm.com 12711986Sandreas.sandberg@arm.compybind11 is a header-only-library, hence it is not necessary to link against 12811986Sandreas.sandberg@arm.comany special libraries (other than Python itself). On Windows, use the CMake 12911986Sandreas.sandberg@arm.combuild file discussed in section :ref:`cmake`. On Linux and Mac OS, the above 13011986Sandreas.sandberg@arm.comexample can be compiled using the following command 13111986Sandreas.sandberg@arm.com 13211986Sandreas.sandberg@arm.com.. code-block:: bash 13311986Sandreas.sandberg@arm.com 13411986Sandreas.sandberg@arm.com $ c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` example.cpp -o example.so 13511986Sandreas.sandberg@arm.com 13611986Sandreas.sandberg@arm.comIn general, it is advisable to include several additional build parameters 13711986Sandreas.sandberg@arm.comthat can considerably reduce the size of the created binary. Refer to section 13811986Sandreas.sandberg@arm.com:ref:`cmake` for a detailed example of a suitable cross-platform CMake-based 13911986Sandreas.sandberg@arm.combuild system. 14011986Sandreas.sandberg@arm.com 14111986Sandreas.sandberg@arm.comAssuming that the created file :file:`example.so` (:file:`example.pyd` on Windows) 14211986Sandreas.sandberg@arm.comis located in the current directory, the following interactive Python session 14311986Sandreas.sandberg@arm.comshows how to load and execute the example. 14411986Sandreas.sandberg@arm.com 14511986Sandreas.sandberg@arm.com.. code-block:: pycon 14611986Sandreas.sandberg@arm.com 14711986Sandreas.sandberg@arm.com $ python 14811986Sandreas.sandberg@arm.com Python 2.7.10 (default, Aug 22 2015, 20:33:39) 14911986Sandreas.sandberg@arm.com [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin 15011986Sandreas.sandberg@arm.com Type "help", "copyright", "credits" or "license" for more information. 15111986Sandreas.sandberg@arm.com >>> import example 15211986Sandreas.sandberg@arm.com >>> example.add(1, 2) 15311986Sandreas.sandberg@arm.com 3L 15411986Sandreas.sandberg@arm.com >>> 15511986Sandreas.sandberg@arm.com 15611986Sandreas.sandberg@arm.com.. _keyword_args: 15711986Sandreas.sandberg@arm.com 15811986Sandreas.sandberg@arm.comKeyword arguments 15911986Sandreas.sandberg@arm.com================= 16011986Sandreas.sandberg@arm.com 16111986Sandreas.sandberg@arm.comWith a simple modification code, it is possible to inform Python about the 16211986Sandreas.sandberg@arm.comnames of the arguments ("i" and "j" in this case). 16311986Sandreas.sandberg@arm.com 16411986Sandreas.sandberg@arm.com.. code-block:: cpp 16511986Sandreas.sandberg@arm.com 16611986Sandreas.sandberg@arm.com m.def("add", &add, "A function which adds two numbers", 16711986Sandreas.sandberg@arm.com py::arg("i"), py::arg("j")); 16811986Sandreas.sandberg@arm.com 16911986Sandreas.sandberg@arm.com:class:`arg` is one of several special tag classes which can be used to pass 17011986Sandreas.sandberg@arm.commetadata into :func:`module::def`. With this modified binding code, we can now 17111986Sandreas.sandberg@arm.comcall the function using keyword arguments, which is a more readable alternative 17211986Sandreas.sandberg@arm.comparticularly for functions taking many parameters: 17311986Sandreas.sandberg@arm.com 17411986Sandreas.sandberg@arm.com.. code-block:: pycon 17511986Sandreas.sandberg@arm.com 17611986Sandreas.sandberg@arm.com >>> import example 17711986Sandreas.sandberg@arm.com >>> example.add(i=1, j=2) 17811986Sandreas.sandberg@arm.com 3L 17911986Sandreas.sandberg@arm.com 18011986Sandreas.sandberg@arm.comThe keyword names also appear in the function signatures within the documentation. 18111986Sandreas.sandberg@arm.com 18211986Sandreas.sandberg@arm.com.. code-block:: pycon 18311986Sandreas.sandberg@arm.com 18411986Sandreas.sandberg@arm.com >>> help(example) 18511986Sandreas.sandberg@arm.com 18611986Sandreas.sandberg@arm.com .... 18711986Sandreas.sandberg@arm.com 18811986Sandreas.sandberg@arm.com FUNCTIONS 18911986Sandreas.sandberg@arm.com add(...) 19011986Sandreas.sandberg@arm.com Signature : (i: int, j: int) -> int 19111986Sandreas.sandberg@arm.com 19211986Sandreas.sandberg@arm.com A function which adds two numbers 19311986Sandreas.sandberg@arm.com 19411986Sandreas.sandberg@arm.comA shorter notation for named arguments is also available: 19511986Sandreas.sandberg@arm.com 19611986Sandreas.sandberg@arm.com.. code-block:: cpp 19711986Sandreas.sandberg@arm.com 19811986Sandreas.sandberg@arm.com // regular notation 19911986Sandreas.sandberg@arm.com m.def("add1", &add, py::arg("i"), py::arg("j")); 20011986Sandreas.sandberg@arm.com // shorthand 20111986Sandreas.sandberg@arm.com using namespace pybind11::literals; 20211986Sandreas.sandberg@arm.com m.def("add2", &add, "i"_a, "j"_a); 20311986Sandreas.sandberg@arm.com 20411986Sandreas.sandberg@arm.comThe :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`. 20511986Sandreas.sandberg@arm.comNote that the literal operator must first be made visible with the directive 20611986Sandreas.sandberg@arm.com``using namespace pybind11::literals``. This does not bring in anything else 20711986Sandreas.sandberg@arm.comfrom the ``pybind11`` namespace except for literals. 20811986Sandreas.sandberg@arm.com 20911986Sandreas.sandberg@arm.com.. _default_args: 21011986Sandreas.sandberg@arm.com 21111986Sandreas.sandberg@arm.comDefault arguments 21211986Sandreas.sandberg@arm.com================= 21311986Sandreas.sandberg@arm.com 21411986Sandreas.sandberg@arm.comSuppose now that the function to be bound has default arguments, e.g.: 21511986Sandreas.sandberg@arm.com 21611986Sandreas.sandberg@arm.com.. code-block:: cpp 21711986Sandreas.sandberg@arm.com 21811986Sandreas.sandberg@arm.com int add(int i = 1, int j = 2) { 21911986Sandreas.sandberg@arm.com return i + j; 22011986Sandreas.sandberg@arm.com } 22111986Sandreas.sandberg@arm.com 22211986Sandreas.sandberg@arm.comUnfortunately, pybind11 cannot automatically extract these parameters, since they 22311986Sandreas.sandberg@arm.comare not part of the function's type information. However, they are simple to specify 22411986Sandreas.sandberg@arm.comusing an extension of :class:`arg`: 22511986Sandreas.sandberg@arm.com 22611986Sandreas.sandberg@arm.com.. code-block:: cpp 22711986Sandreas.sandberg@arm.com 22811986Sandreas.sandberg@arm.com m.def("add", &add, "A function which adds two numbers", 22911986Sandreas.sandberg@arm.com py::arg("i") = 1, py::arg("j") = 2); 23011986Sandreas.sandberg@arm.com 23111986Sandreas.sandberg@arm.comThe default values also appear within the documentation. 23211986Sandreas.sandberg@arm.com 23311986Sandreas.sandberg@arm.com.. code-block:: pycon 23411986Sandreas.sandberg@arm.com 23511986Sandreas.sandberg@arm.com >>> help(example) 23611986Sandreas.sandberg@arm.com 23711986Sandreas.sandberg@arm.com .... 23811986Sandreas.sandberg@arm.com 23911986Sandreas.sandberg@arm.com FUNCTIONS 24011986Sandreas.sandberg@arm.com add(...) 24111986Sandreas.sandberg@arm.com Signature : (i: int = 1, j: int = 2) -> int 24211986Sandreas.sandberg@arm.com 24311986Sandreas.sandberg@arm.com A function which adds two numbers 24411986Sandreas.sandberg@arm.com 24511986Sandreas.sandberg@arm.comThe shorthand notation is also available for default arguments: 24611986Sandreas.sandberg@arm.com 24711986Sandreas.sandberg@arm.com.. code-block:: cpp 24811986Sandreas.sandberg@arm.com 24911986Sandreas.sandberg@arm.com // regular notation 25011986Sandreas.sandberg@arm.com m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2); 25111986Sandreas.sandberg@arm.com // shorthand 25211986Sandreas.sandberg@arm.com m.def("add2", &add, "i"_a=1, "j"_a=2); 25311986Sandreas.sandberg@arm.com 25411986Sandreas.sandberg@arm.comExporting variables 25511986Sandreas.sandberg@arm.com=================== 25611986Sandreas.sandberg@arm.com 25711986Sandreas.sandberg@arm.comTo expose a value from C++, use the ``attr`` function to register it in a 25811986Sandreas.sandberg@arm.commodule as shown below. Built-in types and general objects (more on that later) 25911986Sandreas.sandberg@arm.comare automatically converted when assigned as attributes, and can be explicitly 26011986Sandreas.sandberg@arm.comconverted using the function ``py::cast``. 26111986Sandreas.sandberg@arm.com 26211986Sandreas.sandberg@arm.com.. code-block:: cpp 26311986Sandreas.sandberg@arm.com 26411986Sandreas.sandberg@arm.com PYBIND11_PLUGIN(example) { 26511986Sandreas.sandberg@arm.com py::module m("example", "pybind11 example plugin"); 26611986Sandreas.sandberg@arm.com m.attr("the_answer") = 42; 26711986Sandreas.sandberg@arm.com py::object world = py::cast("World"); 26811986Sandreas.sandberg@arm.com m.attr("what") = world; 26911986Sandreas.sandberg@arm.com return m.ptr(); 27011986Sandreas.sandberg@arm.com } 27111986Sandreas.sandberg@arm.com 27211986Sandreas.sandberg@arm.comThese are then accessible from Python: 27311986Sandreas.sandberg@arm.com 27411986Sandreas.sandberg@arm.com.. code-block:: pycon 27511986Sandreas.sandberg@arm.com 27611986Sandreas.sandberg@arm.com >>> import example 27711986Sandreas.sandberg@arm.com >>> example.the_answer 27811986Sandreas.sandberg@arm.com 42 27911986Sandreas.sandberg@arm.com >>> example.what 28011986Sandreas.sandberg@arm.com 'World' 28111986Sandreas.sandberg@arm.com 28211986Sandreas.sandberg@arm.com.. _supported_types: 28311986Sandreas.sandberg@arm.com 28411986Sandreas.sandberg@arm.comSupported data types 28511986Sandreas.sandberg@arm.com==================== 28611986Sandreas.sandberg@arm.com 28711986Sandreas.sandberg@arm.comA large number of data types are supported out of the box and can be used 28811986Sandreas.sandberg@arm.comseamlessly as functions arguments, return values or with ``py::cast`` in general. 28911986Sandreas.sandberg@arm.comFor a full overview, see the :doc:`advanced/cast/index` section. 290