kvgit 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.0
+Version: 0.3.1
 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.1}/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.1}/kvgit/__init__.py

@@ -21,10 +21,3 @@ __all__ = [
     "last_writer_wins",
     "store",
 ]
-
-try:
-    from .versioned.gp import VersionedGP
-
-    __all__ += ["VersionedGP"]
-except ImportError:
-    pass

kvgit-0.3.1/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.1}/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.0 → kvgit-0.3.1}/kvgit/store.py

@@ -7,11 +7,10 @@ from .kv.base import KVStore
 from .kv.memory import Memory
 from .staged import Staged
 from .versioned.kv import VersionedKV
-from .versioned.protocol import Versioned
 
 
 def store(
-    kind: Literal["memory", "disk", "git", "indexeddb"] = "memory",
+    kind: Literal["memory", "disk", "indexeddb"] = "memory",
     *,
     path: str | None = None,
     db_name: str = "kvgit",
@@ -23,9 +22,9 @@ def store(
     """Create a Staged store with sensible defaults.
 
     Args:
-        kind: ``"memory"`` (default), ``"disk"``, ``"git"``, or ``"indexeddb"``.
-        path: Required when ``kind="disk"`` or ``kind="git"``.
-            Directory path for the disk backend or repo path for git.
+        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"``).
@@ -56,32 +55,20 @@ def store(
 
         encoder, decoder = _resolve_named(codecs)
 
-    versioned: Versioned
-
-    if kind == "git":
+    backend: KVStore
+    if kind == "memory":
+        backend = Memory()
+    elif kind == "disk":
         if path is None:
-            raise ValueError("path is required when kind='git'")
-        from .versioned.gp import VersionedGP
-
-        versioned = VersionedGP(path, branch=branch)
-    else:
-        # Build KV backend
-        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
+            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 = Disk(path)
+    elif kind == "indexeddb":
+        from .kv.indexeddb import IndexedDB
 
-            backend = IndexedDB(db_name=db_name)
-        else:
-            raise ValueError(f"Unknown kind: {kind!r}")
-
-        versioned = VersionedKV(backend, branch=branch)
+        backend = IndexedDB(db_name=db_name)
+    else:
+        raise ValueError(f"Unknown kind: {kind!r}")
 
-    return Staged(versioned, encoder=encoder, decoder=decoder)
+    return Staged(VersionedKV(backend, branch=branch), encoder=encoder, decoder=decoder)

{kvgit-0.3.0 → kvgit-0.3.1}/kvgit/versioned/__init__.py

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

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

@@ -681,6 +681,11 @@ class VersionedKV(VersionedBase):
         if self.store.get(branch_key) is None:
             raise ValueError(f"Branch '{name}' does not exist")
         self.store.remove(branch_key)
+        # The prev-HEAD recovery backup goes too: left behind, a
+        # same-named branch created later would "recover" the deleted
+        # state through _resolve_head's fallback. Removed before
+        # clean_orphans so commits only it referenced are collectable.
+        self.store.remove(BRANCH_HEAD_PREV % name)
         self.clean_orphans()
 
     def switch_branch(self, name: str) -> None:

{kvgit-0.3.0 → kvgit-0.3.1}/kvgit/versioned/merge.py

@@ -37,9 +37,8 @@ def resolve_merge(
 ) -> MergeResolution:
     """Resolve a three-way merge between two diverged keysets.
 
-    Implements the pure merge logic shared between VersionedKV and
-    VersionedGP.  Does NOT create commits or advance HEAD -- the
-    caller handles persistence.
+    Implements the pure merge logic used by VersionedKV. Does NOT
+    create commits or advance HEAD -- the caller handles persistence.
 
     Args:
         lca_keyset: Keyset of the lowest common ancestor commit.

{kvgit-0.3.0 → kvgit-0.3.1}/kvgit/versioned/protocol.py

@@ -38,8 +38,7 @@ class MergeResult:
 class Versioned(Protocol):
     """Protocol for versioned key-value stores.
 
-    Defines the common interface implemented by ``VersionedKV``
-    (KVStore-backed) and ``VersionedGP`` (GitPython-backed).
+    Defines the common interface implemented by ``VersionedKV``.
     """
 
     last_merge_result: MergeResult | None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.0
+Version: 0.3.1
 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.1}/kvgit.egg-info/SOURCES.txt

@@ -29,7 +29,6 @@ kvgit/kv/indexeddb.py
 kvgit/kv/memory.py
 kvgit/versioned/__init__.py
 kvgit/versioned/base.py
-kvgit/versioned/gp.py
 kvgit/versioned/helpers.py
 kvgit/versioned/keyset.py
 kvgit/versioned/kv.py

{kvgit-0.3.0 → kvgit-0.3.1}/kvgit.egg-info/requires.txt

@@ -1,14 +1,12 @@
 
 [all]
 diskcache
-gitpython>=3.1
 numpy>=1.24
 pandas>=2.0
 
 [dev]
 pytest
 diskcache
-gitpython>=3.1
 ruff
 numpy>=1.24
 pandas>=2.0
@@ -16,9 +14,6 @@ pandas>=2.0
 [disk]
 diskcache
 
-[git]
-gitpython>=3.1
-
 [numpy]
 numpy>=1.24
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kvgit"
-version = "0.3.0"
+version = "0.3.1"
 description = "Versioned key-value store with git-like commit, branch, and merge semantics."
 authors = [{ name = "ashenfad" }]
 requires-python = ">=3.10"
@@ -36,15 +36,13 @@ dependencies = []
 
 [project.optional-dependencies]
 disk = ["diskcache"]
-git = ["gitpython>=3.1"]
 numpy = ["numpy>=1.24"]
 pandas = ["numpy>=1.24", "pandas>=2.0"]
 scientific = ["numpy>=1.24", "pandas>=2.0"]
-all = ["diskcache", "gitpython>=3.1", "numpy>=1.24", "pandas>=2.0"]
+all = ["diskcache", "numpy>=1.24", "pandas>=2.0"]
 dev = [
     "pytest",
     "diskcache",
-    "gitpython>=3.1",
     "ruff",
     "numpy>=1.24",
     "pandas>=2.0",
@@ -57,7 +55,7 @@ include = ["kvgit*"]
 warn_unused_configs = true
 
 [[tool.mypy.overrides]]
-module = ["diskcache", "git", "git.*", "gitdb"]
+module = ["diskcache"]
 ignore_missing_imports = true
 
 [tool.pytest.ini_options]

kvgit-0.3.0/kvgit/kv/composite.py

@@ -1,137 +0,0 @@
-"""N-tier composite cache over multiple KV stores."""
-
-from collections.abc import Iterable, Mapping
-
-from .base import KVStore
-
-
-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.
-
-    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 get(self, key: str) -> bytes | None:
-        for i, store in enumerate(self._stores):
-            try:
-                value = store.get(key)
-                if value is not None:
-                    if i > 0:
-                        for j in range(i):
-                            try:
-                                self._stores[j].set(key, value)
-                            except Exception:
-                                pass  # best-effort cache population
-                    return value
-            except Exception:
-                continue  # tier unavailable, try next
-        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:
-                tier_values: dict[str, bytes] = {}
-                for key in remaining:
-                    value = store.get(key)
-                    if value is not None:
-                        tier_values[key] = value
-                if tier_values and i > 0:
-                    for j in range(i):
-                        try:
-                            self._stores[j].set_many(tier_values)
-                        except Exception:
-                            pass
-                result.update(tier_values)
-                remaining -= tier_values.keys()
-            except Exception:
-                continue
-        return result
-
-    def __contains__(self, key: str) -> bool:
-        for store in self._stores:
-            try:
-                if key in store:
-                    return True
-            except Exception:
-                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:
-        self._stores[-1].set(key, value)
-        for store in self._stores[:-1]:
-            try:
-                store.set(key, value)
-            except Exception:
-                pass  # best-effort cache population
-
-    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 store in self._stores[:-1]:
-            try:
-                store.set_many(items)
-            except Exception:
-                pass  # best-effort cache population
-
-    def remove(self, key: str) -> None:
-        self._stores[-1].remove(key)
-        for store in self._stores[:-1]:
-            try:
-                store.remove(key)
-            except Exception:
-                pass  # best-effort cache population
-
-    def remove_many(self, *args) -> None:
-        keys = list(self._normalize_keys(args))
-        self._stores[-1].remove_many(keys)
-        for store in self._stores[:-1]:
-            try:
-                store.remove_many(keys)
-            except Exception:
-                pass  # best-effort cache population
-
-    def clear(self) -> None:
-        self._stores[-1].clear()
-        for store in self._stores[:-1]:
-            try:
-                store.clear()
-            except Exception:
-                pass  # best-effort cache population
-
-    def cas(self, key: str, value: bytes, expected: bytes | None) -> bool:
-        success = self._stores[-1].cas(key, value, expected)
-        if success:
-            for store in self._stores[:-1]:
-                try:
-                    store.set(key, value)
-                except Exception:
-                    pass
-        return success

kvgit-0.3.0/kvgit/versioned/gp.py

@@ -1,360 +0,0 @@
-"""GitPython-backed versioned store.
-
-Importing this module requires GitPython. Both ``kvgit.__init__`` and
-``kvgit.versioned.__init__`` already wrap their imports of this module
-in ``try: ... except ImportError: pass`` so the public ``kvgit`` API
-stays usable on installs that don't have GitPython. Anyone who imports
-this module directly is signaling intent to use the git backend and
-should get a clear ImportError.
-"""
-
-import binascii
-import io
-import json
-import os
-import urllib.parse
-
-import git  # noqa: F401  (re-exported names below need this)
-from git import Blob, Commit, Repo, Tree
-from git.exc import BadObject, GitCommandError
-from gitdb import IStream
-
-from .base import VersionedBase
-from .merge import MergeResolution
-
-
-def _quote(key: str) -> str:
-    return urllib.parse.quote_plus(key)
-
-
-def _unquote(quoted: str) -> str:
-    return urllib.parse.unquote_plus(quoted)
-
-
-class VersionedGP(VersionedBase):
-    """A commit log backed by a Git repository."""
-
-    def __init__(
-        self,
-        repo_path: str,
-        *,
-        commit_hash: str | None = None,
-        branch: str = "main",
-    ) -> None:
-        self.repo_path = repo_path
-
-        if not os.path.exists(repo_path):
-            self.repo = Repo.init(repo_path, bare=True)
-        else:
-            self.repo = Repo(repo_path)
-
-        if commit_hash is None:
-            # Try to read the branch HEAD
-            try:
-                commit_hash = self.repo.heads[branch].commit.hexsha
-            except (IndexError, AttributeError):
-                # Branch doesn't exist, create an initial empty commit
-                commit_hash = self._create_empty_commit(branch)
-
-        if not isinstance(commit_hash, str):
-            raise TypeError(
-                f"commit_hash must be str, got {type(commit_hash).__name__}"
-            )
-
-        super().__init__(branch=branch, commit_hash=commit_hash)
-
-        # Load commit keyset
-        self._load_commit(commit_hash, update_base=True)
-
-    def _create_empty_commit(self, branch: str) -> str:
-        # Create an empty tree
-
-        tree_data = bytearray()
-        istream = self.repo.odb.store(
-            IStream(Tree.type, len(tree_data), io.BytesIO(tree_data))
-        )
-        tree_sha = istream.binsha
-        tree_obj = Tree(self.repo, tree_sha)
-
-        commit = Commit.create_from_tree(
-            self.repo, tree_obj, "Initial commit", parent_commits=[]
-        )
-        self.repo.create_head(branch, commit)
-        return commit.hexsha
-
-    @property
-    def latest_head(self) -> str | None:
-        try:
-            return self.repo.heads[self._branch].commit.hexsha
-        except (IndexError, AttributeError):
-            return None
-
-    # -- Read operations --
-
-    def get(self, key: str) -> bytes | None:
-        """Get a value from the current commit."""
-        hexsha = self._commit_keys.get(key)
-        if hexsha is None:
-            return None
-        return self._read_blob(hexsha)
-
-    def get_many(self, *keys: str) -> dict[str, bytes]:
-        """Get multiple values from the current commit."""
-        result = {}
-        for key in keys:
-            val = self.get(key)
-            if val is not None:
-                result[key] = val
-        return result
-
-    # -- Abstract method implementations --
-
-    def _snapshot_state(self) -> tuple:
-        return (self._current_commit, dict(self._commit_keys))
-
-    def _restore_state(self, saved: tuple) -> None:
-        self._current_commit, self._commit_keys = saved
-
-    def _read_blob(self, content_id: str) -> bytes | None:
-        """Read a blob by its git hex SHA."""
-        try:
-            blob = Blob(self.repo, binascii.unhexlify(content_id))
-            return blob.data_stream.read()
-        except (BadObject, ValueError):
-            return None
-
-    def _write_blob(self, data: bytes) -> str:
-        istream = self.repo.odb.store(IStream(Blob.type, len(data), io.BytesIO(data)))
-        return istream.hexsha
-
-    def _create_tree(self, keyset: dict[str, str]) -> str:
-        # Git tree objects are a sequence of entries sorted by name.
-        # Each entry is: "<mode> <name>\0<20-byte binary SHA>"
-        # We use mode 100644 (regular file) for all entries.
-        tree_data = bytearray()
-        entries = []
-        for key, hexsha in keyset.items():
-            entries.append((0o100644, _quote(key), hexsha))
-
-        for mode, name, hexsha in sorted(entries, key=lambda e: e[1]):
-            tree_data.extend(f"{mode:o} {name}".encode("utf-8"))
-            tree_data.append(0)
-            tree_data.extend(binascii.unhexlify(hexsha))
-
-        istream = self.repo.odb.store(
-            IStream(Tree.type, len(tree_data), io.BytesIO(tree_data))
-        )
-        return istream.hexsha
-
-    def _create_git_commit(
-        self,
-        updates: dict[str, bytes] | None = None,
-        removals: set[str] | None = None,
-        *,
-        info: dict | None = None,
-        parents: list[str] | None = None,
-    ) -> str:
-        """Create a git commit object.
-
-        Internal method that supports explicit parents (for merge commits).
-        """
-        updates = updates or {}
-        removals = removals or set()
-
-        new_commit_keys = dict(self._commit_keys)
-        for key in removals:
-            new_commit_keys.pop(key, None)
-
-        for key, value in updates.items():
-            new_commit_keys[key] = self._write_blob(value)
-
-        tree_hexsha = self._create_tree(new_commit_keys)
-        tree_obj = Tree(self.repo, binascii.unhexlify(tree_hexsha))
-
-        info_str = json.dumps(info, separators=(",", ":")) if info else ""
-        msg = f"kvgit commit\n\n{info_str}" if info_str else "kvgit commit"
-
-        if parents is None:
-            parent_objs = [Commit(self.repo, binascii.unhexlify(self._current_commit))]
-        else:
-            parent_objs = [Commit(self.repo, binascii.unhexlify(p)) for p in parents]
-
-        commit = Commit.create_from_tree(
-            self.repo, tree_obj, msg, parent_commits=parent_objs
-        )
-
-        self._commit_keys = new_commit_keys
-        self._current_commit = commit.hexsha
-        return commit.hexsha
-
-    def _create_commit(
-        self,
-        updates: dict[str, bytes] | None = None,
-        removals: set[str] | None = None,
-        *,
-        info: dict | None = None,
-        chunks: dict[str, bytes] | None = None,
-        chunk_refs: dict[str, list[str]] | None = None,
-    ) -> str:
-        """Create a single-parent commit (parent = current commit).
-
-        ``chunks`` and ``chunk_refs`` are part of the ``Versioned``
-        contract for the chunked-codec layer but the git backend has
-        no chunk namespace and no GC story; they're ignored. Pairing
-        a chunked codec with this backend is rejected at the
-        ``Staged`` construction site, so reaching this path with
-        non-None ``chunks`` would indicate a caller bypassing
-        ``Staged`` and writing to ``VersionedGP`` directly — which is
-        documented as unsupported.
-        """
-        return self._create_git_commit(updates, removals, info=info)
-
-    def _create_merge_commit(
-        self,
-        resolution: MergeResolution,
-        parents: tuple[str, ...],
-        info: dict | None,
-    ) -> str:
-        """Create a multi-parent merge commit from a resolved merge."""
-        merged_keyset = resolution.merged_keyset
-        merged_values = resolution.merged_values
-
-        removals = (
-            set(self._commit_keys.keys())
-            - set(merged_keyset.keys())
-            - set(merged_values.keys())
-        )
-        self._commit_keys = merged_keyset
-        return self._create_git_commit(
-            merged_values, removals, info=info, parents=list(parents)
-        )
-
-    def _cas_head(self, expected: str, new_head: str) -> bool:
-        """Atomically advance branch HEAD via git update-ref."""
-        try:
-            self.repo.git.update_ref(f"refs/heads/{self._branch}", new_head, expected)
-            return True
-        except GitCommandError:
-            return False
-
-    def _load_keyset(self, commit_hash: str) -> dict[str, str]:
-        c = Commit(self.repo, binascii.unhexlify(commit_hash))
-        return {_unquote(blob.name): blob.hexsha for blob in c.tree.blobs}
-
-    def _load_parents(self, commit_hash: str) -> tuple[str, ...]:
-        c = Commit(self.repo, binascii.unhexlify(commit_hash))
-        return tuple(p.hexsha for p in c.parents)
-
-    def _find_lca(self, commit_a: str, commit_b: str) -> str | None:
-        try:
-            bases = self.repo.merge_base(commit_a, commit_b)
-        except GitCommandError:
-            return None
-        if bases:
-            return bases[0].hexsha
-        return None
-
-    # -- Navigation --
-
-    def refresh(self) -> None:
-        """Reload state from HEAD."""
-        head = self.latest_head
-        if head is None:
-            raise ValueError(f"No HEAD commit found for branch {self._branch}")
-        self._load_commit(head, update_base=True)
-
-    def checkout(
-        self, commit_hash: str, *, branch: str | None = None
-    ) -> "VersionedGP | None":
-        """Return a new VersionedGP at a specific commit, or None if missing."""
-        try:
-            Commit(self.repo, binascii.unhexlify(commit_hash))
-            return VersionedGP(
-                self.repo_path, commit_hash=commit_hash, branch=branch or self._branch
-            )
-        except (BadObject, ValueError):
-            return None
-
-    def create_branch(self, name: str, *, at: str | None = None) -> "VersionedGP":
-        """Fork a commit onto a new branch.
-
-        Returns a new ``VersionedGP`` on the new branch.
-        """
-        target = at or self._current_commit
-        if at is not None:
-            try:
-                c = Commit(self.repo, binascii.unhexlify(at))
-                c.tree  # force load to verify commit exists
-            except (BadObject, ValueError):
-                raise ValueError(f"Commit '{at}' does not exist")
-
-        if name in self.repo.heads:
-            raise ValueError(f"Branch '{name}' already exists")
-
-        self.repo.create_head(name, Commit(self.repo, binascii.unhexlify(target)))
-        return VersionedGP(self.repo_path, commit_hash=target, branch=name)
-
-    def delete_branch(self, name: str) -> None:
-        """Delete a branch by name."""
-        if name == self._branch:
-            raise ValueError("Cannot delete the current branch")
-        if name not in self.repo.heads:
-            raise ValueError(f"Branch '{name}' does not exist")
-
-        git.Head.delete(self.repo, self.repo.heads[name], force=True)
-
-    def switch_branch(self, name: str) -> None:
-        """Switch this instance to a different branch in-place."""
-        if name not in self.repo.heads:
-            raise ValueError(f"Branch '{name}' does not exist")
-        self._branch = name
-        self._load_commit(self.repo.heads[name].commit.hexsha, update_base=True)
-
-    def peek(self, key: str, *, branch: str) -> bytes | None:
-        """Read a key from another branch's HEAD without switching."""
-        if branch not in self.repo.heads:
-            return None
-        commit_hash = self.repo.heads[branch].commit.hexsha
-        keyset = self._load_keyset(commit_hash)
-        hexsha = keyset.get(key)
-        if not hexsha:
-            return None
-        return self._read_blob(hexsha)
-
-    def reset_to(self, commit_hash: str) -> bool:
-        """Reset HEAD to a specific commit."""
-        try:
-            c = Commit(self.repo, binascii.unhexlify(commit_hash))
-            c.tree  # force load to verify commit exists
-        except (BadObject, ValueError):
-            return False
-        self.repo.git.update_ref(f"refs/heads/{self._branch}", commit_hash)
-        self._load_commit(commit_hash, update_base=True)
-        return True
-
-    def list_branches(self) -> list[str]:
-        """List all branch names."""
-        return [h.name for h in self.repo.heads]
-
-    def commit_info(self, commit_hash: str | None = None) -> dict | None:
-        """Retrieve the info dict for a commit, or None if none was stored."""
-        target = commit_hash or self._current_commit
-        try:
-            c = Commit(self.repo, binascii.unhexlify(target))
-            msg = c.message
-        except (BadObject, ValueError):
-            return None
-        if "\n\n" not in msg:
-            return None
-        info_part = msg.split("\n\n", 1)[1].strip()
-        if not info_part:
-            return None
-        return json.loads(info_part)
-
-    # -- Internal --
-
-    def _load_commit(self, commit_hash: str, *, update_base: bool) -> None:
-        self._current_commit = commit_hash
-        if update_base:
-            self._base_commit = commit_hash
-        self._commit_keys = self._load_keyset(commit_hash)