kvgit 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.0
+Version: 0.3.2
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -27,8 +27,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: disk
 Requires-Dist: diskcache; extra == "disk"
-Provides-Extra: git
-Requires-Dist: gitpython>=3.1; extra == "git"
 Provides-Extra: numpy
 Requires-Dist: numpy>=1.24; extra == "numpy"
 Provides-Extra: pandas
@@ -39,13 +37,11 @@ Requires-Dist: numpy>=1.24; extra == "scientific"
 Requires-Dist: pandas>=2.0; extra == "scientific"
 Provides-Extra: all
 Requires-Dist: diskcache; extra == "all"
-Requires-Dist: gitpython>=3.1; extra == "all"
 Requires-Dist: numpy>=1.24; extra == "all"
 Requires-Dist: pandas>=2.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: diskcache; extra == "dev"
-Requires-Dist: gitpython>=3.1; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
 Requires-Dist: pandas>=2.0; extra == "dev"
@@ -61,7 +57,7 @@ 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 |
-| **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
+| **Pluggable backends** | In-memory, disk (diskcache), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 | **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
 
 ## Install
@@ -69,7 +65,6 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 ```bash
 pip install kvgit              # in-memory only
 pip install kvgit[disk]        # adds disk backend via diskcache
-pip install kvgit[git]         # adds git backend via GitPython (requires git on PATH)
 pip install kvgit[scientific]  # adds chunked codecs for numpy / pandas
 # IndexedDB backend is available automatically in Pyodide (browser) environments
 ```
@@ -131,3 +126,4 @@ See [`docs/`](docs/) for detailed documentation:
 
 - [Quick Start](docs/quick-start.md) -- common patterns with runnable examples
 - [API Reference](docs/api.md) -- full reference for all classes, methods, and types
+- [Browser persistence (Pyodide)](docs/pyodide.md) -- choosing between the IndexedDB and OPFS-mounted-disk backends, plus the syncfs flush requirement and recommended host-side patterns

{kvgit-0.3.0 → kvgit-0.3.2}/README.md

@@ -8,7 +8,7 @@ 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 |
-| **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
+| **Pluggable backends** | In-memory, disk (diskcache), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
 | **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
 
 ## Install
@@ -16,7 +16,6 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 ```bash
 pip install kvgit              # in-memory only
 pip install kvgit[disk]        # adds disk backend via diskcache
-pip install kvgit[git]         # adds git backend via GitPython (requires git on PATH)
 pip install kvgit[scientific]  # adds chunked codecs for numpy / pandas
 # IndexedDB backend is available automatically in Pyodide (browser) environments
 ```
@@ -78,3 +77,4 @@ See [`docs/`](docs/) for detailed documentation:
 
 - [Quick Start](docs/quick-start.md) -- common patterns with runnable examples
 - [API Reference](docs/api.md) -- full reference for all classes, methods, and types
+- [Browser persistence (Pyodide)](docs/pyodide.md) -- choosing between the IndexedDB and OPFS-mounted-disk backends, plus the syncfs flush requirement and recommended host-side patterns

