voodoo-framework 1.2.0__tar.gz → 1.3.0__tar.gz

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 1.2.0
+Version: 1.3.0
 Summary: Voodoo Framework
 Requires-Python: >=3.12
 Requires-Dist: starlette

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/src/voodoo/__init__.py

@@ -76,7 +76,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     # Core runtime

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/src/voodoo/data/__init__.py

@@ -6,10 +6,13 @@ This package re-exports the names that previously lived in the flat
 
 Storage backend boundary
 -------------------------
-The default backend is SQLite (via :mod:`aiosqlite`).  The functions
-``init_db`` and ``get_db`` together with the module-level ``_db_connection``
-form the seam a future PostgreSQL adapter would replace; everything above
-them (``BaseModel``, ``Model`` and the hooks) is backend-agnostic.
+The default backend is SQLite (via :mod:`aiosqlite`) managed by the
+``VoodooDatabase`` adapter in :mod:`voodoo.storage.database` — it owns
+connection lifecycle, WAL pragmas and the ``schema_migrations`` ledger.
+``init_db`` publishes the raw aiosqlite connection as
+``_db_connection`` / ``get_db()``; everything above it (``BaseModel``,
+``Model`` and the hooks) is backend-agnostic.  A future PostgreSQL
+adapter replaces the adapter, not this package.
 """
 
 from voodoo.data.base import (

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/src/voodoo/data/base.py

@@ -1,30 +1,52 @@
 import asyncio
-import os
 from collections.abc import Callable
 from typing import Any, get_type_hints
 
-import aiosqlite
+from voodoo.storage.database import Migration, SQLiteDatabase, VoodooDatabase
 
 _db_connection = None
 _triggers: dict[str, dict[str, list[Callable]]] = {}
 _rls_policies: dict[str, Callable] = {}
 
 
+async def _ensure_user_tables(db: VoodooDatabase) -> None:
+    """Create tables for every registered user model (idempotent DDL)."""
+    for model in _models:
+        await model._create_table()
+
+
+# Migration 0001: the user-model baseline. Runs once to enter the ledger,
+# then re-runs its idempotent DDL on every ``init_db`` so models imported
+# after the baseline still get their tables (preserves pre-migration
+# behavior exactly).
+USER_MODEL_BASELINE = Migration(
+    version=1,
+    name="user_model_baseline",
+    fn=_ensure_user_tables,
+    rerun=True,
+)
+
+
 async def init_db(db_path: str = None):
+    """Open (and migrate) the SQLite database backing the data layer.
+
+    The raw :class:`aiosqlite.Connection` remains the value of
+    ``_db_connection`` / ``get_db()`` so all existing callers keep working;
+    schema management now flows through the ``SQLiteDatabase`` adapter and
+    its migration ledger.
+    """
     if db_path is None:
         from voodoo.config import config
 
         db_path = config.db_path
 
-    db_dir = os.path.dirname(db_path)
-    if db_dir:
-        os.makedirs(db_dir, exist_ok=True)
-
     global _db_connection
-    _db_connection = await aiosqlite.connect(db_path)
-    _db_connection.row_factory = aiosqlite.Row
-    for model in _models:
-        await model._create_table()
+    database = SQLiteDatabase(db_path, migrations=(USER_MODEL_BASELINE,))
+    await database.connect()
+    _db_connection = database.connection
+    # Migrate after the connection is published so rerunnable migration
+    # functions can use ``get_db()``.
+    await database.migrate()
 
 
 async def get_db():

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/src/voodoo/data/model.py

@@ -8,13 +8,11 @@ storage layer and the ``on_insert`` / ``on_update`` hook system from
 Storage backend boundary
 -------------------------
 Everything in this module talks to the database through ``get_db()``
-and builds portable ANSI-SQL strings.  Swapping SQLite for PostgreSQL
-(or another backend) only requires replacing the connection function
-and the DDL generated by ``BaseModel._create_table``; the facade stays
-the same.  Migrations are an explicit extension point: today the only
-DDL emitted is ``CREATE TABLE IF NOT EXISTS`` (create-if-absent).  A
-future migration runner can hook into ``init_db`` without changing any
-call-site here.
+and builds portable ANSI-SQL strings.  Schema management flows through
+the ``VoodooDatabase`` adapter in :mod:`voodoo.storage.database`
+(SQLite default); the user-model DDL is migration 0001 in its ledger.
+Swapping backends means providing another adapter — no call-site here
+changes.
 """
 
 from typing import Any, get_type_hints

