Implement merge types as an enum

Additional type hints

Author: moomoohk

README.rst

@@ -279,14 +279,13 @@ does.
         Merge source into destination. Like dict.update() but performs
         deep merging.
 
-        flags is an OR'ed combination of MERGE_ADDITIVE, MERGE_REPLACE
-        MERGE_TYPESAFE.
-            * MERGE_ADDITIVE : List objects are combined onto one long
+        flags is an OR'ed combination of MergeType enum members.
+            * ADDITIVE : List objects are combined onto one long
               list (NOT a set). This is the default flag.
-            * MERGE_REPLACE : Instead of combining list objects, when
+            * REPLACE : Instead of combining list objects, when
               2 list objects are at an equal depth of merge, replace
               the destination with the source.
-            * MERGE_TYPESAFE : When 2 keys at equal levels are of different
+            * TYPESAFE : When 2 keys at equal levels are of different
               types, raise a TypeError exception. By default, the source
               replaces the destination in this situation.
 

dpath/util.py

@@ -1,16 +1,25 @@
 from collections.abc import MutableMapping, MutableSequence
+from enum import Flag, IntFlag, auto
+from typing import Union, List, Any, Dict
 
 import dpath.segments
 from dpath import options
 from dpath.exceptions import InvalidKeyName
 
 _DEFAULT_SENTINEL = object()
-MERGE_REPLACE = (1 << 1)
-MERGE_ADDITIVE = (1 << 2)
-MERGE_TYPESAFE = (1 << 3)
 
 
-def __safe_path__(path, separator):
+class MergeType(IntFlag):
+    REPLACE = auto()
+    ADDITIVE = auto()
+    TYPESAFE = auto()
+
+
+# Type alias for dict path segments where integers are explicitly casted
+IntAwareSegment = Union[int, Any]
+
+
+def __safe_path__(path: str, separator: str) -> Union[List[IntAwareSegment], IntAwareSegment]:
     """
     Given a path and separator, return a tuple of segments. If path is
     already a non-leaf thing, return it.
@@ -146,7 +155,7 @@ def f(obj, pair, counter):
     return changed
 
 
-def get(obj, glob, separator='/', default=_DEFAULT_SENTINEL):
+def get(obj: Dict, glob: str, separator="/", default: Any = _DEFAULT_SENTINEL) -> dict:
     """
     Given an object which contains only one possible match for the given glob,
     return the value for the leaf matching the given glob.
@@ -156,7 +165,7 @@ def get(obj, glob, separator='/', default=_DEFAULT_SENTINEL):
     If more than one leaf matches the glob, ValueError is raised. If the glob is
     not found and a default is not provided, KeyError is raised.
     """
-    if glob == '/':
+    if glob == "/":
         return obj
 
     globlist = __safe_path__(glob, separator)
@@ -233,7 +242,7 @@ def f(obj, pair, result):
         return dpath.segments.fold(obj, f, {})
 
 
-def merge(dst, src, separator='/', afilter=None, flags=MERGE_ADDITIVE):
+def merge(dst, src, separator='/', afilter=None, flags=MergeType.ADDITIVE):
     """
     Merge source into destination. Like dict.update() but performs deep
     merging.
@@ -262,14 +271,13 @@ def merge(dst, src, separator='/', afilter=None, flags=MERGE_ADDITIVE):
     objects that you intend to merge. For further notes see
     https://github.com/akesterson/dpath-python/issues/58
 
-    flags is an OR'ed combination of MERGE_ADDITIVE, MERGE_REPLACE,
-    MERGE_TYPESAFE.
-        * MERGE_ADDITIVE : List objects are combined onto one long
+    flags is an OR'ed combination of MergeType enum members.
+        * ADDITIVE : List objects are combined onto one long
           list (NOT a set). This is the default flag.
-        * MERGE_REPLACE : Instead of combining list objects, when
+        * REPLACE : Instead of combining list objects, when
           2 list objects are at an equal depth of merge, replace
           the destination with the source.
