beaver-db 2.0rc2__py3-none-any.whl

beaver/__init__.py

@@ -0,0 +1,16 @@
+from .core import BeaverDB, AsyncBeaverDB
+from .docs import Document
+from .events import Event
+from .queries import q
+from .security import Secret
+
+__version__ = "2.0rc2"
+
+__all__ = [
+    "AsyncBeaverDB",
+    "BeaverDB",
+    "Document",
+    "Secret",
+    "Event",
+    "q",
+]

beaver/blobs.py

@@ -0,0 +1,223 @@
+from base64 import b64encode
+import json
+from typing import (
+    IO,
+    Any,
+    Iterator,
+    Tuple,
+    Protocol,
+    runtime_checkable,
+    TYPE_CHECKING,
+    overload,
+)
+
+from pydantic import BaseModel
+
+from .manager import AsyncBeaverBase, atomic, emits
+
+if TYPE_CHECKING:
+    from .core import AsyncBeaverDB
+
+
+class BlobItem(BaseModel):
+    """Represents a retrieved blob with its metadata."""
+
+    key: str
+    data: bytes
+    metadata: dict | None = None
+
+
+@runtime_checkable
+class IBeaverBlob[T: BaseModel](Protocol):
+    """
+    The Synchronous Protocol exposed to the user via BeaverBridge.
+    """
+
+    def __getitem__(self, key: str) -> bytes: ...
+    def __setitem__(self, key: str, data: bytes) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+    def __len__(self) -> int: ...
+    def __contains__(self, key: str) -> bool: ...
+    def __iter__(self) -> Iterator[str]: ...
+
+    def get(self, key: str) -> bytes: ...
+    def set(self, key: str, data: bytes) -> None: ...
+    def delete(self, key: str) -> None: ...
+
+    def put(self, key: str, data: bytes, metadata: dict | None = None) -> None: ...
+    def fetch(self, key: str) -> BlobItem: ...
+    def count(self) -> int: ...
+    def keys(self) -> Iterator[str]: ...
+    def items(self) -> Iterator[Tuple[str, bytes]]: ...
+    def clear(self) -> None: ...
+    def dump(self, fp: IO[str] | None = None) -> dict | None: ...
+
+
+class AsyncBeaverBlob[T: BaseModel](AsyncBeaverBase[T]):
+    """
+    A wrapper providing a dictionary-like interface for storing binary blobs
+    with optional metadata.
+    Refactored for Async-First architecture (v2.0).
+    """
+
+    @emits("put", payload=lambda key, *args, **kwargs: dict(key=key))
+    @atomic
+    async def put(self, key: str, data: bytes, metadata: dict | None = None):
+        """
+        Stores binary data under a key, optionally with JSON metadata.
+        """
+        if not isinstance(data, bytes):
+            raise TypeError("Blob data must be bytes.")
+
+        meta_json = json.dumps(metadata) if metadata is not None else None
+
+        await self.connection.execute(
+            """
+            INSERT OR REPLACE INTO __beaver_blobs__
+            (store_name, key, data, metadata)
+            VALUES (?, ?, ?, ?)
+            """,
+            (self._name, key, data, meta_json),
+        )
+
+    @atomic
+    async def fetch(self, key: str) -> BlobItem:
+        """
+        Retrieves the full BlobItem (data + metadata).
+        Raises KeyError if missing.
+        """
+        cursor = await self.connection.execute(
+            "SELECT data, metadata FROM __beaver_blobs__ WHERE store_name = ? AND key = ?",
+            (self._name, key),
+        )
+        row = await cursor.fetchone()
+
+        if row is None:
+            raise KeyError(f"Key '{key}' not found in blob store '{self._name}'")
+
+        meta = json.loads(row["metadata"]) if row["metadata"] else None
+        return BlobItem(key=key, data=row["data"], metadata=meta)
+
+    @atomic
+    async def get(self, key: str) -> bytes:
+        """
+        Retrieves just the binary data for a key.
+        Mapped from __getitem__ via the Bridge.
+        """
+        cursor = await self.connection.execute(
+            "SELECT data FROM __beaver_blobs__ WHERE store_name = ? AND key = ?",
+            (self._name, key),
+        )
+        row = await cursor.fetchone()
+
+        if row is None:
+            raise KeyError(f"Key '{key}' not found in blob store '{self._name}'")
+
+        return row["data"]
+
+    @emits("set", payload=lambda key, *args, **kwargs: dict(key=key))
+    @atomic
+    async def set(self, key: str, data: bytes):
+        """
+        Alias for put(key, data) without metadata.
+        Mapped from __setitem__ via the Bridge.
+        """
+        await self.put(key, data)
+
+    @emits("del", payload=lambda key, *args, **kwargs: dict(key=key))
+    @atomic
+    async def delete(self, key: str):
+        """
+        Deletes a blob.
+        Mapped from __delitem__ via the Bridge.
+        """
+        cursor = await self.connection.execute(
+            "DELETE FROM __beaver_blobs__ WHERE store_name = ? AND key = ?",
+            (self._name, key),
+        )
+        if cursor.rowcount == 0:
+            raise KeyError(f"Key '{key}' not found in blob store '{self._name}'")
+
+    async def count(self) -> int:
+        cursor = await self.connection.execute(
+            "SELECT COUNT(*) FROM __beaver_blobs__ WHERE store_name = ?", (self._name,)
+        )
+        row = await cursor.fetchone()
+        return row[0] if row else 0
+
+    async def contains(self, key: str) -> bool:
+        cursor = await self.connection.execute(
+            "SELECT 1 FROM __beaver_blobs__ WHERE store_name = ? AND key = ? LIMIT 1",
+            (self._name, key),
+        )
+        return await cursor.fetchone() is not None
+
+    @emits("clear", payload=lambda *args, **kwargs: dict())
+    @atomic
+    async def clear(self):
+        await self.connection.execute(
+            "DELETE FROM __beaver_blobs__ WHERE store_name = ?",
+            (self._name,),
+        )
+
+    # --- Iterators ---
+
+    async def __aiter__(self):
+        async for key in self.keys():
+            yield key
+
+    async def keys(self):
+        cursor = await self.connection.execute(
+            "SELECT key FROM __beaver_blobs__ WHERE store_name = ?", (self._name,)
+        )
+        async for row in cursor:
+            yield row["key"]
+
+    async def items(self):
+        cursor = await self.connection.execute(
+            "SELECT key, data FROM __beaver_blobs__ WHERE store_name = ?", (self._name,)
+        )
+        async for row in cursor:
+            yield (row["key"], row["data"])
+
+    async def dump(
+        self, fp: IO[str] | None = None, *, payload: bool = False
+    ) -> dict | None:
+        """
+        Dumps blobs to a JSON-compatible object.
+        Note: Binary data is serialized to base-64 strings, *only* when payload=True.
+        Otherwise, only metadata is dumped.
+        """
+        items = []
+        async for key in self.keys():
+            # For blobs, dumping full content to JSON is dangerous (memory).
+            # We dump metadata primarily.
+            try:
+                item = await self.fetch(key)
+                items.append(
+                    {
+                        "key": key,
+                        "metadata": item.metadata,
+                        "size": len(item.data),
+                        "payload": (
+                            b64encode(item.data).decode("utf-8") if payload else None
+                        ),
+                    }
+                )
+            except KeyError:
+                continue
+
+        dump_obj = {
+            "metadata": {
+                "type": "BlobStore",
+                "name": self._name,
+                "count": len(items),
+            },
+            "items": items,
+        }
+
+        if fp:
+            json.dump(dump_obj, fp, indent=2)
+            return None
+
+        return dump_obj

