| Python types |
| ############ |
| |
| Available wrappers |
| ================== |
| |
| All major Python types are available as thin C++ wrapper classes. These |
| can also be used as function parameters -- see :ref:`python_objects_as_args`. |
| |
| Available types include :class:`handle`, :class:`object`, :class:`bool_`, |
| :class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, |
| :class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, |
| :class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, |
| :class:`array`, and :class:`array_t`. |
| |
| Casting back and forth |
| ====================== |
| |
| In this kind of mixed code, it is often necessary to convert arbitrary C++ |
| types to Python, which can be done using :func:`py::cast`: |
| |
| .. code-block:: cpp |
| |
| MyClass *cls = ..; |
| py::object obj = py::cast(cls); |
| |
| The reverse direction uses the following syntax: |
| |
| .. code-block:: cpp |
| |
| py::object obj = ...; |
| MyClass *cls = obj.cast<MyClass *>(); |
| |
| When conversion fails, both directions throw the exception :class:`cast_error`. |
| |
| .. _calling_python_functions: |
| |
| Calling Python functions |
| ======================== |
| |
| It is also possible to call python functions via ``operator()``. |
| |
| .. code-block:: cpp |
| |
| py::function f = <...>; |
| py::object result_py = f(1234, "hello", some_instance); |
| MyClass &result = result_py.cast<MyClass>(); |
| |
| Keyword arguments are also supported. In Python, there is the usual call syntax: |
| |
| .. code-block:: python |
| |
| def f(number, say, to): |
| ... # function code |
| |
| f(1234, say="hello", to=some_instance) # keyword call in Python |
| |
| In C++, the same call can be made using: |
| |
| .. code-block:: cpp |
| |
| using namespace pybind11::literals; // to bring in the `_a` literal |
| f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ |
| |
| Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with |
| other arguments: |
| |
| .. code-block:: cpp |
| |
| // * unpacking |
| py::tuple args = py::make_tuple(1234, "hello", some_instance); |
| f(*args); |
| |
| // ** unpacking |
| py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); |
| f(**kwargs); |
| |
| // mixed keywords, * and ** unpacking |
| py::tuple args = py::make_tuple(1234); |
| py::dict kwargs = py::dict("to"_a=some_instance); |
| f(*args, "say"_a="hello", **kwargs); |
| |
| Generalized unpacking according to PEP448_ is also supported: |
| |
| .. code-block:: cpp |
| |
| py::dict kwargs1 = py::dict("number"_a=1234); |
| py::dict kwargs2 = py::dict("to"_a=some_instance); |
| f(**kwargs1, "say"_a="hello", **kwargs2); |
| |
| .. seealso:: |
| |
| The file :file:`tests/test_python_types.cpp` contains a complete |
| example that demonstrates passing native Python types in more detail. The |
| file :file:`tests/test_callbacks.cpp` presents a few examples of calling |
| Python functions from C++, including keywords arguments and unpacking. |
| |
| .. _PEP448: https://www.python.org/dev/peps/pep-0448/ |