object.rst revision 12037
11689SN/APython types 22325SN/A############ 31689SN/A 41689SN/AAvailable wrappers 51689SN/A================== 61689SN/A 71689SN/AAll major Python types are available as thin C++ wrapper classes. These 81689SN/Acan also be used as function parameters -- see :ref:`python_objects_as_args`. 91689SN/A 101689SN/AAvailable types include :class:`handle`, :class:`object`, :class:`bool_`, 111689SN/A:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, 121689SN/A:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, 131689SN/A:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, 141689SN/A:class:`array`, and :class:`array_t`. 151689SN/A 161689SN/ACasting back and forth 171689SN/A====================== 181689SN/A 191689SN/AIn this kind of mixed code, it is often necessary to convert arbitrary C++ 201689SN/Atypes to Python, which can be done using :func:`py::cast`: 211689SN/A 221689SN/A.. code-block:: cpp 231689SN/A 241689SN/A MyClass *cls = ..; 251689SN/A py::object obj = py::cast(cls); 261689SN/A 272665Ssaidi@eecs.umich.eduThe reverse direction uses the following syntax: 282665Ssaidi@eecs.umich.edu 292756Sksewell@umich.edu.. code-block:: cpp 301689SN/A 311689SN/A py::object obj = ...; 321858SN/A MyClass *cls = obj.cast<MyClass *>(); 332733Sktlim@umich.edu 341858SN/AWhen conversion fails, both directions throw the exception :class:`cast_error`. 351858SN/A 361060SN/A.. _calling_python_functions: 371060SN/A 381060SN/ACalling Python functions 391060SN/A======================== 401060SN/A 412325SN/AIt is also possible to call python functions via ``operator()``. 422683Sktlim@umich.edu 432680Sktlim@umich.edu.. code-block:: cpp 442817Sksewell@umich.edu 451717SN/A py::function f = <...>; 461060SN/A py::object result_py = f(1234, "hello", some_instance); 472325SN/A MyClass &result = result_py.cast<MyClass>(); 482292SN/A 492292SN/AKeyword arguments are also supported. In Python, there is the usual call syntax: 502794Sktlim@umich.edu 512794Sktlim@umich.edu.. code-block:: python 522794Sktlim@umich.edu 532794Sktlim@umich.edu def f(number, say, to): 541060SN/A ... # function code 552669Sktlim@umich.edu 561060SN/A f(1234, say="hello", to=some_instance) # keyword call in Python 572733Sktlim@umich.edu 582292SN/AIn C++, the same call can be made using: 591060SN/A 601060SN/A.. code-block:: cpp 611060SN/A 622292SN/A using namespace pybind11::literals; // to bring in the `_a` literal 632733Sktlim@umich.edu f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ 642292SN/A 652292SN/AUnpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with 662292SN/Aother arguments: 672292SN/A 681060SN/A.. code-block:: cpp 691755SN/A 701060SN/A // * unpacking 711060SN/A py::tuple args = py::make_tuple(1234, "hello", some_instance); 721060SN/A f(*args); 731060SN/A 741060SN/A // ** unpacking 751060SN/A py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); 761755SN/A f(**kwargs); 771060SN/A 781060SN/A // mixed keywords, * and ** unpacking 791060SN/A py::tuple args = py::make_tuple(1234); 801060SN/A py::dict kwargs = py::dict("to"_a=some_instance); 811060SN/A f(*args, "say"_a="hello", **kwargs); 821060SN/A 831755SN/AGeneralized unpacking according to PEP448_ is also supported: 841060SN/A 851755SN/A.. code-block:: cpp 861060SN/A 871060SN/A py::dict kwargs1 = py::dict("number"_a=1234); 881060SN/A py::dict kwargs2 = py::dict("to"_a=some_instance); 892829Sksewell@umich.edu f(**kwargs1, "say"_a="hello", **kwargs2); 902829Sksewell@umich.edu 912829Sksewell@umich.edu.. seealso:: 922829Sksewell@umich.edu 932829Sksewell@umich.edu The file :file:`tests/test_python_types.cpp` contains a complete 942829Sksewell@umich.edu example that demonstrates passing native Python types in more detail. The 952829Sksewell@umich.edu file :file:`tests/test_callbacks.cpp` presents a few examples of calling 962829Sksewell@umich.edu Python functions from C++, including keywords arguments and unpacking. 972829Sksewell@umich.edu 982829Sksewell@umich.edu.. _PEP448: https://www.python.org/dev/peps/pep-0448/ 992829Sksewell@umich.edu