beaver/bridge.py

@@ -0,0 +1,167 @@
+import asyncio
+import inspect
+from typing import Any, Iterator, AsyncIterator
+
+
+class _SyncIteratorBridge:
+    """
+    Helper class that wraps an AsyncIterator (or AsyncGenerator)
+    and exposes it as a standard synchronous Iterator.
+    """
+
+    def __init__(self, async_iter: AsyncIterator, loop: asyncio.AbstractEventLoop):
+        self._async_iter = async_iter
+        self._loop = loop
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        # Define a coroutine to fetch the next item safely on the background loop
+        async def step():
+            try:
+                # Use the builtin anext() (Python 3.10+)
+                return await anext(self._async_iter)
+            except StopAsyncIteration:
+                # Raise a special sentinel to signal the loop to stop
+                return StopAsyncIteration
+
+        # Run the step on the reactor thread
+        future = asyncio.run_coroutine_threadsafe(step(), self._loop)
+        result = future.result()
+
+        # Propagate the stop signal as a synchronous StopIteration
+        if result is StopAsyncIteration:
+            raise StopIteration
+
+        return result
+
+
+class BeaverBridge:
+    """
+    A generic synchronous bridge that proxies access to an asynchronous object
+    running on a background asyncio loop.
+
+    This class enables the "Portal Pattern", allowing standard synchronous
+    Python code to interact with the Async-First core of BeaverDB safely.
+    """
+
+    def __init__(self, async_obj: Any, loop: asyncio.AbstractEventLoop):
+        self._async_obj = async_obj
+        self._loop = loop
+
+    def _run(self, coro: Any) -> Any:
+        """
+        Helper to run a coroutine on the background loop and block
+        the calling thread until the result is ready.
+        """
+        if not inspect.iscoroutine(coro):
+            return coro
+
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        return future.result()
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Dynamically intercepts method calls and properties.
+        """
+        try:
+            attr = getattr(self._async_obj, name)
+        except AttributeError:
+            raise AttributeError(
+                f"'{type(self._async_obj).__name__}' object has no attribute '{name}'"
+            )
+
+        # If it is a method, wrap it to handle Coroutines AND AsyncGenerators
+        if inspect.ismethod(attr) or inspect.isfunction(attr):
+
+            def wrapper(*args, **kwargs):
+                # 1. Call the method (this is fast/non-blocking for async defs)
+                result = attr(*args, **kwargs)
+
+                # 2. Check if it returned an Async Generator (e.g. .keys(), .live())
+                if inspect.isasyncgen(result):
+                    return _SyncIteratorBridge(result, self._loop)
+
+                # 3. Otherwise, run it (handles coroutines or regular values)
+                return self._run(result)
+
+            return wrapper
+
+        return attr
+
+    def __repr__(self) -> str:
+        async def safe_repr():
+            return repr(self._async_obj)
+
+        try:
+            return self._run(safe_repr())
+        except Exception:
+            return f"<BeaverBridge wrapping {type(self._async_obj).__name__}>"
+
+    # --- Context Manager ---
+
+    def __enter__(self):
+        if not hasattr(self._async_obj, "__aenter__"):
+            raise TypeError(
+                f"Object of type {type(self._async_obj).__name__} does not support context manager protocol"
+            )
+
+        raw_result = self._run(self._async_obj.__aenter__())
+
+        if raw_result is self._async_obj:
+            return self
+
+        return BeaverBridge(raw_result, self._loop)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        return self._run(self._async_obj.__aexit__(exc_type, exc_val, exc_tb))
+
+    # --- Magic Methods (Container Emulation) ---
+
+    def __len__(self) -> int:
+        if hasattr(self._async_obj, "count"):
+            return self._run(self._async_obj.count())
+        raise TypeError(f"Object of type {type(self._async_obj).__name__} has no len()")
+
+    def __getitem__(self, key: Any) -> Any:
+        if hasattr(self._async_obj, "get"):
+            return self._run(self._async_obj.get(key))
+        raise TypeError(
+            f"Object of type {type(self._async_obj).__name__} is not subscriptable"
+        )
+
+    def __setitem__(self, key: Any, value: Any):
+        if hasattr(self._async_obj, "set"):
+            return self._run(self._async_obj.set(key, value))
+        raise TypeError(
+            f"Object of type {type(self._async_obj).__name__} does not support item assignment"
+        )
+
+    def __delitem__(self, key: Any):
+        if hasattr(self._async_obj, "delete"):
+            return self._run(self._async_obj.delete(key))
+        raise TypeError(
+            f"Object of type {type(self._async_obj).__name__} does not support item deletion"
+        )
+
+    def __contains__(self, key: Any) -> bool:
+        if hasattr(self._async_obj, "contains"):
+            return self._run(self._async_obj.contains(key))
+        return False
+
+    def __iter__(self) -> Iterator[Any]:
+        """
+        Bridges AsyncIterator -> SyncIterator using the helper class.
+        """
+        if not hasattr(self._async_obj, "__aiter__"):
+            raise TypeError(
+                f"Object of type {type(self._async_obj).__name__} is not iterable"
+            )
+
+        # Create the async iterator on the background thread
+        async def get_iter():
+            return self._async_obj.__aiter__()
+
+        async_iter = self._run(get_iter())
+        return _SyncIteratorBridge(async_iter, self._loop)

beaver/cache.py

@@ -0,0 +1,274 @@
+import os
+import functools
+import threading
+import time
+from typing import Optional, Any, Protocol, NamedTuple
+
+
+class CacheStats(NamedTuple):
+    """Holds performance metrics for a cache instance."""
+
+    hits: int
+    misses: int
+    invalidations: int
+    sets: int
+    pops: int
+
+    @property
+    def reads(self) -> int:
+        return self.hits + self.misses
+
+    @property
+    def operations(self) -> int:
+        return self.hits + self.misses + self.sets + self.pops
+
+    @property
+    def hit_rate(self) -> float:
+        """Returns the cache hit rate (0.0 to 1.0)."""
+        if self.reads == 0:
+            return 0.0
+
+        return self.hits / self.reads
+
+    @property
+    def invalidation_rate(self) -> float:
+        """Returns the rate of invalidations per operation (0.0 to 1.0)."""
+        if self.reads == 0:
+            return 0.0
+
+        return self.invalidations / self.operations
+
+
+class ICache(Protocol):
+    """Defines the public interface for all cache objects."""
+
+    def get(self, key: str) -> Optional[Any]: ...
+    def set(self, key: Any, value: Any): ...
+    def pop(self, key: str): ...
+    def invalidate(self): ...
+    def stats(self) -> CacheStats: ...
+    def touch(self): ...
+
+
+class DummyCache:
+    """A cache object that does nothing. Used when caching is disabled."""
+
+    _stats = CacheStats(hits=0, misses=0, invalidations=0, sets=0, pops=0)
+
+    def get(self, key: str) -> Optional[Any]:
+        return None
+
+    def set(self, key: str, value: Any):
+        pass
+
+    def pop(self, key: str):
+        pass
+
+    def invalidate(self):
+        pass
+
+    def stats(self) -> CacheStats:
+        return self._stats
+
+    @classmethod
+    def singleton(cls) -> ICache:
+        if not hasattr(cls, "__instance"):
+            cls.__instance = cls()
+
+        return cls.__instance
+
+    def touch(self):
+        pass
+
+
+class LocalCache:
+    """
+    A thread-local cache that invalidates based on a central,
+    database-backed version number, checking only once per interval.
+    """
+
+    def __init__(self, db, cache_namespace: str, check_interval: float):
+        from .types import IDatabase
+
+        self._db: IDatabase = db
+        self._data: dict[str, Any] = {}
+        self._lock = threading.Lock()
+
+        self._version_key: str = cache_namespace  # e.g., "list:tasks"
+        self._local_version: int = -1
+        self._last_check_time: float = 0.0
+        self._min_check_interval: float = check_interval
+
+        # Statistics
+        self._hits = 0
+        self._misses = 0
+        self._invalidations = 0
+        self._sets = 0
+        self._pops = 0
+        self._clears = 0
+
+    def _get_global_version(self) -> int:
+        """Reads the 'source of truth' version from the DB."""
+        # This is a raw, direct DB call to avoid circular dependencies
+        cursor = self._db.connection.cursor()
+        cursor.execute(
+            "SELECT version FROM beaver_manager_versions WHERE namespace = ?",
+            (self._version_key,),
+        )
+        result = cursor.fetchone()
+        return int(result[0]) if result else 0
+
+    def _check_and_invalidate(self):
+        """
+        Checks if the cache is stale, but only hits the DB
+        once per check_interval.
+        """
+        now = time.time()
+
+        # --- 1. The Hot Path (Pure In-Memory Check) ---
+        if (now - self._last_check_time) < self._min_check_interval:
+            return
+
+        # --- 2. The "Coalesced" DB Check ---
+        with self._lock:
+            # Double-check inside lock in case another thread just ran this
+            if (time.time() - self._last_check_time) < self._min_check_interval:
+                return
+
+            global_version = self._get_global_version()
+            self._last_check_time = time.time()  # Reset timer
+
+            if global_version != self._local_version:
+                self._data.clear()
+                self._local_version = global_version
+                self._invalidations += 1
+
+    def get(self, key: str) -> Optional[Any]:
+        # This check is now extremely fast
+        self._check_and_invalidate()
+
+        with self._lock:
+            value = self._data.get(key)
+
+            if value is not None:
+                self._hits += 1
+                return value
+
+            self._misses += 1
+
+        return None
+
+    def set(self, key: str, value: Any):
+        with self._lock:
+            self._data[key] = value
+            self._sets += 1
+
+    def pop(self, key: str):
+        with self._lock:
+            self._data.pop(key, None)
+            self._pops += 1
+
+    def invalidate(self):
+        with self._lock:
+            self._data.clear()
+            self._local_version = 0  # Must force re-check
+            self._invalidations += 1
+            self._last_check_time = 0.0
+
+    def touch(self):
+        """
+        Atomically increments the cache version in the native SQL table
+        and syncs the cache's local version to avoid self-invalidation.
+
+        Only call this when you make a change that should invalidate
+        other caches of the same namespace in other processes,
+        but keep this cache valid.
+        """
+        with self._lock:
+            new_version = 0
+
+            with self._db.connection:
+                # This is a single, atomic, native SQL operation.
+                cursor = self._db.connection.execute(
+                    """
+                    INSERT INTO beaver_manager_versions (namespace, version)
+                    VALUES (?, 1)
+                    ON CONFLICT(namespace) DO UPDATE SET
+                        version = version + 1
+                    RETURNING version;
+                    """,
+                    (self._version_key,),
+                )
+                new_version = cursor.fetchone()[0]
+
+            # Keep the cache in sync to avoid self-invalidation
+            self._last_check_time = time.time()
+            self._local_version = new_version
+
+    def stats(self) -> CacheStats:
+        return CacheStats(
+            hits=self._hits,
+            misses=self._misses,
+            invalidations=self._invalidations,
+            sets=self._sets,
+            pops=self._pops,
+        )
+
+    def __repr__(self) -> str:
+        return f"<LocalCache namespace='{self._version_key}', version={self._local_version}>"
+
+
+def cached(key):
+    """
+    Decorator for read methods.
+    - Generates a cache key using key on the arguments.
+    - If key is None, bypasses cache.
+    - If key is in cache, returns cached value.
+    - If key is not in cache, runs the decorated function,
+      stores the result, and returns it.
+    """
+    from .manager import AsyncBeaverBase
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(self: AsyncBeaverBase, *args, **kwargs):
+            cache = self.cache
+            cache_key = key(*args, **kwargs)
+
+            if cache_key is None:
+                return func(self, *args, **kwargs)
+
+            if not self.locked:
+                cached_value = cache.get(cache_key)
+
+                if cached_value is not None:
+                    return cached_value  # HIT
+
+            result = func(self, *args, **kwargs)
+            cache.set(cache_key, result)
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def invalidates_cache(func):
+    """
+    Decorator for write methods that need to invalidate cache.
+    - Runs the decorated function.
+    - Clears the cache even if there is any exception.
+    """
+    from .manager import AsyncBeaverBase
+
+    @functools.wraps(func)
+    def wrapper(self: AsyncBeaverBase, *args, **kwargs):
+        try:
+            result = func(self, *args, **kwargs)
+        finally:
+            self.cache.invalidate()
+
+        return result
+
+    return wrapper