object.rst revision 12037
1Python types 2############ 3 4Available wrappers 5================== 6 7All major Python types are available as thin C++ wrapper classes. These 8can also be used as function parameters -- see :ref:`python_objects_as_args`. 9 10Available types include :class:`handle`, :class:`object`, :class:`bool_`, 11:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, 12:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, 13:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, 14:class:`array`, and :class:`array_t`. 15 16Casting back and forth 17====================== 18 19In this kind of mixed code, it is often necessary to convert arbitrary C++ 20types to Python, which can be done using :func:`py::cast`: 21 22.. code-block:: cpp 23 24 MyClass *cls = ..; 25 py::object obj = py::cast(cls); 26 27The reverse direction uses the following syntax: 28 29.. code-block:: cpp 30 31 py::object obj = ...; 32 MyClass *cls = obj.cast<MyClass *>(); 33 34When conversion fails, both directions throw the exception :class:`cast_error`. 35 36.. _calling_python_functions: 37 38Calling Python functions 39======================== 40 41It is also possible to call python functions via ``operator()``. 42 43.. code-block:: cpp 44 45 py::function f = <...>; 46 py::object result_py = f(1234, "hello", some_instance); 47 MyClass &result = result_py.cast<MyClass>(); 48 49Keyword arguments are also supported. In Python, there is the usual call syntax: 50 51.. code-block:: python 52 53 def f(number, say, to): 54 ... # function code 55 56 f(1234, say="hello", to=some_instance) # keyword call in Python 57 58In C++, the same call can be made using: 59 60.. code-block:: cpp 61 62 using namespace pybind11::literals; // to bring in the `_a` literal 63 f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ 64 65Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with 66other arguments: 67 68.. code-block:: cpp 69 70 // * unpacking 71 py::tuple args = py::make_tuple(1234, "hello", some_instance); 72 f(*args); 73 74 // ** unpacking 75 py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); 76 f(**kwargs); 77 78 // mixed keywords, * and ** unpacking 79 py::tuple args = py::make_tuple(1234); 80 py::dict kwargs = py::dict("to"_a=some_instance); 81 f(*args, "say"_a="hello", **kwargs); 82 83Generalized unpacking according to PEP448_ is also supported: 84 85.. code-block:: cpp 86 87 py::dict kwargs1 = py::dict("number"_a=1234); 88 py::dict kwargs2 = py::dict("to"_a=some_instance); 89 f(**kwargs1, "say"_a="hello", **kwargs2); 90 91.. seealso:: 92 93 The file :file:`tests/test_python_types.cpp` contains a complete 94 example that demonstrates passing native Python types in more detail. The 95 file :file:`tests/test_callbacks.cpp` presents a few examples of calling 96 Python functions from C++, including keywords arguments and unpacking. 97 98.. _PEP448: https://www.python.org/dev/peps/pep-0448/ 99