kvgit 0.3.1__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.1
+Version: 0.3.3
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -42,7 +42,7 @@ Requires-Dist: pandas>=2.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: diskcache; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
 Dynamic: license-file

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

@@ -3,10 +3,10 @@
 from .content_types import MergeFn, counter, last_writer_wins
 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
+from .versioned.protocol import MergeResult, Versioned
 
 __all__ = [
     "ConcurrencyError",
@@ -18,6 +18,7 @@ __all__ = [
     "Versioned",
     "VersionedKV",
     "counter",
+    "delete_branches",
     "last_writer_wins",
     "store",
 ]

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/codecs/numpy.py

@@ -33,7 +33,7 @@ storing each unique buffer once instead of N times.)
 
 from __future__ import annotations
 
-from typing import Any, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     import numpy as np
@@ -66,7 +66,7 @@ def _descr_to_dtype(descr):
     return npf.descr_to_dtype(descr)
 
 
-def _root_and_offset(arr: "np.ndarray") -> tuple["np.ndarray", int]:
+def _root_and_offset(arr: np.ndarray) -> tuple[np.ndarray, int]:
     """Walk ``.base`` to the root buffer; return (root, byte_offset).
 
     Returns ``(arr, 0)`` if the .base chain leads somewhere we can't

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/codecs/pickler.py

@@ -16,7 +16,8 @@ from __future__ import annotations
 
 import io
 import pickle
-from typing import Any, Iterable
+from collections.abc import Iterable
+from typing import Any
 
 from .base import ChunkReader, ChunkSink, Codec
 

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/content_types.py

@@ -1,6 +1,7 @@
 """Merge functions for typed values."""
 
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 MergeFn = Callable[[Any | None, Any, Any], Any]
 """Merge function: (old_value | None, our_value, their_value) -> merged_value.

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/encoding.py

@@ -28,5 +28,6 @@ def safe_loads(raw: bytes):
     """
     try:
         return json.loads(raw)
-    except Exception:
+    except Exception:  # noqa: BLE001 — the point of the function: any
+        # decode failure (garbage, partial write, version skew) is a miss.
         return None

{kvgit-0.3.1 → kvgit-0.3.3}/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.1 → kvgit-0.3.3}/kvgit/kv/indexeddb.py

@@ -47,8 +47,8 @@ the handler is set, causing a deadlock.
 
 from collections.abc import Iterable, Mapping
 
-from pyodide.ffi import create_proxy, run_sync, to_js  # type: ignore[import-not-found]
 from js import Promise, indexedDB, undefined  # type: ignore[import-not-found]
+from pyodide.ffi import create_proxy, run_sync, to_js  # type: ignore[import-not-found]
 
 from .base import KVStore
 
@@ -155,8 +155,9 @@ def _to_bytes(js_value) -> bytes | None:
         return None
     try:
         return js_value.to_py().tobytes()
-    except Exception:
-        # Corrupted or unexpected JS value — treat as missing
+    except Exception:  # noqa: BLE001 — a JS->Python conversion can fail
+        # with anything the FFI decides to raise; there is no narrower
+        # type to name. Corrupted or unexpected JS value — treat as missing.
         return None
 
 

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/namespaced.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterator, MutableMapping
-from typing import Any, Iterable
+from collections.abc import Iterable, Iterator, MutableMapping
+from typing import Any
 
 
 class Namespaced(MutableMapping[str, Any]):

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/staged.py

@@ -2,8 +2,8 @@
 
 import inspect
 import pickle
-from collections.abc import Iterable, Iterator, MutableMapping
-from typing import Any, Callable
+from collections.abc import Callable, Iterable, Iterator, MutableMapping
+from typing import Any
 
 from .codecs._hash import hash_bytes
 from .content_types import MergeFn

kvgit-0.3.3/kvgit/store.py

@@ -0,0 +1,157 @@
+"""Store factory function."""
+
+import pickle
+from collections.abc import Callable, Iterable
+from typing import Any, 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.
+
+    That sweep does not reclaim chunks — the content-addressed bytes a
+    chunked codec writes — because a chunk key is not the deleted
+    branch's to give away. On a store using chunked codecs, follow up
+    with ``deep_clean`` on a quiescent store to get that space back.
+
+    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.3}/kvgit/versioned/base.py

@@ -1,7 +1,7 @@
 """Shared commit/merge orchestration for versioned stores."""
 
 from abc import ABC, abstractmethod
-from typing import Iterable
+from collections.abc import Iterable
 
 from ..errors import ConcurrencyError, MergeConflict
 from .helpers import diff_keysets, walk_history

{kvgit-0.3.1 → kvgit-0.3.3}/kvgit/versioned/helpers.py

@@ -1,7 +1,7 @@
 """Shared diff and history helpers."""
 
 from collections import deque
-from typing import Callable, Iterable
+from collections.abc import Callable, Iterable
 
 from .protocol import DiffResult