Documentation

Author: moomoohk

dpath/segments.py

@@ -1,10 +1,10 @@
 from copy import deepcopy
 from fnmatch import fnmatchcase
-from typing import List, Sequence, Tuple, Iterator, Any, Dict, Union
+from typing import List, Sequence, Tuple, Iterator, Any, Dict, Union, Optional
 
 from dpath import options
 from dpath.exceptions import InvalidGlob, InvalidKeyName, PathNotFound
-from dpath.util import PathSegment
+from dpath.util import PathSegment, Creator, Hints
 
 
 def make_walkable(node) -> Iterator[Tuple[PathSegment, Any]]:
@@ -266,9 +266,9 @@ def extend(thing: List, index: int, value=None):
     return thing
 
 
-def __default_creator__(
+def _default_creator(
         current: Union[Dict, List],
-        segments: List[PathSegment],
+        segments: Sequence[PathSegment],
         i: int,
         hints: Sequence[Tuple[PathSegment, type]] = ()
 ):
@@ -301,7 +301,13 @@ def __default_creator__(
             current[segment] = {}
 
 
-def set(obj, segments, value, creator=__default_creator__, hints=()):
+def set(
+        obj,
+        segments: Sequence[PathSegment],
+        value,
+        creator: Optional[Creator] = _default_creator,
+        hints: Hints = ()
+):
     """
     Set the value in obj at the place indicated by segments. If creator is not
     None (default __default_creator__), then call the creator function to
@@ -323,7 +329,7 @@ def set(obj, segments, value, creator=__default_creator__, hints=()):
             current[segment]
         except:
             if creator is not None:
-                creator(current, segments, i, hints=hints)
+                creator(current, segments, i, hints)
             else:
                 raise
 

dpath/util.py

@@ -1,6 +1,6 @@
 from collections.abc import MutableMapping, MutableSequence
 from enum import IntFlag, auto
-from typing import Union, List, Any, Dict, Callable, Sequence, Tuple
+from typing import Union, List, Any, Dict, Callable, Sequence, Tuple, Optional
 
 from dpath import options, segments
 from dpath.exceptions import InvalidKeyName, PathNotFound
@@ -9,19 +9,40 @@
 
 
 class MergeType(IntFlag):
-    REPLACE = auto()
     ADDITIVE = auto()
+    """List objects are combined onto one long list (NOT a set). This is the default flag."""
+
+    REPLACE = auto()
+    """Instead of combining list objects, when 2 list objects are at an equal depth of merge, replace the destination 
+    with the source."""
+
     TYPESAFE = auto()
+    """When 2 keys at equal levels are of different types, raise a TypeError exception. By default, the source 
+    replaces the destination in this situation."""
 
 
-# Type alias for dict path segments where integers are explicitly casted
 PathSegment = Union[int, str]
+"""Type alias for dict path segments where integers are explicitly casted."""
+
+Filter = Callable[[Any], bool]
+"""Type alias for filter functions.
+
+(Any) -> bool"""
+
+Hints = Sequence[Tuple[PathSegment, type]]
+"""Type alias for creator function hint sequences."""
 
-# Type alias for filter functions
-Filter = Callable[[Any], bool]  # (Any) -> bool
+Creator = Callable[[Union[Dict, List], Sequence[PathSegment], int, Optional[Hints]], None]
+"""Type alias for creator functions.
 
-# Type alias for creator functions
-Creator = Callable[[Union[Dict, List], List[PathSegment], int, Sequence[Tuple[PathSegment, type]]], None]
+Example creator function signature:
+    
+    def creator(
+        current: Union[Dict, List],
+        segments: Sequence[PathSegment],
+        i: int,
+        hints: Sequence[Tuple[PathSegment, type]] = ()
+    )"""
 
 
 def _split_path(path: str, separator: str) -> Union[List[PathSegment], PathSegment]:
@@ -270,14 +291,6 @@ def merge(dst: Dict, src: Dict, separator='/', afilter: Filter = None, flags=Mer
     https://github.com/akesterson/dpath-python/issues/58
 
     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.
-        * REPLACE : Instead of combining list objects, when
-          2 list objects are at an equal depth of merge, replace
-          the destination with the source.
-        * 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.
     """
     filtered_src = search(src, '**', afilter=afilter, separator='/')