object.rst revision 12037
111986Sandreas.sandberg@arm.comPython types 211986Sandreas.sandberg@arm.com############ 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comAvailable wrappers 511986Sandreas.sandberg@arm.com================== 611986Sandreas.sandberg@arm.com 711986Sandreas.sandberg@arm.comAll major Python types are available as thin C++ wrapper classes. These 811986Sandreas.sandberg@arm.comcan also be used as function parameters -- see :ref:`python_objects_as_args`. 911986Sandreas.sandberg@arm.com 1011986Sandreas.sandberg@arm.comAvailable types include :class:`handle`, :class:`object`, :class:`bool_`, 1111986Sandreas.sandberg@arm.com:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, 1211986Sandreas.sandberg@arm.com:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, 1311986Sandreas.sandberg@arm.com:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, 1411986Sandreas.sandberg@arm.com:class:`array`, and :class:`array_t`. 1511986Sandreas.sandberg@arm.com 1611986Sandreas.sandberg@arm.comCasting back and forth 1711986Sandreas.sandberg@arm.com====================== 1811986Sandreas.sandberg@arm.com 1911986Sandreas.sandberg@arm.comIn this kind of mixed code, it is often necessary to convert arbitrary C++ 2011986Sandreas.sandberg@arm.comtypes to Python, which can be done using :func:`py::cast`: 2111986Sandreas.sandberg@arm.com 2211986Sandreas.sandberg@arm.com.. code-block:: cpp 2311986Sandreas.sandberg@arm.com 2411986Sandreas.sandberg@arm.com MyClass *cls = ..; 2511986Sandreas.sandberg@arm.com py::object obj = py::cast(cls); 2611986Sandreas.sandberg@arm.com 2711986Sandreas.sandberg@arm.comThe reverse direction uses the following syntax: 2811986Sandreas.sandberg@arm.com 2911986Sandreas.sandberg@arm.com.. code-block:: cpp 3011986Sandreas.sandberg@arm.com 3111986Sandreas.sandberg@arm.com py::object obj = ...; 3211986Sandreas.sandberg@arm.com MyClass *cls = obj.cast<MyClass *>(); 3311986Sandreas.sandberg@arm.com 3411986Sandreas.sandberg@arm.comWhen conversion fails, both directions throw the exception :class:`cast_error`. 3511986Sandreas.sandberg@arm.com 3612037Sandreas.sandberg@arm.com.. _calling_python_functions: 3712037Sandreas.sandberg@arm.com 3811986Sandreas.sandberg@arm.comCalling Python functions 3911986Sandreas.sandberg@arm.com======================== 4011986Sandreas.sandberg@arm.com 4111986Sandreas.sandberg@arm.comIt is also possible to call python functions via ``operator()``. 4211986Sandreas.sandberg@arm.com 4311986Sandreas.sandberg@arm.com.. code-block:: cpp 4411986Sandreas.sandberg@arm.com 4511986Sandreas.sandberg@arm.com py::function f = <...>; 4611986Sandreas.sandberg@arm.com py::object result_py = f(1234, "hello", some_instance); 4711986Sandreas.sandberg@arm.com MyClass &result = result_py.cast<MyClass>(); 4811986Sandreas.sandberg@arm.com 4911986Sandreas.sandberg@arm.comKeyword arguments are also supported. In Python, there is the usual call syntax: 5011986Sandreas.sandberg@arm.com 5111986Sandreas.sandberg@arm.com.. code-block:: python 5211986Sandreas.sandberg@arm.com 5311986Sandreas.sandberg@arm.com def f(number, say, to): 5411986Sandreas.sandberg@arm.com ... # function code 5511986Sandreas.sandberg@arm.com 5611986Sandreas.sandberg@arm.com f(1234, say="hello", to=some_instance) # keyword call in Python 5711986Sandreas.sandberg@arm.com 5811986Sandreas.sandberg@arm.comIn C++, the same call can be made using: 5911986Sandreas.sandberg@arm.com 6011986Sandreas.sandberg@arm.com.. code-block:: cpp 6111986Sandreas.sandberg@arm.com 6212037Sandreas.sandberg@arm.com using namespace pybind11::literals; // to bring in the `_a` literal 6311986Sandreas.sandberg@arm.com f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ 6411986Sandreas.sandberg@arm.com 6511986Sandreas.sandberg@arm.comUnpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with 6611986Sandreas.sandberg@arm.comother arguments: 6711986Sandreas.sandberg@arm.com 6811986Sandreas.sandberg@arm.com.. code-block:: cpp 6911986Sandreas.sandberg@arm.com 7011986Sandreas.sandberg@arm.com // * unpacking 7111986Sandreas.sandberg@arm.com py::tuple args = py::make_tuple(1234, "hello", some_instance); 7211986Sandreas.sandberg@arm.com f(*args); 7311986Sandreas.sandberg@arm.com 7411986Sandreas.sandberg@arm.com // ** unpacking 7511986Sandreas.sandberg@arm.com py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); 7611986Sandreas.sandberg@arm.com f(**kwargs); 7711986Sandreas.sandberg@arm.com 7811986Sandreas.sandberg@arm.com // mixed keywords, * and ** unpacking 7911986Sandreas.sandberg@arm.com py::tuple args = py::make_tuple(1234); 8011986Sandreas.sandberg@arm.com py::dict kwargs = py::dict("to"_a=some_instance); 8111986Sandreas.sandberg@arm.com f(*args, "say"_a="hello", **kwargs); 8211986Sandreas.sandberg@arm.com 8311986Sandreas.sandberg@arm.comGeneralized unpacking according to PEP448_ is also supported: 8411986Sandreas.sandberg@arm.com 8511986Sandreas.sandberg@arm.com.. code-block:: cpp 8611986Sandreas.sandberg@arm.com 8711986Sandreas.sandberg@arm.com py::dict kwargs1 = py::dict("number"_a=1234); 8811986Sandreas.sandberg@arm.com py::dict kwargs2 = py::dict("to"_a=some_instance); 8911986Sandreas.sandberg@arm.com f(**kwargs1, "say"_a="hello", **kwargs2); 9011986Sandreas.sandberg@arm.com 9111986Sandreas.sandberg@arm.com.. seealso:: 9211986Sandreas.sandberg@arm.com 9311986Sandreas.sandberg@arm.com The file :file:`tests/test_python_types.cpp` contains a complete 9411986Sandreas.sandberg@arm.com example that demonstrates passing native Python types in more detail. The 9511986Sandreas.sandberg@arm.com file :file:`tests/test_callbacks.cpp` presents a few examples of calling 9611986Sandreas.sandberg@arm.com Python functions from C++, including keywords arguments and unpacking. 9711986Sandreas.sandberg@arm.com 9811986Sandreas.sandberg@arm.com.. _PEP448: https://www.python.org/dev/peps/pep-0448/ 99