From 835fc06ca4d74b0c03325090fd108486833b440b Mon Sep 17 00:00:00 2001
From: Brad Harmon <bharmon@exegy.com>
Date: Thu, 16 Jun 2016 13:19:15 -0500
Subject: [PATCH] Add callback examples with named parameters

---
 docs/advanced.rst    | 18 ++++++++++++++++--
 example/example5.cpp |  6 ++++++
 example/example5.py  |  3 +++
 example/example5.ref |  1 +
 4 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/advanced.rst b/docs/advanced.rst
index 1ef7fdb67..00e43f972 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -139,8 +139,19 @@ its return value upon execution.
         };
     }
 
+This example demonstrates using python named parameters in C++ callbacks which
+requires using ``py::cpp_function`` as a wrapper. Usage is similar to defining
+methods of classes:
+
+.. code-block:: cpp
+
+    py::cpp_function func_cpp() {
+        return py::cpp_function([](int i) { return i+1; },
+           py::arg("number"));
+    }
+
 After including the extra header file :file:`pybind11/functional.h`, it is almost
-trivial to generate binding code for both of these functions.
+trivial to generate binding code for all of these functions.
 
 .. code-block:: cpp
 
@@ -151,6 +162,7 @@ trivial to generate binding code for both of these functions.
 
         m.def("func_arg", &func_arg);
         m.def("func_ret", &func_ret);
+        m.def("func_cpp", &func_cpp);
 
         return m.ptr();
     }
@@ -169,7 +181,9 @@ The following interactive session shows how to call them from Python.
     >>> square_plus_1 = example.func_ret(square)
     >>> square_plus_1(4)
     17L
-    >>>
+    >>> plus_1 = func_cpp()
+    >>> plus_1(number=43)
+    44L
 
 .. note::
 
diff --git a/example/example5.cpp b/example/example5.cpp
index 11d37d0ef..0e1d2cd13 100644
--- a/example/example5.cpp
+++ b/example/example5.cpp
@@ -60,6 +60,11 @@ std::function<int(int)> test_callback4() {
     return [](int i) { return i+1; };
 }
 
+py::cpp_function test_callback5() {
+    return py::cpp_function([](int i) { return i+1; },
+       py::arg("number"));
+}
+
 void init_ex5(py::module &m) {
     py::class_<Pet> pet_class(m, "Pet");
     pet_class
@@ -82,6 +87,7 @@ void init_ex5(py::module &m) {
     m.def("test_callback2", &test_callback2);
     m.def("test_callback3", &test_callback3);
     m.def("test_callback4", &test_callback4);
+    m.def("test_callback5", &test_callback5);
 
     /* Test cleanup of lambda closure */
 
diff --git a/example/example5.py b/example/example5.py
index ef90cfd07..1361c7519 100755
--- a/example/example5.py
+++ b/example/example5.py
@@ -29,6 +29,7 @@ from example import test_callback1
 from example import test_callback2
 from example import test_callback3
 from example import test_callback4
+from example import test_callback5
 from example import test_cleanup
 
 def func1():
@@ -49,5 +50,7 @@ print(test_callback1(partial(func3, "Partial object with one argument")))
 test_callback3(lambda i: i + 1)
 f = test_callback4()
 print("func(43) = %i" % f(43))
+f = test_callback5()
+print("func(number=43) = %i" % f(number=43))
 
 test_cleanup()
diff --git a/example/example5.ref b/example/example5.ref
index a9c7d465f..f32ba3af1 100644
--- a/example/example5.ref
+++ b/example/example5.ref
@@ -24,3 +24,4 @@ False
 Callback function 3 called : Partial object with one argument
 False
 func(43) = 44
+func(number=43) = 44