voodoo_framework-1.3.0/src/voodoo/storage/__init__.py

@@ -0,0 +1,15 @@
+"""Voodoo storage package.
+
+Two concerns live here:
+
+- ``voodoo.storage.manager`` — the legacy ``StorageManager`` facade over
+  local-filesystem / S3-compatible uploads (import-compatible re-export of
+  the former flat ``voodoo/storage.py`` module).
+- ``voodoo.storage.database`` — the ``VoodooDatabase`` capability adapters
+  (SQLite default, PostgreSQL later) that own all durable schema through
+  the migration runner.
+"""
+
+from voodoo.storage.manager import StorageManager, storage
+
+__all__ = ["StorageManager", "storage"]

voodoo_framework-1.3.0/src/voodoo/storage/database/__init__.py

@@ -0,0 +1,27 @@
+"""Voodoo database adapters (spec §11).
+
+SQLite is the embedded default; PostgreSQL arrives behind the same
+``VoodooDatabase`` protocol as an optional extra. Migrations form one global
+version namespace: 1 = user-model baseline (registered by ``voodoo.data``),
+2+ reserved by the framework, 100+ available to applications.
+"""
+
+from voodoo.storage.database.interfaces import (
+    DatabaseCapabilities,
+    Migration,
+    VoodooDatabase,
+)
+from voodoo.storage.database.sqlite import (
+    FRAMEWORK_MIGRATIONS,
+    LEDGER_TABLE,
+    SQLiteDatabase,
+)
+
+__all__ = [
+    "DatabaseCapabilities",
+    "FRAMEWORK_MIGRATIONS",
+    "LEDGER_TABLE",
+    "Migration",
+    "SQLiteDatabase",
+    "VoodooDatabase",
+]

voodoo_framework-1.3.0/src/voodoo/storage/database/interfaces.py

