X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=dict_utils.py;h=573e683c1d84d2f0f11d18e61fa9f950f585e1c4;hb=a9bdfd8fc9f84b7b2c09a57cd12ba32259e84d1c;hp=b1464c6bb9967ce4efa48318a288babd0ff322e9;hpb=8d6abef443543013d7b37cda1375a28f040d24a6;p=python_utils.git

diff --git a/dict_utils.py b/dict_utils.py
index b1464c6..573e683 100644
--- a/dict_utils.py
+++ b/dict_utils.py
@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+# © Copyright 2021-2022, Scott Gasch
+
+"""Helper functions for dealing with dictionaries."""
+
 from itertools import islice
 from typing import Any, Callable, Dict, Iterator, List, Tuple
 
@@ -38,47 +42,60 @@ def shard(d: Dict[Any, Any], size: int) -> Iterator[Dict[Any, Any]]:
     """
     Shards a dict into N subdicts which, together, contain all keys/values
     from the original unsharded dict.
-
     """
     items = d.items()
     for x in range(0, len(d), size):
-        yield {key: value for (key, value) in islice(items, x, x + size)}
+        yield dict(islice(items, x, x + size))
 
 
-def coalesce_by_creating_list(key, new_value, old_value):
+def coalesce_by_creating_list(_, new_value, old_value):
+    """Helper for use with :meth:`coalesce` that creates a list on
+    collision."""
     from list_utils import flatten
 
     return flatten([new_value, old_value])
 
 
 def coalesce_by_creating_set(key, new_value, old_value):
+    """Helper for use with :meth:`coalesce` that creates a set on
+    collision."""
     return set(coalesce_by_creating_list(key, new_value, old_value))
 
 
-def coalesce_last_write_wins(key, new_value, old_value):
+def coalesce_last_write_wins(_, new_value, discarded_old_value):
+    """Helper for use with :meth:`coalsce` that klobbers the old
+    with the new one on collision."""
     return new_value
 
 
-def coalesce_first_write_wins(key, new_value, old_value):
+def coalesce_first_write_wins(_, discarded_new_value, old_value):
+    """Helper for use with :meth:`coalsce` that preserves the old
+    value and discards the new one on collision."""
     return old_value
 
 
 def raise_on_duplicated_keys(key, new_value, old_value):
+    """Helper for use with :meth:`coalesce` that raises an exception
+    when a collision is detected.
+    """
     raise Exception(f'Key {key} is duplicated in more than one input dict.')
 
 
 def coalesce(
     inputs: Iterator[Dict[Any, Any]],
     *,
-    aggregation_function: Callable[[Any, Any], Any] = coalesce_by_creating_list,
+    aggregation_function: Callable[[Any, Any, Any], Any] = coalesce_by_creating_list,
 ) -> Dict[Any, Any]:
     """Merge N dicts into one dict containing the union of all keys /
     values in the input dicts.  When keys collide, apply the
     aggregation_function which, by default, creates a list of values.
-    See also several other alternative functions for coalescing values
-    (coalesce_by_creating_set, coalesce_first_write_wins,
-    coalesce_last_write_wins, raise_on_duplicated_keys) or provide a
-    custom helper function.
+    See also several other alternative functions for coalescing values:
+
+        * :meth:`coalesce_by_creating_set`
+        * :meth:`coalesce_first_write_wins`
+        * :meth:`coalesce_last_write_wins`
+        * :meth:`raise_on_duplicated_keys`
+        * or provive your own collision resolution code.
 
     >>> a = {'a': 1, 'b': 2}
     >>> b = {'b': 1, 'c': 2, 'd': 3}
@@ -107,7 +124,7 @@ def coalesce(
 
 
 def item_with_max_value(d: Dict[Any, Any]) -> Tuple[Any, Any]:
-    """Returns the key and value with the max value in a dict.
+    """Returns the key and value of the item with the max value in a dict.
 
     >>> d = {'a': 1, 'b': 2, 'c': 3}
     >>> item_with_max_value(d)
@@ -122,7 +139,7 @@ def item_with_max_value(d: Dict[Any, Any]) -> Tuple[Any, Any]:
 
 
 def item_with_min_value(d: Dict[Any, Any]) -> Tuple[Any, Any]:
-    """Returns the key and value with the min value in a dict.
+    """Returns the key and value of the item with the min value in a dict.
 
     >>> d = {'a': 1, 'b': 2, 'c': 3}
     >>> item_with_min_value(d)
@@ -223,7 +240,7 @@ def dict_to_key_value_lists(d: Dict[Any, Any]) -> Tuple[List[Any], List[Any]]:
     ['scott', '555-1212', '123 main st.', '12345']
 
     """
-    r = ([], [])
+    r: Tuple[List[Any], List[Any]] = ([], [])
     for (k, v) in d.items():
         r[0].append(k)
         r[1].append(v)