beaver-db 2.0rc2__py3-none-any.whl

beaver/locks.py

@@ -0,0 +1,186 @@
+import asyncio
+import random
+import time
+import os
+import uuid
+from typing import Optional, Protocol, runtime_checkable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core import AsyncBeaverDB
+
+
+@runtime_checkable
+class IBeaverLock[T: BaseModel](Protocol):
+    def acquire(
+        self,
+        timeout: float | None = None,
+        lock_ttl: float | None = None,
+        poll_interval: float | None = None,
+        block: bool = True,
+    ) -> bool: ...
+
+    def release(self) -> None: ...
+    def renew(self, lock_ttl: float | None = None) -> bool: ...
+    def clear(self) -> bool: ...
+    def __enter__(self) -> "IBeaverLock": ...
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
+
+
+class AsyncBeaverLock:
+    def __init__(
+        self,
+        db: "AsyncBeaverDB",
+        name: str,
+        timeout: Optional[float] = None,
+        lock_ttl: float = 60.0,
+        poll_interval: float = 0.1,
+    ):
+        if not isinstance(name, str) or not name:
+            raise ValueError("Lock name must be a non-empty string.")
+        self._db = db
+        self._lock_name = name
+        self._timeout = timeout
+        self._lock_ttl = lock_ttl
+        self._poll_interval = poll_interval
+        self._waiter_id = f"pid:{os.getpid()}:id:{uuid.uuid4()}"
+        self._acquired = False
+
+    async def renew(self, lock_ttl: Optional[float] = None) -> bool:
+        if not self._acquired:
+            return False
+
+        ttl = lock_ttl or self._lock_ttl
+        new_expires_at = time.time() + ttl
+
+        async with self._db.transaction():
+            cursor = await self._db.connection.execute(
+                "UPDATE __beaver_lock_waiters__ SET expires_at = ? WHERE lock_name = ? AND waiter_id = ?",
+                (new_expires_at, self._lock_name, self._waiter_id),
+            )
+            return cursor.rowcount > 0
+
+    async def clear(self) -> bool:
+        async with self._db.transaction():
+            cursor = await self._db.connection.execute(
+                "DELETE FROM __beaver_lock_waiters__ WHERE lock_name = ?",
+                (self._lock_name,),
+            )
+            count = cursor.rowcount
+
+        self._acquired = False
+        return count > 0
+
+    async def acquire(
+        self,
+        timeout: float | None = None,
+        lock_ttl: float | None = None,
+        poll_interval: float | None = None,
+        block: bool = True,
+    ) -> bool:
+        if self._acquired:
+            return True
+
+        current_timeout = timeout if timeout is not None else self._timeout
+        current_lock_ttl = lock_ttl if lock_ttl is not None else self._lock_ttl
+        current_poll_interval = (
+            poll_interval if poll_interval is not None else self._poll_interval
+        )
+
+        start_time = time.time()
+        requested_at = time.time()
+        expires_at = requested_at + current_lock_ttl
+
+        try:
+            # 1. Add self to the FIFO queue (Atomic via transaction() lock)
+            async with self._db.transaction():
+                await self._db.connection.execute(
+                    """
+                    INSERT INTO __beaver_lock_waiters__
+                    (lock_name, waiter_id, requested_at, expires_at)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (self._lock_name, self._waiter_id, requested_at, expires_at),
+                )
+
+            # 2. Start Polling Loop
+            while True:
+                async with self._db.transaction():
+                    # A. Clean up expired locks from crashed processes
+                    now = time.time()
+                    await self._db.connection.execute(
+                        "DELETE FROM __beaver_lock_waiters__ WHERE lock_name = ? AND expires_at < ?",
+                        (self._lock_name, now),
+                    )
+
+                    # B. Check who is at the front of the queue
+                    cursor = await self._db.connection.execute(
+                        """
+                        SELECT waiter_id FROM __beaver_lock_waiters__
+                        WHERE lock_name = ?
+                        ORDER BY requested_at ASC, rowid ASC
+                        LIMIT 1
+                        """,
+                        (self._lock_name,),
+                    )
+                    result = await cursor.fetchone()
+
+                    # C. Sanity Check: Ensure we are still in the queue
+                    check_self = await self._db.connection.execute(
+                        "SELECT 1 FROM __beaver_lock_waiters__ WHERE waiter_id = ?",
+                        (self._waiter_id,),
+                    )
+                    if not await check_self.fetchone():
+                        return False  # We were deleted (cleared or expired)
+
+                    if result and result["waiter_id"] == self._waiter_id:
+                        self._acquired = True
+                        return True
+
+                # 3. Check for timeout or non-blocking return
+                elapsed = time.time() - start_time
+                if current_timeout is not None and elapsed > current_timeout:
+                    await self._release_from_queue()
+                    return False
+
+                if not block:
+                    await self._release_from_queue()
+                    return False
+
+                # 4. Wait safely
+                jitter = current_poll_interval * 0.1
+                sleep_time = random.uniform(
+                    current_poll_interval - jitter, current_poll_interval + jitter
+                )
+                await asyncio.sleep(sleep_time)
+
+        except Exception:
+            await self._release_from_queue()
+            raise
+
+    async def _release_from_queue(self):
+        try:
+            async with self._db.transaction():
+                await self._db.connection.execute(
+                    "DELETE FROM __beaver_lock_waiters__ WHERE lock_name = ? AND waiter_id = ?",
+                    (self._lock_name, self._waiter_id),
+                )
+        except Exception:
+            pass
+
+    async def release(self):
+        if not self._acquired:
+            return
+
+        await self._release_from_queue()
+        self._acquired = False
+
+    async def __aenter__(self) -> "AsyncBeaverLock":
+        if await self.acquire():
+            return self
+        raise TimeoutError("Cannot acquire lock.")
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.release()
+
+    def __repr__(self) -> str:
+        return f"AsyncBeaverLock(name='{self._lock_name}', acquired={self._acquired})"

beaver/logs.py

@@ -0,0 +1,187 @@
+import asyncio
+import json
+import time
+import sqlite3
+from typing import (
+    IO,
+    Iterator,
+    AsyncIterator,
+    Protocol,
+    runtime_checkable,
+    TYPE_CHECKING,
+    NamedTuple,
+)
+
+from pydantic import BaseModel
+
+from .manager import AsyncBeaverBase, atomic, emits
+
+if TYPE_CHECKING:
+    from .core import AsyncBeaverDB
+
+
+class LogEntry[T](NamedTuple):
+    """A single log entry with timestamp and data."""
+
+    timestamp: float
+    data: T
+
+
+@runtime_checkable
+class IBeaverLog[T: BaseModel](Protocol):
+    """
+    The Synchronous Protocol exposed to the user via BeaverBridge.
+    """
+
+    def log(self, data: T, timestamp: float | None = None) -> None: ...
+    def range(
+        self,
+        start: float | None = None,
+        end: float | None = None,
+        limit: int | None = None,
+    ) -> list[LogEntry[T]]: ...
+
+    def live(self, poll_interval: float = 0.1) -> Iterator[LogEntry[T]]: ...
+
+    def clear(self) -> None: ...
+    def count(self) -> int: ...
+    def dump(self, fp: IO[str] | None = None) -> dict | None: ...
+
+
+class AsyncBeaverLog[T: BaseModel](AsyncBeaverBase[T]):
+    """
+    A wrapper providing a Pythonic interface to a time-indexed log.
+    Refactored for Async-First architecture (v2.0).
+    """
+
+    @emits("log", payload=lambda data, *args, **kwargs: dict(data=data))
+    @atomic
+    async def log(self, data: T, timestamp: float | None = None):
+        """
+        Appends an entry to the log.
+        Ensures timestamp uniqueness (PK constraint) by micro-incrementing on collision.
+        """
+        ts = timestamp or time.time()
+        serialized_data = self._serialize(data)
+
+        # Retry loop to handle PK collisions (same microsecond)
+        while True:
+            try:
+                await self.connection.execute(
+                    "INSERT INTO __beaver_logs__ (log_name, timestamp, data) VALUES (?, ?, ?)",
+                    (self._name, ts, serialized_data),
+                )
+                break
+            except sqlite3.IntegrityError:
+                # Collision detected: shift by 1 microsecond and retry
+                ts += 0.000001
+
+    async def range(
+        self,
+        start: float | None = None,
+        end: float | None = None,
+        limit: int | None = None,
+    ) -> list[LogEntry[T]]:
+        """
+        Retrieves a list of log entries within a time range.
+        """
+        query = "SELECT timestamp, data FROM __beaver_logs__ WHERE log_name = ?"
+        params = [self._name]
+
+        if start is not None:
+            query += " AND timestamp >= ?"
+            params.append(start)
+
+        if end is not None:
+            query += " AND timestamp <= ?"
+            params.append(end)
+
+        query += " ORDER BY timestamp ASC"
+
+        if limit is not None:
+            query += " LIMIT ?"
+            params.append(limit)
+
+        cursor = await self.connection.execute(query, tuple(params))
+        rows = await cursor.fetchall()
+
+        return [
+            LogEntry(timestamp=row["timestamp"], data=self._deserialize(row["data"]))
+            for row in rows
+        ]
+
+    async def live(self, poll_interval: float = 0.1) -> AsyncIterator[LogEntry[T]]:
+        """
+        Yields new log entries as they are added in real-time.
+        This is an infinite async generator.
+        """
+        # Start trailing from "now"
+        last_ts = time.time()
+
+        while True:
+            # Poll for new items since last_ts
+            cursor = await self.connection.execute(
+                """
+                SELECT timestamp, data FROM __beaver_logs__
+                WHERE log_name = ? AND timestamp > ?
+                ORDER BY timestamp ASC
+                """,
+                (self._name, last_ts),
+            )
+            rows = await cursor.fetchall()
+
+            if rows:
+                last_ts = rows[-1]["timestamp"]
+                for row in rows:
+                    yield LogEntry(
+                        timestamp=row["timestamp"], data=self._deserialize(row["data"])
+                    )
+
+            # Non-blocking sleep yields control to the event loop
+            await asyncio.sleep(poll_interval)
+
+    async def count(self) -> int:
+        """Returns the total number of entries in the log."""
+        cursor = await self.connection.execute(
+            "SELECT COUNT(*) FROM __beaver_logs__ WHERE log_name = ?", (self._name,)
+        )
+        row = await cursor.fetchone()
+        return row[0] if row else 0
+
+    @emits("clear", payload=lambda *args, **kwargs: dict())
+    @atomic
+    async def clear(self):
+        """Clears all entries in this log."""
+        await self.connection.execute(
+            "DELETE FROM __beaver_logs__ WHERE log_name = ?", (self._name,)
+        )
+
+    async def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire log to a JSON-compatible object.
+        """
+        # Retrieve all items
+        entries = await self.range()
+
+        items_list = []
+        for entry in entries:
+            val = entry.data
+            if self._model and isinstance(val, BaseModel):
+                val = json.loads(val.model_dump_json())
+
+            items_list.append({"timestamp": entry.timestamp, "data": val})
+
+        dump_obj = {
+            "metadata": {
+                "type": "Log",
+                "name": self._name,
+                "count": len(items_list),
+            },
+            "items": items_list,
+        }
+
+        if fp:
+            json.dump(dump_obj, fp, indent=2)
+            return None
+
+        return dump_obj

beaver/manager.py

@@ -0,0 +1,203 @@
+import json
+import functools
+import weakref
+from typing import Callable, Type, Optional, Self, Any, TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from .locks import AsyncBeaverLock
+
+# Forward reference for type checking to avoid circular imports
+if TYPE_CHECKING:
+    from .core import AsyncBeaverDB
+    from .cache import ICache
+    from .events import AsyncBeaverEvents, EventHandler
+
+
+class AsyncBeaverBase[T: BaseModel]:
+    """
+    Base class for async data managers.
+    Handles serialization, locking, and basic connection access.
+    """
+
+    def __init__(self, name: str, db: "AsyncBeaverDB", model: Type[T] | None = None):
+        """
+        Initializes the base manager.
+        """
+        # Automatically determine the prefix from the child class name
+        cls_name = self.__class__.__name__
+        manager_type_prefix = cls_name.replace("AsyncBeaver", "").lower()
+
+        if not isinstance(name, str) or not name:
+            raise TypeError(
+                f"{manager_type_prefix.capitalize()} name must be a non-empty string."
+            )
+
+        self._name = name
+        self._db = db
+        self._model = model
+        self._topic = f"{manager_type_prefix}:{self._name}"
+
+        # Lazy-loaded event manager
+        self._event_manager: "AsyncBeaverEvents | None" = None
+
+        # Public lock for batch operations
+        public_lock_name = f"__lock__{manager_type_prefix}__{name}"
+        self._lock = AsyncBeaverLock(db, public_lock_name)
+
+        # Internal lock for atomic methods
+        internal_lock_name = f"__internal_lock__{manager_type_prefix}__{name}"
+        self._internal_lock = AsyncBeaverLock(
+            db,
+            internal_lock_name,
+            timeout=5.0,  # Short timeout for internal operations
+            lock_ttl=5.0,  # Short TTL to clear crashes
+        )
+
+    @property
+    def locked(self) -> bool:
+        """Returns whether the current manager is locked by this process."""
+        return self._lock._acquired
+
+    @property
+    def connection(self) -> Any:
+        """Returns the shared async connection."""
+        return self._db.connection
+
+    @property
+    def cache(self) -> "ICache":
+        """Returns the thread-local cache for this manager (Stub)."""
+        return self._db.cache(self._topic)
+
+    @property
+    def events(self) -> "AsyncBeaverEvents":
+        """
+        Returns the Event Manager attached to this data structure.
+        Lazy-loaded to avoid circular imports during init.
+        """
+        if self._event_manager is None:
+            # Import here to avoid circular dependency loop
+            from .events import AsyncBeaverEvents
+
+            # We create an event manager scoped to this manager's unique topic name
+            # This ensures events like "set" are unique to THIS dictionary instance.
+            # We use the same model T so event payloads are typed correctly if applicable.
+            self._event_manager = AsyncBeaverEvents(
+                name=self._topic, db=self._db, model=self._model
+            )
+
+        return self._event_manager
+
+    def _serialize(self, value: T) -> str:
+        """Serializes the given value to a JSON string (Sync CPU bound)."""
+        if isinstance(value, BaseModel):
+            return value.model_dump_json()
+        return json.dumps(value)
+
+    def _deserialize(self, value: str) -> T:
+        """Deserializes a JSON string (Sync CPU bound)."""
+        if self._model:
+            return self._model.model_validate_json(value)
+        return json.loads(value)
+
+    # --- Public Lock Interface ---
+
+    async def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        block: bool = True,
+    ) -> bool:
+        """Acquires the public inter-process lock on this manager."""
+        return await self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval,
+            block=block,
+        )
+
+    async def release(self):
+        """Releases the public inter-process lock on this manager."""
+        await self._lock.release()
+
+    async def renew(self, lock_ttl: Optional[float] = None) -> bool:
+        """Renews the TTL (heartbeat) of the public lock."""
+        return await self._lock.renew(lock_ttl)
+
+    async def __aenter__(self) -> Self:
+        """Async Context Manager for public locking."""
+        if await self.acquire():
+            return self
+        raise TimeoutError(f"Failed to acquire public lock for '{self._name}'")
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.release()
+
+    # --- Events Portal ---
+
+    async def on(self, event: str, callback: Callable) -> "EventHandler":
+        """
+        Subscribes to an event on this manager (e.g. "set", "push").
+        This is a convenience wrapper around self.events.attach().
+        """
+        return await self.events.attach(event, callback)
+
+    async def off(self, event: str, callback: Callable):
+        """
+        Unsubscribes from an event.
+        Convenience wrapper around self.events.detach().
+        """
+        await self.events.detach(event, callback)
+
+
+def atomic(func):
+    """
+    A decorator to wrap a manager method in the manager's *internal* lock
+    AND a database transaction.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(self: AsyncBeaverBase, *args, **kwargs):
+        async with self._internal_lock:
+            async with self._db.transaction():
+                return await func(self, *args, **kwargs)
+
+    return wrapper
+
+
+def emits(event: str | None = None, payload: Callable | None = None):
+    """
+    A decorator to emit an event after a manager method completes.
+    Uses the manager's attached Event Bus.
+    """
+
+    def decorator(func):
+        event_name = event or func.__name__
+        payload_func = payload or (lambda *args, **kwargs: dict(args=args, **kwargs))
+
+        @functools.wraps(func)
+        async def wrapper(self: AsyncBeaverBase, *args, **kwargs):
+            # Calculate payload BEFORE mutation (to capture args)
+            # or AFTER? Usually we want the *result* or the *input*.
+            # The current lambda often uses args.
+
+            # Execute the actual async operation
+            result = await func(self, *args, **kwargs)
+
+            # PERFORMANCE FIX: Only emit if the event manager has been initialized.
+            # This prevents starting the background polling loop for every manager
+            # unless the user has explicitly attached a listener (which inits the manager).
+            if self._event_manager is not None:
+                try:
+                    payload_data = payload_func(*args, **kwargs)
+                    # We await it to ensure the event is persisted to the log before returning
+                    await self._event_manager.emit(event_name, payload_data)
+                except Exception:
+                    pass
+
+            return result
+
+        return wrapper
+
+    return decorator

beaver/queries.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+from typing import Any, cast, overload
+
+
+@dataclass
+class Filter:
+    path: str
+    operator: str
+    value: Any
+
+
+class Query[T]:
+    def __init__(self, model: type[T] | None = None, path: str = "") -> None:
+        self._model = model
+        self._path = path
+
+    def __getattr__(self, name: str):
+        new_path = f"{self._path}.{name}" if self._path else name
+        return Query(self._model, new_path)
+
+    # --- Standard Operators ---
+
+    def __eq__(self, other) -> Filter:  # type: ignore
+        return Filter(self._path, "==", other)
+
+    def __ne__(self, other) -> Filter:  # type: ignore
+        return Filter(self._path, "!=", other)
+
+    # --- Arithmetic Operators
+
+    def __gt__(self, other) -> Filter:
+        return Filter(self._path, ">", other)
+
+    def __ge__(self, other) -> Filter:
+        return Filter(self._path, ">=", other)
+
+    def __lt__(self, other) -> Filter:
+        return Filter(self._path, "<", other)
+
+    def __le__(self, other) -> Filter:
+        return Filter(self._path, "<=", other)
+
+
+@overload
+def q[T](model_or_path: type[T]) -> T:
+    pass
+
+
+@overload
+def q(model_or_path: str) -> Query:
+    pass
+
+
+@overload
+def q() -> Query:
+    pass
+
+
+def q(model_or_path: type | str | None = None) -> Any:
+    if isinstance(model_or_path, type):
+        return Query(model=model_or_path)
+
+    if isinstance(model_or_path, str):
+        return Query(path=model_or_path)
+
+    return Query()