kvgit 0.4.2__tar.gz → 0.4.3__tar.gz

{kvgit-0.4.2 → kvgit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.4.2
+Version: 0.4.3
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -144,7 +144,9 @@ with Repo(Disk("/tmp/kvgit-demo")) as on_disk:
 | `git gc [--prune=now]` | `repo.gc([min_age=0])` |
 
 Where it differs: there is no index; several worktrees can hold one
-branch, and their commits race and merge rather than being refused; a
+branch, and their commits race and merge rather than being refused
+(`commit(on_moved="raise")` refuses instead, raising
+`BranchMovedError`, for data whose keys aren't independent); a
 conflicted merge raises `MergeConflict` and changes nothing (unless a
 merge function such as `text_merge` writes markers into the value);
 commit hashes are not git's, and there are no remotes.

{kvgit-0.4.2 → kvgit-0.4.3}/README.md

@@ -90,7 +90,9 @@ with Repo(Disk("/tmp/kvgit-demo")) as on_disk:
 | `git gc [--prune=now]` | `repo.gc([min_age=0])` |
 
 Where it differs: there is no index; several worktrees can hold one
-branch, and their commits race and merge rather than being refused; a
+branch, and their commits race and merge rather than being refused
+(`commit(on_moved="raise")` refuses instead, raising
+`BranchMovedError`, for data whose keys aren't independent); a
 conflicted merge raises `MergeConflict` and changes nothing (unless a
 merge function such as `text_merge` writes markers into the value);
 commit hashes are not git's, and there are no remotes.

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/__init__.py

@@ -4,6 +4,7 @@ from ._open import open
 from .content_types import MergeFn, counter, last_writer_wins, text_merge
 from .errors import (
     BranchExistsError,
+    BranchMovedError,
     ConcurrencyError,
     CorruptHeadError,
     GcBusy,
@@ -40,6 +41,7 @@ from .worktree import Status, Worktree
 __all__ = [
     "ROOT_COMMIT",
     "BranchExistsError",
+    "BranchMovedError",
     "Branches",
     "CantMark",
     "Commit",

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/_codec.py

@@ -61,6 +61,27 @@ class _ChunkReader:
         return None
 
 
+class _CountingReader:
+    """A chunk reader that tallies the bytes of the chunks it returns."""
+
+    def __init__(self, reader: _ChunkReader) -> None:
+        self._reader = reader
+        self.nbytes = 0
+
+    def get(self, ref: str) -> bytes:
+        raw = self._reader.get(ref)
+        self.nbytes += len(raw)
+        return raw
+
+    def get_many(self, refs):
+        found = self._reader.get_many(refs)
+        self.nbytes += sum(len(v) for v in found.values())
+        return found
+
+    def prefetch(self, refs) -> None:
+        self._reader.prefetch(refs)
+
+
 def _is_chunk_aware(fn) -> bool:
     """Whether an encoder/decoder takes a required sink/reader argument.
 
@@ -148,6 +169,14 @@ class Codec:
             return self.decoder(raw, self._reader)
         return self.decoder(raw)
 
+    def decode_sized(self, raw: bytes) -> tuple[Any, int]:
+        """A value, and the bytes it was decoded from: its blob plus any
+        chunks a chunked decoder read, which the value usually keeps."""
+        if self.decoder_chunked:
+            reader = _CountingReader(self._reader)  # type: ignore[arg-type]
+            return self.decoder(raw, reader), len(raw) + reader.nbytes
+        return self.decoder(raw), len(raw)
+
     def encode_merged(self, value: Any) -> bytes:
         """Encode a value a merge function produced.
 

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/_open.py

@@ -3,7 +3,7 @@
 from typing import Literal
 
 from ._codec import CodecSpec
-from .cache import DEFAULT_CACHE_BYTES
+from .cache import DEFAULT_CACHE_BYTES, DEFAULT_VALUE_CACHE_BYTES
 from .kv.base import KVStore
 from .kv.memory import Memory
 from .repo import Repo
@@ -41,6 +41,7 @@ def open(
     branch: str = "main",
     codec: CodecSpec = "pickle",
     cache_bytes: int = DEFAULT_CACHE_BYTES,
+    value_cache_bytes: int = DEFAULT_VALUE_CACHE_BYTES,
 ) -> Worktree:
     """Open (or create) a store, and a worktree on ``branch`` of it.
 
@@ -61,8 +62,14 @@ def open(
         codec: How values are stored; see :class:`Repo`.
         cache_bytes: Memory for what the store never changes; see
             :class:`Repo`.
+        value_cache_bytes: Memory for the values the worktree reads;
+            see :class:`Repo`.
     """
     backend = _make_backend(kind, path=path, db_name=db_name)
-    return Repo(backend, codec=codec, cache_bytes=cache_bytes).worktree(
-        branch, create=True
+    repo = Repo(
+        backend,
+        codec=codec,
+        cache_bytes=cache_bytes,
+        value_cache_bytes=value_cache_bytes,
     )
+    return repo.worktree(branch, create=True)

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/cache.py

@@ -19,6 +19,10 @@ commit exists — what ``snapshot(commit=)`` and a tag's ``dangling``
 ask — so it is always read, and whatever is reached through a root the
 store still holds is safe to answer from here. Absence is never cached
 either: a key missing now may be written by the next commit.
+
+A worktree keeps a second, separate memory: the decoded values it has
+read at its head (:class:`ValueCache`). That one holds blobs, so it is
+per worktree, emptied whenever the head moves, and bounded in bytes.
 """
 
 from __future__ import annotations
@@ -41,6 +45,9 @@ from .versioned.kv import (
 DEFAULT_CACHE_BYTES = 32 * 1024 * 1024
 """The default budget: tens of thousands of tree nodes."""
 
+DEFAULT_VALUE_CACHE_BYTES = 32 * 1024 * 1024
+"""The default budget for each worktree's decoded values."""
+
 _CACHEABLE_PREFIXES = (
     Keyset.DEFAULT_PREFIX,
     PARENT_COMMIT.replace("%s", ""),
@@ -281,3 +288,82 @@ class CachedStore(KVStore):
         if GC_LEASE_KEY in writes:
             # This process's own sweep taking or releasing the lease.
             self.cache.saw_lease(writes[GC_LEASE_KEY])
+
+
+class ValueCache:
+    """A worktree's decoded values of committed keys, least recently
+    used first out, bounded in bytes.
+
+    It holds only what the worktree's head already stores, so anything
+    it lets go is read again from the store; pending writes are kept by
+    the worktree itself and never pass through here. A value's cost is
+    the bytes it was decoded from (its blob, plus any chunks a chunked
+    codec read), and a value costing more than a quarter of the budget
+    is not held at all, so one large read cannot push out everything
+    else and the largest values, the ones a caller may want only a few
+    bytes of, are not kept alive by the cache. A budget of ``0`` holds
+    nothing.
+
+    Safe to use from several threads.
+    """
+
+    def __init__(self, max_bytes: int = DEFAULT_VALUE_CACHE_BYTES) -> None:
+        if max_bytes < 0:
+            raise ValueError(f"max_bytes must not be negative, got {max_bytes}")
+        self.max_bytes = max_bytes
+        self._entries: OrderedDict[str, tuple[Any, int]] = OrderedDict()
+        self._bytes = 0
+        self._lock = threading.Lock()
+
+    def __repr__(self) -> str:
+        return (
+            f"ValueCache({len(self._entries)} entries, "
+            f"{self._bytes}/{self.max_bytes} bytes)"
+        )
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._entries
+
+    @property
+    def size_bytes(self) -> int:
+        """What the values held now cost, by the budget's estimate."""
+        return self._bytes
+
+    @property
+    def max_value_bytes(self) -> int:
+        """The largest cost of a value that is held."""
+        return self.max_bytes // 4
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """The value held for ``key``, marked as just used; ``default``
+        if none is."""
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                return default
+            self._entries.move_to_end(key)
+            return entry[0]
+
+    def remember(self, key: str, value: Any, nbytes: int) -> None:
+        """Hold ``value``, decoded from ``nbytes`` bytes, evicting the
+        least recently used to fit."""
+        cost = nbytes + len(key) + _ENTRY_OVERHEAD
+        if cost > self.max_value_bytes:
+            return
+        with self._lock:
+            old = self._entries.pop(key, None)
+            if old is not None:
+                self._bytes -= old[1]
+            self._entries[key] = (value, cost)
+            self._bytes += cost
+            while self._bytes > self.max_bytes:
+                _, (_, evicted) = self._entries.popitem(last=False)
+                self._bytes -= evicted
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+            self._bytes = 0

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/errors.py

@@ -18,6 +18,28 @@ class ConcurrencyError(KvgitError):
     """
 
 
+class BranchMovedError(ConcurrencyError):
+    """Raised by a commit made with ``on_moved="raise"`` that found its
+    branch moved: the branch's head is no longer the commit the handle
+    is based on. Nothing was published and pending changes are kept;
+    refresh and redo the work, or give up.
+
+    Attributes:
+        branch: The branch.
+        base: The commit the handle is based on, which the branch no
+            longer names.
+        head: The branch's head as the commit found it.
+    """
+
+    def __init__(self, branch: str, base: str, head: str) -> None:
+        self.branch = branch
+        self.base = base
+        self.head = head
+        super().__init__(
+            f"Branch '{branch}' moved from {base} to {head}; nothing was committed"
+        )
+
+
 class MergeConflict(KvgitError):
     """Raised when a three-way merge encounters unresolvable conflicts.
 

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/refs.py

@@ -77,8 +77,19 @@ class Branches(Mapping[str, str]):
         ``gc``; worktrees still holding it read from their heads and raise
         :class:`UnknownBranchError` on commit.
 
+        The removal is conditional on the head this call read: if another
+        writer moves the branch, or deletes and recreates it, in between,
+        nothing is removed and the call raises rather than retrying, so a
+        newer head is never deleted on the strength of an older one. A
+        branch made again at the same commit is indistinguishable from
+        the one read, and is deleted, as with git's
+        ``update-ref -d <ref> <old-oid>``.
+
         Raises:
             UnknownBranchError: if there is no such branch.
+            ConcurrencyError: if the branch changed while being deleted.
+            ValueError: if ``name`` is empty or in the reserved tag
+                namespace.
         """
         _kv.delete_branch(self._repo._store, name)
 
@@ -136,8 +147,14 @@ class Tags(Mapping[str, str]):
         """Delete a tag. A commit it alone kept alive becomes collectable
         at the next ``gc``.
 
+        The removal is conditional on the head and info record this call
+        read: a tag deleted and made again by another writer in between,
+        even at the same commit, keeps its new commit and info, and the
+        call raises rather than retrying.
+
         Raises:
             UnknownTagError: if there is no such tag.
+            ConcurrencyError: if the tag changed while being deleted.
         """
         _kv.delete_tag(self._repo._store, name)
 

{kvgit-0.4.2 → kvgit-0.4.3}/kvgit/repo.py

@@ -7,7 +7,12 @@ from dataclasses import dataclass
 from typing import Any
 
 from ._codec import Codec, CodecSpec
-from .cache import DEFAULT_CACHE_BYTES, CachedStore, ContentCache
+from .cache import (
+    DEFAULT_CACHE_BYTES,
+    DEFAULT_VALUE_CACHE_BYTES,
+    CachedStore,
+    ContentCache,
+)
 from .content_types import MergeFn
 from .encoding import loads, safe_loads
 from .errors import (
@@ -75,6 +80,11 @@ class Repo:
             default; ``0`` turns the cache off). A sweep by any process
             empties it before this one builds on what the sweep removed;
             see :class:`~kvgit.cache.ContentCache`.
+        value_cache_bytes: Memory for the decoded values each worktree
+            reads, held until its head moves (32 MB per worktree by
+            default; ``0`` holds none). A value costing more than a
+            quarter of it is never held; see
+            :class:`~kvgit.cache.ValueCache`.
 
     Raises:
         StorageVersionError: if the store is stamped with a layout this
@@ -91,8 +101,14 @@ class Repo:
         default_merge: MergeRule | None = None,
         recover_from_corrupt_head: CorruptHeadRecoverer | None = None,
         cache_bytes: int = DEFAULT_CACHE_BYTES,
+        value_cache_bytes: int = DEFAULT_VALUE_CACHE_BYTES,
     ) -> None:
         _kv._check_storage_version(backend)
+        if value_cache_bytes < 0:
+            raise ValueError(
+                f"value_cache_bytes must not be negative, got {value_cache_bytes}"
+            )
+        self._value_cache_bytes = value_cache_bytes
         self._backend = backend
         # 0 turns the cache off; anything else is a budget, and
         # ContentCache refuses one that is negative.