@@ -0,0 +1,80 @@
+"""Voodoo database capability interface.
+
+Every durable Voodoo subsystem (state, executions, tasks, events, schedules)
+persists through a ``VoodooDatabase`` implementation. SQLite is the default
+embedded backend (spec §11); PostgreSQL arrives later as an optional adapter
+behind the same protocol.
+
+Application code must never import ``aiosqlite``/``psycopg`` directly — the
+adapter boundary lives here (spec §2).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class DatabaseCapabilities:
+    """Declarative contract of what a database adapter guarantees (spec §9)."""
+
+    provider: str
+    transactions: bool = True
+    migrations: bool = True
+    native_json: bool = False
+    concurrent_writers: bool = False
+
+
+@dataclass(frozen=True)
+class Migration:
+    """One ordered, tracked schema change.
+
+    Version numbering is a single global namespace shared by the framework
+    and the application: version 1 is the user-model baseline, the framework
+    reserves 2+, applications may use 100+.
+
+    ``fn`` receives the ``VoodooDatabase`` instance, keeping migrations
+    backend-neutral. ``rerun=True`` steps re-execute ``fn`` on every
+    ``migrate()`` call (idempotent DDL only) so items registered after the
+    baseline — e.g. models imported later — still get their tables.
+    """
+
+    version: int
+    name: str
+    statements: tuple[str, ...] = ()
+    fn: Callable[[VoodooDatabase], Awaitable[None]] | None = None
+    rerun: bool = False
+
+
+class VoodooDatabase(Protocol):
+    """Backend-neutral database capability.
+
+    Implementations provide: connection lifecycle, an ordered idempotent
+    migration runner backed by a ledger table, a transaction helper, and
+    query primitives. ``connect()`` intentionally does not migrate — callers
+    control when schema changes apply.
+    """
+
+    provider: str
+
+    async def connect(self) -> None: ...
+
+    async def close(self) -> None: ...
+
+    async def migrate(self) -> None: ...
+
+    def current_version(self) -> int: ...
+
+    def capabilities(self) -> DatabaseCapabilities: ...
+
+    @asynccontextmanager
+    def transaction(self) -> AsyncIterator[Any]: ...
+
+    async def execute(self, query: str, params: Sequence[Any] = ()) -> Any: ...
+
+    async def fetch_all(self, query: str, params: Sequence[Any] = ()) -> list[Any]: ...
+
+    async def fetch_one(self, query: str, params: Sequence[Any] = ()) -> Any | None: ...

voodoo_framework-1.3.0/src/voodoo/storage/database/sqlite.py

@@ -0,0 +1,174 @@
+"""SQLite implementation of the Voodoo database capability.
+
+The local source of truth (spec §11): WAL journaling for file-backed
+databases, ordered idempotent migrations tracked in ``schema_migrations``,
+and commit/rollback transaction semantics. Every SQLite-backed runtime
+subsystem persists through this adapter — never through aiosqlite directly.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+import aiosqlite
+
+from voodoo.storage.database.interfaces import (
+    DatabaseCapabilities,
+    Migration,
+    VoodooDatabase,
+)
+
+LEDGER_TABLE = "schema_migrations"
+
+# Framework-owned schema changes. Version 1 is the user-model baseline
+# registered by ``voodoo.data``; the framework reserves 2+ (tasks table,
+# executions journal, schedules, … arrive in later sprints).
+FRAMEWORK_MIGRATIONS: tuple[Migration, ...] = ()
+
+
+class SQLiteDatabase:
+    """Embedded SQLite backend — the default Voodoo database."""
+
+    provider = "sqlite"
+
+    def __init__(self, path: str, migrations: Sequence[Migration] = ()) -> None:
+        self.path = path
+        self._extra_migrations = tuple(migrations)
+        self._migrations = self._merge_migrations()
+        self._conn: aiosqlite.Connection | None = None
+        self._version = 0
+
+    def _merge_migrations(self) -> tuple[Migration, ...]:
+        by_version: dict[int, Migration] = {}
+        for migration in (*FRAMEWORK_MIGRATIONS, *self._extra_migrations):
+            if migration.version in by_version:
+                raise ValueError(
+                    f"duplicate migration version {migration.version} "
+                    f"({by_version[migration.version].name!r} vs {migration.name!r})"
+                )
+            by_version[migration.version] = migration
+        return tuple(by_version[v] for v in sorted(by_version))
+
+    @property
+    def connection(self) -> aiosqlite.Connection:
+        if self._conn is None:
+            raise RuntimeError(
+                f"sqlite database at {self.path!r} is not connected; "
+                "call connect() first"
+            )
+        return self._conn
+
+    # -- lifecycle -----------------------------------------------------------
+
+    async def connect(self) -> None:
+        if self._conn is not None:
+            return
+        db_dir = os.path.dirname(self.path)
+        if db_dir:
+            os.makedirs(db_dir, exist_ok=True)
+        self._conn = await aiosqlite.connect(self.path)
+        self._conn.row_factory = aiosqlite.Row
+        # Durability/concurrency pragmas. WAL is a no-op on :memory:.
+        await self._conn.execute("PRAGMA journal_mode=WAL")
+        await self._conn.execute("PRAGMA busy_timeout=5000")
+        await self._conn.commit()
+
+    async def close(self) -> None:
+        """Close the connection if open. No-op otherwise (keeps startup lazy).
+
+        aiosqlite runs each connection on a dedicated non-daemon thread; an
+        unclosed connection would keep the interpreter alive at shutdown.
+        """
+        if self._conn is not None:
+            try:
+                await self._conn.close()
+            finally:
+                self._conn = None
+
+    # -- migrations ----------------------------------------------------------
+
+    async def migrate(self) -> None:
+        conn = self.connection
+        await conn.execute(
+            f"CREATE TABLE IF NOT EXISTS {LEDGER_TABLE} ("
+            "version INTEGER PRIMARY KEY,"
+            "name TEXT NOT NULL,"
+            "applied_at TEXT NOT NULL DEFAULT (datetime('now')))"
+        )
+        await conn.commit()
+
+        applied = {
+            row["version"]
+            for row in await self.fetch_all(f"SELECT version FROM {LEDGER_TABLE}")
+        }
+        for migration in self._migrations:
+            if migration.version not in applied:
+                async with self.transaction():
+                    for statement in migration.statements:
+                        await conn.execute(statement)
+                    if migration.fn is not None:
+                        await migration.fn(self)
+                    await conn.execute(
+                        f"INSERT INTO {LEDGER_TABLE} (version, name) VALUES (?, ?)",
+                        (migration.version, migration.name),
+                    )
+                self._version = migration.version
+            elif migration.rerun and migration.fn is not None:
+                # Idempotent re-runnable step: keep late-registered items
+                # (e.g. models imported after the baseline) working.
+                await migration.fn(self)
+
+    def current_version(self) -> int:
+        return self._version
+
+    # -- queries -------------------------------------------------------------
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[aiosqlite.Connection]:
+        """Run a block atomically: commit on success, rollback on error.
+
+        Yields the raw connection so callers compose arbitrary statements;
+        aiosqlite opens the implicit transaction on first DML.
+        """
+        conn = self.connection
+        try:
+            yield conn
+        except BaseException:
+            await conn.rollback()
+            raise
+        await conn.commit()
+
+    async def execute(self, query: str, params: Sequence[Any] = ()) -> aiosqlite.Cursor:
+        cursor = await self.connection.execute(query, params)
+        await self.connection.commit()
+        return cursor
+
+    async def fetch_all(
+        self, query: str, params: Sequence[Any] = ()
+    ) -> list[aiosqlite.Row]:
+        async with self.connection.execute(query, params) as cursor:
+            return list(await cursor.fetchall())
+
+    async def fetch_one(
+        self, query: str, params: Sequence[Any] = ()
+    ) -> aiosqlite.Row | None:
+        async with self.connection.execute(query, params) as cursor:
+            return await cursor.fetchone()
+
+    def capabilities(self) -> DatabaseCapabilities:
+        return DatabaseCapabilities(
+            provider=self.provider,
+            transactions=True,
+            migrations=True,
+            native_json=False,  # JSON persisted as TEXT
+            concurrent_writers=False,  # single writer at a time (WAL readers ok)
+        )
+
+
+if TYPE_CHECKING:
+    # Structural conformance assertion — mypy errors here if the adapter
+    # drifts from the VoodooDatabase protocol.
+    _protocol_check: VoodooDatabase = SQLiteDatabase("check")

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/src/voodoo_framework.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 1.2.0
+Version: 1.3.0
 Summary: Voodoo Framework
 Requires-Python: >=3.12
 Requires-Dist: starlette

{voodoo_framework-1.2.0 → voodoo_framework-1.3.0}/src/voodoo_framework.egg-info/SOURCES.txt

@@ -10,7 +10,6 @@ src/voodoo/py.typed
 src/voodoo/queue.py
 src/voodoo/seo.py
 src/voodoo/status.py
-src/voodoo/storage.py
 src/voodoo/theme.py
 src/voodoo/adapters/__init__.py
 src/voodoo/adapters/tailwind.py
@@ -93,6 +92,11 @@ src/voodoo/security/headers.py
 src/voodoo/security/passwords.py
 src/voodoo/security/rate_limit.py
 src/voodoo/static/client.js
+src/voodoo/storage/__init__.py
+src/voodoo/storage/manager.py
+src/voodoo/storage/database/__init__.py
+src/voodoo/storage/database/interfaces.py
+src/voodoo/storage/database/sqlite.py
 src/voodoo/telemetry/__init__.py
 src/voodoo/telemetry/api.py
 src/voodoo/telemetry/middleware.py