docs: Describe importing Python modules and Python methods (#1079)
* Expand documentation to include explicit example of py::module::import
where one would expect it.
* Describe how to use unbound and bound methods to class Python classes.
[skip ci]
diff --git a/docs/advanced/pycpp/object.rst b/docs/advanced/pycpp/object.rst
index c9728e9..117131e 100644
--- a/docs/advanced/pycpp/object.rst
+++ b/docs/advanced/pycpp/object.rst
@@ -33,12 +33,50 @@
When conversion fails, both directions throw the exception :class:`cast_error`.
+.. _python_libs:
+
+Accessing Python libraries from C++
+===================================
+
+It is also possible to import objects defined in the Python standard
+library or available in the current Python environment (``sys.path``) and work
+with these in C++.
+
+This example obtains a reference to the Python ``Decimal`` class.
+
+.. code-block:: cpp
+
+ // Equivalent to "from decimal import Decimal"
+ py::object Decimal = py::module::import("decimal").attr("Decimal");
+
+.. code-block:: cpp
+
+ // Try to import scipy
+ py::object scipy = py::module::import("scipy");
+ return scipy.attr("__version__");
+
.. _calling_python_functions:
Calling Python functions
========================
-It is also possible to call python functions via ``operator()``.
+It is also possible to call Python classes, functions and methods
+via ``operator()``.
+
+.. code-block:: cpp
+
+ // Construct a Python object of class Decimal
+ py::object pi = Decimal("3.14159");
+
+.. code-block:: cpp
+
+ // Use Python to make our directories
+ py::object os = py::module::import("os");
+ py::object makedirs = os.attr("makedirs");
+ makedirs("/tmp/path/to/somewhere");
+
+One can convert the result obtained from Python to a pure C++ version
+if a ``py::class_`` or type conversion is defined.
.. code-block:: cpp
@@ -46,6 +84,37 @@
py::object result_py = f(1234, "hello", some_instance);
MyClass &result = result_py.cast<MyClass>();
+.. _calling_python_methods:
+
+Calling Python methods
+========================
+
+To call an object's method, one can again use ``.attr`` to obtain access to the
+Python method.
+
+.. code-block:: cpp
+
+ // Calculate e^π in decimal
+ py::object exp_pi = pi.attr("exp")();
+ py::print(py::str(exp_pi));
+
+In the example above ``pi.attr("exp")`` is a *bound method*: it will always call
+the method for that same instance of the class. Alternately one can create an
+*unbound method* via the Python class (instead of instance) and pass the ``self``
+object explicitly, followed by other arguments.
+
+.. code-block:: cpp
+
+ py::object decimal_exp = Decimal.attr("exp");
+
+ // Compute the e^n for n=0..4
+ for (int n = 0; n < 5; n++) {
+ py::print(decimal_exp(Decimal(n));
+ }
+
+Keyword arguments
+=================
+
Keyword arguments are also supported. In Python, there is the usual call syntax:
.. code-block:: python
@@ -62,6 +131,9 @@
using namespace pybind11::literals; // to bring in the `_a` literal
f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++
+Unpacking arguments
+===================
+
Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with
other arguments: