kvgit 0.1.0__tar.gz

kvgit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Ashenfelter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kvgit-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: kvgit
+Version: 0.1.0
+Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
+Author: ashenfad
+License: MIT
+Project-URL: Homepage, https://github.com/ashenfad/kvgit
+Project-URL: Bug Tracker, https://github.com/ashenfad/kvgit/issues
+Project-URL: Documentation, https://github.com/ashenfad/kvgit#readme
+Project-URL: Source, https://github.com/ashenfad/kvgit
+Keywords: versioning,git,key-value,branching,merge
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: disk
+Requires-Dist: diskcache; extra == "disk"
+Provides-Extra: all
+Requires-Dist: diskcache; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: diskcache; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# kvgit 🔀
+
+Versioned key-value store with git-like commit, branch, and merge semantics.
+
+Values are `Any` (serialized via pickle by default). Commits are content-addressable. Branches are cheap. Merges are three-way with pluggable per-key conflict resolution.
+
+## Features
+
+- **Commits** -- immutable, content-addressable snapshots
+- **Branches** -- named branch heads with CAS-based concurrency
+- **Three-way merge** -- auto-merges non-overlapping changes, pluggable merge functions for conflicts
+- **Merge functions** -- counters, last-writer-wins, or custom per-key merge logic
+- **Garbage collection** -- high/low water rebase drops cold keys automatically
+- **Namespaces** -- key-prefixed views with full read/write support
+- **Pluggable backends** -- in-memory, disk (via diskcache), or bring your own `KVStore`
+
+## Install
+
+```bash
+pip install kvgit            # in-memory only
+pip install kvgit[disk]      # adds disk backend via diskcache
+```
+
+## Quick example
+
+```python
+import kvgit
+
+# Create a store -- values are Any (pickle-serialized by default)
+s = kvgit.store()
+
+s["user"] = "alice"
+s["score"] = 0
+s.commit()
+
+first = s.current_commit
+
+# Update and commit again
+s["score"] = 100
+s.commit()
+print(s["score"])              # 100
+
+# Rollback to the first commit
+s.reset_to(first)
+print(s["score"])              # 0
+
+# Branching
+s["score"] = 50
+s.commit()
+
+dev = s.create_branch("dev")
+dev["score"] = 999
+dev.commit()
+
+print(s["score"])              # 50  (main unchanged)
+print(dev["score"])            # 999 (dev branch)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## Documentation
+
+See [`docs/`](docs/) for detailed API documentation:
+
+- [Core API (Versioned)](docs/versioned.md) -- commits, reads, writes, merging, branching, history
+- [Merge Functions](docs/content-types.md) -- per-key merge logic for conflict resolution
+- [Garbage Collection](docs/gc.md) -- GCVersioned, rebase, orphan cleanup
+- [Backends & Namespaces](docs/backends.md) -- KVStore interface, Memory, Disk, Store, Staged, Live, Namespaced

kvgit-0.1.0/README.md

@@ -0,0 +1,73 @@
+# kvgit 🔀
+
+Versioned key-value store with git-like commit, branch, and merge semantics.
+
+Values are `Any` (serialized via pickle by default). Commits are content-addressable. Branches are cheap. Merges are three-way with pluggable per-key conflict resolution.
+
+## Features
+
+- **Commits** -- immutable, content-addressable snapshots
+- **Branches** -- named branch heads with CAS-based concurrency
+- **Three-way merge** -- auto-merges non-overlapping changes, pluggable merge functions for conflicts
+- **Merge functions** -- counters, last-writer-wins, or custom per-key merge logic
+- **Garbage collection** -- high/low water rebase drops cold keys automatically
+- **Namespaces** -- key-prefixed views with full read/write support
+- **Pluggable backends** -- in-memory, disk (via diskcache), or bring your own `KVStore`
+
+## Install
+
+```bash
+pip install kvgit            # in-memory only
+pip install kvgit[disk]      # adds disk backend via diskcache
+```
+
+## Quick example
+
+```python
+import kvgit
+
+# Create a store -- values are Any (pickle-serialized by default)
+s = kvgit.store()
+
+s["user"] = "alice"
+s["score"] = 0
+s.commit()
+
+first = s.current_commit
+
+# Update and commit again
+s["score"] = 100
+s.commit()
+print(s["score"])              # 100
+
+# Rollback to the first commit
+s.reset_to(first)
+print(s["score"])              # 0
+
+# Branching
+s["score"] = 50
+s.commit()
+
+dev = s.create_branch("dev")
+dev["score"] = 999
+dev.commit()
+
+print(s["score"])              # 50  (main unchanged)
+print(dev["score"])            # 999 (dev branch)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## Documentation
+
+See [`docs/`](docs/) for detailed API documentation:
+
+- [Core API (Versioned)](docs/versioned.md) -- commits, reads, writes, merging, branching, history
+- [Merge Functions](docs/content-types.md) -- per-key merge logic for conflict resolution
+- [Garbage Collection](docs/gc.md) -- GCVersioned, rebase, orphan cleanup
+- [Backends & Namespaces](docs/backends.md) -- KVStore interface, Memory, Disk, Store, Staged, Live, Namespaced

