kvgit 0.3.1__tar.gz → 0.3.2__tar.gz

{kvgit-0.3.1 → kvgit-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.1
+Version: 0.3.2
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.3.1 → kvgit-0.3.2}/kvgit/__init__.py

@@ -5,7 +5,7 @@ from .errors import ConcurrencyError, MergeConflict
 from .namespaced import Namespaced
 from .versioned.protocol import MergeResult, Versioned
 from .staged import Staged
-from .store import store
+from .store import delete_branches, store
 from .versioned.kv import VersionedKV
 
 __all__ = [
@@ -18,6 +18,7 @@ __all__ = [
     "Versioned",
     "VersionedKV",
     "counter",
+    "delete_branches",
     "last_writer_wins",
     "store",
 ]

{kvgit-0.3.1 → kvgit-0.3.2}/kvgit/kv/disk.py

@@ -87,3 +87,10 @@ class Disk(KVStore):
 
     def clear(self) -> None:
         self.store.clear()
+
+    def close(self) -> None:
+        # diskcache holds SQLite connections (one per thread) open until
+        # closed. Admin teardown (kvgit.delete_branches) constructs a
+        # backend just to sweep and must release the handle so the next
+        # opener on the same directory isn't blocked.
+        self.store.close()

kvgit-0.3.2/kvgit/store.py

@@ -0,0 +1,152 @@
+"""Store factory function."""
+
+import pickle
+from collections.abc import Iterable
+from typing import Any, Callable, Literal
+
+from .kv.base import KVStore
+from .kv.memory import Memory
+from .staged import Staged
+from .versioned.kv import BRANCH_HEAD, BRANCH_HEAD_PREV, VersionedKV, clean_orphans
+
+
+def _make_backend(
+    kind: Literal["memory", "disk", "indexeddb"],
+    *,
+    path: str | None,
+    db_name: str,
+) -> KVStore:
+    """Construct a raw ``KVStore`` backend by kind.
+
+    Shared by :func:`store` and :func:`delete_branches` so both open the
+    exact same backends from the same parameters.
+    """
+    if kind == "memory":
+        return Memory()
+    elif kind == "disk":
+        if path is None:
+            raise ValueError("path is required when kind='disk'")
+        from .kv.disk import Disk
+
+        return Disk(path)
+    elif kind == "indexeddb":
+        from .kv.indexeddb import IndexedDB
+
+        return IndexedDB(db_name=db_name)
+    else:
+        raise ValueError(f"Unknown kind: {kind!r}")
+
+
+def store(
+    kind: Literal["memory", "disk", "indexeddb"] = "memory",
+    *,
+    path: str | None = None,
+    db_name: str = "kvgit",
+    branch: str = "main",
+    encoder: Callable[..., bytes] = pickle.dumps,
+    decoder: Callable[..., Any] = pickle.loads,
+    codecs: str | None = None,
+) -> Staged:
+    """Create a Staged store with sensible defaults.
+
+    Args:
+        kind: ``"memory"`` (default), ``"disk"``, or ``"indexeddb"``.
+        path: Required when ``kind="disk"``. Directory path for the
+            disk backend.
+        db_name: IndexedDB database name (default ``"kvgit"``).
+            Only used when ``kind="indexeddb"``.
+        branch: Branch name (default ``"main"``).
+        encoder: Value encoder (default ``pickle.dumps``).
+        decoder: Value decoder (default ``pickle.loads``).
+        codecs: Optional named codec preset. Currently supported:
+            ``"scientific"`` — numpy/pandas chunked codecs (requires
+            numpy; install with ``pip install kvgit[scientific]``).
+            Mutually exclusive with explicit ``encoder`` / ``decoder``.
+
+    Returns:
+        A ``Staged`` store instance.
+
+    Raises:
+        ValueError: if ``codecs`` is given alongside non-default
+            ``encoder`` / ``decoder``, or if ``codecs`` names an
+            unknown preset.
+        ImportError: if a codec preset's optional dependency is not
+            installed.
+    """
+    if codecs is not None:
+        if encoder is not pickle.dumps or decoder is not pickle.loads:
+            raise ValueError(
+                "codecs= is mutually exclusive with explicit encoder/decoder; "
+                "pass one or the other"
+            )
+        from .codecs import _resolve_named
+
+        encoder, decoder = _resolve_named(codecs)
+
+    backend = _make_backend(kind, path=path, db_name=db_name)
+
+    return Staged(VersionedKV(backend, branch=branch), encoder=encoder, decoder=decoder)
+
+
+def delete_branches(
+    names: str | Iterable[str],
+    *,
+    kind: Literal["memory", "disk", "indexeddb"] = "disk",
+    path: str | None = None,
+    db_name: str = "kvgit",
+    min_age: float = 3600,
+) -> None:
+    """Delete branches with no branch anchor, then sweep orphans.
+
+    :meth:`VersionedKV.delete_branch` refuses to delete the branch its
+    handle is anchored on — and there is no way to open a handle
+    *without* a branch. When the branch you want gone is the store's
+    only branch, there is nothing safe to anchor on. This admin entry
+    point sidesteps the whole problem: it opens the backend directly
+    (no ``VersionedKV``, so no current branch) and edits the branch
+    keys itself.
+
+    For each name, ``__branch_head__<name>`` and its
+    ``__branch_head_prev__<name>`` recovery backup are removed — the
+    backup too, so a later same-named branch can't "recover" the
+    deleted state through ``_resolve_head``'s fallback. A name with no
+    head is simply skipped: this is teardown, and idempotency beats a
+    ``ValueError`` here. Deleting every branch is legal — the store
+    just mints a fresh empty ``main`` on next open.
+
+    One :func:`clean_orphans` sweep runs after all removals, so commits
+    that only the deleted branches referenced are reclaimed. All heads
+    (and prev-heads) are gone before the sweep, so it can't mistake a
+    doomed branch for a live one. ``min_age`` defaults to
+    ``clean_orphans``'s one-hour guard (matching ``delete_branch``), so
+    an in-flight commit from a concurrent writer on another branch is
+    not swept out from under it; an admin who knows the store is quiet
+    can pass ``0`` to reclaim young commits immediately.
+
+    Args:
+        names: Branch names to delete — one name or an iterable of
+            them. Missing names are no-ops. (A bare string is treated
+            as ONE name, not iterated per character.)
+        kind: ``"disk"`` (default), ``"memory"``, or ``"indexeddb"``.
+        path: Required when ``kind="disk"``. Store directory.
+        db_name: IndexedDB database name (``kind="indexeddb"`` only).
+        min_age: Passed to :func:`clean_orphans` — commits younger than
+            this many seconds survive the sweep.
+    """
+    # A bare string is a plausible one-branch call, and iterating it
+    # would "delete" each character as a branch name — a silent no-op
+    # at best. Treat it as a single name, like nontainer's
+    # delete_workspace does one layer up.
+    doomed = {names} if isinstance(names, str) else set(names)
+    if not doomed:
+        return  # nothing asked: skip the backend open and the sweep
+    backend = _make_backend(kind, path=path, db_name=db_name)
+    try:
+        for name in doomed:
+            backend.remove(BRANCH_HEAD % name)
+            backend.remove(BRANCH_HEAD_PREV % name)
+        clean_orphans(backend, min_age=min_age)
+    finally:
+        close = getattr(backend, "close", None)
+        if callable(close):
+            close()

{kvgit-0.3.1 → kvgit-0.3.2}/kvgit/versioned/kv.py

@@ -47,6 +47,7 @@ from ..hamt import EMPTY_HASH
 from ..kv.base import KVStore
 from ..kv.memory import Memory
 from .base import VersionedBase
+from .helpers import walk_history
 from .keyset import Keyset, KeysetEntry, MetaEntry
 from .merge import MergeResolution
 
@@ -265,6 +266,167 @@ def _scan_for_best_commit(store: KVStore, branch: str) -> str | None:
     return max(tips, key=lambda h: all_commits.get(h, 0))
 
 
+def clean_orphans(store: KVStore, min_age: float = 3600) -> int:
+    """Remove orphaned commits unreachable from any branch HEAD.
+
+    Traces all reachable commits from live branch HEADs, then deletes
+    commit metadata, blobs, and HAMT nodes that are not reachable from
+    any reachable commit.
+
+    Handle-independent by design: it marks from ALL live branch HEADs
+    and touches nothing but ``store``, so it works with or without a
+    ``VersionedKV`` anchored on it. :meth:`VersionedKV.clean_orphans`
+    and the anchor-free admin path (:func:`kvgit.delete_branches`)
+    share this one implementation.
+
+    The ``min_age`` guard (default 1 hour) prevents recently created
+    commits from being falsely swept during concurrent writes.
+
+    Returns:
+        Number of orphaned commits removed.
+    """
+    gc_logger = logging.getLogger("kvgit.orphans")
+    cutoff_time = time.time() - min_age
+
+    def _parent_loader(commit_hash: str) -> tuple[str, ...]:
+        parent_bytes = store.get(PARENT_COMMIT % commit_hash)
+        if parent_bytes is None:
+            return ()
+        raw = loads(parent_bytes)
+        if raw is None:
+            return ()
+        if isinstance(raw, str):
+            return (raw,)
+        return tuple(raw)
+
+    # Mark phase: walk every branch's history, collecting reachable
+    # commits, blob keys, HAMT node hashes, and chunk references.
+    reachable_commits: set[str] = set()
+    reachable_blobs: set[str] = set()
+    reachable_nodes: set[str] = set()
+    reachable_chunks: set[str] = set()
+
+    def _walk_commit_for_marks(commit_hash: str) -> None:
+        """Walk one commit's keyset, accumulating reachable refs."""
+        root = _load_root(store, commit_hash)
+        if root is None:
+            return
+        # Single batched walk per commit collects HAMT node hashes
+        # and the entries (each carrying blob + optional chunks).
+        # ``skip_nodes`` lets us skip subtrees already seen via
+        # structural sharing — the blobs under those subtrees are
+        # already accounted for.
+        entries, new_nodes = Keyset(store, root=root).walk(skip_nodes=reachable_nodes)
+        for entry in entries.values():
+            reachable_blobs.add(entry.blob)
+            if entry.meta.chunks:
+                reachable_chunks.update(entry.meta.chunks)
+        reachable_nodes.update(new_nodes)
+
+    branch_prefix = BRANCH_HEAD.replace("%s", "")
+    for key in store.keys():
+        if not (isinstance(key, str) and key.startswith(branch_prefix)):
+            continue
+        branch_name = key[len(branch_prefix) :]
+        branch_head = _resolve_head(store, branch_name)
+        if branch_head is None:
+            continue
+        for commit in walk_history(branch_head, _parent_loader, all_parents=True):
+            if commit in reachable_commits:
+                continue
+            reachable_commits.add(commit)
+            _walk_commit_for_marks(commit)
+
+    # Sweep phase: find orphaned commits via __commit_root__ scan.
+    # Also identify "young orphans" — commits inside the min_age
+    # window that aren't branch-reachable. Their chunks must be
+    # protected from sweeping (they may be in-flight from another
+    # writer), even though we won't delete the commits themselves
+    # until they age past the cutoff.
+    orphans: list[str] = []
+    young_orphan_commits: list[str] = []
+    root_prefix = COMMIT_ROOT.replace("%s", "")
+
+    for key in store.keys():
+        if not (isinstance(key, str) and key.startswith(root_prefix)):
+            continue
+        commit_hash = key[len(root_prefix) :]
+        if not commit_hash or commit_hash in reachable_commits:
+            continue
+        time_bytes = store.get(COMMIT_TIME % commit_hash)
+        if time_bytes is None:
+            # No timestamp recorded — be conservative, leave it alone.
+            continue
+        try:
+            ts_val = safe_loads(time_bytes)
+            if not isinstance(ts_val, (int, float)):
+                continue
+            if float(ts_val) < cutoff_time:
+                orphans.append(commit_hash)
+            else:
+                young_orphan_commits.append(commit_hash)
+        except (TypeError, ValueError):
+            continue
+
+    # Protect chunks referenced by young orphan commits — those
+    # may belong to in-flight writers whose CAS has not landed yet.
+    for young in young_orphan_commits:
+        _walk_commit_for_marks(young)
+
+    # Collect everything to delete in one batch so the sweep is atomic
+    # at the store level (defends against partial sweeps under crash).
+    all_removals: list[str] = []
+
+    for orphan_hash in orphans:
+        orphan_root = _load_root(store, orphan_hash)
+        if orphan_root is not None and orphan_root != EMPTY_HASH:
+            try:
+                # Batched walk for the orphan's blob references.
+                orphan_entries = Keyset(store, root=orphan_root).materialize()
+                for entry in orphan_entries.values():
+                    if entry.blob not in reachable_blobs:
+                        all_removals.append(entry.blob)
+                    # Chunks in the orphan are only swept later via
+                    # the chunk-namespace scan below; here we only
+                    # need to ensure we've picked up the blob refs.
+            except Exception:
+                pass
+        all_removals.extend(
+            [
+                COMMIT_ROOT % orphan_hash,
+                PARENT_COMMIT % orphan_hash,
+                COMMIT_TIME % orphan_hash,
+                INFO_KEY % orphan_hash,
+            ]
+        )
+
+    # Orphan HAMT nodes: any keyset node not reachable from a live commit
+    keyset_prefix = Keyset.DEFAULT_PREFIX
+    for key in store.keys():
+        if not (isinstance(key, str) and key.startswith(keyset_prefix)):
+            continue
+        node_hash = key[len(keyset_prefix) :]
+        if node_hash and node_hash not in reachable_nodes:
+            all_removals.append(key)
+
+    # Orphan chunks: any chunk not reachable from a live commit
+    # (or a young orphan, see above) is fair game.
+    for key in store.keys():
+        if not (isinstance(key, str) and key.startswith(CHUNK_PREFIX)):
+            continue
+        chunk_hash = key[len(CHUNK_PREFIX) :]
+        if chunk_hash and chunk_hash not in reachable_chunks:
+            all_removals.append(key)
+
+    if all_removals:
+        store.remove_many(*all_removals)
+
+    if orphans:
+        gc_logger.debug("Cleaned %d orphaned commit(s)", len(orphans))
+
+    return len(orphans)
+
+
 class VersionedKV(VersionedBase):
     """A commit log over a KV store.
 
@@ -755,148 +917,14 @@ class VersionedKV(VersionedBase):
     def clean_orphans(self, min_age: float = 3600) -> int:
         """Remove orphaned commits unreachable from any branch HEAD.
 
-        Traces all reachable commits from live branch HEADs, then
-        deletes commit metadata, blobs, and HAMT nodes that are not
-        reachable from any reachable commit.
-
-        The ``min_age`` guard (default 1 hour) prevents recently
-        created commits from being falsely swept during concurrent
-        writes.
+        Thin instance wrapper over :func:`clean_orphans`, which does the
+        mark-and-sweep against ``self.store``. Kept as a method so
+        existing callers (and ``delete_branch``) read naturally.
 
         Returns:
             Number of orphaned commits removed.
         """
-        gc_logger = logging.getLogger("kvgit.orphans")
-        cutoff_time = time.time() - min_age
-
-        # Mark phase: walk every branch's history, collecting reachable
-        # commits, blob keys, HAMT node hashes, and chunk references.
-        reachable_commits: set[str] = set()
-        reachable_blobs: set[str] = set()
-        reachable_nodes: set[str] = set()
-        reachable_chunks: set[str] = set()
-
-        def _walk_commit_for_marks(commit_hash: str) -> None:
-            """Walk one commit's keyset, accumulating reachable refs."""
-            root = _load_root(self.store, commit_hash)
-            if root is None:
-                return
-            # Single batched walk per commit collects HAMT node hashes
-            # and the entries (each carrying blob + optional chunks).
-            # ``skip_nodes`` lets us skip subtrees already seen via
-            # structural sharing — the blobs under those subtrees are
-            # 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)
-                if entry.meta.chunks:
-                    reachable_chunks.update(entry.meta.chunks)
-            reachable_nodes.update(new_nodes)
-
-        branch_prefix = BRANCH_HEAD.replace("%s", "")
-        for key in self.store.keys():
-            if not (isinstance(key, str) and key.startswith(branch_prefix)):
-                continue
-            branch_name = key[len(branch_prefix) :]
-            branch_head = _resolve_head(self.store, branch_name)
-            if branch_head is None:
-                continue
-            for commit in self.history(commit_hash=branch_head, all_parents=True):
-                if commit in reachable_commits:
-                    continue
-                reachable_commits.add(commit)
-                _walk_commit_for_marks(commit)
-
-        # Sweep phase: find orphaned commits via __commit_root__ scan.
-        # Also identify "young orphans" — commits inside the min_age
-        # window that aren't branch-reachable. Their chunks must be
-        # protected from sweeping (they may be in-flight from another
-        # writer), even though we won't delete the commits themselves
-        # until they age past the cutoff.
-        orphans: list[str] = []
-        young_orphan_commits: list[str] = []
-        root_prefix = COMMIT_ROOT.replace("%s", "")
-
-        for key in self.store.keys():
-            if not (isinstance(key, str) and key.startswith(root_prefix)):
-                continue
-            commit_hash = key[len(root_prefix) :]
-            if not commit_hash or commit_hash in reachable_commits:
-                continue
-            time_bytes = self.store.get(COMMIT_TIME % commit_hash)
-            if time_bytes is None:
-                # No timestamp recorded — be conservative, leave it alone.
-                continue
-            try:
-                ts_val = safe_loads(time_bytes)
-                if not isinstance(ts_val, (int, float)):
-                    continue
-                if float(ts_val) < cutoff_time:
-                    orphans.append(commit_hash)
-                else:
-                    young_orphan_commits.append(commit_hash)
-            except (TypeError, ValueError):
-                continue
-
-        # Protect chunks referenced by young orphan commits — those
-        # may belong to in-flight writers whose CAS has not landed yet.
-        for young in young_orphan_commits:
-            _walk_commit_for_marks(young)
-
-        # Collect everything to delete in one batch so the sweep is atomic
-        # at the store level (defends against partial sweeps under crash).
-        all_removals: list[str] = []
-
-        for orphan_hash in orphans:
-            orphan_root = _load_root(self.store, orphan_hash)
-            if orphan_root is not None and orphan_root != EMPTY_HASH:
-                try:
-                    # Batched walk for the orphan's blob references.
-                    orphan_entries = Keyset(self.store, root=orphan_root).materialize()
-                    for entry in orphan_entries.values():
-                        if entry.blob not in reachable_blobs:
-                            all_removals.append(entry.blob)
-                        # Chunks in the orphan are only swept later via
-                        # the chunk-namespace scan below; here we only
-                        # need to ensure we've picked up the blob refs.
-                except Exception:
-                    pass
-            all_removals.extend(
-                [
-                    COMMIT_ROOT % orphan_hash,
-                    PARENT_COMMIT % orphan_hash,
-                    COMMIT_TIME % orphan_hash,
-                    INFO_KEY % orphan_hash,
-                ]
-            )
-
-        # Orphan HAMT nodes: any keyset node not reachable from a live commit
-        keyset_prefix = Keyset.DEFAULT_PREFIX
-        for key in self.store.keys():
-            if not (isinstance(key, str) and key.startswith(keyset_prefix)):
-                continue
-            node_hash = key[len(keyset_prefix) :]
-            if node_hash and node_hash not in reachable_nodes:
-                all_removals.append(key)
-
-        # Orphan chunks: any chunk not reachable from a live commit
-        # (or a young orphan, see above) is fair game.
-        for key in self.store.keys():
-            if not (isinstance(key, str) and key.startswith(CHUNK_PREFIX)):
-                continue
-            chunk_hash = key[len(CHUNK_PREFIX) :]
-            if chunk_hash and chunk_hash not in reachable_chunks:
-                all_removals.append(key)
-
-        if all_removals:
-            self.store.remove_many(*all_removals)
-
-        if orphans:
-            gc_logger.debug("Cleaned %d orphaned commit(s)", len(orphans))
-
-        return len(orphans)
+        return clean_orphans(self.store, min_age)
 
     # -- Internal --
 

{kvgit-0.3.1 → kvgit-0.3.2}/kvgit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.1
+Version: 0.3.2
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT

{kvgit-0.3.1 → kvgit-0.3.2}/kvgit.egg-info/SOURCES.txt

@@ -35,6 +35,7 @@ kvgit/versioned/kv.py
 kvgit/versioned/merge.py
 kvgit/versioned/protocol.py
 tests/test_content_types.py
+tests/test_delete_branches.py
 tests/test_hamt.py
 tests/test_namespaced.py
 tests/test_staged.py

{kvgit-0.3.1 → kvgit-0.3.2}/pyproject.toml

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

kvgit-0.3.2/tests/test_delete_branches.py

@@ -0,0 +1,209 @@
+"""Tests for the anchor-free admin deletion API (``kvgit.delete_branches``)
+and the module-level ``clean_orphans`` it shares with ``VersionedKV``.
+"""
+
+import os
+import tempfile
+
+import kvgit
+from kvgit import VersionedKV, store
+from kvgit.kv.memory import Memory
+from kvgit.versioned.kv import (
+    BRANCH_HEAD,
+    BRANCH_HEAD_PREV,
+    _resolve_head,
+    clean_orphans,
+)
+
+
+def _blob_keys(backend) -> set[str]:
+    """Versioned blob keys (``<commit>:<user_key>``) currently in the store."""
+    return {
+        k
+        for k in backend.keys()
+        if isinstance(k, str)
+        and ":" in k
+        and not k.startswith("__")
+        and "kvgit:" not in k
+    }
+
+
+class TestDeleteBranches:
+    def test_delete_sole_branch(self):
+        """Deleting the store's ONLY branch is legal — the exact case the
+        instance method can't reach (no anchor left to open on)."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            s = store(kind="disk", path=p)  # only branch: main
+            s["x"] = "1"
+            s.commit()
+            s.versioned.store.close()
+
+            kvgit.delete_branches(["main"], kind="disk", path=p)
+
+            # Reopening mints a fresh empty main.
+            s2 = store(kind="disk", path=p)
+            assert s2.list_branches() == ["main"]
+            assert s2.get("x") is None
+
+    def test_delete_batch(self):
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            s = store(kind="disk", path=p)
+            s["base"] = "ok"
+            s.commit()
+            s.create_branch("dev")["d"] = "1"
+            s.create_branch("feature")["f"] = "1"
+            assert set(s.list_branches()) == {"main", "dev", "feature"}
+            s.versioned.store.close()
+
+            kvgit.delete_branches(["dev", "feature"], kind="disk", path=p)
+
+            s2 = store(kind="disk", path=p)
+            assert s2.list_branches() == ["main"]
+            assert s2.get("base") == "ok"
+
+    def test_nonexistent_names_noop(self):
+        """Teardown is idempotent: unknown names don't raise (unlike the
+        instance method's ValueError)."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            store(kind="disk", path=p)["x"] = "1"  # materialize main
+            kvgit.delete_branches(["never", "existed"], kind="disk", path=p)
+            # main untouched
+            assert store(kind="disk", path=p).list_branches() == ["main"]
+
+    def test_delete_all_branches_legal(self):
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            s = store(kind="disk", path=p)
+            s.commit()
+            s.create_branch("dev")
+            s.versioned.store.close()
+
+            kvgit.delete_branches(["main", "dev"], kind="disk", path=p)
+
+            s2 = store(kind="disk", path=p)
+            assert s2.list_branches() == ["main"]  # fresh empty main
+
+    def test_prev_head_cleanup_no_resurrection(self):
+        """The prev-HEAD recovery backup must go with the head, or a
+        same-named branch created later would 'recover' deleted state
+        through _resolve_head's fallback."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            s = store(kind="disk", path=p)
+            s.commit()  # main genesis
+            dev = s.create_branch("dev")
+            dev["secret"] = "deleted data"
+            dev.commit()
+            dev["more"] = "moves prev-HEAD off genesis"
+            dev.commit()
+            s.versioned.store.close()
+
+            kvgit.delete_branches(["dev"], kind="disk", path=p)
+
+            s2 = store(kind="disk", path=p, branch="dev")  # recreate the name
+            assert s2.get("secret") is None
+            assert s2.get("more") is None
+            assert s2.versioned.store.get(BRANCH_HEAD_PREV % "dev") is None
+
+    def test_memory_kind_smoke(self):
+        """kind='memory' constructs a fresh empty Memory each call, so
+        this is a no-op — but it must not raise."""
+        kvgit.delete_branches(["anything"], kind="memory")
+
+    def test_bare_string_is_one_name(self):
+        """A bare string is treated as ONE branch name — iterated, it
+        would 'delete' each character as a branch and silently no-op
+        the real request."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            s = store(kind="disk", path=p)
+            s["base"] = "ok"
+            s.commit()
+            s.create_branch("dev")["d"] = "1"
+            s.versioned.store.close()
+
+            kvgit.delete_branches("dev", kind="disk", path=p)
+
+            s2 = store(kind="disk", path=p)
+            assert s2.list_branches() == ["main"]
+            assert s2.get("base") == "ok"
+
+    def test_empty_names_early_return(self):
+        """An empty iterable returns before the backend opens — no
+        store directory is created as a side effect."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            kvgit.delete_branches([], kind="disk", path=p)
+            assert not os.path.exists(p)
+
+    def test_min_age_zero_reclaims_immediately(self):
+        """min_age=0 lets an admin who knows the store is quiet reclaim
+        a just-committed branch's blobs in the same call, instead of
+        waiting out the one-hour concurrent-writer guard."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            s = store(kind="disk", path=p)
+            s["base"] = "ok"
+            s.commit()
+            dev = s.create_branch("dev")
+            dev["secret"] = "unique-blob-value"
+            dev.commit()
+            backend = s.versioned.store
+            assert {k for k in _blob_keys(backend) if k.endswith(":secret")}
+            backend.close()
+
+            kvgit.delete_branches("dev", kind="disk", path=p, min_age=0)
+
+            s2 = store(kind="disk", path=p)
+            after = {k for k in _blob_keys(s2.versioned.store) if k.endswith(":secret")}
+            assert not after  # reclaimed without waiting out the guard
+
+    def test_reopen_after_delete_not_locked(self):
+        """The disk handle is released (finally-close), so the next
+        opener on the same directory is not blocked."""
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "store")
+            store(kind="disk", path=p).commit()
+            kvgit.delete_branches(["main"], kind="disk", path=p)
+            # Would wedge if delete_branches leaked the diskcache handle.
+            store(kind="disk", path=p).commit()
+
+
+class TestSharedOrphanSweep:
+    def test_orphan_gc_reclaims_deleted_branch_blobs(self):
+        """The deleted branch's unique blobs are gone after the shared
+        sweep. Uses min_age=0 to bypass the age guard on fresh commits."""
+        backend = Memory()
+        v = VersionedKV(backend)  # main
+        dev = v.create_branch("dev")
+        dev.commit({"secret": b"unique-blob-value"})
+
+        # A blob key referencing the dev-only value exists.
+        before = {k for k in _blob_keys(backend) if k.endswith(":secret")}
+        assert before
+
+        # Mimic delete_branches' removals, then the shared sweep at min_age=0.
+        backend.remove(BRANCH_HEAD % "dev")
+        backend.remove(BRANCH_HEAD_PREV % "dev")
+        removed = clean_orphans(backend, min_age=0)
+
+        assert removed >= 1
+        after = {k for k in _blob_keys(backend) if k.endswith(":secret")}
+        assert not after  # reclaimed
+
+    def test_module_clean_orphans_matches_instance(self):
+        """The instance method delegates to the module function; both
+        return the orphan count for the same store."""
+        backend = Memory()
+        v = VersionedKV(backend)
+        dev = v.create_branch("dev")
+        dev.commit({"k": b"v"})
+        backend.remove(BRANCH_HEAD % "dev")
+        backend.remove(BRANCH_HEAD_PREV % "dev")
+
+        # No live branch references dev's commit anymore.
+        assert _resolve_head(backend, "dev") is None
+        assert clean_orphans(backend, min_age=0) >= 1

