feat: py::prepend tag (#1131)
* feat: add a priority overload with py::prepend
* doc: fix wording as suggested by rwgk
* feat: add get_pointer
* refactor: is_prepended -> prepend (internal)
* docs: suggestion from @wjakob
* tests: add test covering get_pointer/set_pointer
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 81b4c02..ebdff9c 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -540,11 +540,13 @@
If the second pass also fails a ``TypeError`` is raised.
Within each pass, overloads are tried in the order they were registered with
-pybind11.
+pybind11. If the ``py::prepend()`` tag is added to the definition, a function
+can be placed at the beginning of the overload sequence instead, allowing user
+overloads to proceed built in functions.
What this means in practice is that pybind11 will prefer any overload that does
-not require conversion of arguments to an overload that does, but otherwise prefers
-earlier-defined overloads to later-defined ones.
+not require conversion of arguments to an overload that does, but otherwise
+prefers earlier-defined overloads to later-defined ones.
.. note::
@@ -553,3 +555,7 @@
requiring one conversion over one requiring three, but only prioritizes
overloads requiring no conversion at all to overloads that require
conversion of at least one argument.
+
+.. versionadded:: 2.6
+
+ The ``py::prepend()`` tag.