kvgit-0.1.0/kvgit/__init__.py

@@ -0,0 +1,23 @@
+"""kvgit: Versioned key-value store."""
+
+from .content_types import MergeFn, counter, last_writer_wins
+from .errors import ConcurrencyError, MergeConflict
+from .live import Live
+from .namespaced import Namespaced
+from .staged import Staged
+from .store import store
+from .versioned import MergeResult, Versioned
+
+__all__ = [
+    "ConcurrencyError",
+    "Live",
+    "MergeConflict",
+    "MergeFn",
+    "MergeResult",
+    "Namespaced",
+    "Staged",
+    "Versioned",
+    "counter",
+    "last_writer_wins",
+    "store",
+]

kvgit-0.1.0/kvgit/content_types.py

@@ -0,0 +1,24 @@
+"""Merge functions for typed values."""
+
+from typing import Any, Callable
+
+MergeFn = Callable[[Any | None, Any, Any], Any]
+"""Merge function: (old_value | None, our_value, their_value) -> merged_value.
+
+Any argument can be None (key absent or removed on that side).
+"""
+
+
+def counter() -> MergeFn:
+    """Counter merge: ours + theirs - old."""
+
+    def merge(old: int | None, ours: int, theirs: int) -> int:
+        base = old if old is not None else 0
+        return ours + theirs - base
+
+    return merge
+
+
+def last_writer_wins() -> MergeFn:
+    """Last-writer-wins: always returns theirs."""
+    return lambda old, ours, theirs: theirs

kvgit-0.1.0/kvgit/errors.py

@@ -0,0 +1,28 @@
+"""kvgit error types."""
+
+
+class ConcurrencyError(Exception):
+    """Raised when a concurrent write conflict occurs during merge.
+
+    Another process updated HEAD between when this branch started
+    and when merge was attempted via CAS. The caller should reset
+    and retry.
+    """
+
+
+class MergeConflict(Exception):
+    """Raised when a three-way merge encounters unresolvable conflicts.
+
+    Attributes:
+        conflicting_keys: The set of keys that could not be auto-merged.
+    """
+
+    def __init__(
+        self,
+        conflicting_keys: set[str],
+        merge_errors: dict[str, Exception] | None = None,
+    ) -> None:
+        self.conflicting_keys = conflicting_keys
+        self.merge_errors = merge_errors or {}
+        keys_str = ", ".join(sorted(conflicting_keys))
+        super().__init__(f"Merge conflict on keys: {keys_str}")

kvgit-0.1.0/kvgit/gc.py