kvgit-0.3.1/kvgit/store.py

@@ -1,74 +0,0 @@
-"""Store factory function."""
-
-import pickle
-from typing import Any, Callable, Literal
-
-from .kv.base import KVStore
-from .kv.memory import Memory
-from .staged import Staged
-from .versioned.kv import VersionedKV
-
-
-def store(
-    kind: Literal["memory", "disk", "indexeddb"] = "memory",
-    *,
-    path: str | None = None,
-    db_name: str = "kvgit",
-    branch: str = "main",
-    encoder: Callable[..., bytes] = pickle.dumps,
-    decoder: Callable[..., Any] = pickle.loads,
-    codecs: str | None = None,
-) -> Staged:
-    """Create a Staged store with sensible defaults.
-
-    Args:
-        kind: ``"memory"`` (default), ``"disk"``, or ``"indexeddb"``.
-        path: Required when ``kind="disk"``. Directory path for the
-            disk backend.
-        db_name: IndexedDB database name (default ``"kvgit"``).
-            Only used when ``kind="indexeddb"``.
-        branch: Branch name (default ``"main"``).
-        encoder: Value encoder (default ``pickle.dumps``).
-        decoder: Value decoder (default ``pickle.loads``).
-        codecs: Optional named codec preset. Currently supported:
-            ``"scientific"`` — numpy/pandas chunked codecs (requires
-            numpy; install with ``pip install kvgit[scientific]``).
-            Mutually exclusive with explicit ``encoder`` / ``decoder``.
-
-    Returns:
-        A ``Staged`` store instance.
-
-    Raises:
-        ValueError: if ``codecs`` is given alongside non-default
-            ``encoder`` / ``decoder``, or if ``codecs`` names an
-            unknown preset.
-        ImportError: if a codec preset's optional dependency is not
-            installed.
-    """
-    if codecs is not None:
-        if encoder is not pickle.dumps or decoder is not pickle.loads:
-            raise ValueError(
-                "codecs= is mutually exclusive with explicit encoder/decoder; "
-                "pass one or the other"
-            )
-        from .codecs import _resolve_named
-
-        encoder, decoder = _resolve_named(codecs)
-
-    backend: KVStore
-    if kind == "memory":
-        backend = Memory()
-    elif kind == "disk":
-        if path is None:
-            raise ValueError("path is required when kind='disk'")
-        from .kv.disk import Disk
-
-        backend = Disk(path)
-    elif kind == "indexeddb":
-        from .kv.indexeddb import IndexedDB
-
-        backend = IndexedDB(db_name=db_name)
-    else:
-        raise ValueError(f"Unknown kind: {kind!r}")
-
-    return Staged(VersionedKV(backend, branch=branch), encoder=encoder, decoder=decoder)