kvgit 0.3.3__tar.gz → 0.3.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.3.3
+Version: 0.3.5
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -56,6 +56,7 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Dict interface** | `MutableMapping[str, Any]` -- reads and writes work like a dict |
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
+| **Tags** | Immutable names for commits; a tagged commit outlives every branch that reached it, in every kvgit version |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
 | **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 |
@@ -87,6 +88,10 @@ dev.commit()
 
 print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
+
+# Tag a commit by name -- immutable, and safe from garbage collection
+main.tag("v1")
+print(main.peek("score", tag="v1"))  # 0
 ```
 
 ## Chunked codecs (numpy / pandas)

{kvgit-0.3.3 → kvgit-0.3.5}/README.md

@@ -7,6 +7,7 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Dict interface** | `MutableMapping[str, Any]` -- reads and writes work like a dict |
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
+| **Tags** | Immutable names for commits; a tagged commit outlives every branch that reached it, in every kvgit version |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
 | **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 |
@@ -38,6 +39,10 @@ dev.commit()
 
 print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
+
+# Tag a commit by name -- immutable, and safe from garbage collection
+main.tag("v1")
+print(main.peek("score", tag="v1"))  # 0
 ```
 
 ## Chunked codecs (numpy / pandas)

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

@@ -4,9 +4,9 @@ from .content_types import MergeFn, counter, last_writer_wins
 from .errors import ConcurrencyError, MergeConflict
 from .namespaced import Namespaced
 from .staged import Staged
-from .store import delete_branches, store
+from .store import delete_branches, delete_tags, store
 from .versioned.kv import VersionedKV
-from .versioned.protocol import MergeResult, Versioned
+from .versioned.protocol import MergeResult, TagInfo, Versioned
 
 __all__ = [
     "ConcurrencyError",
@@ -15,10 +15,12 @@ __all__ = [
     "MergeResult",
     "Namespaced",
     "Staged",
+    "TagInfo",
     "Versioned",
     "VersionedKV",
     "counter",
     "delete_branches",
+    "delete_tags",
     "last_writer_wins",
     "store",
 ]

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

@@ -8,7 +8,7 @@ from typing import Any
 from .codecs._hash import hash_bytes
 from .content_types import MergeFn
 from .versioned.kv import CHUNK_PREFIX, VersionedKV
-from .versioned.protocol import BytesMergeFn, MergeResult, Versioned
+from .versioned.protocol import BytesMergeFn, MergeResult, TagInfo, Versioned
 
 
 class _ChunkSink:
@@ -407,10 +407,22 @@ class Staged(MutableMapping[str, Any]):
         )
 
     def checkout(
-        self, commit_hash: str, *, branch: str | None = None
+        self,
+        commit_hash: str | None = None,
+        *,
+        branch: str | None = None,
+        tag: str | None = None,
     ) -> "Staged | None":
-        """Create a new Staged at a specific commit. Returns None if not found."""
-        v = self._versioned.checkout(commit_hash, branch=branch)
+        """Create a new Staged at a specific commit or tag.
+
+        Pass exactly one of ``commit_hash`` or ``tag``. Returns None if
+        the commit or tag is not in the store.
+
+        The handle is a normal writable one on the caller's branch: a
+        commit from it advances that branch when it has not moved, and
+        conflicts when it has.
+        """
+        v = self._versioned.checkout(commit_hash, branch=branch, tag=tag)
         if v is None:
             return None
         return Staged(v, encoder=self._encoder, decoder=self._decoder)
@@ -430,13 +442,46 @@ class Staged(MutableMapping[str, Any]):
         self._removals.clear()
         self._cache.clear()
 
-    def peek(self, key: str, *, branch: str) -> Any:
-        """Read a key from another branch without switching. Returns None if not found."""
-        raw = self._versioned.peek(key, branch=branch)
+    def peek(
+        self, key: str, *, branch: str | None = None, tag: str | None = None
+    ) -> Any:
+        """Read a key from another branch, or from a tag, without switching.
+
+        Pass exactly one of ``branch`` or ``tag``. Returns None if not
+        found.
+        """
+        raw = self._versioned.peek(key, branch=branch, tag=tag)
         if raw is None:
             return None
         return self._decode(raw)
 
+    # -- Tags --
+
+    def tag(self, name: str, *, at: str | None = None, info: dict | None = None) -> str:
+        """Name a commit permanently. Returns the commit hash tagged.
+
+        Tags the **current commit** — the last committed state — not the
+        staging buffer. Staged changes are not part of any commit yet,
+        so there is nothing there to name; commit first if you meant to
+        tag them.
+
+        Immutable: an existing name raises rather than moving. Tags keep
+        their commit's ancestry alive through garbage collection.
+        """
+        return self._versioned.tag(name, at=at, info=info)
+
+    def tags(self) -> dict[str, str]:
+        """Map every tag in the store to the commit it names."""
+        return self._versioned.tags()
+
+    def tag_info(self, name: str) -> TagInfo | None:
+        """Describe one tag, or None if the store has no such tag."""
+        return self._versioned.tag_info(name)
+
+    def delete_tag(self, name: str) -> None:
+        """Delete a tag, then sweep commits nothing else reaches."""
+        self._versioned.delete_tag(name)
+
     def reset_to(self, commit_hash: str) -> bool:
         """Reset HEAD to a specific commit and clear staged changes.
 

{kvgit-0.3.3 → kvgit-0.3.5}/kvgit/store.py

@@ -7,7 +7,16 @@ 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
+from .versioned.kv import (
+    BRANCH_HEAD,
+    BRANCH_HEAD_PREV,
+    TAG_BRANCH_PREFIX,
+    TAG_INFO_KEY,
+    CorruptHeadRecoverer,
+    VersionedKV,
+    _assert_supported_version,
+    clean_orphans,
+)
 
 
 def _make_backend(
@@ -46,6 +55,7 @@ def store(
     encoder: Callable[..., bytes] = pickle.dumps,
     decoder: Callable[..., Any] = pickle.loads,
     codecs: str | None = None,
+    recover_from_corrupt_head: CorruptHeadRecoverer | None = None,
 ) -> Staged:
     """Create a Staged store with sensible defaults.
 
