Refactor deep_merge

The previous implementation didn't deep-copy values. The current
implementation fixes this and adds additional tests to cover also
tuples and sets.

Author: tomschr

src/docbuild/config/merge.py

@@ -1,23 +1,24 @@
 """Merge multiple dictionaries into a new one without modifying inputs."""
 
 from collections.abc import Mapping
+from copy import deepcopy
 from typing import Any
 
 
 def deep_merge(
-    # dct1: ,
-    *dcts: dict[str, Any],
+    *dcts: Mapping[str, Any],
 ) -> dict[str, Any]:
     """Merge multiple dictionaries into a new one without modifying inputs.
 
     Make a deep copy of the first dictionary and then update the copy with the
     subsequent dictionaries:
 
-    * If a key exists in both dictionaries, the value from the last dictionary
-      will overwrite the previous one.
-    * If the value is a list, it will concatenate the lists.
-    * If the value is a primitive type, it will overwrite the value.
-    * If a key exists in multiple dictionaries, the last one will take precedence.
+    * If a key exists in both dictionaries and both values are Mappings,
+      they will be merged recursively.
+    * If both values are lists or tuples, they will be concatenated.
+    * If both values are sets, they will be unioned.
+    * Otherwise (different types or primitive values), the value from the
+      subsequent dictionary will overwrite the previous one.
 
     This means that the order of dictionaries matters. The first dictionary
     will be the base, and the subsequent dictionaries will update it.
@@ -29,22 +30,27 @@ def deep_merge(
     if not dcts:
         return {}
 
-    # Start with a shallow copy of the first dictionary
-    merged = dcts[0].copy()
+    merged: dict[str, Any] = deepcopy(dict(dcts[0]))
 
     for d in dcts[1:]:
-        stack = [(merged, d)]
-
-        while stack:
-            d1, d2 = stack.pop()
-            for key, value in d2.items():
-                if (
-                    key in merged
-                    and isinstance(d1[key], dict | Mapping)
-                    and isinstance(value, dict | Mapping)
-                ):
-                    stack.append((d1[key], value))
-                else:
-                    d1[key] = value
+        for key, value in d.items():
+            if key in merged:
+                if isinstance(merged[key], Mapping) and isinstance(value, Mapping):
+                    merged[key] = deep_merge(merged[key], value)
+                    continue
+
+                is_list = isinstance(merged[key], list) and isinstance(value, list)
+                is_tuple = isinstance(merged[key], tuple) and isinstance(value, tuple)
+                is_set = isinstance(merged[key], set) and isinstance(value, set)
+
+                if is_list or is_tuple:
+                    merged[key] = merged[key] + deepcopy(value)
+                    continue
+
+                if is_set:
+                    merged[key] = merged[key] | deepcopy(value)
+                    continue
+
+            merged[key] = deepcopy(value)
 
     return merged

tests/config/app/test_deep_merge.py

@@ -6,17 +6,107 @@
 @pytest.mark.parametrize(
     "thedicts,expected",
     [
-        # 1
+        # 1: two dicts with a common key (last one wins)
         ([{"a": 1}, {"a": 2}], {"a": 2}),
-        # 2
+        # 2: two dicts with a common key and another key
+        # (last one wins for common key, other key is preserved)
         ([{"a": 1, "b": 2}, {"a": 2}], {"a": 2, "b": 2}),
-        # 3
+        # 3: nested dictionaries
         (
             [{"db": {"host": "localhost", "port": 1234}}, {"db": {"port": 5432}}],
             {"db": {"host": "localhost", "port": 5432}},
         ),
-        #
+        # 4: Lists
+        (
+            [{"a": [1, 2]}, {"a": [3, 4]}],
+            {"a": [1, 2, 3, 4]},
+        ),
+        # 5: Mixed types (overwrite list with int)
+        (
+            [{"a": [1, 2]}, {"a": 3}],
+            {"a": 3},
+        ),
+        # 6: Mixed types (overwrite int with list)
+        (
+            [{"a": 1}, {"a": [2, 3]}],
+            {"a": [2, 3]},
+        ),
+        # 7: Nested lists
+        (
+            [{"x": {"l": ["a"]}}, {"x": {"l": ["b"]}}],
+            {"x": {"l": ["a", "b"]}},
+        ),
+        # 8: Lists containing dictionaries
+        (
+            [{"a": [{"x": 1}]}, {"a": [{"y": 2}]}],
+            {"a": [{"x": 1}, {"y": 2}]},
+        ),
+        # 9: Tuples
+        (
+            [{"t": (1, 2)}, {"t": (3, 4)}],
+            {"t": (1, 2, 3, 4)},
+        ),
+        # 10: Sets
+        (
+            [{"s": {1, 2}}, {"s": {3, 4}}],
+            {"s": {1, 2, 3, 4}},
+        ),
+        # 11: Sets with overlap
+        (
+            [{"s": {1, 2}}, {"s": {2, 3}}],
+            {"s": {1, 2, 3}},
+        ),
     ],
 )
 def test_deep_merge(thedicts, expected):
     assert deep_merge(*thedicts) == expected
+
+
+def test_deep_merge_is_truly_deep():
+    d1 = {"nested": [1, 2], "deep": {"a": 1}}
+    d2 = {}
+    merged = deep_merge(d1, d2)
+
+    # Modify result
+    merged["nested"].append(3)
+    merged["deep"]["b"] = 2
+
+    # Assert original is untouched
+    assert d1["nested"] == [1, 2]
+    assert "b" not in d1["deep"]
+
+
+def test_three_way_merge():
+    d1 = {"a": 1}
+    d2 = {"b": 2}
+    d3 = {"c": 3}
+    assert deep_merge(d1, d2, d3) == {"a": 1, "b": 2, "c": 3}
+
+
+def test_deep_merge_inputs_remain_independent():
+    # Verify that subsequent dictionaries (not just the first) are also treated as immutable sources
+    d1 = {}
+    d2 = {"a": [1, 2], "b": {"x": 1}}
+    merged = deep_merge(d1, d2)
+
+    # Modify result
+    merged["a"].append(3)
+    merged["b"]["y"] = 2
+
+    # Assert input d2 is untouched
+    assert d2["a"] == [1, 2]
+    assert "y" not in d2["b"]
+
+
+def test_deep_merge_return_type():
+    class MyMap(dict):
+        pass
+
+    m1 = MyMap({"a": 1})
+    m2 = {"b": 2}
+    result = deep_merge(m1, m2)
+
+    assert isinstance(result, dict)
+    assert not isinstance(result, MyMap)
+    assert result == {"a": 1, "b": 2}
+