@@ -0,0 +1,346 @@
+"""GCVersioned: Versioned state with automatic garbage collection."""
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Callable
+
+from .errors import ConcurrencyError
+from .kv.base import KVStore
+from .versioned import (
+    BRANCH_HEAD,
+    COMMIT_KEYSET,
+    INFO_KEY,
+    META_KEY,
+    PARENT_COMMIT,
+    TOTAL_VAR_SIZE_KEY,
+    MergeResult,
+    MetaEntry,
+    Versioned,
+    _from_bytes,
+    _meta_from_bytes,
+    _meta_to_bytes,
+    _to_bytes,
+)
+
+
+def _is_system_key(key: str) -> bool:
+    """Check if a key is a system/protected key (starts with ``__``).
+
+    Handles both direct keys (``"__foo__"``) and namespaced keys
+    (``"ns/__foo__"``) by extracting the base key name.
+
+    This is the default ``is_protected`` policy for ``GCVersioned``.
+    """
+    base_key = key.split("/")[-1] if "/" in key else key
+    return base_key.startswith("__")
+
+
+@dataclass(frozen=True)
+class RebaseResult:
+    """Result of a rebase/GC operation."""
+
+    performed: bool
+    new_commit: str | None
+    dropped_keys: tuple[str, ...]
+    kept_keys: tuple[str, ...]
+    total_size_before: int
+    total_size_after: int
+    orphans_cleaned: int = 0
+
+
+class GCVersioned(Versioned):
+    """Versioned state with built-in garbage collection via rebase.
+
+    Rebase strategy (high/low water):
+    - Track total persisted user-var size from commit metadata.
+    - If total <= high_water_bytes: no-op.
+    - If total > high_water_bytes: drop coldest user keys (oldest touch,
+      then largest) until total <= low_water_bytes (default 80% of high).
+    - Protected keys (as determined by ``is_protected``) are always retained.
+    - Write a fresh root commit with only retained keys, then delete
+      dropped blobs and orphaned commits.
+
+    Every ``commit()`` auto-runs the high/low check.
+    """
+
+    def __init__(
+        self,
+        store: KVStore | None = None,
+        *,
+        commit_hash: str | None = None,
+        branch: str = "main",
+        high_water_bytes: int,
+        low_water_bytes: int | None = None,
+        is_protected: Callable[[str], bool] = _is_system_key,
+    ) -> None:
+        super().__init__(store, commit_hash=commit_hash, branch=branch)
+        if high_water_bytes <= 0:
+            raise ValueError("high_water_bytes must be > 0")
+        self.high_water = high_water_bytes
+        self.low_water = (
+            low_water_bytes
+            if low_water_bytes is not None
+            else int(high_water_bytes * 0.8)
+        )
+        if self.low_water <= 0 or self.low_water > self.high_water:
+            self.low_water = int(high_water_bytes * 0.8)
+        self._is_protected = is_protected
+        self.last_rebase_result: RebaseResult | None = None
+
+    def commit(
+        self,
+        updates: dict[str, bytes] | None = None,
+        removals: set[str] | None = None,
+        *,
+        on_conflict: str = "raise",
+        merge_fns=None,
+        default_merge=None,
+        info: dict | None = None,
+    ) -> "MergeResult":
+        """Commit changes, then run GC if above high water mark."""
+
+        result = super().commit(
+            updates,
+            removals,
+            on_conflict=on_conflict,
+            merge_fns=merge_fns,
+            default_merge=default_merge,
+            info=info,
+        )
+        if result.merged:
+            rebase_result = self.maybe_rebase()
+            self.last_rebase_result = rebase_result
+        return result
+
+    def maybe_rebase(self) -> RebaseResult:
+        """Run rebase only if total size exceeds high water mark."""
+        total = self._load_total_size()
+        if total <= self.high_water:
+            return RebaseResult(
+                performed=False,
+                new_commit=None,
+                dropped_keys=(),
+                kept_keys=tuple(self._commit_keys.keys()),
+                total_size_before=total,
+                total_size_after=total,
+            )
+        return self.rebase()
+
+    def rebase(
+        self,
+        keep_keys: set[str] | None = None,
+        *,
+        info: dict | None = None,
+    ) -> RebaseResult:
+        """Rebase: create a fresh root commit, dropping cold keys.
+
+        Args:
+            keep_keys: If provided, retain exactly these keys (plus protected
+                keys). Otherwise, use the high/low water strategy.
+            info: Optional metadata for the rebase commit.
+        """
+        meta = self._meta
+        total_before = self._load_total_size(
+            default=sum(e.size or 0 for e in meta.values())
+        )
+
+        # Identify protected and user keys
+        protected_keys = {
+            k: v for k, v in self._commit_keys.items() if self._is_protected(k)
+        }
+        user_meta = {k: v for k, v in meta.items() if not self._is_protected(k)}
+
+        retained_keys = set(protected_keys.keys()) | set(user_meta.keys())
+        total = sum(e.size or 0 for e in user_meta.values())
+        dropped: list[str] = []
+
+        if keep_keys is not None:
+            # Explicit keep set — drop everything not in it (except protected keys)
+            for key in list(retained_keys):
+                if self._is_protected(key):
+                    continue
+                if key not in keep_keys:
+                    retained_keys.discard(key)
+                    dropped.append(key)
+                    total -= (user_meta.get(key) and user_meta[key].size) or 0
+        else:
+            # High/low water strategy: drop coldest until under low water
+            candidates: list[tuple[str, MetaEntry]] = sorted(
+                user_meta.items(),
+                key=lambda kv: (kv[1].last_touch, -(kv[1].size or 0)),
+            )
+            for key, entry in candidates:
+                if total <= self.low_water:
+                    break
+                retained_keys.discard(key)
+                dropped.append(key)
+                total -= entry.size or 0
+
+        # Build new commit with retained keys
+        from .versioned import _content_hash
+
+        # Collect retained data
+        new_commit_keys: dict[str, str] = {}
+        new_meta: dict[str, MetaEntry] = {}
+        retained_data: dict[str, bytes] = {}
+
+        for key in retained_keys:
+            versioned_key = self._commit_keys.get(key)
+            if not versioned_key:
+                continue
+            value = self.store.get(versioned_key)
+            if value is None:
+                continue
+            if not self._is_protected(key):
+                retained_data[key] = value
+                if key in meta:
+                    new_meta[key] = meta[key]
+
+        # Content-addressable hash for the rebase commit (parent=None, fresh root)
+        preview_keys: dict[str, str] = {}
+        for key in protected_keys:
+            preview_keys[key] = protected_keys[key]
+        for key in retained_data:
+            preview_keys[key] = f"<pending:{key}>"
+        new_hash = _content_hash((), preview_keys, retained_data, info=info)
+
+        # Build the write batch
+        diffs: dict[str, bytes] = {}
+
+        # Protected keys — copy blobs with new versioned keys
+        for key, old_vk in protected_keys.items():
+            value = self.store.get(old_vk)
+            if value is None:
+                continue
+            new_vk = f"{new_hash}:{key}"
+            new_commit_keys[key] = new_vk
+            diffs[new_vk] = value
+
+        # Retained user keys
+        for key, value in retained_data.items():
+            new_vk = f"{new_hash}:{key}"
+            new_commit_keys[key] = new_vk
+            diffs[new_vk] = value
+
+        # Commit metadata
+        diffs[COMMIT_KEYSET % new_hash] = _to_bytes(new_commit_keys)
+        diffs[PARENT_COMMIT % new_hash] = _to_bytes([])
+        diffs[META_KEY % new_hash] = _meta_to_bytes(new_meta)
+        total_after = sum(e.size or 0 for e in new_meta.values())
+        diffs[TOTAL_VAR_SIZE_KEY % new_hash] = _to_bytes(total_after)
+        if info is not None:
+            diffs[INFO_KEY % new_hash] = _to_bytes(info)
+
+        self.store.set_many(**diffs)
+
+        # CAS HEAD to the new rebase commit
+        branch_key = BRANCH_HEAD % self._branch
+        expected = _to_bytes(self._base_commit)
+        if not self.store.cas(branch_key, _to_bytes(new_hash), expected=expected):
+            raise ConcurrencyError("HEAD changed during rebase.")
+
+        # Delete dropped blobs
+        to_delete = []
+        for key in dropped:
+            vk = self._commit_keys.get(key)
+            if vk:
+                to_delete.append(vk)
+        if to_delete:
+            self.store.remove_many(*to_delete)
+
+        # Update in-memory state
+        self._commit_keys = new_commit_keys
+        self._current_commit = new_hash
+        self._base_commit = new_hash
+        self._meta = new_meta
+
+        # Clean orphaned commits
+        orphans_cleaned = self.clean_orphans()
+
+        return RebaseResult(
+            performed=True,
+            new_commit=new_hash,
+            dropped_keys=tuple(dropped),
+            kept_keys=tuple(retained_keys),
+            total_size_before=total_before,
+            total_size_after=total_after,
+            orphans_cleaned=orphans_cleaned,
+        )
+
+    def clean_orphans(self, min_age: float = 3600) -> int:
+        """Remove orphaned commits unreachable from HEAD.
+
+        Args:
+            min_age: Only delete orphans older than this many seconds
+                (default 1 hour).
+
+        Returns:
+            Number of orphaned commits cleaned.
+        """
+        # Mark phase: find all reachable commits across ALL branches
+        reachable: set[str] = set()
+        prefix = BRANCH_HEAD.replace("%s", "")
+        for key in self.store.keys():
+            if isinstance(key, str) and key.startswith(prefix):
+                head_bytes = self.store.get(key)
+                if head_bytes is None:
+                    continue
+                branch_head = _from_bytes(head_bytes)
+                for commit in self.history(commit_hash=branch_head, all_parents=True):
+                    reachable.add(commit)
+
+        # Sweep phase: find orphaned commits by scanning for meta keys
+        meta_prefix = META_KEY.replace("%s", "")
+        cutoff_time = time.time() - min_age
+        orphans: list[str] = []
+
+        for key in self.store.keys():
+            if not isinstance(key, str) or not key.startswith(meta_prefix):
+                continue
+            commit_hash = key[len(meta_prefix) :]
+            if not commit_hash or commit_hash in reachable:
+                continue
+            # Check age
+            meta_bytes = self.store.get(key)
+            if meta_bytes is None:
+                continue
+            try:
+                meta = _meta_from_bytes(meta_bytes)
+                if meta:
+                    first_entry = next(iter(meta.values()), None)
+                    if first_entry and first_entry.created_at < cutoff_time:
+                        orphans.append(commit_hash)
+            except (json.JSONDecodeError, TypeError, KeyError):
+                continue
+
+        # Delete orphaned commits and their data
+        for orphan_hash in orphans:
+            keyset_bytes = self.store.get(COMMIT_KEYSET % orphan_hash)
+            if keyset_bytes:
+                try:
+                    keyset = _from_bytes(keyset_bytes)
+                    blob_keys = list(keyset.values())
+                    if blob_keys:
+                        self.store.remove_many(*blob_keys)
+                except Exception:
+                    pass
+            self.store.remove_many(
+                META_KEY % orphan_hash,
+                COMMIT_KEYSET % orphan_hash,
+                PARENT_COMMIT % orphan_hash,
+                TOTAL_VAR_SIZE_KEY % orphan_hash,
+                INFO_KEY % orphan_hash,
+            )
+
+        return len(orphans)
+
+    def _load_total_size(self, default: int = 0) -> int:
+        """Load the total variable size for the current commit."""
+        total_bytes = self.store.get(TOTAL_VAR_SIZE_KEY % self._current_commit)
+        if total_bytes is None:
+            return default
+        try:
+            return _from_bytes(total_bytes)
+        except Exception:
+            return default

kvgit-0.1.0/kvgit/kv/__init__.py

@@ -0,0 +1,8 @@
+"""KV store backends."""
+
+from .base import KVStore
+from .composite import Composite
+from .disk import Disk
+from .memory import Memory
+
+__all__ = ["Composite", "Disk", "KVStore", "Memory"]