-        * MERGE_TYPESAFE : When 2 keys at equal levels are of different
+        * TYPESAFE : When 2 keys at equal levels are of different
           types, raise a TypeError exception. By default, the source
           replaces the destination in this situation.
     """
@@ -295,7 +303,7 @@ def merger(dst, src, _segments=()):
                                      "{}".format(segments))
 
             # Validate src and dst types match.
-            if flags & MERGE_TYPESAFE:
+            if flags & MergeType.TYPESAFE:
                 if dpath.segments.has(dst, segments):
                     target = dpath.segments.get(dst, segments)
                     tt = type(target)
@@ -332,11 +340,11 @@ def merger(dst, src, _segments=()):
             #
             # Pretend we have a sequence and account for the flags.
             try:
-                if flags & MERGE_ADDITIVE:
+                if flags & MergeType.ADDITIVE:
                     target += found
                     continue
 
-                if flags & MERGE_REPLACE:
+                if flags & MergeType.REPLACE:
                     try:
                         target['']
                     except TypeError:

tests/test_types.py

@@ -106,7 +106,7 @@ def test_types_merge_simple_list_replace():
         "list": TestSequence([0, 1, 2, 3])
     })
 
-    dpath.util.merge(dst, src, flags=dpath.util.MERGE_REPLACE)
+    dpath.util.merge(dst, src, flags=dpath.util.MergeType.REPLACE)
     nose.tools.eq_(dst["list"], TestSequence([7, 8, 9, 10]))
 
 

tests/test_util_merge.py

@@ -19,7 +19,7 @@ def test_merge_typesafe_and_separator():
     }
 
     try:
-        dpath.util.merge(dst, src, flags=(dpath.util.MERGE_ADDITIVE | dpath.util.MERGE_TYPESAFE), separator=";")
+        dpath.util.merge(dst, src, flags=(dpath.util.MergeType.ADDITIVE | dpath.util.MergeType.TYPESAFE), separator=";")
     except TypeError as e:
         assert(str(e).endswith("dict;integer"))
 
@@ -59,7 +59,7 @@ def test_merge_simple_list_additive():
         "list": [0, 1, 2, 3],
     }
 
-    dpath.util.merge(dst, src, flags=dpath.util.MERGE_ADDITIVE)
+    dpath.util.merge(dst, src, flags=dpath.util.MergeType.ADDITIVE)
     nose.tools.eq_(dst["list"], [0, 1, 2, 3, 7, 8, 9, 10])
 
 
@@ -71,7 +71,7 @@ def test_merge_simple_list_replace():
         "list": [0, 1, 2, 3],
     }
 
-    dpath.util.merge(dst, src, flags=dpath.util.MERGE_REPLACE)
+    dpath.util.merge(dst, src, flags=dpath.util.MergeType.REPLACE)
     nose.tools.eq_(dst["list"], [7, 8, 9, 10])
 
 
@@ -123,7 +123,7 @@ def test_merge_typesafe():
         ],
     }
 
-    dpath.util.merge(dst, src, flags=dpath.util.MERGE_TYPESAFE)
+    dpath.util.merge(dst, src, flags=dpath.util.MergeType.TYPESAFE)
 
 
 @raises(TypeError)
@@ -156,20 +156,20 @@ class tcis(list):
     assert(dst['ms'][2] == 'c')
     assert("casserole" in dst["mm"])
 
-    dpath.util.merge(dst, src, flags=dpath.util.MERGE_TYPESAFE)
+    dpath.util.merge(dst, src, flags=dpath.util.MergeType.TYPESAFE)
 
 
 def test_merge_replace_1():
     dct_a = {"a": {"b": [1, 2, 3]}}
     dct_b = {"a": {"b": [1]}}
-    dpath.util.merge(dct_a, dct_b, flags=dpath.util.MERGE_REPLACE)
+    dpath.util.merge(dct_a, dct_b, flags=dpath.util.MergeType.REPLACE)
     assert(len(dct_a['a']['b']) == 1)
 
 
 def test_merge_replace_2():
     d1 = {'a': [0, 1, 2]}
     d2 = {'a': ['a']}
-    dpath.util.merge(d1, d2, flags=dpath.util.MERGE_REPLACE)
+    dpath.util.merge(d1, d2, flags=dpath.util.MergeType.REPLACE)
     assert(len(d1['a']) == 1)
     assert(d1['a'][0] == 'a')