@@ -62,6 +72,13 @@ def store(
             ``"scientific"`` — numpy/pandas chunked codecs (requires
             numpy; install with ``pip install kvgit[scientific]``).
             Mutually exclusive with explicit ``encoder`` / ``decoder``.
+        recover_from_corrupt_head: Optional last-resort recovery for a
+            branch whose HEAD is unresolvable *and* whose prev-HEAD
+            backup is gone. Off by default: with both gone the store
+            does not know what the branch pointed at, so the honest
+            answer is to fail rather than guess. Pass
+            ``kvgit.versioned.kv.recover_by_commit_scan`` to opt into
+            the scan, having read what it can return.
 
     Returns:
         A ``Staged`` store instance.
@@ -85,7 +102,15 @@ def store(
 
     backend = _make_backend(kind, path=path, db_name=db_name)
 
-    return Staged(VersionedKV(backend, branch=branch), encoder=encoder, decoder=decoder)
+    return Staged(
+        VersionedKV(
+            backend,
+            branch=branch,
+            recover_from_corrupt_head=recover_from_corrupt_head,
+        ),
+        encoder=encoder,
+        decoder=decoder,
+    )
 
 
 def delete_branches(
@@ -115,7 +140,10 @@ def delete_branches(
     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
+    that only the deleted branches referenced are reclaimed. A tag is a
+    head under the reserved ``refs/tags/`` name, so a tagged commit
+    survives the deletion of every ordinary branch that reached it —
+    the sweep marks from it like any other head. 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
@@ -147,6 +175,12 @@ def delete_branches(
         return  # nothing asked: skip the backend open and the sweep
     backend = _make_backend(kind, path=path, db_name=db_name)
     try:
+        # No ``VersionedKV`` is constructed here, so nothing else on this
+        # path checks the store's layout version. Checked before the
+        # first removal rather than leaving it to the sweep: a store this
+        # code cannot read must come out of the call untouched, not with
+        # its branch keys already gone.
+        _assert_supported_version(backend)
         for name in doomed:
             backend.remove(BRANCH_HEAD % name)
             backend.remove(BRANCH_HEAD_PREV % name)
@@ -155,3 +189,59 @@ def delete_branches(
         close = getattr(backend, "close", None)
         if callable(close):
             close()
+
+
+def delete_tags(
+    names: str | Iterable[str],
+    *,
+    kind: Literal["memory", "disk", "indexeddb"] = "disk",
+    path: str | None = None,
+    db_name: str = "kvgit",
+    min_age: float = 3600,
+) -> None:
+    """Delete tags with no branch anchor, then sweep orphans.
+
+    The tag counterpart of :func:`delete_branches`, and anchor-free for
+    the same reason: teardown should not need a handle, and a handle
+    always has a current branch to open on. A tag is stored as a branch
+    head under the reserved name ``refs/tags/<name>``, so for each name
+    that head, its ``__branch_head_prev__`` backup and its
+    ``__tag_info__<name>`` record are removed, then a single
+    :func:`clean_orphans` sweep reclaims commits that only the deleted
+    tags kept alive. The backup is defensive: this code never writes one
+    for a tag, but something that treated the tag as an ordinary branch
+    could have, and a backup outliving its head would let a later tag of
+    the same name resolve to the deleted commit. A name with no tag is
+    skipped — idempotency beats a ``ValueError`` in teardown.
+
+    That sweep does not reclaim chunks; follow up with ``deep_clean`` on
+    a quiescent store if the store uses chunked codecs.
+
+    Args:
+        names: Tag 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.
+    """
+    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:
+        # Same reasoning as delete_branches: no handle is constructed on
+        # this path, so the layout check has to happen here, before
+        # anything is removed.
+        _assert_supported_version(backend)
+        for name in doomed:
+            backend.remove(BRANCH_HEAD % (TAG_BRANCH_PREFIX + name))
+            backend.remove(BRANCH_HEAD_PREV % (TAG_BRANCH_PREFIX + name))
+            backend.remove(TAG_INFO_KEY % name)
+        clean_orphans(backend, min_age=min_age)
+    finally:
+        close = getattr(backend, "close", None)
+        if callable(close):
+            close()

{kvgit-0.3.3 → kvgit-0.3.5}/kvgit/versioned/__init__.py

@@ -1,12 +1,13 @@
 """Versioned store implementations."""
 
 from .kv import VersionedKV
-from .protocol import BytesMergeFn, DiffResult, MergeResult, Versioned
+from .protocol import BytesMergeFn, DiffResult, MergeResult, TagInfo, Versioned
 
 __all__ = [
     "BytesMergeFn",
     "DiffResult",
     "MergeResult",
+    "TagInfo",
     "Versioned",
     "VersionedKV",
 ]