Move _deep_merge to src/usethis/_file/merge.py, add unit tests

Copilot · nathanjmcdougall · Copilot · commit 43f85fa99342 · 2026-03-20T21:46:01.000Z
Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/f3e236f8-f385-4552-9e5c-cd568c97529c
diff --git a/.importlinter b/.importlinter
@@ -119,7 +119,7 @@ containers =
 layers =
     pyproject_toml | setup_cfg
     ini | toml | yaml
-    dir
+    dir | merge
 exhaustive = true
 
 [importlinter:contract:ui_interface]
diff --git a/src/usethis/_file/merge.py b/src/usethis/_file/merge.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+
+
+def _deep_merge(
+    target: MutableMapping[Any, Any], source: MutableMapping[Any, Any]
+) -> MutableMapping[Any, Any]:
+    """Recursively merge source into target in place, returning target.
+
+    For keys present in both mappings, if both values are mappings the merge is
+    applied recursively; otherwise the source value replaces the target value.
+    """
+    for key, value in source.items():
+        if (
+            key in target
+            and isinstance(target[key], MutableMapping)
+            and isinstance(value, MutableMapping)
+        ):
+            _deep_merge(target[key], value)
+        else:
+            target[key] = value
+    return target
diff --git a/src/usethis/_file/toml/io_.py b/src/usethis/_file/toml/io_.py
@@ -12,6 +12,7 @@
 from tomlkit.exceptions import TOMLKitError
 from typing_extensions import assert_never
 
+from usethis._file.merge import _deep_merge
 from usethis._file.toml.errors import (
     TOMLDecodeError,
     TOMLNotFoundError,
@@ -26,7 +27,6 @@
     KeyValueFileManager,
     UnexpectedFileIOError,
     UnexpectedFileOpenError,
-    _deep_merge,
     print_keys,
 )
 
diff --git a/src/usethis/_file/yaml/io_.py b/src/usethis/_file/yaml/io_.py
@@ -15,6 +15,7 @@
 from typing_extensions import assert_never
 
 from usethis._console import info_print
+from usethis._file.merge import _deep_merge
 from usethis._file.yaml.errors import (
     UnexpectedYAMLIOError,
     UnexpectedYAMLOpenError,
@@ -29,7 +30,6 @@
     KeyValueFileManager,
     UnexpectedFileIOError,
     UnexpectedFileOpenError,
-    _deep_merge,
     print_keys,
 )
 
diff --git a/src/usethis/_io.py b/src/usethis/_io.py
@@ -2,8 +2,7 @@
 
 import re
 from abc import abstractmethod
-from collections.abc import MutableMapping
-from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeAlias, TypeVar
 
 from typing_extensions import assert_never
 
@@ -14,7 +13,7 @@
     from collections.abc import Sequence
     from pathlib import Path
     from types import TracebackType
-    from typing import ClassVar
+    from typing import Any, ClassVar
 
     from typing_extensions import Self
 
@@ -247,23 +246,3 @@ def print_keys(keys: Sequence[Key]) -> str:
             assert_never(key)
 
     return ".".join(components)
-
-
-def _deep_merge(
-    target: MutableMapping[Any, Any], source: MutableMapping[Any, Any]
-) -> MutableMapping[Any, Any]:
-    """Recursively merge source into target in place, returning target.
-
-    For keys present in both mappings, if both values are mappings the merge is
-    applied recursively; otherwise the source value replaces the target value.
-    """
-    for key, value in source.items():
-        if (
-            key in target
-            and isinstance(target[key], MutableMapping)
-            and isinstance(value, MutableMapping)
-        ):
-            _deep_merge(target[key], value)
-        else:
-            target[key] = value
-    return target
diff --git a/tests/usethis/_file/test_merge.py b/tests/usethis/_file/test_merge.py
@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from usethis._file.merge import _deep_merge
+
+
+class TestDeepMerge:
+    class TestBasicMerge:
+        def test_top_level_key_added(self) -> None:
+            target: dict = {"a": 1}
+            source: dict = {"b": 2}
+            result = _deep_merge(target, source)
+            assert result == {"a": 1, "b": 2}
+
+    class TestNestedDicts:
+        def test_nested_merge(self) -> None:
+            target: dict = {"a": {"x": 1}}
+            source: dict = {"a": {"y": 2}}
+            result = _deep_merge(target, source)
+            assert result == {"a": {"x": 1, "y": 2}}
+
+        def test_deeply_nested(self) -> None:
+            target: dict = {"a": {"b": {"c": 1}}}
+            source: dict = {"a": {"b": {"d": 2}}}
+            result = _deep_merge(target, source)
+            assert result == {"a": {"b": {"c": 1, "d": 2}}}
+
+    class TestReplacementOfNonDictValues:
+        def test_scalar_replaced_by_scalar(self) -> None:
+            target: dict = {"a": 1}
+            source: dict = {"a": 2}
+            result = _deep_merge(target, source)
+            assert result == {"a": 2}
+
+        def test_dict_replaced_by_scalar(self) -> None:
+            target: dict = {"a": {"x": 1}}
+            source: dict = {"a": 99}
+            result = _deep_merge(target, source)
+            assert result == {"a": 99}
+
+        def test_scalar_replaced_by_dict(self) -> None:
+            target: dict = {"a": 99}
+            source: dict = {"a": {"x": 1}}
+            result = _deep_merge(target, source)
+            assert result == {"a": {"x": 1}}
+
+        def test_list_replaced_by_list(self) -> None:
+            target: dict = {"a": [1, 2]}
+            source: dict = {"a": [3, 4]}
+            result = _deep_merge(target, source)
+            assert result == {"a": [3, 4]}
+
+    class TestInPlaceMutation:
+        def test_returns_target(self) -> None:
+            target: dict = {"a": 1}
+            source: dict = {"b": 2}
+            result = _deep_merge(target, source)
+            assert result is target
+
+        def test_target_is_mutated(self) -> None:
+            target: dict = {"a": 1}
+            source: dict = {"b": 2}
+            _deep_merge(target, source)
+            assert target == {"a": 1, "b": 2}
+
+    class TestDisjointKeys:
+        def test_disjoint_keys_merged(self) -> None:
+            target: dict = {"a": 1, "b": 2}
+            source: dict = {"c": 3, "d": 4}
+            result = _deep_merge(target, source)
+            assert result == {"a": 1, "b": 2, "c": 3, "d": 4}
+
+        def test_empty_source(self) -> None:
+            target: dict = {"a": 1}
+            source: dict = {}
+            result = _deep_merge(target, source)
+            assert result == {"a": 1}
+
+        def test_empty_target(self) -> None:
+            target: dict = {}
+            source: dict = {"a": 1}
+            result = _deep_merge(target, source)
+            assert result == {"a": 1}
