Add hash map

Author: Cjkjvfnby

data_structures/hashing/hash_map.py

@@ -1,3 +1,12 @@
+"""
+Hash map with open addressing.
+
+https://en.wikipedia.org/wiki/Hash_table
+
+Another hash map implementation, with a good explanation.
+Modern Dictionaries by Raymond Hettinger
+https://www.youtube.com/watch?v=p33CVV29OG8
+"""
 from collections.abc import Iterator, MutableMapping
 from dataclasses import dataclass
 from typing import Generic, TypeVar
@@ -24,20 +33,37 @@ def __bool__(self):
 
 
 class HashMap(MutableMapping, Generic[KEY, VAL]):
+    """
+    Hash map with open addressing.
+    """
+
     def __init__(self, initial_block_size: int = 8, capacity_factor: float = 0.75):
         self._initial_block_size = initial_block_size
         self._buckets: list[_Item | None] = [None] * initial_block_size
         assert 0.0 < capacity_factor < 1.0
         self._capacity_factor = capacity_factor
         self._len = 0
 
-    def _get_index(self, key: KEY) -> int:
+    def _get_bucket_index(self, key: KEY) -> int:
         return hash(key) % len(self._buckets)
 
     def _get_next_ind(self, ind: int) -> int:
+        """
+        Get next index.
+
+        Implements linear open addressing.
+        """
         return (ind + 1) % len(self._buckets)
 
     def _try_set(self, ind: int, key: KEY, val: VAL) -> bool:
+        """
+        Try to add value to the bucket.
+
+        If bucket is empty or key is the same, does insert and return True.
+
+        If bucket has another key or deleted placeholder,
+        that means that we need to check next bucket.
+        """
         stored = self._buckets[ind]
         if not stored:
             self._buckets[ind] = _Item(key, val)
@@ -50,10 +76,16 @@ def _try_set(self, ind: int, key: KEY, val: VAL) -> bool:
             return False
 
     def _is_full(self):
+        """
+        Return true if we have reached safe capacity.
+
+        So we need to increase the number of buckets to avoid collisions.
+        """
         limit = len(self._buckets) * self._capacity_factor
         return len(self) >= int(limit)
 
     def _is_sparse(self):
+        """Return true if we need twice fewer buckets when we have now."""
         if len(self._buckets) <= self._initial_block_size:
             return False
         limit = len(self._buckets) * self._capacity_factor / 2
@@ -73,8 +105,8 @@ def _size_up(self):
     def _size_down(self):
         self._resize(len(self._buckets) // 2)
 
-    def _iterate_buckets(self, key: KEY):
-        ind = self._get_index(key)
+    def _iterate_buckets(self, key: KEY) -> Iterator[int]:
+        ind = self._get_bucket_index(key)
         for _ in range(len(self._buckets)):
             yield ind
             ind = self._get_next_ind(ind)
@@ -85,9 +117,6 @@ def _add_item(self, key: KEY, val: VAL):
                 break
 
     def __setitem__(self, key: KEY, val: VAL) -> None:
-        if self._is_sparse():
-            self._size_down()
-
         if self._is_full():
             self._size_up()
 
@@ -104,6 +133,8 @@ def __delitem__(self, key: KEY) -> None:
                 self._buckets[ind] = _deleted
                 self._len -= 1
                 break
+        if self._is_sparse():
+            self._size_down()
 
     def __getitem__(self, key: KEY) -> VAL:
         for ind in self._iterate_buckets(key):

data_structures/hashing/test_hash_map.py

@@ -5,66 +5,73 @@
 from data_structures.hashing.hash_map import HashMap
 
 
-def get(k):
+def _get(k):
     return getitem, k
 
 
-def set_(k, v):
+def _set(k, v):
     return setitem, k, v
 
 
-def delete(k):
+def _del(k):
     return delitem, k
 
 
-add_items = (
-    set_("key_a", "val_a"),
-    set_("key_b", "val_b"),
+def _run_operation(obj, fun, *args):
+    try:
+        return fun(obj, *args), None
+    except Exception as e:
+        return None, e
+
+
+_add_items = (
+    _set("key_a", "val_a"),
+    _set("key_b", "val_b"),
 )
 
-overwrite_items = [
-    set_("key_a", "val_a"),
-    set_("key_a", "val_b"),
+_overwrite_items = [
+    _set("key_a", "val_a"),
+    _set("key_a", "val_b"),
 ]
 
-delete_items = [
-    set_("key_a", "val_a"),
-    set_("key_b", "val_b"),
-    delete("key_a"),
-    delete("key_b"),
-    set_("key_a", "val_a"),
-    delete("key_a"),
+_delete_items = [
+    _set("key_a", "val_a"),
+    _set("key_b", "val_b"),
+    _del("key_a"),
+    _del("key_b"),
+    _set("key_a", "val_a"),
+    _del("key_a"),
 ]
 
-access_not_existing_items = [
-    get("key_a"),
-    delete("key_a"),
-    set_("key_a", "val_a"),
-    delete("key_a"),
-    delete("key_a"),
-    get("key_a"),
+_access_absent_items = [
+    _get("key_a"),
+    _del("key_a"),
+    _set("key_a", "val_a"),
+    _del("key_a"),
+    _del("key_a"),
+    _get("key_a"),
 ]
 
-with_resize_up = [
-    *[set_(x, x) for x in range(5)],  # guaranteed upsize
+_add_with_resize_up = [
+    *[_set(x, x) for x in range(5)],  # guaranteed upsize
 ]
 
-with_resize_down = [
-    *[set_(x, x) for x in range(5)],  # guaranteed upsize
-    *[delete(x) for x in range(5)],
-    set_("key_a", "val_b"),
+_add_with_resize_down = [
+    *[_set(x, x) for x in range(5)],  # guaranteed upsize
+    *[_del(x) for x in range(5)],
+    _set("key_a", "val_b"),
 ]
 
 
 @pytest.mark.parametrize(
     "operations",
     (
-        pytest.param(add_items, id="add items"),
-        pytest.param(overwrite_items, id="overwrite items"),
-        pytest.param(delete_items, id="delete items"),
-        pytest.param(access_not_existing_items, id="access none existing items"),
-        pytest.param(with_resize_up, id="with resize up"),
-        pytest.param(with_resize_down, id="with resize down"),
+        pytest.param(_add_items, id="add items"),
+        pytest.param(_overwrite_items, id="overwrite items"),
+        pytest.param(_delete_items, id="delete items"),
+        pytest.param(_access_absent_items, id="access absent items"),
+        pytest.param(_add_with_resize_up, id="add with resize up"),
+        pytest.param(_add_with_resize_down, id="add with resize down"),
     ),
 )
 def test_hash_map_is_the_same_as_dict(operations):
@@ -80,8 +87,11 @@ def test_hash_map_is_the_same_as_dict(operations):
         assert set(my.items()) == set(py.items())
 
 
-def _run_operation(obj, fun, *args):
-    try:
-        return fun(obj, *args), None
-    except Exception as e:
-        return None, e
+def test_no_new_methods_was_added_to_api():
+    def is_public(name: str) -> bool:
+        return not name.startswith("_")
+
+    dict_public_names = {name for name in dir({}) if is_public(name)}
+    hash_public_names = {name for name in dir(HashMap()) if is_public(name)}
+
+    assert dict_public_names > hash_public_names