Type hint improvements and exports

Author: moomoohk

dpath/__init__.py

@@ -11,19 +11,26 @@
     "segments",
     "types",
     "version",
+    "MergeType",
+    "PathSegment",
+    "Filter",
+    "Glob",
+    "Path",
+    "Hints",
+    "Creator",
 ]
 
 from collections.abc import MutableMapping, MutableSequence
-from typing import Union, List, Dict, Any
+from typing import Union, List, Any, Callable, Optional
 
 from dpath import segments, options
 from dpath.exceptions import InvalidKeyName, PathNotFound
-from dpath.types import MergeType, PathSegment, Creator, Filter
+from dpath.types import MergeType, PathSegment, Creator, Filter, Glob, Path, Hints
 
 _DEFAULT_SENTINEL = object()
 
 
-def _split_path(path: str, separator: str) -> Union[List[PathSegment], PathSegment]:
+def _split_path(path: Path, separator: Optional[str]) -> Union[List[PathSegment], PathSegment]:
     """
     Given a path and separator, return a tuple of segments. If path is
     already a non-leaf thing, return it.
@@ -51,7 +58,7 @@ def _split_path(path: str, separator: str) -> Union[List[PathSegment], PathSegme
     return split_segments
 
 
-def new(obj: Dict, path: str, value, separator="/", creator: Creator = None) -> Dict:
+def new(obj: MutableMapping, path: Path, value, separator="/", creator: Creator = None) -> MutableMapping:
     """
     Set the element at the terminus of path to value, and create
     it if it does not exist (as opposed to 'set' that can only
@@ -71,7 +78,7 @@ def new(obj: Dict, path: str, value, separator="/", creator: Creator = None) ->
     return segments.set(obj, split_segments, value)
 
 
-def delete(obj: Dict, glob: str, separator="/", afilter: Filter = None) -> int:
+def delete(obj: MutableMapping, glob: Glob, separator="/", afilter: Filter = None) -> int:
     """
     Given a obj, delete all elements that match the glob.
 
@@ -130,7 +137,7 @@ def f(obj, pair, counter):
     return deleted
 
 
-def set(obj: Dict, glob: str, value, separator="/", afilter: Filter = None) -> int:
+def set(obj: MutableMapping, glob: Glob, value, separator="/", afilter: Filter = None) -> int:
     """
     Given a path glob, set all existing elements in the document
     to the given value. Returns the number of elements changed.
@@ -155,7 +162,12 @@ def f(obj, pair, counter):
     return changed
 
 
-def get(obj: Dict, glob: str, separator="/", default: Any = _DEFAULT_SENTINEL) -> Dict:
+def get(
+        obj: MutableMapping,
+        glob: Glob,
+        separator="/",
+        default: Any = _DEFAULT_SENTINEL
+) -> Union[MutableMapping, object, Callable]:
     """
     Given an object which contains only one possible match for the given glob,
     return the value for the leaf matching the given glob.
@@ -191,7 +203,7 @@ def f(_, pair, results):
     return results[0]
 
 
-def values(obj: Dict, glob: str, separator="/", afilter: Filter = None, dirs=True):
+def values(obj: MutableMapping, glob: Glob, separator="/", afilter: Filter = None, dirs=True):
     """
     Given an object and a path glob, return an array of all values which match
     the glob. The arguments to this function are identical to those of search().
@@ -201,7 +213,7 @@ def values(obj: Dict, glob: str, separator="/", afilter: Filter = None, dirs=Tru
     return [v for p, v in search(obj, glob, yielded, separator, afilter, dirs)]
 
 
-def search(obj: Dict, glob: str, yielded=False, separator="/", afilter: Filter = None, dirs=True):
+def search(obj: MutableMapping, glob: Glob, yielded=False, separator="/", afilter: Filter = None, dirs=True):
     """
     Given a path glob, return a dictionary containing all keys
     that matched the given glob.
@@ -243,7 +255,7 @@ def f(obj, pair, result):
         return segments.fold(obj, f, {})
 
 
-def merge(dst: Dict, src: Dict, separator="/", afilter: Filter = None, flags=MergeType.ADDITIVE):
+def merge(dst: MutableMapping, src: MutableMapping, separator="/", afilter: Filter = None, flags=MergeType.ADDITIVE):
     """
     Merge source into destination. Like dict.update() but performs deep
     merging.

dpath/segments.py

@@ -1,6 +1,6 @@
 from copy import deepcopy
 from fnmatch import fnmatchcase
-from typing import List, Sequence, Tuple, Iterator, Any, Dict, Union, Optional
+from typing import List, Sequence, Tuple, Iterator, Any, Union, Optional, MutableMapping
 
 from dpath import options
 from dpath.exceptions import InvalidGlob, InvalidKeyName, PathNotFound
@@ -266,7 +266,7 @@ def extend(thing: List, index: int, value=None):
 
 
 def _default_creator(
-        current: Union[Dict, List],
+        current: Union[MutableMapping, List],
         segments: Sequence[PathSegment],
         i: int,
         hints: Sequence[Tuple[PathSegment, type]] = ()
@@ -301,12 +301,12 @@ def _default_creator(
 
 
 def set(
-        obj,
+        obj: MutableMapping,
         segments: Sequence[PathSegment],
         value,
         creator: Optional[Creator] = _default_creator,
         hints: Hints = ()
-):
+) -> MutableMapping:
     """
     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

dpath/types.py

@@ -1,5 +1,5 @@
 from enum import IntFlag, auto
-from typing import Union, Any, Callable, Sequence, Tuple, Dict, List, Optional
+from typing import Union, Any, Callable, Sequence, Tuple, List, Optional, MutableMapping
 
 
 class MergeType(IntFlag):
@@ -23,16 +23,22 @@ class MergeType(IntFlag):
 
 (Any) -> bool"""
 
+Glob = Union[str, Sequence[str]]
+"""Type alias for glob parameters."""
+
+Path = Union[str, Sequence[PathSegment]]
+"""Type alias for path parameters."""
+
 Hints = Sequence[Tuple[PathSegment, type]]
 """Type alias for creator function hint sequences."""
 
-Creator = Callable[[Union[Dict, List], Sequence[PathSegment], int, Optional[Hints]], None]
+Creator = Callable[[Union[MutableMapping, List], Path, int, Optional[Hints]], None]
 """Type alias for creator functions.
 
 Example creator function signature:
 
     def creator(
-        current: Union[Dict, List],
+        current: Union[MutableMapping, List],
         segments: Sequence[PathSegment],
         i: int,
         hints: Sequence[Tuple[PathSegment, type]] = ()

tests/test_types.py

@@ -7,7 +7,10 @@
 
 
 class TestMapping(MutableMapping):
-    def __init__(self, data={}):
+    def __init__(self, data=None):
+        if data is None:
+            data = {}
+
         self._mapping = {}
         self._mapping.update(data)
 
@@ -31,7 +34,10 @@ def __delitem__(self, key):
 
 
 class TestSequence(MutableSequence):
-    def __init__(self, data=list()):
+    def __init__(self, data=None):
+        if data is None:
+            data = list()
+
         self._list = [] + data
 
     def __len__(self):