kvgit 0.2.0__tar.gz → 0.2.2__tar.gz

{kvgit-0.2.0 → kvgit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.2.0
+Version: 0.2.2
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -49,7 +49,6 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
-| **Eviction** | High/low water rebase drops least-recently-used keys automatically |
 | **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 
 ## Install

{kvgit-0.2.0 → kvgit-0.2.2}/README.md

@@ -8,7 +8,6 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
-| **Eviction** | High/low water rebase drops least-recently-used keys automatically |
 | **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 
 ## Install

{kvgit-0.2.0 → kvgit-0.2.2}/kvgit/hamt.py

@@ -217,7 +217,9 @@ class Hamt:
         """
         return self.walk()[0]
 
-    def walk(self) -> tuple[dict[str, bytes], set[str]]:
+    def walk(
+        self, skip_nodes: set[str] | None = None
+    ) -> tuple[dict[str, bytes], set[str]]:
         """Walk the entire HAMT, returning (items, node_hashes).
 
         Single batched BFS that collects both the key→value entries
@@ -229,8 +231,19 @@ class Hamt:
         Same batching properties as ``materialize()``: one
         ``get_many`` call per tree level, O(log_branching N)
         round-trips total.
+
+        ``skip_nodes`` is an optional set of node hashes to treat as
+        already-visited. Skipped subtrees are not fetched, not
+        recursed into, and not included in the returned ``nodes``
+        set. Items beneath skipped subtrees are also omitted from
+        the returned ``items`` dict. Pass a cumulative seen-set
+        across multiple ``walk()`` calls (e.g. across the commits
+        of a branch's history) to share work where the underlying
+        HAMTs share structure — turns N-walks-over-shared-tree from
+        O(N · subtree) into O(unique nodes).
         """
-        if self.root == EMPTY_HASH:
+        skip = skip_nodes if skip_nodes is not None else set()
+        if self.root == EMPTY_HASH or self.root in skip:
             return {}, set()
 
         items: dict[str, bytes] = {}
@@ -239,11 +252,13 @@ class Hamt:
 
         while current_level:
             # Partition this level: nodes already in pending vs
-            # nodes that need to be fetched from the store.
+            # nodes that need to be fetched from the store. Drop
+            # anything in skip_nodes — those subtrees have already
+            # been visited by a prior walk.
             cached_nodes: dict[str, dict] = {}
             to_fetch: list[str] = []
             for node_hash in current_level:
-                if node_hash == EMPTY_HASH:
+                if node_hash == EMPTY_HASH or node_hash in skip:
                     continue
                 prefixed = self.prefix + node_hash
                 if prefixed in self.pending:
@@ -261,7 +276,7 @@ class Hamt:
             # node hash we successfully load.
             next_level: list[str] = []
             for node_hash in current_level:
-                if node_hash == EMPTY_HASH:
+                if node_hash == EMPTY_HASH or node_hash in skip:
                     continue
                 if node_hash in cached_nodes:
                     node = cached_nodes[node_hash]

{kvgit-0.2.0 → kvgit-0.2.2}/kvgit/kv/indexeddb.py

@@ -63,7 +63,14 @@ def _promise(executor):
 
 
 async def _idb_open(db_name: str, store_name: str):
-    """Open (or create) an IndexedDB database, returning the IDBDatabase."""
+    """Open (or create) an IndexedDB database, returning the IDBDatabase.
+
+    Rejects with a clear error when ``onblocked`` fires — a zombie
+    connection from another tab / window (or transient browser-side
+    state) can refuse the open indefinitely.  Without an explicit
+    handler the promise would never resolve and ``run_sync`` would
+    hang forever.
+    """
 
     def _executor(resolve, reject):
         request = indexedDB.open(db_name, 1)
@@ -79,9 +86,19 @@ async def _idb_open(db_name: str, store_name: str):
         def on_error(event):
             reject(event.target.error)
 
+        def on_blocked(event):
+            reject(
+                Exception(
+                    f"IndexedDB open of {db_name!r} is blocked. Close other "
+                    f"tabs / windows holding the database open and reload, "
+                    f"or restart the browser."
+                )
+            )
+
         request.onupgradeneeded = on_upgrade
         request.onsuccess = on_success
         request.onerror = on_error
+        request.onblocked = on_blocked
 
     return await _promise(_executor)
 

{kvgit-0.2.0 → kvgit-0.2.2}/kvgit/staged.py

@@ -140,6 +140,7 @@ class Staged(MutableMapping[str, Any]):
     def commit(
         self,
         *,
+        keys: set[str] | None = None,
         on_conflict: str = "raise",
         merge_fns: dict[str, MergeFn] | None = None,
         default_merge: MergeFn | None = None,
@@ -148,20 +149,36 @@ class Staged(MutableMapping[str, Any]):
         """Flush staged changes to the underlying Versioned store.
 
         Encodes staged values to bytes, wraps merge functions, and
-        calls ``Versioned.commit()``. On success, clears the staging
-        buffer.
+        calls ``Versioned.commit()``. On success, clears the committed
+        entries from the staging buffer.
+
+        Args:
+            keys: If provided, only commit these specific keys.
+                Keys not in ``_updates`` or ``_removals`` are silently
+                ignored. Uncommitted keys remain staged for a future
+                commit. When ``None`` (default), all staged changes
+                are committed.
 
         Returns:
             A MergeResult (truthy when committed).
         """
-        # Encode staged updates to bytes
+        # Encode staged updates to bytes — scoped to keys if provided
         encoded_updates: dict[str, bytes] | None = None
-        if self._updates:
-            encoded_updates = {
-                key: self._encoder(value) for key, value in self._updates.items()
-            }
-
-        removals = self._removals if self._removals else None
+        if keys is not None:
+            # Iterate the (typically small) keys set, not the full _updates dict
+            matched_updates = {k: self._updates[k] for k in keys if k in self._updates}
+            if matched_updates:
+                encoded_updates = {
+                    k: self._encoder(v) for k, v in matched_updates.items()
+                }
+            # .intersection() accepts any iterable, not just sets
+            removals = self._removals.intersection(keys) or None
+        else:
+            if self._updates:
+                encoded_updates = {
+                    key: self._encoder(value) for key, value in self._updates.items()
+                }
+            removals = self._removals if self._removals else None
 
         # Build effective merge fns and wrap to bytes-level
         effective_fns = dict(self._merge_fns)
@@ -188,8 +205,16 @@ class Staged(MutableMapping[str, Any]):
             info=info,
         )
         if result.merged:
-            self._updates.clear()
-            self._removals.clear()
+            if keys is not None:
+                # Only clear the committed keys from staging
+                for k in keys:
+                    self._updates.pop(k, None)
+                    self._removals.discard(k)
+            else:
+                self._updates.clear()
+                self._removals.clear()
+            # Always clear the full read cache — HEAD moved, so cached
+            # values from other keys may be stale after a merge.
             self._cache.clear()
         return result
 

{kvgit-0.2.0 → kvgit-0.2.2}/kvgit/versioned/keyset.py

@@ -146,14 +146,17 @@ class Keyset:
         """
         return {k: decode_entry(v) for k, v in self._hamt.materialize().items()}
 
-    def walk(self) -> tuple[dict[str, KeysetEntry], set[str]]:
+    def walk(
+        self, skip_nodes: set[str] | None = None
+    ) -> tuple[dict[str, KeysetEntry], set[str]]:
         """Single batched walk returning (entries, hamt_node_hashes).
 
         Equivalent to ``materialize()`` plus collecting every HAMT
         node hash, in one tree traversal. Used by GC mark phases
-        that need both — see ``Hamt.walk``.
+        that need both — see ``Hamt.walk`` (including the
+        ``skip_nodes`` cumulative seen-set semantics).
         """
-        raw_items, nodes = self._hamt.walk()
+        raw_items, nodes = self._hamt.walk(skip_nodes=skip_nodes)
         return {k: decode_entry(v) for k, v in raw_items.items()}, nodes
 
     def keys(self) -> Iterator[str]:

{kvgit-0.2.0 → kvgit-0.2.2}/kvgit/versioned/kv.py

@@ -735,11 +735,17 @@ class VersionedKV(VersionedBase):
                 if root is None:
                     continue
                 # Single batched walk per commit collects both the
-                # blob references and the HAMT node hashes.
-                entries, nodes = Keyset(self.store, root=root).walk()
+                # blob references and the HAMT node hashes. Pass the
+                # cumulative ``reachable_nodes`` as ``skip_nodes`` so
+                # subtrees already seen on a prior commit / branch are
+                # not re-fetched — structural sharing means the blobs
+                # under those subtrees are also already accounted for.
+                entries, new_nodes = Keyset(self.store, root=root).walk(
+                    skip_nodes=reachable_nodes
+                )
                 for entry in entries.values():
                     reachable_blobs.add(entry.blob)
-                reachable_nodes.update(nodes)
+                reachable_nodes.update(new_nodes)
 
         # Sweep phase: find orphaned commits via __commit_root__ scan.
         cutoff_time = time.time() - min_age

{kvgit-0.2.0 → kvgit-0.2.2}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.2.0
+Version: 0.2.2
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -49,7 +49,6 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
-| **Eviction** | High/low water rebase drops least-recently-used keys automatically |
 | **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 
 ## Install

{kvgit-0.2.0 → kvgit-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kvgit"
-version = "0.2.0"
+version = "0.2.2"
 description = "Versioned key-value store with git-like commit, branch, and merge semantics."
 authors = [{ name = "ashenfad" }]
 requires-python = ">=3.10"

{kvgit-0.2.0 → kvgit-0.2.2}/tests/test_hamt.py

@@ -779,3 +779,116 @@ def test_materialize_is_walk_dot_zero():
     items = {f"k{i:03d}": f"v{i}".encode() for i in range(50)}
     h = Hamt(_store(), bucket_max=4).persist(items)
     assert h.materialize() == h.walk()[0]
+
+
+# ---- walk(skip_nodes=...) cumulative seen-set ----
+
+
+def test_walk_skip_nodes_root_short_circuits():
+    """Skipping the root yields nothing — entire tree pruned."""
+    items = {f"k{i:03d}": f"v{i}".encode() for i in range(20)}
+    h = Hamt(_store(), bucket_max=4).persist(items)
+    walked_items, walked_nodes = h.walk(skip_nodes={h.root})
+    assert walked_items == {}
+    assert walked_nodes == set()
+
+
+def test_walk_skip_nodes_excludes_skipped_from_returned_set():
+    """Returned ``nodes`` excludes anything in ``skip_nodes``."""
+    items = {f"k{i:03d}": f"v{i}".encode() for i in range(60)}
+    h = Hamt(_store(), bucket_max=4).persist(items)
+    full_nodes = h.walk()[1]
+    # Pick an arbitrary non-root node to skip.
+    interior = next(iter(full_nodes - {h.root}))
+    _, walked_nodes = h.walk(skip_nodes={interior})
+    assert interior not in walked_nodes
+    # Other nodes are still visited (root at minimum).
+    assert h.root in walked_nodes
+
+
+def test_walk_skip_nodes_skips_subtree_items():
+    """Items beneath a skipped subtree are not returned."""
+    items = {f"k{i:03d}": f"v{i}".encode() for i in range(80)}
+    h = Hamt(_store(), bucket_max=4).persist(items)
+
+    # Find a non-root branch node and the items reachable beneath it,
+    # then verify those items are absent when we skip that node.
+    full_items, full_nodes = h.walk()
+    interior_candidates = full_nodes - {h.root}
+    # Walk only the subtree rooted at the candidate to see what's under it.
+    for candidate in interior_candidates:
+        sub_items = Hamt(h.store, root=candidate, bucket_max=4).walk()[0]
+        if sub_items and len(sub_items) < len(full_items):
+            walked_items, _ = h.walk(skip_nodes={candidate})
+            for k in sub_items:
+                assert k not in walked_items
+            # And the items not in that subtree are still present.
+            for k in full_items:
+                if k not in sub_items:
+                    assert walked_items[k] == full_items[k]
+            return
+    pytest.fail("expected to find at least one non-root subtree to skip")
+
+
+def test_walk_skip_nodes_does_not_fetch_skipped():
+    """Skipped nodes should not be fetched from the store at all."""
+    store = _CountingMemory()
+    items = {f"k{i:04d}": f"v{i}".encode() for i in range(200)}
+    h = Hamt(store, bucket_max=4).persist(items)
+    full_nodes = h.walk()[1]
+
+    # Skip every node — the only fetches should be ones forced by
+    # the level-batched fetch *before* we filter (we filter first
+    # in the implementation, so even those should be zero).
+    store.reset_counts()
+    walked_items, walked_nodes = h.walk(skip_nodes=full_nodes)
+    assert walked_items == {}
+    assert walked_nodes == set()
+    assert store.get_calls == 0
+    assert store.get_many_calls == 0, (
+        f"expected zero fetches when skipping the whole tree, "
+        f"got {store.get_many_calls}"
+    )
+
+
+def test_walk_skip_nodes_cumulative_across_shared_subtree():
+    """Two HAMTs sharing structure: walking the second with the
+    first's nodes as skip_nodes should fetch only what's new."""
+    base_items = {f"k{i:04d}": f"v{i}".encode() for i in range(120)}
+    store = _CountingMemory()
+    h1 = Hamt(store, bucket_max=4).persist(base_items)
+
+    # h2 shares the bulk of h1's structure — single-key delta.
+    h2 = h1.persist({"new-key": b"new-value"})
+    assert h2.root != h1.root
+
+    # First walk seeds the seen-set.
+    seen: set[str] = set()
+    items1, nodes1 = h1.walk(skip_nodes=seen)
+    seen |= nodes1
+
+    # Second walk: only the path from h2.root down to the changed
+    # leaf should be visited; the rest of the tree is in ``seen``.
+    store.reset_counts()
+    items2, nodes2 = h2.walk(skip_nodes=seen)
+    # New items: just the added key (and only items along visited
+    # paths — which by definition contain the new key).
+    assert "new-key" in items2
+    # Visited node count should be tiny relative to the full tree.
+    assert len(nodes2) < len(nodes1) // 4, (
+        f"expected shared-structure walk to revisit << {len(nodes1) // 4} "
+        f"nodes; got {len(nodes2)}"
+    )
+    # And no overlap between the two walks' returned node sets.
+    assert nodes1.isdisjoint(nodes2)
+
+
+def test_walk_skip_nodes_none_matches_no_arg():
+    """Passing skip_nodes=None is identical to omitting it."""
+    items = {f"k{i:03d}": f"v{i}".encode() for i in range(40)}
+    h = Hamt(_store(), bucket_max=4).persist(items)
+    a_items, a_nodes = h.walk()
+    b_items, b_nodes = h.walk(skip_nodes=None)
+    c_items, c_nodes = h.walk(skip_nodes=set())
+    assert a_items == b_items == c_items
+    assert a_nodes == b_nodes == c_nodes

{kvgit-0.2.0 → kvgit-0.2.2}/tests/test_staged.py

@@ -173,6 +173,117 @@ class TestStagedCommit:
         assert s.versioned.commit_info() == {"author": "test"}
 
 
+class TestStagedPartialCommit:
+    """Tests for commit(keys=...) partial commit support."""
+
+    def test_partial_commit_only_flushes_specified_keys(self):
+        store = Memory()
+        v = Versioned(store)
+        s = Staged(v)
+        s["a"] = 1
+        s["b"] = 2
+        result = s.commit(keys={"a"})
+        assert result.merged
+
+        # "a" is committed and no longer staged
+        assert not s.is_staged("a")
+        # "b" is still staged
+        assert s.is_staged("b")
+        assert s["b"] == 2
+
+    def test_partial_commit_persists_committed_keys(self):
+        store = Memory()
+        v = Versioned(store)
+        s = Staged(v)
+        s["a"] = 1
+        s["b"] = 2
+        s.commit(keys={"a"})
+
+        # Verify "a" is persisted (visible from a fresh Staged)
+        s2 = Staged(Versioned(store))
+        assert s2.get("a") == 1
+        # "b" is NOT persisted (still only in s's staging buffer)
+        assert s2.get("b") is None
+
+    def test_partial_commit_with_info(self):
+        s = Staged(Versioned())
+        s["a"] = 1
+        s["b"] = 2
+        result = s.commit(keys={"a"}, info={"message": "just a"})
+        assert result.merged
+        assert s.versioned.commit_info()["message"] == "just a"
+
+    def test_partial_commit_ignores_unknown_keys(self):
+        s = Staged(Versioned())
+        s["a"] = 1
+        # "ghost" is not staged — should be silently ignored
+        result = s.commit(keys={"a", "ghost"})
+        assert result.merged
+        assert not s.is_staged("a")
+
+    def test_partial_commit_with_removals(self):
+        s = Staged(Versioned())
+        s["a"] = 1
+        s["b"] = 2
+        s.commit()
+
+        del s["a"]
+        s["c"] = 3
+        # Partial commit: only the removal of "a"
+        s.commit(keys={"a"})
+        assert s.get("a") is None  # deleted
+        assert s.is_staged("c")  # still pending
+
+    def test_partial_commit_clears_full_cache(self):
+        """Regression test: after a partial commit, the entire read cache
+        must be cleared because HEAD moved. Cached values from non-committed
+        keys could be stale if a concurrent writer modified them.
+        """
+        store = Memory()
+        v = Versioned(store)
+        s = Staged(v)
+
+        s["x"] = "original_x"
+        s["y"] = "original_y"
+        s.commit()
+
+        # Read "y" to populate the cache
+        assert s["y"] == "original_y"
+
+        # Simulate a concurrent writer updating "y" on the same branch
+        v2 = Versioned(store)
+        v2.commit({"y": s._encoder("updated_by_other")})
+
+        # Partial commit of "x" — HEAD moves to include the concurrent write
+        s["x"] = "new_x"
+        s.commit(keys={"x"})
+
+        # After partial commit, "y" should reflect the concurrent update,
+        # NOT the stale cached value.  Before the fix, only "x" was evicted
+        # from cache, leaving "y" stale as "original_y".
+        s.refresh()
+        assert s["y"] == "updated_by_other"
+
+    def test_keys_accepts_non_set_iterable(self):
+        """keys parameter should accept any iterable, not just sets."""
+        s = Staged(Versioned())
+        s["a"] = 1
+        s["b"] = 2
+        # Pass a list instead of a set
+        result = s.commit(keys=["a"])
+        assert result.merged
+        assert not s.is_staged("a")
+        assert s.is_staged("b")
+
+    def test_full_commit_unchanged_when_keys_is_none(self):
+        """Without keys, commit flushes everything (backwards compatible)."""
+        s = Staged(Versioned())
+        s["a"] = 1
+        s["b"] = 2
+        s.commit()
+        assert not s.has_changes
+
+
 class TestStagedReset:
     def test_reset_clears_staging(self):
         s = Staged(Versioned())