feat: paths_getter (to make multiple paths extractors)

dol/paths.py

@@ -101,7 +101,13 @@ def _path_get(
         except caught_errors as error:
             if callable(on_error):
                 return on_error(
-                    dict(obj=obj, path=path, result=result, k=k, error=error,)
+                    dict(
+                        obj=obj,
+                        path=path,
+                        result=result,
+                        k=k,
+                        error=error,
+                    )
                 )
             elif isinstance(on_error, str):
                 # use on_error as a message, raising the same error class
@@ -226,6 +232,37 @@ def path_get(
 path_get.get_attr = getattr
 
 
+@add_as_attribute_of(path_get)
+def paths_getter(paths, obj=None, *, egress=dict, **kwargs):
+    """
+    Returns (path, values) pairs of the given paths in the given object.
+    This is the "fan-out" version of ``path_get``, specifically designed to
+    get multiple paths, returning the (path, value) pairs in a dict (by default),
+    or via any pairs aggregator (``egress``) function.
+
+    :param paths: The paths to get
+    :param obj: The object to get the paths from
+    :param egress: The egress function to use (default: dict)
+    :param kwargs: Extra kwargs to pass to ``path_get``
+
+    >>> obj = {'a': {'b': 1, 'c': 2}, 'd': 3}
+    >>> paths = ['a.c', 'd']
+    >>> paths_getter(paths, obj=obj)
+    {'a.c': 2, 'd': 3}
+    >>> path_extractor = paths_getter(paths)
+    >>> path_extractor(obj)
+    {'a.c': 2, 'd': 3}
+    """
+    if obj is None:
+        return partial(paths_getter, paths, **kwargs)
+
+    def pairs():
+        for path in paths:
+            yield path, path_get(obj, path=path, **kwargs)
+
+    return egress(pairs())
+
+
 @add_as_attribute_of(path_get)
 def chain_of_getters(
     getters: Iterable[Callable], obj=None, k=None, *, caught_errors=(Exception,)
@@ -682,7 +719,11 @@ def __init__(self, _prefix=''):
 
 @store_decorator
 def mk_relative_path_store(
-    store_cls=None, *, name=None, with_key_validation=False, prefix_attr='_prefix',
+    store_cls=None,
+    *,
+    name=None,
+    with_key_validation=False,
+    prefix_attr='_prefix',
 ):
     """
 
@@ -1556,7 +1597,8 @@ def single_to_str(self, k: Any) -> str:
 
     # @_return_none_if_none_input
     def dict_to_namedtuple(
-        self, params: dict,
+        self,
+        params: dict,
     ):
         r"""Generates a namedtuple from the dictionary values based on the template.