kvgit 0.3.4__tar.gz → 0.3.6__tar.gz

{kvgit-0.3.4 → kvgit-0.3.6}/PKG-INFO

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

@@ -2,23 +2,30 @@
 
 from .content_types import MergeFn, counter, last_writer_wins
 from .errors import ConcurrencyError, MergeConflict
+from .merges import CantMark, TextMergeFn, make_text_merge, text
 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__ = [
+    "CantMark",
     "ConcurrencyError",
     "MergeConflict",
     "MergeFn",
     "MergeResult",
     "Namespaced",
     "Staged",
+    "TagInfo",
+    "TextMergeFn",
     "Versioned",
     "VersionedKV",
     "counter",
     "delete_branches",
+    "delete_tags",
     "last_writer_wins",
+    "make_text_merge",
     "store",
+    "text",
 ]

kvgit-0.3.6/kvgit/merges.py

@@ -0,0 +1,247 @@
+"""Text merge with conflict markers.
+
+A batteries-included ``BytesMergeFn`` for line-oriented text: disjoint
+changes merge cleanly, overlapping changes come back with git-style
+``<<<<<<<`` markers instead of raising. Register it as a per-key fn or
+as ``default_merge`` wherever text blobs merge (see ``resolve_merge``).
+
+Anything that cannot be marked — undecodable bytes, NUL bytes, inputs
+over the size cap — raises :class:`CantMark`, which the merge machinery
+files as an ordinary conflict. Callers that need to tell "no encoding"
+from "too big" catch it themselves; callers that don't let it flow.
+"""
+
+from __future__ import annotations
+
+import difflib
+from collections.abc import Callable
+
+from .versioned.protocol import BytesMergeFn
+
+#: Inputs whose combined size exceeds this are refused with
+#: :class:`CantMark` rather than merged. Line-diffing is quadratic-ish
+#: in the worst case (minified single-line megabytes); a merge this big
+#: is a whole-file conflict by inspection anyway.
+MAX_MARK_BYTES = 1024 * 1024
+
+
+class CantMark(Exception):
+    """A value cannot be marker-merged: not text, or too big.
+
+    Raised instead of returning bytes when the inputs are undecodable as
+    UTF-8, contain NUL bytes, or exceed ``MAX_MARK_BYTES`` combined.
+    The merge machinery reports it as a conflict for that key.
+    """
+
+
+def _decode(data: bytes | None) -> list[str]:
+    """Split one side into lines; a removed side is the empty list.
+
+    The markers then show one populated side against nothing, which
+    reads correctly.
+    """
+    if data is None:
+        return []
+    if b"\x00" in data:
+        raise CantMark("NUL byte: not text")
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise CantMark(f"not UTF-8: {e}") from e
+    return text.splitlines(keepends=True)
+
+
+def _changes(base: list[str], side: list[str]) -> list[tuple[int, int, list[str]]]:
+    """Non-equal opcode intervals of ``side`` against ``base``.
+
+    Each tuple is ``(base_start, base_end, replacement_lines)``;
+    pure insertions have ``base_start == base_end``.
+    """
+    matcher = difflib.SequenceMatcher(None, base, side, autojunk=False)
+    return [
+        (i1, i2, side[j1:j2])
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes()
+        if tag != "equal"
+    ]
+
+
+def _terminate(lines: list[str]) -> list[str]:
+    """Ensure every non-final line ends with a newline.
+
+    A line without a trailing newline glued onto following output would
+    corrupt both; clean regions stay byte-exact (a final line keeps its
+    missing newline), markers pay the newline tax.
+    """
+    fixed: list[str] = []
+    for i, ln in enumerate(lines):
+        if not ln.endswith("\n") and i + 1 < len(lines):
+            ln += "\n"
+        fixed.append(ln)
+    return fixed
+
+
+def _replay(base: list[str], start: int, end: int, events: list[tuple]) -> list[str]:
+    """One side's full content over ``base[start:end]``.
+
+    Base lines outside the side's own hunks, replacement lines inside.
+    Same-side events come from one SequenceMatcher pass, so they are
+    disjoint and the replay is well-defined. Without this, overlapping
+    groups spanning different base ranges would emit only replacement
+    lines and silently drop the base lines between them.
+    """
+    out: list[str] = []
+    pos = start
+    for _, s, e, lines in sorted(events, key=lambda ev: (ev[1], ev[2])):
+        out.extend(base[pos:s])
+        out.extend(lines)
+        pos = max(pos, e)
+    out.extend(base[pos:end])
+    return out
+
+
+def _merge_lines(
+    base: list[str],
+    ours: list[str],
+    theirs: list[str],
+    ours_label: str,
+    theirs_label: str,
+    ours_deleted: bool = False,
+    theirs_deleted: bool = False,
+) -> tuple[list[str], bool]:
+    """Three-way line merge. Returns ``(lines, conflicted)``.
+
+    The ``*_deleted`` flags record raw ``None`` inputs (a removed side),
+    tracked separately from decoded emptiness: an empty base file that
+    one side deletes and the other writes is a modify/delete conflict,
+    not a clean add. Still-absent on an added/added merge (base itself
+    missing) is not a deletion.
+    """
+    if ours == theirs:
+        return list(ours), False
+
+    # Whole-file deletion on one side against any change on the other is
+    # a modify/delete conflict with the survivor shown whole — the
+    # interval machinery below only sees hunks and would drop the
+    # surviving context. (Unchanged-vs-deleted resolves above through
+    # the empty-changes fast paths.)
+    if ours_deleted and theirs != base:
+        return _terminate(
+            [
+                f"<<<<<<< {ours_label}\n",
+                "=======\n",
+                *theirs,
+                f">>>>>>> {theirs_label}\n",
+            ]
+        ), True
+    if theirs_deleted and ours != base:
+        return _terminate(
+            [
+                f"<<<<<<< {ours_label}\n",
+                *ours,
+                "=======\n",
+                f">>>>>>> {theirs_label}\n",
+            ]
+        ), True
+
+    our_changes = _changes(base, ours)
+    their_changes = _changes(base, theirs)
+    if not our_changes:
+        return list(theirs), False
+    if not their_changes:
+        return list(ours), False
+
+    # Merge overlapping change intervals into conflict groups; disjoint
+    # intervals resolve independently. Intervals are half-open over base
+    # positions; pure insertions are points. Join on strict overlap, plus
+    # same-point inserts colliding with each other — an insert merely
+    # adjacent to a change interval resolves cleanly beside it, while two
+    # different inserts at one point genuinely conflict.
+    events = [("ours", s, e, lines) for s, e, lines in our_changes]
+    events += [("theirs", s, e, lines) for s, e, lines in their_changes]
+    events.sort(key=lambda ev: (ev[1], ev[2]))
+
+    # Each group tracks its member events plus its max base end, since
+    # overlap is against the group's full span, not the last event.
+    groups: list[list[tuple]] = []
+    group_ends: list[int] = []
+    for ev in events:
+        _, s, e, _ = ev
+        if groups and (
+            s < group_ends[-1]
+            or (s == e and any(g[1] == g[2] == s for g in groups[-1]))
+        ):
+            groups[-1].append(ev)
+            group_ends[-1] = max(group_ends[-1], e)
+        else:
+            groups.append([ev])
+            group_ends.append(e)
+
+    out: list[str] = []
+    conflicted = False
+    pos = 0
+    for group in groups:
+        start = min(ev[1] for ev in group)
+        end = max(ev[2] for ev in group)
+        out.extend(base[pos:start])
+        ours_ev = [ev for ev in group if ev[0] == "ours"]
+        theirs_ev = [ev for ev in group if ev[0] == "theirs"]
+        if not theirs_ev:
+            out.extend(_replay(base, start, end, ours_ev))
+        elif not ours_ev:
+            out.extend(_replay(base, start, end, theirs_ev))
+        else:
+            ours_full = _replay(base, start, end, ours_ev)
+            theirs_full = _replay(base, start, end, theirs_ev)
+            if ours_full == theirs_full:
+                out.extend(ours_full)
+            else:
+                conflicted = True
+                out.append(f"<<<<<<< {ours_label}\n")
+                out.extend(ours_full)
+                out.append("=======\n")
+                out.extend(theirs_full)
+                out.append(f">>>>>>> {theirs_label}\n")
+        pos = end
+    out.extend(base[pos:])
+
+    return _terminate(out), conflicted
+
+
+def make_text_merge(
+    *, ours_label: str = "ours", theirs_label: str = "theirs"
+) -> BytesMergeFn:
+    """Build a marker-merge fn with custom conflict labels.
+
+    Labels ride git's positions (``<<<<<<< <ours>`` /
+    ``>>>>>>> <theirs>``); pass branch names so conflicts read
+    attributably. Labels may not contain newlines.
+    """
+    for name, label in (("ours_label", ours_label), ("theirs_label", theirs_label)):
+        if "\n" in label:
+            raise ValueError(f"{name} may not contain a newline: {label!r}")
+
+    def merge(old: bytes | None, ours: bytes | None, theirs: bytes | None) -> bytes:
+        total = sum(len(d) for d in (old, ours, theirs) if d is not None)
+        if total > MAX_MARK_BYTES:
+            raise CantMark(f"inputs total {total} bytes over cap {MAX_MARK_BYTES}")
+        merged, _ = _merge_lines(
+            _decode(old),
+            _decode(ours),
+            _decode(theirs),
+            ours_label,
+            theirs_label,
+            ours_deleted=ours is None and old is not None,
+            theirs_deleted=theirs is None and old is not None,
+        )
+        return "".join(merged).encode("utf-8")
+
+    return merge
+
+
+def text(old: bytes | None, ours: bytes | None, theirs: bytes | None) -> bytes:
+    """Marker-merge with default labels. Usable as ``default_merge`` directly."""
+    return make_text_merge()(old, ours, theirs)
+
+
+TextMergeFn = Callable[[bytes | None, bytes | None, bytes | None], bytes]
+"""Type of what :func:`make_text_merge` builds (== ``BytesMergeFn``)."""

{kvgit-0.3.4 → kvgit-0.3.6}/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.4 → kvgit-0.3.6}/kvgit/store.py

@@ -10,8 +10,11 @@ from .staged import Staged
 from .versioned.kv import (
     BRANCH_HEAD,
     BRANCH_HEAD_PREV,
+    TAG_BRANCH_PREFIX,
+    TAG_INFO_KEY,
     CorruptHeadRecoverer,
     VersionedKV,
+    _assert_supported_version,
     clean_orphans,
 )
 
@@ -137,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
@@ -169,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)
@@ -177,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.4 → kvgit-0.3.6}/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",
 ]