object.rst revision 11986
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 36Calling Python functions 37======================== 38 39It is also possible to call python functions via ``operator()``. 40 41.. code-block:: cpp 42 43 py::function f = <...>; 44 py::object result_py = f(1234, "hello", some_instance); 45 MyClass &result = result_py.cast<MyClass>(); 46 47Keyword arguments are also supported. In Python, there is the usual call syntax: 48 49.. code-block:: python 50 51 def f(number, say, to): 52 ... # function code 53 54 f(1234, say="hello", to=some_instance) # keyword call in Python 55 56In C++, the same call can be made using: 57 58.. code-block:: cpp 59 60 using pybind11::literals; // to bring in the `_a` literal 61 f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ 62 63Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with 64other arguments: 65 66.. code-block:: cpp 67 68 // * unpacking 69 py::tuple args = py::make_tuple(1234, "hello", some_instance); 70 f(*args); 71 72 // ** unpacking 73 py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); 74 f(**kwargs); 75 76 // mixed keywords, * and ** unpacking 77 py::tuple args = py::make_tuple(1234); 78 py::dict kwargs = py::dict("to"_a=some_instance); 79 f(*args, "say"_a="hello", **kwargs); 80 81Generalized unpacking according to PEP448_ is also supported: 82 83.. code-block:: cpp 84 85 py::dict kwargs1 = py::dict("number"_a=1234); 86 py::dict kwargs2 = py::dict("to"_a=some_instance); 87 f(**kwargs1, "say"_a="hello", **kwargs2); 88 89.. seealso:: 90 91 The file :file:`tests/test_python_types.cpp` contains a complete 92 example that demonstrates passing native Python types in more detail. The 93 file :file:`tests/test_callbacks.cpp` presents a few examples of calling 94 Python functions from C++, including keywords arguments and unpacking. 95 96.. _PEP448: https://www.python.org/dev/peps/pep-0448/ 97