Implement md.merge() (#1204)

asvetlov · web-flow · commit 259ca8c16c3f · 2025-06-27T09:11:19.000+02:00
Closes #292
diff --git a/.codecov.yml b/.codecov.yml
@@ -40,7 +40,7 @@ coverage:
       typing:
         flags:
         - MyPy
-        target: 80%
+        target: 40%
 
 github_checks:
   annotations: false
diff --git a/CHANGES/292.feature.rst b/CHANGES/292.feature.rst
@@ -0,0 +1,2 @@
+Added :meth:`multidict.MultiDict.merge` which copies all items from arguments if its key
+not exist in the dictionary -- by :user:`asvetlov`.
diff --git a/docs/multidict.rst b/docs/multidict.rst
@@ -181,7 +181,30 @@ MultiDict
 
       .. seealso::
 
-         :meth:`update`
+         :meth:`merge` and :meth:`update`
+
+   .. method:: merge([other], **kwargs)
+
+      Merge the dictionary with the key/value pairs from *other* and *kwargs*,
+      appending non-existing pairs to this dictionary. For existing keys,
+      the addition is skipped.
+
+      Returns ``None``.
+
+      :meth:`merge` accepts either another dictionary object or an
+      iterable of key/value pairs (as tuples or other iterables of
+      length two). If keyword arguments are specified, the dictionary
+      is then merged with those key/value pairs:
+      ``d.merge(red=1, blue=2)``.
+
+      Effectively the same as calling :meth:`add` for every
+      ``(key, value)`` pair where ``key not in self``.
+
+      .. seealso::
+
+         :meth:`extend` and :meth:`update`
+
+      .. versionadded:: 6.6
 
    .. method:: update([other], **kwargs)
 
@@ -198,7 +221,7 @@ MultiDict
 
       .. seealso::
 
-         :meth:`extend`
+         :meth:`extend` and :meth:`merge`
 
    .. seealso::
 
diff --git a/multidict/_abc.py b/multidict/_abc.py
@@ -52,6 +52,10 @@ def add(self, key: str, value: _V) -> None:
     def extend(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None:
         """Add everything from arg and kwargs to the mapping."""
 
+    @abc.abstractmethod
+    def merge(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None:
+        """Merge into the mapping, adding non-existing keys."""
+
     @overload
     def popone(self, key: str) -> _V: ...
     @overload
diff --git a/multidict/_multidict.c b/multidict/_multidict.c
@@ -66,7 +66,7 @@ _multidict_getone(MultiDictObject *self, PyObject *key, PyObject *_default)
 
 static inline int
 _multidict_extend(MultiDictObject *self, PyObject *arg, PyObject *kwds,
-                  const char *name, bool update)
+                  const char *name, UpdateOp op)
 {
     mod_state *state = self->state;
     PyObject *seq = NULL;
@@ -78,24 +78,24 @@ _multidict_extend(MultiDictObject *self, PyObject *arg, PyObject *kwds,
     if (arg != NULL) {
         if (AnyMultiDict_Check(state, arg)) {
             MultiDictObject *other = (MultiDictObject *)arg;
-            if (md_update_from_ht(self, other, update) < 0) {
+            if (md_update_from_ht(self, other, op) < 0) {
                 goto fail;
             }
         } else if (AnyMultiDictProxy_Check(state, arg)) {
             MultiDictObject *other = ((MultiDictProxyObject *)arg)->md;
-            if (md_update_from_ht(self, other, update) < 0) {
+            if (md_update_from_ht(self, other, op) < 0) {
                 goto fail;
             }
         } else if (PyDict_CheckExact(arg)) {
-            if (md_update_from_dict(self, arg, update) < 0) {
+            if (md_update_from_dict(self, arg, op) < 0) {
                 goto fail;
             }
         } else if (PyList_CheckExact(arg)) {
-            if (md_update_from_seq(self, arg, update) < 0) {
+            if (md_update_from_seq(self, arg, op) < 0) {
                 goto fail;
             }
         } else if (PyTuple_CheckExact(arg)) {
-            if (md_update_from_seq(self, arg, update) < 0) {
+            if (md_update_from_seq(self, arg, op) < 0) {
                 goto fail;
             }
         } else {
@@ -105,19 +105,19 @@ _multidict_extend(MultiDictObject *self, PyObject *arg, PyObject *kwds,
                 seq = Py_NewRef(arg);
             }
 
-            if (md_update_from_seq(self, seq, update) < 0) {
+            if (md_update_from_seq(self, seq, op) < 0) {
                 goto fail;
             }
         }
     }
 
     if (kwds != NULL) {
-        if (md_update_from_dict(self, kwds, update) < 0) {
+        if (md_update_from_dict(self, kwds, op) < 0) {
             goto fail;
         }
     }
 
-    if (update) {
+    if (op != Extend) {  // Update or Merge
         if (md_post_update(self) < 0) {
             goto fail;
         }
@@ -551,7 +551,7 @@ multidict_tp_init(MultiDictObject *self, PyObject *args, PyObject *kwds)
     if (md_init(self, state, false, size) < 0) {
         goto fail;
     }
-    if (_multidict_extend(self, arg, kwds, "MultiDict", false) < 0) {
+    if (_multidict_extend(self, arg, kwds, "MultiDict", Extend) < 0) {
         goto fail;
     }
 done:
@@ -592,7 +592,7 @@ multidict_extend(MultiDictObject *self, PyObject *args, PyObject *kwds)
     if (md_reserve(self, size) < 0) {
         goto fail;
     }
-    if (_multidict_extend(self, arg, kwds, "extend", false) < 0) {
+    if (_multidict_extend(self, arg, kwds, "extend", Extend) < 0) {
         goto fail;
     }
     Py_CLEAR(arg);
@@ -774,7 +774,30 @@ multidict_update(MultiDictObject *self, PyObject *args, PyObject *kwds)
     if (md_reserve(self, size) < 0) {
         goto fail;
     }
-    if (_multidict_extend(self, arg, kwds, "update", true) < 0) {
+    if (_multidict_extend(self, arg, kwds, "update", Update) < 0) {
+        goto fail;
+    }
+    Py_CLEAR(arg);
+    ASSERT_CONSISTENT(self, false);
+    Py_RETURN_NONE;
+fail:
+    Py_CLEAR(arg);
+    return NULL;
+}
+
+static PyObject *
+multidict_merge(MultiDictObject *self, PyObject *args, PyObject *kwds)
+{
+    PyObject *arg = NULL;
+    Py_ssize_t size =
+        _multidict_extend_parse_args(self->state, args, kwds, "merge", &arg);
+    if (size < 0) {
+        goto fail;
+    }
+    if (md_reserve(self, size) < 0) {
+        goto fail;
+    }
+    if (_multidict_extend(self, arg, kwds, "merge", Merge) < 0) {
         goto fail;
     }
     Py_CLEAR(arg);
@@ -824,6 +847,9 @@ PyDoc_STRVAR(multidict_popitem_doc,
 PyDoc_STRVAR(multidict_update_doc,
              "Update the dictionary, overwriting existing keys.");
 
+PyDoc_STRVAR(multidict_merge_doc,
+             "Merge into the dictionary, adding non-existing keys.");
+
 PyDoc_STRVAR(sizeof__doc__, "D.__sizeof__() -> size of D in memory, in bytes");
 
 static PyObject *
@@ -887,6 +913,10 @@ static PyMethodDef multidict_methods[] = {
      (PyCFunction)multidict_update,
      METH_VARARGS | METH_KEYWORDS,
      multidict_update_doc},
+    {"merge",
+     (PyCFunction)multidict_merge,
+     METH_VARARGS | METH_KEYWORDS,
+     multidict_merge_doc},
     {
         "__reduce__",
         (PyCFunction)multidict_reduce,
@@ -979,7 +1009,7 @@ cimultidict_tp_init(MultiDictObject *self, PyObject *args, PyObject *kwds)
     if (md_init(self, state, true, size) < 0) {
         goto fail;
     }
-    if (_multidict_extend(self, arg, kwds, "CIMultiDict", false) < 0) {
+    if (_multidict_extend(self, arg, kwds, "CIMultiDict", Extend) < 0) {
         goto fail;
     }
 done:
diff --git a/multidict/_multidict_py.py b/multidict/_multidict_py.py
@@ -999,10 +999,9 @@ def update(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None:
         if log2_size > self._keys.log2_size:
             self._resize(log2_size, False)
         self._update_items(items)
+        self._post_update()
 
     def _update_items(self, items: list[_Entry[_V]]) -> None:
-        if not items:
-            return
         for entry in items:
             found = False
             hash_ = entry.hash
@@ -1019,6 +1018,7 @@ def _update_items(self, items: list[_Entry[_V]]) -> None:
             if not found:
                 self._add_with_hash_for_upd(entry)
 
+    def _post_update(self) -> None:
         keys = self._keys
         indices = keys.indices
         entries = keys.entries
@@ -1028,14 +1028,38 @@ def _update_items(self, items: list[_Entry[_V]]) -> None:
                 e2 = entries[idx]
                 assert e2 is not None
                 if e2.key is None:
-                    entries[idx] = None  # type: ignore[unreachable]
+                    entries[idx] = None
                     indices[slot] = -2
                     self._used -= 1
                 if e2.hash == -1:
                     e2.hash = hash(e2.identity)
 
         self._incr_version()
 
+    def merge(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None:
+        """Merge into the dictionary, adding non-existing keys."""
+        items = self._parse_args(arg, kwargs)
+        newsize = self._used + len(items)
+        log2_size = estimate_log2_keysize(newsize)
+        if log2_size > 17:  # pragma: no cover
+            # Don't overallocate really huge keys space in update,
+            # duplicate keys could reduce the resulting anount of entries
+            log2_size = 17
+        if log2_size > self._keys.log2_size:
+            self._resize(log2_size, False)
+        self._merge_items(items)
+        self._post_update()
+
+    def _merge_items(self, items: list[_Entry[_V]]) -> None:
+        for entry in items:
+            hash_ = entry.hash
+            identity = entry.identity
+            for slot, idx, e in self._keys.iter_hash(hash_):
+                if e.identity == identity:  # pragma: no branch
+                    break
+            else:
+                self._add_with_hash_for_upd(entry)
+
     def _incr_version(self) -> None:
         v = _version
         v[0] += 1
diff --git a/multidict/_multilib/hashtable.h b/multidict/_multilib/hashtable.h
diff --git a/tests/test_mutable_multidict.py b/tests/test_mutable_multidict.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Added :meth:`multidict.MultiDict.merge` which copies all items from arguments if its key
	`2`	+not exist in the dictionary -- by :user:`asvetlov`.