Python types

Available wrappers

All major Python types are available as thin C++ wrapper classes. These can also be used as function parameters – see Python objects as arguments.

Available types include handle, object, bool_, int_, float_, str, bytes, tuple, list, dict, slice, none, capsule, iterable, iterator, function, buffer, array, and 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 py::cast():

MyClass *cls = ..;
py::object obj = py::cast(cls);

The reverse direction uses the following syntax:

py::object obj = ...;
MyClass *cls = obj.cast<MyClass *>();

When conversion fails, both directions throw the exception cast_error.

Calling Python functions

It is also possible to call python functions via operator().

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:

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:

using 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:

// * unpacking
py::tuple args = py::make_tuple(1234, "hello", some_instance);

// ** unpacking
py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance);

// 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:

py::dict kwargs1 = py::dict("number"_a=1234);
py::dict kwargs2 = py::dict("to"_a=some_instance);
f(**kwargs1, "say"_a="hello", **kwargs2);

See also

The file tests/test_python_types.cpp contains a complete example that demonstrates passing native Python types in more detail. The file tests/test_callbacks.cpp presents a few examples of calling Python functions from C++, including keywords arguments and unpacking.