object.rst revision 12391
111986Sandreas.sandberg@arm.comPython types 211986Sandreas.sandberg@arm.com############ 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comAvailable wrappers 511986Sandreas.sandberg@arm.com================== 611986Sandreas.sandberg@arm.com 711986Sandreas.sandberg@arm.comAll major Python types are available as thin C++ wrapper classes. These 811986Sandreas.sandberg@arm.comcan also be used as function parameters -- see :ref:`python_objects_as_args`. 911986Sandreas.sandberg@arm.com 1011986Sandreas.sandberg@arm.comAvailable types include :class:`handle`, :class:`object`, :class:`bool_`, 1111986Sandreas.sandberg@arm.com:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, 1211986Sandreas.sandberg@arm.com:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, 1311986Sandreas.sandberg@arm.com:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, 1411986Sandreas.sandberg@arm.com:class:`array`, and :class:`array_t`. 1511986Sandreas.sandberg@arm.com 1611986Sandreas.sandberg@arm.comCasting back and forth 1711986Sandreas.sandberg@arm.com====================== 1811986Sandreas.sandberg@arm.com 1911986Sandreas.sandberg@arm.comIn this kind of mixed code, it is often necessary to convert arbitrary C++ 2011986Sandreas.sandberg@arm.comtypes to Python, which can be done using :func:`py::cast`: 2111986Sandreas.sandberg@arm.com 2211986Sandreas.sandberg@arm.com.. code-block:: cpp 2311986Sandreas.sandberg@arm.com 2411986Sandreas.sandberg@arm.com MyClass *cls = ..; 2511986Sandreas.sandberg@arm.com py::object obj = py::cast(cls); 2611986Sandreas.sandberg@arm.com 2711986Sandreas.sandberg@arm.comThe reverse direction uses the following syntax: 2811986Sandreas.sandberg@arm.com 2911986Sandreas.sandberg@arm.com.. code-block:: cpp 3011986Sandreas.sandberg@arm.com 3111986Sandreas.sandberg@arm.com py::object obj = ...; 3211986Sandreas.sandberg@arm.com MyClass *cls = obj.cast<MyClass *>(); 3311986Sandreas.sandberg@arm.com 3411986Sandreas.sandberg@arm.comWhen conversion fails, both directions throw the exception :class:`cast_error`. 3511986Sandreas.sandberg@arm.com 3612391Sjason@lowepower.com.. _python_libs: 3712391Sjason@lowepower.com 3812391Sjason@lowepower.comAccessing Python libraries from C++ 3912391Sjason@lowepower.com=================================== 4012391Sjason@lowepower.com 4112391Sjason@lowepower.comIt is also possible to import objects defined in the Python standard 4212391Sjason@lowepower.comlibrary or available in the current Python environment (``sys.path``) and work 4312391Sjason@lowepower.comwith these in C++. 4412391Sjason@lowepower.com 4512391Sjason@lowepower.comThis example obtains a reference to the Python ``Decimal`` class. 4612391Sjason@lowepower.com 4712391Sjason@lowepower.com.. code-block:: cpp 4812391Sjason@lowepower.com 4912391Sjason@lowepower.com // Equivalent to "from decimal import Decimal" 5012391Sjason@lowepower.com py::object Decimal = py::module::import("decimal").attr("Decimal"); 5112391Sjason@lowepower.com 5212391Sjason@lowepower.com.. code-block:: cpp 5312391Sjason@lowepower.com 5412391Sjason@lowepower.com // Try to import scipy 5512391Sjason@lowepower.com py::object scipy = py::module::import("scipy"); 5612391Sjason@lowepower.com return scipy.attr("__version__"); 5712391Sjason@lowepower.com 5812037Sandreas.sandberg@arm.com.. _calling_python_functions: 5912037Sandreas.sandberg@arm.com 6011986Sandreas.sandberg@arm.comCalling Python functions 6111986Sandreas.sandberg@arm.com======================== 6211986Sandreas.sandberg@arm.com 6312391Sjason@lowepower.comIt is also possible to call Python classes, functions and methods 6412391Sjason@lowepower.comvia ``operator()``. 6512391Sjason@lowepower.com 6612391Sjason@lowepower.com.. code-block:: cpp 6712391Sjason@lowepower.com 6812391Sjason@lowepower.com // Construct a Python object of class Decimal 6912391Sjason@lowepower.com py::object pi = Decimal("3.14159"); 7012391Sjason@lowepower.com 7112391Sjason@lowepower.com.. code-block:: cpp 7212391Sjason@lowepower.com 7312391Sjason@lowepower.com // Use Python to make our directories 7412391Sjason@lowepower.com py::object os = py::module::import("os"); 7512391Sjason@lowepower.com py::object makedirs = os.attr("makedirs"); 7612391Sjason@lowepower.com makedirs("/tmp/path/to/somewhere"); 7712391Sjason@lowepower.com 7812391Sjason@lowepower.comOne can convert the result obtained from Python to a pure C++ version 7912391Sjason@lowepower.comif a ``py::class_`` or type conversion is defined. 8011986Sandreas.sandberg@arm.com 8111986Sandreas.sandberg@arm.com.. code-block:: cpp 8211986Sandreas.sandberg@arm.com 8311986Sandreas.sandberg@arm.com py::function f = <...>; 8411986Sandreas.sandberg@arm.com py::object result_py = f(1234, "hello", some_instance); 8511986Sandreas.sandberg@arm.com MyClass &result = result_py.cast<MyClass>(); 8611986Sandreas.sandberg@arm.com 8712391Sjason@lowepower.com.. _calling_python_methods: 8812391Sjason@lowepower.com 8912391Sjason@lowepower.comCalling Python methods 9012391Sjason@lowepower.com======================== 9112391Sjason@lowepower.com 9212391Sjason@lowepower.comTo call an object's method, one can again use ``.attr`` to obtain access to the 9312391Sjason@lowepower.comPython method. 9412391Sjason@lowepower.com 9512391Sjason@lowepower.com.. code-block:: cpp 9612391Sjason@lowepower.com 9712391Sjason@lowepower.com // Calculate e^π in decimal 9812391Sjason@lowepower.com py::object exp_pi = pi.attr("exp")(); 9912391Sjason@lowepower.com py::print(py::str(exp_pi)); 10012391Sjason@lowepower.com 10112391Sjason@lowepower.comIn the example above ``pi.attr("exp")`` is a *bound method*: it will always call 10212391Sjason@lowepower.comthe method for that same instance of the class. Alternately one can create an 10312391Sjason@lowepower.com*unbound method* via the Python class (instead of instance) and pass the ``self`` 10412391Sjason@lowepower.comobject explicitly, followed by other arguments. 10512391Sjason@lowepower.com 10612391Sjason@lowepower.com.. code-block:: cpp 10712391Sjason@lowepower.com 10812391Sjason@lowepower.com py::object decimal_exp = Decimal.attr("exp"); 10912391Sjason@lowepower.com 11012391Sjason@lowepower.com // Compute the e^n for n=0..4 11112391Sjason@lowepower.com for (int n = 0; n < 5; n++) { 11212391Sjason@lowepower.com py::print(decimal_exp(Decimal(n)); 11312391Sjason@lowepower.com } 11412391Sjason@lowepower.com 11512391Sjason@lowepower.comKeyword arguments 11612391Sjason@lowepower.com================= 11712391Sjason@lowepower.com 11811986Sandreas.sandberg@arm.comKeyword arguments are also supported. In Python, there is the usual call syntax: 11911986Sandreas.sandberg@arm.com 12011986Sandreas.sandberg@arm.com.. code-block:: python 12111986Sandreas.sandberg@arm.com 12211986Sandreas.sandberg@arm.com def f(number, say, to): 12311986Sandreas.sandberg@arm.com ... # function code 12411986Sandreas.sandberg@arm.com 12511986Sandreas.sandberg@arm.com f(1234, say="hello", to=some_instance) # keyword call in Python 12611986Sandreas.sandberg@arm.com 12711986Sandreas.sandberg@arm.comIn C++, the same call can be made using: 12811986Sandreas.sandberg@arm.com 12911986Sandreas.sandberg@arm.com.. code-block:: cpp 13011986Sandreas.sandberg@arm.com 13112037Sandreas.sandberg@arm.com using namespace pybind11::literals; // to bring in the `_a` literal 13211986Sandreas.sandberg@arm.com f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ 13311986Sandreas.sandberg@arm.com 13412391Sjason@lowepower.comUnpacking arguments 13512391Sjason@lowepower.com=================== 13612391Sjason@lowepower.com 13711986Sandreas.sandberg@arm.comUnpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with 13811986Sandreas.sandberg@arm.comother arguments: 13911986Sandreas.sandberg@arm.com 14011986Sandreas.sandberg@arm.com.. code-block:: cpp 14111986Sandreas.sandberg@arm.com 14211986Sandreas.sandberg@arm.com // * unpacking 14311986Sandreas.sandberg@arm.com py::tuple args = py::make_tuple(1234, "hello", some_instance); 14411986Sandreas.sandberg@arm.com f(*args); 14511986Sandreas.sandberg@arm.com 14611986Sandreas.sandberg@arm.com // ** unpacking 14711986Sandreas.sandberg@arm.com py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); 14811986Sandreas.sandberg@arm.com f(**kwargs); 14911986Sandreas.sandberg@arm.com 15011986Sandreas.sandberg@arm.com // mixed keywords, * and ** unpacking 15111986Sandreas.sandberg@arm.com py::tuple args = py::make_tuple(1234); 15211986Sandreas.sandberg@arm.com py::dict kwargs = py::dict("to"_a=some_instance); 15311986Sandreas.sandberg@arm.com f(*args, "say"_a="hello", **kwargs); 15411986Sandreas.sandberg@arm.com 15511986Sandreas.sandberg@arm.comGeneralized unpacking according to PEP448_ is also supported: 15611986Sandreas.sandberg@arm.com 15711986Sandreas.sandberg@arm.com.. code-block:: cpp 15811986Sandreas.sandberg@arm.com 15911986Sandreas.sandberg@arm.com py::dict kwargs1 = py::dict("number"_a=1234); 16011986Sandreas.sandberg@arm.com py::dict kwargs2 = py::dict("to"_a=some_instance); 16111986Sandreas.sandberg@arm.com f(**kwargs1, "say"_a="hello", **kwargs2); 16211986Sandreas.sandberg@arm.com 16311986Sandreas.sandberg@arm.com.. seealso:: 16411986Sandreas.sandberg@arm.com 16512391Sjason@lowepower.com The file :file:`tests/test_pytypes.cpp` contains a complete 16611986Sandreas.sandberg@arm.com example that demonstrates passing native Python types in more detail. The 16711986Sandreas.sandberg@arm.com file :file:`tests/test_callbacks.cpp` presents a few examples of calling 16811986Sandreas.sandberg@arm.com Python functions from C++, including keywords arguments and unpacking. 16911986Sandreas.sandberg@arm.com 17011986Sandreas.sandberg@arm.com.. _PEP448: https://www.python.org/dev/peps/pep-0448/ 171