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
| 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
|
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
| 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
|
60 using pybind11::literals; // to bring in the `_a` literal
| 62 using namespace 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/
| 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/
|