c79706ff4c
Change-Id: I52e4fc9ebf2f59da57d8cf8f3e37cc79598c2f5f Signed-off-by: Andreas Sandberg <andreas.sandberg@arm.com> Reviewed-by: Andreas Hansson <andreas.hansson@arm.com> Reviewed-by: Curtis Dunham <curtis.dunham@arm.com> Reviewed-on: https://gem5-review.googlesource.com/2229 Reviewed-by: Tony Gutierrez <anthony.gutierrez@amd.com> Reviewed-by: Jason Lowe-Power <jason@lowepower.com> Reviewed-by: Pierre-Yves Péneau <pierre-yves.peneau@lirmm.fr>
97 lines
2.8 KiB
ReStructuredText
97 lines
2.8 KiB
ReStructuredText
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
|
|
========================
|
|
|
|
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 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/
|