feat: add a priority overload with py::prepend

Author: henryiii

docs/changelog.rst

@@ -32,6 +32,9 @@ See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
   ``py::type::of(h)``.
   `#2364 <https://github.com/pybind/pybind11/pull/2364>`_
 
+* Added ``py::prepend()``, allowing a function to be placed at the beginning of
+  the overload chain.
+  `#1131 <https://github.com/pybind/pybind11/pull/1131>`_
 
 * Perfect forwarding support for methods.
   `#2048 <https://github.com/pybind/pybind11/pull/2048>`_

docs/classes.rst

@@ -367,7 +367,9 @@ Attempting to bind ``Pet::set`` will cause an error since the compiler does not
 know which method the user intended to select. We can disambiguate by casting
 them to function pointers. Binding multiple functions to the same Python name
 automatically creates a chain of function overloads that will be tried in
-sequence.
+the order they were defined. If the ``py::prepend()`` tag is added to the
+definition, the function will be placed at the begining of the overload sequence
+instead.
 
 .. code-block:: cpp
 

include/pybind11/attr.h

@@ -74,6 +74,9 @@ struct module_local { const bool value; constexpr module_local(bool v = true) :
 /// Annotation to mark enums as an arithmetic type
 struct arithmetic { };
 
+/// Mark a function for addition at the beginning of the existing overload chain instead of the end
+struct prepend { };
+
 /** \rst
     A call policy which places one or more guard variables (``Ts...``) around the function call.
 
@@ -138,8 +141,8 @@ struct argument_record {
 struct function_record {
     function_record()
         : is_constructor(false), is_new_style_constructor(false), is_stateless(false),
-          is_operator(false), is_method(false),
-          has_args(false), has_kwargs(false), has_kw_only_args(false) { }
+          is_operator(false), is_method(false), has_args(false), 
+          has_kwargs(false), has_kw_only_args(false), is_prepended(false) { }
 
     /// Function name
     char *name = nullptr; /* why no C++ strings? They generate heavier code.. */
@@ -189,6 +192,9 @@ struct function_record {
     /// True once a 'py::kw_only' is encountered (any following args are keyword-only)
     bool has_kw_only_args : 1;
 
+    /// True if this function is to be inserted at the beginning of the overload resolution chain
+    bool is_prepended : 1;
+
     /// Number of arguments (including py::args and/or py::kwargs, if present)
     std::uint16_t nargs;
 
@@ -477,6 +483,11 @@ struct process_attribute<module_local> : process_attribute_default<module_local>
     static void init(const module_local &l, type_record *r) { r->module_local = l.value; }
 };
 
+/// Process an 'prepend' attribute, putting this at the top of the overload chain
+template <> struct process_attribute<prepend> : process_attribute_default<prepend> {
+    static void init(const prepend &, function_record *r) { r->is_prepended = true; }
+};
+
 /// Process an 'arithmetic' attribute for enums (does nothing here)
 template <>
 struct process_attribute<arithmetic> : process_attribute_default<arithmetic> {};

include/pybind11/pybind11.h

@@ -372,10 +372,9 @@ class cpp_function : public function {
             if (!m_ptr)
                 pybind11_fail("cpp_function::cpp_function(): Could not allocate function object");
         } else {
-            /* Append at the end of the overload chain */
+            /* Append at the beginning or end of the overload chain */
             m_ptr = rec->sibling.ptr();
             inc_ref();
-            chain_start = chain;
             if (chain->is_method != rec->is_method)
                 pybind11_fail("overloading a method with both static and instance methods is not supported; "
                     #if defined(NDEBUG)
@@ -385,9 +384,22 @@ class cpp_function : public function {
                         std::string(pybind11::str(rec->scope.attr("__name__"))) + "." + std::string(rec->name) + signature
                     #endif
                 );
-            while (chain->next)
-                chain = chain->next;
-            chain->next = rec;
+
+            if (rec->is_prepended) {
+                // Beginning of chain; we need to replace the capsule's current head-of-the-chain
+                // pointer with this one, then make this one point to the previous head of the
+                // chain.
+                chain_start = rec;
+                rec->next = chain;
+                auto rec_capsule = reinterpret_borrow<capsule>(((PyCFunctionObject *) m_ptr)->m_self);
+                rec_capsule.set_pointer(rec);
+            } else {
+                // Or end of chain (normal behavior)
+                chain_start = chain;
+                while (chain->next)
+                    chain = chain->next;
+                chain->next = rec;
+            }
         }
 
         std::string signatures;

include/pybind11/pytypes.h

@@ -1235,6 +1235,12 @@ class capsule : public object {
         return result;
     }
 
+    // Replaces a capsule's pointer *without* calling the destructor on the existing one.
+    void set_pointer(const void *value) {
+        if (PyCapsule_SetPointer(m_ptr, const_cast<void *>(value)) != 0)
+            pybind11_fail("Could not set capsule pointer");
+    }
+
     const char *name() const { return PyCapsule_GetName(m_ptr); }
 };
 

tests/test_methods_and_attributes.cpp

@@ -284,6 +284,12 @@ TEST_SUBMODULE(methods_and_attributes, m) {
     py::class_<MetaclassOverride>(m, "MetaclassOverride", py::metaclass((PyObject *) &PyType_Type))
         .def_property_readonly_static("readonly", [](py::object) { return 1; });
 
+    // test_overload_ordering
+    m.def("overload_order", [](std::string) { return 1; });
+    m.def("overload_order", [](std::string) { return 2; });
+    m.def("overload_order", [](int) { return 3; });
+    m.def("overload_order", [](int) { return 4; }, py::prepend{});
+
 #if !defined(PYPY_VERSION)
     // test_dynamic_attributes
     class DynamicClass {

tests/test_methods_and_attributes.py

@@ -438,3 +438,25 @@ def test_ref_qualified():
     r.refQualified(17)
     assert r.value == 17
     assert r.constRefQualified(23) == 40
+
+
+def test_overload_ordering():
+    'Check to see if the normal overload order (first defined) and prepend overload order works'
+    assert m.overload_order("string") == 1
+    assert m.overload_order(0) == 4
+
+    # Different for Python 2 vs. 3
+    uni_name = type(u"").__name__
+
+    assert "1. overload_order(arg0: int) -> int" in m.overload_order.__doc__
+    assert "2. overload_order(arg0: {}) -> int".format(uni_name) in m.overload_order.__doc__
+    assert "3. overload_order(arg0: {}) -> int".format(uni_name) in m.overload_order.__doc__
+    assert "4. overload_order(arg0: int) -> int" in m.overload_order.__doc__
+
+    with pytest.raises(TypeError) as err:
+        m.overload_order(1.1)
+
+    assert "1. (arg0: int) -> int" in str(err.value)
+    assert "2. (arg0: {}) -> int".format(uni_name) in str(err.value)
+    assert "3. (arg0: {}) -> int".format(uni_name) in str(err.value)
+    assert "4. (arg0: int) -> int" in str(err.value)