glyff-sqlite 0.12.0__tar.gz

glyff_sqlite-0.12.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+Thumbs.db
+
+node_modules/
+
+.env
+.env.local
+
+/out/
+/.local/
+__pycache__/
+*.pyc

glyff_sqlite-0.12.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nueruyu
+
+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.

glyff_sqlite-0.12.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: glyff-sqlite
+Version: 0.12.0
+Summary: SQLite-backed durable SessionStore for glyff.
+License: MIT License
+        
+        Copyright (c) 2026 nueruyu
+        
+        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.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: glyff>=0.1.0
+Description-Content-Type: text/markdown
+
+# glyff-sqlite
+
+SQLite-backed durable `SessionStore` implementation for
+[glyff](https://pypi.org/project/glyff/).
+
+This is the **production** backend: one row per execution in a SQLite database,
+WAL mode, indexed lookups, and native transaction atomicity.
+
+## Install
+
+```bash
+pip install glyff-sqlite
+```
+
+This package depends on `glyff>=0.1.0` (no additional runtime dependencies —
+`sqlite3` is part of the standard library).
+
+## Usage
+
+```python
+from glyff.serialization import JsonSerializer
+from glyff_sqlite import SQLiteSessionStore
+
+store = SQLiteSessionStore("executions.sqlite3", JsonSerializer())
+```
+
+## Public API
+
+| Name                 | Description                                                   |
+| -------------------- | ------------------------------------------------------------- |
+| `SQLiteSessionStore` | Durable `SessionStore` backed by a local SQLite database.     |
+| `SQLiteClient`       | Low-level SQLite key/value store (generic, reusable).         |
+
+## External metadata
+
+The underlying ``SQLiteClient`` exposes ``stage_write`` / ``stage_delete`` /
+``stage_update`` so application code can persist its own rows alongside execution
+records and commit or roll back atomically together:
+
+```python
+client = SQLiteClient("session.sqlite3")
+store = SQLiteSessionStore(client=client, serializer=JsonSerializer())
+
+tx = await store.begin_transaction()
+execution = await store.start_execution(some_id)
+await execution.complete("ok", str)
+
+client.stage_write("metadata", "my_key", b"my_value")
+client.stage_delete("metadata", "old_key")
+
+await tx.commit()   # execution record + metadata commit atomically
+```
+
+## Transaction model
+
+- Writes are staged in-memory per transaction and flushed on commit.
+- Nested transactions (child scopes) commit independently of their parent.
+- `BEGIN IMMEDIATE` prevents writer contention; WAL mode keeps reads fast.
+- A per-database asyncio write lock serialises concurrent write transactions.
+
+## Status
+
+Early development. APIs may change before v1.0.
+
+## License
+
+MIT

glyff_sqlite-0.12.0/README.md

@@ -0,0 +1,67 @@
+# glyff-sqlite
+
+SQLite-backed durable `SessionStore` implementation for
+[glyff](https://pypi.org/project/glyff/).
+
+This is the **production** backend: one row per execution in a SQLite database,
+WAL mode, indexed lookups, and native transaction atomicity.
+
+## Install
+
+```bash
+pip install glyff-sqlite
+```
+
+This package depends on `glyff>=0.1.0` (no additional runtime dependencies —
+`sqlite3` is part of the standard library).
+
+## Usage
+
+```python
+from glyff.serialization import JsonSerializer
+from glyff_sqlite import SQLiteSessionStore
+
+store = SQLiteSessionStore("executions.sqlite3", JsonSerializer())
+```
+
+## Public API
+
+| Name                 | Description                                                   |
+| -------------------- | ------------------------------------------------------------- |
+| `SQLiteSessionStore` | Durable `SessionStore` backed by a local SQLite database.     |
+| `SQLiteClient`       | Low-level SQLite key/value store (generic, reusable).         |
+
+## External metadata
+
+The underlying ``SQLiteClient`` exposes ``stage_write`` / ``stage_delete`` /
+``stage_update`` so application code can persist its own rows alongside execution
+records and commit or roll back atomically together:
+
+```python
+client = SQLiteClient("session.sqlite3")
+store = SQLiteSessionStore(client=client, serializer=JsonSerializer())
+
+tx = await store.begin_transaction()
+execution = await store.start_execution(some_id)
+await execution.complete("ok", str)
+
+client.stage_write("metadata", "my_key", b"my_value")
+client.stage_delete("metadata", "old_key")
+
+await tx.commit()   # execution record + metadata commit atomically
+```
+
+## Transaction model
+
+- Writes are staged in-memory per transaction and flushed on commit.
+- Nested transactions (child scopes) commit independently of their parent.
+- `BEGIN IMMEDIATE` prevents writer contention; WAL mode keeps reads fast.
+- A per-database asyncio write lock serialises concurrent write transactions.
+
+## Status
+
+Early development. APIs may change before v1.0.
+
+## License
+
+MIT

glyff_sqlite-0.12.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "glyff-sqlite"
+description = "SQLite-backed durable SessionStore for glyff."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+dependencies = [
+    "glyff>=0.1.0",
+]
+dynamic = ["version"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+
+[tool.uv.sources]
+glyff = { workspace = true }
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/glyff_sqlite"]
+exclude = ["src/glyff_sqlite/tests"]
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["src/glyff_sqlite/tests"]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]

glyff_sqlite-0.12.0/src/glyff_sqlite/__init__.py

@@ -0,0 +1,7 @@
+from ._sqlite_client import SQLiteClient
+from ._sqlite_store import SQLiteSessionStore
+
+__all__ = [
+    "SQLiteClient",
+    "SQLiteSessionStore",
+]

glyff_sqlite-0.12.0/src/glyff_sqlite/_sqlite_client.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import sqlite3
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SQLiteUpdate = Callable[[bytes | None], bytes | None]
+
+
+@dataclass(frozen=True)
+class _Write:
+    value: bytes
+
+
+@dataclass(frozen=True)
+class _Delete:
+    pass
+
+
+@dataclass(frozen=True)
+class _Update:
+    fn: SQLiteUpdate
+
+
+_StagedOp = _Write | _Delete | _Update
+
+_VALID_SYNCHRONOUS_VALUES = {"OFF", "NORMAL", "FULL", "EXTRA"}
+
+
+class _SQLiteStagingBuffer:
+    __slots__ = ("ops",)
+
+    def __init__(self) -> None:
+        self.ops: dict[tuple[str, str], list[_StagedOp]] = {}
+
+    def clear(self) -> None:
+        self.ops.clear()
+
+
+class SQLiteClient:
+    """A generic SQLite-backed transactional key/value store.
+
+    Each record is identified by ``(namespace, key)`` and stored as a blob
+    in the ``records`` table. Operations are staged per-transaction and
+    committed atomically.
+    """
+
+    def __init__(
+        self,
+        database_path: str | Path,
+        *,
+        busy_timeout_ms: int = 30_000,
+        synchronous: str = "FULL",
+    ) -> None:
+        synchronous = synchronous.upper()
+        if synchronous not in _VALID_SYNCHRONOUS_VALUES:
+            valid = ", ".join(sorted(_VALID_SYNCHRONOUS_VALUES))
+            raise ValueError(f"synchronous must be one of: {valid}")
+
+        if str(database_path) == ":memory:":
+            raise ValueError(
+                "SQLiteClient does not support ':memory:' because it opens "
+                "a new connection per operation."
+            )
+
+        self._database_path = Path(database_path)
+        self._busy_timeout_ms = busy_timeout_ms
+        self._synchronous = synchronous
+        self._write_lock = asyncio.Lock()
+        self._current: contextvars.ContextVar[_SQLiteStagingBuffer | None] = (
+            contextvars.ContextVar("sqlite_client_staging", default=None)
+        )
+
+        self._database_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # -- Connection helpers ----------------------------------------------------
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(
+            self._database_path,
+            isolation_level=None,
+            timeout=self._busy_timeout_ms / 1000,
+            check_same_thread=False,
+        )
+        connection.execute(f"PRAGMA busy_timeout={self._busy_timeout_ms}")
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute(f"PRAGMA synchronous={self._synchronous}")
+        return connection
+
+    # -- Schema initialization -------------------------------------------------
+
+    def _initialize_schema_sync(self) -> None:
+        connection = self._connect()
+        in_transaction = False
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            in_transaction = True
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS records (
+                    namespace TEXT NOT NULL,
+                    key TEXT NOT NULL,
+                    value BLOB NOT NULL,
+                    PRIMARY KEY (namespace, key)
+                )
+                """
+            )
+            connection.execute("COMMIT")
+            in_transaction = False
+        except BaseException:
+            if in_transaction:
+                try:
+                    connection.execute("ROLLBACK")
+                except sqlite3.Error:
+                    pass
+            raise
+        finally:
+            connection.close()
+
+    # -- Staging lifecycle -----------------------------------------------------
+
+    def begin_staging(self) -> tuple[contextvars.Token, _SQLiteStagingBuffer]:
+        staging = _SQLiteStagingBuffer()
+        token = self._current.set(staging)
+        return token, staging
+
+    def end_staging(self, token: contextvars.Token) -> None:
+        self._current.reset(token)
+
+    def _require_staging(self) -> _SQLiteStagingBuffer:
+        staging = self._current.get()
+        if staging is None:
+            raise RuntimeError("SQLiteClient write attempted outside a transaction.")
+        return staging
+
+    def _require_current_staging(self, expected: _SQLiteStagingBuffer) -> None:
+        if self._current.get() is not expected:
+            raise RuntimeError("Transaction closed out of order.")
+
+    # -- Staging API -----------------------------------------------------------
+
+    def stage_write(self, namespace: str, key: str, value: bytes) -> None:
+        staging = self._require_staging()
+        staging.ops.setdefault((namespace, key), []).append(_Write(value))
+
+    def stage_delete(self, namespace: str, key: str) -> None:
+        staging = self._require_staging()
+        staging.ops.setdefault((namespace, key), []).append(_Delete())
+
+    def stage_update(self, namespace: str, key: str, fn: SQLiteUpdate) -> None:
+        staging = self._require_staging()
+        staging.ops.setdefault((namespace, key), []).append(_Update(fn))
+
+    async def clear_staged(self) -> None:
+        self._require_staging().clear()
+
+    # -- Commit ----------------------------------------------------------------
+
+    async def commit_staged(self) -> None:
+        staging = self._require_staging()
+
+        if not staging.ops:
+            return
+
+        async with self._write_lock:
+            await asyncio.to_thread(self._commit_staged_sync, staging)
+
+        staging.clear()
+
+    def _commit_staged_sync(self, staging: _SQLiteStagingBuffer) -> None:
+        connection = self._connect()
+        in_transaction = False
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            in_transaction = True
+
+            for (namespace, key), ops in staging.ops.items():
+                current = self._read_value_sync(connection, namespace, key)
+                result = self._apply_ops(current, ops)
+
+                if result is None:
+                    connection.execute(
+                        "DELETE FROM records WHERE namespace = ? AND key = ?",
+                        (namespace, key),
+                    )
+                else:
+                    connection.execute(
+                        """INSERT INTO records (namespace, key, value)
+                           VALUES (?, ?, ?)
+                           ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value""",
+                        (namespace, key, result),
+                    )
+
+            connection.execute("COMMIT")
+            in_transaction = False
+        except BaseException:
+            if in_transaction:
+                try:
+                    connection.execute("ROLLBACK")
+                except sqlite3.Error:
+                    pass
+            raise
+        finally:
+            connection.close()
+
+    @staticmethod
+    def _apply_ops(data: bytes | None, ops: list[_StagedOp]) -> bytes | None:
+        current = data
+        for op in ops:
+            if isinstance(op, _Write):
+                current = op.value
+            elif isinstance(op, _Delete):
+                current = None
+            elif isinstance(op, _Update):
+                current = op.fn(current)
+            else:
+                raise TypeError(f"Unknown SQLite op: {op!r}")
+        return current
+
+    # -- Read / list_keys ------------------------------------------------------
+
+    async def read(
+        self, namespace: str, key: str, *, staged: bool = True
+    ) -> bytes | None:
+        committed = await asyncio.to_thread(self._read_committed_sync, namespace, key)
+
+        if staged:
+            staging = self._current.get()
+            if staging is not None:
+                ops = staging.ops.get((namespace, key))
+                if ops:
+                    committed = self._apply_ops(committed, ops)
+
+        return committed
+
+    def _read_committed_sync(self, namespace: str, key: str) -> bytes | None:
+        connection = self._connect()
+        try:
+            return self._read_value_sync(connection, namespace, key)
+        finally:
+            connection.close()
+
+    @staticmethod
+    def _read_value_sync(
+        connection: sqlite3.Connection, namespace: str, key: str
+    ) -> bytes | None:
+        row = connection.execute(
+            "SELECT value FROM records WHERE namespace = ? AND key = ?",
+            (namespace, key),
+        ).fetchone()
+        return row[0] if row else None
+
+    async def list_keys(
+        self, namespace: str, prefix: str = "", *, staged: bool = True
+    ) -> set[str]:
+        committed = await asyncio.to_thread(
+            self._list_committed_keys_sync, namespace, prefix
+        )
+
+        if staged:
+            staging = self._current.get()
+            if staging is not None:
+                for (ns, key), ops in staging.ops.items():
+                    if ns != namespace:
+                        continue
+                    if not key.startswith(prefix):
+                        continue
+                    final = self._apply_ops(
+                        self._read_committed_sync(namespace, key),
+                        ops,
+                    )
+                    if final is None:
+                        committed.discard(key)
+                    else:
+                        committed.add(key)
+
+        return committed
+
+    def _list_committed_keys_sync(self, namespace: str, prefix: str = "") -> set[str]:
+        connection = self._connect()
+        try:
+            if prefix:
+                rows = connection.execute(
+                    "SELECT key FROM records WHERE namespace = ? AND substr(key, 1, ?) = ?",
+                    (namespace, len(prefix), prefix),
+                ).fetchall()
+            else:
+                rows = connection.execute(
+                    "SELECT key FROM records WHERE namespace = ?",
+                    (namespace,),
+                ).fetchall()
+            return {row[0] for row in rows}
+        finally:
+            connection.close()
+
+    # -- Direct SQL access (for initialization / inspection) -------------------
+
+    async def read_sql(self, sql: str, *params: Any) -> list[tuple]:
+        return await asyncio.to_thread(self._read_sql_sync, sql, params)
+
+    def _read_sql_sync(self, sql: str, params: tuple[Any, ...]) -> list[tuple]:
+        connection = self._connect()
+        try:
+            return list(connection.execute(sql, params))
+        finally:
+            connection.close()
+
+    async def execute(self, sql: str, *params: Any) -> None:
+        async with self._write_lock:
+            await asyncio.to_thread(self._execute_sync, sql, params)
+
+    def _execute_sync(self, sql: str, params: tuple[Any, ...]) -> None:
+        connection = self._connect()
+        in_transaction = False
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            in_transaction = True
+            connection.execute(sql, params)
+            connection.execute("COMMIT")
+            in_transaction = False
+        except BaseException:
+            if in_transaction:
+                try:
+                    connection.execute("ROLLBACK")
+                except sqlite3.Error:
+                    pass
+            raise
+        finally:
+            connection.close()