Support keyword-only arguments
This adds support for a `py::args_kw_only()` annotation that can be
specified between `py::arg` annotations to indicate that any following
arguments are keyword-only. This allows you to write:
m.def("f", [](int a, int b) { /* ... */ },
py::arg("a"), py::args_kw_only(), py::arg("b"));
and have it work like Python 3's:
def f(a, *, b):
# ...
with respect to how `a` and `b` arguments are accepted (that is, `a` can
be positional or by keyword; `b` can only be specified by keyword).
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 3e1a3ff..c779053 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -362,6 +362,34 @@
py::class_<MyClass>("MyClass")
.def("myFunction", py::arg("arg") = (SomeType *) nullptr);
+Keyword-only arguments
+======================
+
+Python 3 introduced keyword-only arguments by specifying an unnamed ``*``
+argument in a function definition:
+
+.. code-block:: python
+
+ def f(a, *, b): # a can be positional or via keyword; b must be via keyword
+ pass
+
+ f(a=1, b=2) # good
+ f(b=2, a=1) # good
+ f(1, b=2) # good
+ f(1, 2) # TypeError: f() takes 1 positional argument but 2 were given
+
+Pybind11 provides a ``py::args_kw_only`` object that allows you to implement
+the same behaviour by specifying the object between positional and keyword-only
+argument annotations when registering the function:
+
+.. code-block:: cpp
+
+ m.def("f", [](int a, int b) { /* ... */ },
+ py::arg("a"), py::args_kw_only(), py::arg("b"));
+
+Note that, as in Python, you cannot combine this with a ``py::args`` argument.
+This feature does *not* require Python 3 to work.
+
.. _nonconverting_arguments:
Non-converting arguments