accessor: Overload operators to allow in-place assignments on m_base (#1119)

This enables users to write the following for in-place ops:

```cpp
nb::object obj = ...;
// increment a (mutable) counter value inline.
obj.attr("count") += nb::int(1);
```

This is useful in bindings and wrappers because it avoids the duplication of
`obj.attr()` calls. Templating the operator declaration allows their use in all
accessor implementations.

A new `test_accessor` CMake target was defined along with a Python test file,
covering the most important accessor types.

Author: nicholasjng

include/nanobind/nb_accessor.h

@@ -10,6 +10,17 @@
 NAMESPACE_BEGIN(NB_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
+#define NB_DECL_ACCESSOR_OP_I(name)                                            \
+    template <typename T> accessor& name(const api<T> &o);
+
+#define NB_IMPL_ACCESSOR_OP_I(name, op)                                        \
+    template <typename Impl> template <typename T>                             \
+    accessor<Impl>& accessor<Impl>::name(const api<T> &o) {                    \
+        PyObject *res = obj_op_2(ptr(), o.derived().ptr(), op);                \
+        Impl::set(m_base, m_key, res);                                         \
+        return *this;                                                          \
+    }
+
 template <typename Impl> class accessor : public api<accessor<Impl>> {
     template <typename T> friend void nanobind::del(accessor<T> &);
     template <typename T> friend void nanobind::del(accessor<T> &&);
@@ -37,6 +48,17 @@ template <typename Impl> class accessor : public api<accessor<Impl>> {
     NB_INLINE handle base() const { return m_base; }
     NB_INLINE object key() const { return steal(Impl::key(m_key)); }
 
+    NB_DECL_ACCESSOR_OP_I(operator+=)
+    NB_DECL_ACCESSOR_OP_I(operator-=)
+    NB_DECL_ACCESSOR_OP_I(operator*=)
+    NB_DECL_ACCESSOR_OP_I(operator/=)
+    NB_DECL_ACCESSOR_OP_I(operator%=)
+    NB_DECL_ACCESSOR_OP_I(operator|=)
+    NB_DECL_ACCESSOR_OP_I(operator&=)
+    NB_DECL_ACCESSOR_OP_I(operator^=)
+    NB_DECL_ACCESSOR_OP_I(operator<<=)
+    NB_DECL_ACCESSOR_OP_I(operator>>=)
+
 private:
     NB_INLINE void del () { Impl::del(m_base, m_key); }
 
@@ -205,6 +227,17 @@ accessor<num_item> api<D>::operator[](T index) const {
     return { derived(), (Py_ssize_t) index };
 }
 
+NB_IMPL_ACCESSOR_OP_I(operator+=, PyNumber_InPlaceAdd)
+NB_IMPL_ACCESSOR_OP_I(operator%=, PyNumber_InPlaceRemainder)
+NB_IMPL_ACCESSOR_OP_I(operator-=, PyNumber_InPlaceSubtract)
+NB_IMPL_ACCESSOR_OP_I(operator*=, PyNumber_InPlaceMultiply)
+NB_IMPL_ACCESSOR_OP_I(operator/=, PyNumber_InPlaceTrueDivide)
+NB_IMPL_ACCESSOR_OP_I(operator|=, PyNumber_InPlaceOr)
+NB_IMPL_ACCESSOR_OP_I(operator&=, PyNumber_InPlaceAnd)
+NB_IMPL_ACCESSOR_OP_I(operator^=, PyNumber_InPlaceXor)
+NB_IMPL_ACCESSOR_OP_I(operator<<=,PyNumber_InPlaceLshift)
+NB_IMPL_ACCESSOR_OP_I(operator>>=,PyNumber_InPlaceRshift)
+
 NAMESPACE_END(detail)
 
 template <typename T, detail::enable_if_t<std::is_arithmetic_v<T>>>

tests/CMakeLists.txt

@@ -61,6 +61,7 @@ if (NB_TEST_SANITIZERS)
 endif()
 
 set(TEST_NAMES
+  accessor
   functions
   callbacks
   classes
@@ -149,6 +150,7 @@ target_link_libraries(test_inter_module_2_ext PRIVATE inter_module)
 set(TEST_FILES
   common.py
   conftest.py
+  test_accessor.py
   test_callbacks.py
   test_classes.py
   test_eigen.py

tests/test_accessor.cpp

@@ -0,0 +1,39 @@
+#include <nanobind/nanobind.h>
+
+namespace nb = nanobind;
+
+struct A { int value; };
+
+NB_MODULE(test_accessor_ext, m) {
+    nb::class_<A>(m, "A")
+    .def(nb::init<>())
+    .def_rw("value", &A::value);
+
+    m.def("test_str_attr_accessor_inplace_mutation", []() {
+        nb::object a_ = nb::module_::import_("test_accessor_ext").attr("A")();
+        a_.attr("value") += nb::int_(1);
+        return a_;
+    });
+
+    m.def("test_str_item_accessor_inplace_mutation", []() {
+        nb::dict d;
+        d["a"] = nb::int_(0);
+        d["a"] += nb::int_(1);
+        return d;
+    });
+
+    m.def("test_num_item_list_accessor_inplace_mutation", []() {
+        nb::list l;
+        l.append(nb::int_(0));
+        l[0] += nb::int_(1);
+        return l;
+    });
+
+    m.def("test_obj_item_accessor_inplace_mutation", []() {
+        nb::dict d;
+        nb::int_ key = nb::int_(0);
+        d[key] = nb::int_(0);
+        d[key] += nb::int_(1);
+        return d;
+    });
+}

tests/test_accessor.py

@@ -0,0 +1,41 @@
+import test_accessor_ext as t
+
+
+def test_01_str_attr_inplace_mutation():
+    """
+    Tests that a C++ expression like obj.attr("foo") += ... 
+    can actually modify the object in-place.
+    """
+    a = t.test_str_attr_accessor_inplace_mutation()
+    assert a.value == 1
+
+
+def test_02_str_item_inplace_mutation():
+    """
+    Similar to test 01, but tests obj["foo"] (keyed attribute access)
+    on the C++ side.
+    """
+    d = t.test_str_item_accessor_inplace_mutation()
+    assert d.keys() == {"a"}
+    assert d["a"] == 1
+
+
+def test_03_num_item_list_inplace_mutation():
+    """
+    Similar to test 01, but tests l[n] (index access)
+    on the C++ side, where l is an ``nb::list``.
+    """
+    l = t.test_num_item_list_accessor_inplace_mutation()
+    assert len(l) == 1
+    assert l[0] == 1
+
+
+def test_04_obj_item_inplace_mutation():
+    """
+    Similar to test 01, but tests obj[h] (handle access)
+    on the C++ side.
+    """
+    d = t.test_obj_item_accessor_inplace_mutation()
+    assert len(d) == 1
+    assert d.keys() == {0}
+    assert d[0] == 1  # dict lookup