feat: py::pos_only (#2459)
* feat: py::pos_only
* fix: review points from @YannickJadoul
* fix: review points from @bstaletic
* refactor: kwonly -> kw_only
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 3e33c9c..2814adf 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -378,17 +378,35 @@
f(1, b=2) # good
f(1, 2) # TypeError: f() takes 1 positional argument but 2 were given
-Pybind11 provides a ``py::kwonly`` object that allows you to implement
+Pybind11 provides a ``py::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::kwonly(), py::arg("b"));
+ py::arg("a"), py::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.
+Note that you currently cannot combine this with a ``py::args`` argument. This
+feature does *not* require Python 3 to work.
+
+.. versionadded:: 2.6
+
+Positional-only arguments
+=========================
+
+Python 3.8 introduced a new positional-only argument syntax, using ``/`` in the
+function definition (note that this has been a convention for CPython
+positional arguments, such as in ``pow()``, since Python 2). You can
+do the same thing in any version of Python using ``py::pos_only()``:
+
+.. code-block:: cpp
+
+ m.def("f", [](int a, int b) { /* ... */ },
+ py::arg("a"), py::pos_only(), py::arg("b"));
+
+You now cannot give argument ``a`` by keyword. This can be combined with
+keyword-only arguments, as well.
.. versionadded:: 2.6