{kvgit-0.3.0 → 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,13 +18,7 @@ __all__ = [
     "Versioned",
     "VersionedKV",
     "counter",
+    "delete_branches",
     "last_writer_wins",
     "store",
 ]
-
-try:
-    from .versioned.gp import VersionedGP
-
-    __all__ += ["VersionedGP"]
-except ImportError:
-    pass

kvgit-0.3.2/kvgit/kv/composite.py

@@ -0,0 +1,191 @@
+"""N-tier composite cache over multiple KV stores."""
+
+import logging
+from collections.abc import Iterable, Mapping
+
+from .base import KVStore
+
+logger = logging.getLogger("kvgit.kv.composite")
+
+# Exceptions we treat as programming bugs (a misconfigured tier, a
+# protocol mismatch) rather than operational tier unavailability.
+# These are re-raised so they surface instead of being silently masked
+# by the cache-fallback machinery. Everything else under Exception
+# (OSError, ConnectionError, Pyodide JsException, ...) is logged and
+# treated as "tier unavailable, try next".
+_BUG_EXCEPTIONS = (TypeError, AttributeError, AssertionError)
+
+
+def _is_bug(exc: BaseException) -> bool:
+    return isinstance(exc, _BUG_EXCEPTIONS)
+
+
+class Composite(KVStore):
+    """N-tier cache composing any number of KV stores.
+
+    On get: check L1, L2, ..., Ln in order. On hit at tier i,
+    populate L1..L(i-1) and return.
+
+    On set: write to all tiers (most durable first).
+
+    On cas: delegate to Ln (authoritative), update caches on success.
+
+    Tier failures (``OSError``, network errors, etc.) are logged at
+    WARNING and the next tier is tried; programming-error exceptions
+    (``TypeError``, ``AttributeError``, ``AssertionError``) propagate
+    so they aren't silently swallowed.
+
+    Args:
+        stores: List of KV stores ordered fastest -> most durable.
+    """
+
+    def __init__(self, stores: list[KVStore]) -> None:
+        if not stores:
+            raise ValueError("Composite requires at least one store")
+        self._stores = stores
+
+    def _populate_caches(self, upto: int, items: Mapping[str, bytes]) -> None:
+        """Best-effort write to faster tiers after a slow-tier hit."""
+        for j in range(upto):
+            try:
+                self._stores[j].set_many(items)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite cache populate failed at tier %d: %s", j, e)
+
+    def get(self, key: str) -> bytes | None:
+        for i, store in enumerate(self._stores):
+            try:
+                value = store.get(key)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite get failed at tier %d for %r: %s", i, key, e)
+                continue
+            if value is not None:
+                if i > 0:
+                    self._populate_caches(i, {key: value})
+                return value
+        return None
+
+    def get_many(self, *args) -> Mapping[str, bytes]:
+        result: dict[str, bytes] = {}
+        remaining = set(self._normalize_keys(args))
+        for i, store in enumerate(self._stores):
+            if not remaining:
+                break
+            try:
+                # Delegate to the tier's bulk get — backends with high
+                # per-call latency (Disk, IndexedDB) collapse N round-trips
+                # into one. The protocol guarantees only existing keys
+                # appear in the result.
+                tier_values = store.get_many(remaining)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite get_many failed at tier %d: %s", i, e)
+                continue
+            if tier_values and i > 0:
+                self._populate_caches(i, tier_values)
+            result.update(tier_values)
+            remaining -= tier_values.keys()
+        return result
+
+    def __contains__(self, key: str) -> bool:
+        for i, store in enumerate(self._stores):
+            try:
+                if key in store:
+                    return True
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning(
+                    "Composite contains failed at tier %d for %r: %s", i, key, e
+                )
+                continue
+        return False
+
+    def keys(self) -> Iterable[str]:
+        return self._stores[-1].keys()
+
+    def items(self) -> Iterable[tuple[str, bytes]]:
+        return self._stores[-1].items()
+
+    def set(self, key: str, value: bytes) -> None:
+        # Authoritative tier first; failures here propagate (durability
+        # is the contract of set()). Cache-tier failures are logged.
+        self._stores[-1].set(key, value)
+        for i, store in enumerate(self._stores[:-1]):
+            try:
+                store.set(key, value)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite set failed at tier %d for %r: %s", i, key, e)
+
+    def set_many(
+        self,
+        items: Mapping[str, bytes] | None = None,
+        /,
+        **kwargs: bytes,
+    ) -> None:
+        items = self._normalize_items(items, kwargs)
+        self._stores[-1].set_many(items)
+        for i, store in enumerate(self._stores[:-1]):
+            try:
+                store.set_many(items)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite set_many failed at tier %d: %s", i, e)
+
+    def remove(self, key: str) -> None:
+        self._stores[-1].remove(key)
+        for i, store in enumerate(self._stores[:-1]):
+            try:
+                store.remove(key)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning(
+                    "Composite remove failed at tier %d for %r: %s", i, key, e
+                )
+
+    def remove_many(self, *args) -> None:
+        keys = list(self._normalize_keys(args))
+        self._stores[-1].remove_many(keys)
+        for i, store in enumerate(self._stores[:-1]):
+            try:
+                store.remove_many(keys)
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite remove_many failed at tier %d: %s", i, e)
+
+    def clear(self) -> None:
+        self._stores[-1].clear()
+        for i, store in enumerate(self._stores[:-1]):
+            try:
+                store.clear()
+            except Exception as e:
+                if _is_bug(e):
+                    raise
+                logger.warning("Composite clear failed at tier %d: %s", i, e)
+
+    def cas(self, key: str, value: bytes, expected: bytes | None) -> bool:
+        success = self._stores[-1].cas(key, value, expected)
+        if success:
+            for i, store in enumerate(self._stores[:-1]):
+                try:
+                    store.set(key, value)
+                except Exception as e:
+                    if _is_bug(e):
+                        raise
+                    logger.warning(
+                        "Composite cas cache-update failed at tier %d for %r: %s",
+                        i,
+                        key,
+                        e,
+                    )
+        return success

{kvgit-0.3.0 → 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.0 → kvgit-0.3.2}/kvgit/staged.py

@@ -126,8 +126,7 @@ class Staged(MutableMapping[str, Any]):
                 "chunked encoder/decoder requires a VersionedKV-backed Staged "
                 f"(got {type(versioned).__name__}). "
                 "Use kvgit.store(kind='memory'/'disk'/'indexeddb') or build a "
-                "VersionedKV directly. The git backend (VersionedGP) does not "
-                "support chunked codecs."
+                "VersionedKV directly."
             )
         self._chunk_reader = (
             _ChunkReader(versioned.store) if self._decoder_chunked else None

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.0 → kvgit-0.3.2}/kvgit/versioned/__init__.py

@@ -10,10 +10,3 @@ __all__ = [
     "Versioned",
     "VersionedKV",
 ]
-
-try:
-    from .gp import VersionedGP
-
-    __all__ += ["VersionedGP"]
-except ImportError:
-    pass