beaver-db 0.19.3__py3-none-any.whl → 0.20.2__py3-none-any.whl

beaver/__init__.py

@@ -2,4 +2,4 @@ from .core import BeaverDB
 from .types import Model
 from .collections import Document, WalkDirection
 
-__version__ = "0.19.3"
+__version__ = "0.20.2"

beaver/blobs.py

@@ -1,6 +1,8 @@
+import base64
+from datetime import datetime, timezone
 import json
 import sqlite3
-from typing import Any, Dict, Iterator, NamedTuple, Optional, Type, TypeVar
+from typing import IO, Any, Dict, Iterator, NamedTuple, Optional, Type, TypeVar
 from .types import JsonSerializable, IDatabase
 from .locks import LockManager
 
@@ -170,3 +172,60 @@ class BlobManager[M]:
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Releases the lock when exiting a 'with' statement."""
         self.release()
+
+    def _get_dump_object(self) -> dict:
+        """Builds the JSON-compatible dump object."""
+
+        items_list = []
+        # __iter__ yields keys, so we get each blob
+        for key in self:
+            blob = self.get(key)
+            if blob:
+                metadata = blob.metadata
+
+                # Handle model instances in metadata
+                if self._model and isinstance(metadata, JsonSerializable):
+                    metadata = json.loads(metadata.model_dump_json())
+
+                # Encode binary data to a base64 string
+                data_b64 = base64.b64encode(blob.data).decode('utf-8')
+
+                items_list.append({
+                    "key": blob.key,
+                    "metadata": metadata,
+                    "data_b64": data_b64
+                })
+
+        metadata = {
+            "type": "BlobStore",
+            "name": self._name,
+            "count": len(items_list),
+            "dump_date": datetime.now(timezone.utc).isoformat()
+        }
+
+        return {
+            "metadata": metadata,
+            "items": items_list
+        }
+
+    def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire contents of the blob store to a JSON-compatible
+        Python object or a file-like object.
+
+        Args:
+            fp: A file-like object opened in text mode (e.g., with 'w').
+                If provided, the JSON dump will be written to this file.
+                If None (default), the dump will be returned as a dictionary.
+
+        Returns:
+            A dictionary containing the dump if fp is None.
+            None if fp is provided.
+        """
+        dump_object = self._get_dump_object()
+
+        if fp:
+            json.dump(dump_object, fp, indent=2)
+            return None
+
+        return dump_object

beaver/client.py

@@ -0,0 +1,360 @@
+"""
+This module implements the BeaverClient, a drop-in replacement for the
+BeaverDB class that interacts with a remote BeaverDB server over HTTP.
+
+This implementation relies on the 'httpx' library.
+"""
+
+import threading
+from typing import Generic, Type, TypeVar, Optional, Any
+import httpx
+from .types import JsonSerializable
+from .collections import Document
+
+# --- Base Remote Manager ---
+
+class RemoteManager:
+    """Base class for all remote managers, holding the HTTP client."""
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type | None = None
+    ):
+        self._client = client
+        self._name = name
+        self._model = model
+        self._validate_model(model)
+
+    def _validate_model(self, model: Type | None):
+        """Helper to validate the model, mirroring BeaverDB.core"""
+        if model and not isinstance(model, JsonSerializable):
+            # This check might need to be refined if Pydantic isn't a direct dependency
+            pass
+
+# --- Stub Remote Manager Implementations ---
+
+class RemoteDictManager[T](RemoteManager):
+    """
+    Manages a remote dictionary. All methods will make HTTP requests.
+    (This is a skeleton implementation)
+    """
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type[T] | None = None
+    ):
+        super().__init__(client, name, model)
+        # Placeholder for manager-level locking, mirroring local implementation
+        self._lock = RemoteLockManager(client, f"__lock__dict__{name}", None)
+
+    def __setitem__(self, key: str, value: T):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def __getitem__(self, key: str) -> T:
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    # ... other dict methods (get, __delitem__, __len__, items, etc.) ...
+
+
+class RemoteListManager[T](RemoteManager):
+    """
+    Manages a remote list. All methods will make HTTP requests.
+    (This is a skeleton implementation)
+    """
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type[T] | None = None
+    ):
+        super().__init__(client, name, model)
+        self._lock = RemoteLockManager(client, f"__lock__list__{name}", None)
+
+    def push(self, value: T):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    # ... other list methods (pop, __getitem__, __setitem__, etc.) ...
+
+
+class RemoteQueueManager[T](RemoteManager):
+    """
+    Manages a remote priority queue. All methods will make HTTP requests.
+    (This is a skeleton implementation)
+    """
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type[T] | None = None
+    ):
+        super().__init__(client, name, model)
+        self._lock = RemoteLockManager(client, f"__lock__queue__{name}", None)
+
+    def put(self, data: T, priority: float):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def get(self, block: bool = True, timeout: float | None = None):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    # ... other queue methods (peek, __len__, etc.) ...
+
+
+class RemoteCollectionManager[D](RemoteManager):
+    """
+    Manages a remote collection. All methods will make HTTP requests.
+    (This is a skeleton implementation)
+    """
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type[D] | None = None
+    ):
+        super().__init__(client, name, model)
+        self._lock = RemoteLockManager(client, f"__lock__collection__{name}", None)
+
+    def index(self, document: D, *, fts: bool | list[str] = True, fuzzy: bool = False):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def search(self, vector: list[float], top_k: int = 10):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    # ... other collection methods (drop, match, connect, walk, etc.) ...
+
+
+class RemoteChannelManager[T](RemoteManager):
+    """
+    Manages a remote pub/sub channel.
+    (This is a skeleton implementation)
+    """
+    def publish(self, payload: T):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def subscribe(self):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+
+class RemoteBlobManager[M](RemoteManager):
+    """
+    Manages a remote blob store. All methods will make HTTP requests.
+    (This is a skeleton implementation)
+    """
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type[M] | None = None
+    ):
+        super().__init__(client, name, model)
+        self._lock = RemoteLockManager(client, f"__lock__blob__{name}", None)
+
+    def put(self, key: str, data: bytes, metadata: Optional[M] = None):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def get(self, key: str):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    # ... other blob methods (delete, __len__, etc.) ...
+
+
+class RemoteLogManager[T](RemoteManager):
+    """
+    Manages a remote time-indexed log.
+    (This is a skeleton implementation)
+    """
+    def log(self, data: T, timestamp: Any | None = None): # Using Any for datetime
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def range(self, start: Any, end: Any): # Using Any for datetime
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def live(self, window: Any, period: Any, aggregator: Any): # Using Any for timedelta/callable
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+
+class RemoteLockManager(RemoteManager):
+    """
+    Manages a remote inter-process lock.
+    (This is a skeleton implementation)
+    """
+    def __init__(
+        self,
+        client: httpx.Client,
+        name: str,
+        model: Type | None = None,
+        timeout: float | None = None,
+        lock_ttl: float = 60.0,
+        poll_interval: float = 0.1,
+    ):
+        super().__init__(client, name, model)
+        self._timeout = timeout
+        self._lock_ttl = lock_ttl
+        self._poll_interval = poll_interval
+
+    def acquire(self):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def release(self):
+        raise NotImplementedError("This method will be implemented in a future milestone.")
+
+    def __enter__(self):
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.release()
+
+
+# --- The Main Client Class ---
+
+class BeaverClient:
+    """
+    A drop-in client for a remote BeaverDB server.
+
+    This class provides the same factory methods as the local BeaverDB class,
+    but all operations are performed over HTTP/WebSockets against a
+    server running 'beaver serve'.
+    """
+
+    def __init__(self, base_url: str, **httpx_args):
+        """
+        Initializes the client.
+
+        Args:
+            base_url: The base URL of the BeaverDB server (e.g., "http://127.0.0.1:8000").
+            **httpx_args: Additional keyword arguments to pass to the httpx.Client
+                          (e.g., headers, timeouts).
+        """
+        self._client = httpx.Client(base_url=base_url, **httpx_args)
+
+        # Singleton managers for collections and channels, just like in BeaverDB.core
+        self._collections: dict[str, RemoteCollectionManager] = {}
+        self._collections_lock = threading.Lock()
+        self._channels: dict[str, RemoteChannelManager] = {}
+        self._channels_lock = threading.Lock()
+
+    def close(self):
+        """Closes the underlying HTTP client session."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def dict[T](self, name: str, model: type[T] | None = None) -> RemoteDictManager[T]:
+        """
+        Returns a wrapper for interacting with a remote named dictionary.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("Dictionary name must be a non-empty string.")
+
+        return RemoteDictManager(self._client, name, model)
+
+    def list[T](self, name: str, model: type[T] | None = None) -> RemoteListManager[T]:
+        """
+        Returns a wrapper for interacting with a remote named list.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("List name must be a non-empty string.")
+
+        return RemoteListManager(self._client, name, model)
+
+    def queue[T](self, name: str, model: type[T] | None = None) -> RemoteQueueManager[T]:
+        """
+        Returns a wrapper for interacting with a remote persistent priority queue.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("Queue name must be a non-empty string.")
+
+        return RemoteQueueManager(self._client, name, model)
+
+    def collection[D: Document](
+        self, name: str, model: Type[D] | None = None
+    ) -> RemoteCollectionManager[D]:
+        """
+        Returns a singleton wrapper for a remote document collection.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("Collection name must be a non-empty string.")
+
+        with self._collections_lock:
+            if name not in self._collections:
+                self._collections[name] = RemoteCollectionManager(self._client, name, model)
+            return self._collections[name] # type: ignore
+
+    def channel[T](self, name: str, model: type[T] | None = None) -> RemoteChannelManager[T]:
+        """
+        Returns a singleton wrapper for a remote pub/sub channel.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("Channel name must be a non-empty string.")
+
+        with self._channels_lock:
+            if name not in self._channels:
+                self._channels[name] = RemoteChannelManager(self._client, name, model)
+            return self._channels[name]
+
+    def blobs[M](self, name: str, model: type[M] | None = None) -> RemoteBlobManager[M]:
+        """Returns a wrapper for interacting with a remote blob store."""
+        if not isinstance(name, str) or not name:
+            raise TypeError("Blob store name must be a non-empty string.")
+
+        return RemoteBlobManager(self._client, name, model)
+
+    def log[T](self, name: str, model: type[T] | None = None) -> RemoteLogManager[T]:
+        """
+        Returns a wrapper for interacting with a remote, time-indexed log.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
+        if not isinstance(name, str) or not name:
+            raise TypeError("Log name must be a non-empty string.")
+
+        return RemoteLogManager(self._client, name, model)
+
+    def lock(
+        self,
+        name: str,
+        timeout: float | None = None,
+        lock_ttl: float = 60.0,
+        poll_interval: float = 0.1,
+    ) -> RemoteLockManager:
+        """
+        Returns a wrapper for a remote inter-process lock.
+        """
+        return RemoteLockManager(
+            self._client,
+            name,
+            model=None,
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval,
+        )
+
+    # --- Async API ---
+
+    def as_async(self) -> "AsyncBeaverClient":
+        """
+        Returns an async-compatible version of the client.
+        (This is a skeleton implementation)
+        """
+        raise NotImplementedError("AsyncBeaverClient will be implemented in a future milestone.")
+
+
+class AsyncBeaverClient:
+    """
+    An async-compatible, drop-in client for a remote BeaverDB server.
+    (This is a skeleton implementation)
+    """
+    def __init__(self, base_url: str, **httpx_args):
+        self._client = httpx.AsyncClient(base_url=base_url, **httpx_args)
+        # ... async-compatible locks and manager caches ...
+
+    async def close(self):
+        await self._client.aclose()

beaver/collections.py

@@ -1,9 +1,10 @@
+from datetime import datetime, timezone
 import json
 import sqlite3
 import threading
 import uuid
 from enum import Enum
-from typing import Any, Iterator, List, Literal, Tuple, Type, TypeVar, Optional
+from typing import IO, Any, Iterator, List, Literal, Tuple, Type, TypeVar, Optional
 from .types import Model, stub, IDatabase
 from .locks import LockManager
 
@@ -679,6 +680,47 @@ class CollectionManager[D: Document]:
         """Releases the lock when exiting a 'with' statement."""
         self.release()
 
+    def _get_dump_object(self) -> dict:
+        """Builds the JSON-compatible dump object."""
+
+        # The __iter__ method yields Document instances.
+        # doc.to_dict(metadata_only=False) correctly serializes
+        # the Document (including embedding) to a plain dictionary.
+        items_list = [doc.to_dict(metadata_only=False) for doc in self]
+
+        metadata = {
+            "type": "Collection",
+            "name": self._name,
+            "count": len(items_list),
+            "dump_date": datetime.now(timezone.utc).isoformat()
+        }
+
+        return {
+            "metadata": metadata,
+            "items": items_list
+        }
+
+    def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire contents of the collection to a JSON-compatible
+        Python object or a file-like object.
+
+        Args:
+            fp: A file-like object opened in text mode (e.g., with 'w').
+                If provided, the JSON dump will be written to this file.
+                If None (default), the dump will be returned as a dictionary.
+
+        Returns:
+            A dictionary containing the dump if fp is None.
+            None if fp is provided.
+        """
+        dump_object = self._get_dump_object()
+
+        if fp:
+            json.dump(dump_object, fp, indent=2)
+            return None
+
+        return dump_object
 
 def rerank[D: Document](
     *results: list[D], weights: list[float] | None = None, k: int = 60

beaver/core.py

@@ -167,7 +167,7 @@ class BeaverDB:
         """Creates the table to store the serialized base ANN index."""
         self.connection.execute(
             """
-            CREATE TABLE IF NOT EXISTS _beaver_ann_indexes (
+            CREATE TABLE IF NOT EXISTS beaver_ann_indexes (
                 collection_name TEXT PRIMARY KEY,
                 index_data BLOB,
                 base_index_version INTEGER NOT NULL DEFAULT 0
@@ -179,7 +179,7 @@ class BeaverDB:
         """Creates the log for new vector additions."""
         self.connection.execute(
             """
-            CREATE TABLE IF NOT EXISTS _beaver_ann_pending_log (
+            CREATE TABLE IF NOT EXISTS beaver_ann_pending_log (
                 collection_name TEXT NOT NULL,
                 str_id TEXT NOT NULL,
                 PRIMARY KEY (collection_name, str_id)
@@ -191,7 +191,7 @@ class BeaverDB:
         """Creates the log for vector deletions (tombstones)."""
         self.connection.execute(
             """
-            CREATE TABLE IF NOT EXISTS _beaver_ann_deletions_log (
+            CREATE TABLE IF NOT EXISTS beaver_ann_deletions_log (
                 collection_name TEXT NOT NULL,
                 int_id INTEGER NOT NULL,
                 PRIMARY KEY (collection_name, int_id)
@@ -203,7 +203,7 @@ class BeaverDB:
         """Creates the table to map string IDs to integer IDs for Faiss."""
         self.connection.execute(
             """
-            CREATE TABLE IF NOT EXISTS _beaver_ann_id_mapping (
+            CREATE TABLE IF NOT EXISTS beaver_ann_id_mapping (
                 collection_name TEXT NOT NULL,
                 str_id TEXT NOT NULL,
                 int_id INTEGER PRIMARY KEY AUTOINCREMENT,

beaver/dicts.py

@@ -1,7 +1,8 @@
+from datetime import datetime, timezone
 import json
 import sqlite3
 import time
-from typing import Any, Iterator, Tuple, Type, Optional
+from typing import IO, Any, Iterator, Tuple, Type, Optional
 from .types import JsonSerializable, IDatabase
 from .locks import LockManager
 
@@ -15,6 +16,55 @@ class DictManager[T]:
         lock_name = f"__lock__dict__{name}"
         self._lock = LockManager(db, lock_name)
 
+    def _get_dump_object(self) -> dict:
+        """Builds the JSON-compatible dump object."""
+        items = []
+
+        for k, v in self.items():
+            item_value = v
+            # Check if a model is defined and the value is a model instance
+            if self._model and isinstance(v, JsonSerializable):
+                # Use the model's serializer to get its string representation,
+                # then parse that string back into a dict.
+                # This ensures the dump contains serializable dicts, not model objects.
+                item_value = json.loads(v.model_dump_json())
+
+            items.append({"key": k, "value": item_value})
+
+        metadata = {
+            "type": "Dict",
+            "name": self._name,
+            "count": len(items),
+            "dump_date": datetime.now(timezone.utc).isoformat()
+        }
+
+        return {
+            "metadata": metadata,
+            "items": items
+        }
+
+    def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire contents of the dictionary to a JSON-compatible
+        Python object or a file-like object.
+
+        Args:
+            fp: A file-like object opened in text mode (e.g., with 'w').
+                If provided, the JSON dump will be written to this file.
+                If None (default), the dump will be returned as a dictionary.
+
+        Returns:
+            A dictionary containing the dump if fp is None.
+            None if fp is provided.
+        """
+        dump_object = self._get_dump_object()
+
+        if fp:
+            json.dump(dump_object, fp, indent=2)
+            return None
+
+        return dump_object
+
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
         if isinstance(value, JsonSerializable):

beaver/lists.py

@@ -1,10 +1,10 @@
 import json
 import sqlite3
-from typing import Any, Iterator, Type, Union, Optional
+from typing import Any, Iterator, Type, Union, Optional, IO
+from datetime import datetime, timezone
 from .types import JsonSerializable, IDatabase
 from .locks import LockManager
 
-
 class ListManager[T]:
     """A wrapper providing a Pythonic, full-featured interface to a list in the database."""
 
@@ -15,6 +15,53 @@ class ListManager[T]:
         lock_name = f"__lock__list__{name}"
         self._lock = LockManager(db, lock_name)
 
+    def _get_dump_object(self) -> dict:
+        """Builds the JSON-compatible dump object."""
+        items = []
+
+        for item in self:
+            item_value = item
+            # Check if a model is defined and the item is a model instance
+            if self._model and isinstance(item, JsonSerializable):
+                # Convert the model object to a serializable dict
+                item_value = json.loads(item.model_dump_json())
+
+            items.append(item_value)
+
+        metadata = {
+            "type": "List",
+            "name": self._name,
+            "count": len(items),
+            "dump_date": datetime.now(timezone.utc).isoformat()
+        }
+
+        return {
+            "metadata": metadata,
+            "items": items
+        }
+
+    def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire contents of the list to a JSON-compatible
+        Python object or a file-like object.
+
+        Args:
+            fp: A file-like object opened in text mode (e.g., with 'w').
+                If provided, the JSON dump will be written to this file.
+                If None (default), the dump will be returned as a dictionary.
+
+        Returns:
+            A dictionary containing the dump if fp is None.
+            None if fp is provided.
+        """
+        dump_object = self._get_dump_object()
+
+        if fp:
+            json.dump(dump_object, fp, indent=2)
+            return None
+
+        return dump_object
+
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
         if isinstance(value, JsonSerializable):

beaver/logs.py

@@ -6,7 +6,7 @@ import threading
 import time
 from datetime import datetime, timedelta, timezone
 from queue import Empty, Queue
-from typing import Any, AsyncIterator, Callable, Iterator, Type, TypeVar
+from typing import IO, Any, AsyncIterator, Callable, Iterator, Type, TypeVar
 
 from .types import JsonSerializable, IDatabase
 
@@ -15,7 +15,7 @@ from .types import JsonSerializable, IDatabase
 _SHUTDOWN_SENTINEL = object()
 
 
-class LiveIterator[T,R]:
+class LiveIterator[T, R]:
     """
     A thread-safe, blocking iterator that yields aggregated results from a
     rolling window of log data.
@@ -119,10 +119,10 @@ class LiveIterator[T,R]:
             self._thread.join()
 
 
-class AsyncLiveIterator[T,R]:
+class AsyncLiveIterator[T, R]:
     """An async wrapper for the LiveIterator."""
 
-    def __init__(self, sync_iterator: LiveIterator[T,R]):
+    def __init__(self, sync_iterator: LiveIterator[T, R]):
         self._sync_iterator = sync_iterator
 
     async def __anext__(self) -> R:
@@ -162,9 +162,7 @@ class AsyncLogManager[T]:
         aggregator: Callable[[list[T]], R],
     ) -> AsyncIterator[R]:
         """Returns an async, infinite iterator for real-time log analysis."""
-        sync_iterator = self._sync_manager.live(
-            window, period, aggregator
-        )
+        sync_iterator = self._sync_manager.live(window, period, aggregator)
         return AsyncLiveIterator(sync_iterator)
 
 
@@ -272,3 +270,70 @@ class LogManager[T]:
     def as_async(self) -> AsyncLogManager[T]:
         """Returns an async-compatible version of the log manager."""
         return AsyncLogManager(self)
+
+    def __iter__(self) -> Iterator[tuple[float, T]]:
+        """Returns an iterator over all log entries, in chronological order.
+
+        Yields:
+            A dictionary for each log entry with keys "timestamp" and "data".
+            The "data" is deserialized.
+        """
+        cursor = self._db.connection.cursor()
+        cursor.execute(
+            "SELECT timestamp, data FROM beaver_logs WHERE log_name = ? ORDER BY timestamp ASC",
+            (self._name,),
+        )
+        try:
+            for row in cursor:
+                yield (row["timestamp"], self._deserialize(row["data"]))
+        finally:
+            cursor.close()
+
+    def _get_dump_object(self) -> dict:
+        """Builds the JSON-compatible dump object."""
+
+        items_list = []
+        # Use the new __iter__ method
+        for timestamp, data in self:
+
+            # Handle model instances
+            if self._model and isinstance(data, JsonSerializable):
+                data = json.loads(data.model_dump_json())
+
+            items_list.append(
+                {
+                    "timestamp": timestamp,
+                    "data": data,
+                }
+            )
+
+        metadata = {
+            "type": "Log",
+            "name": self._name,
+            "count": len(items_list),
+            "dump_date": datetime.now(timezone.utc).isoformat(),
+        }
+
+        return {"metadata": metadata, "items": items_list}
+
+    def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire contents of the log to a JSON-compatible
+        Python object or a file-like object.
+
+        Args:
+            fp: A file-like object opened in text mode (e.g., with 'w').
+                If provided, the JSON dump will be written to this file.
+                If None (default), the dump will be returned as a dictionary.
+
+        Returns:
+            A dictionary containing the dump if fp is None.
+            None if fp is provided.
+        """
+        dump_object = self._get_dump_object()
+
+        if fp:
+            json.dump(dump_object, fp, indent=2)
+            return None
+
+        return dump_object

beaver/queues.py

@@ -1,8 +1,9 @@
 import asyncio
+from datetime import datetime, timezone
 import json
 import sqlite3
 import time
-from typing import Any, Literal, NamedTuple, Type, overload, Optional
+from typing import IO, Any, Iterator, Literal, NamedTuple, Type, overload, Optional
 from .types import JsonSerializable, IDatabase
 from .locks import LockManager
 
@@ -219,3 +220,83 @@ class QueueManager[T]:
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Releases the lock when exiting a 'with' statement."""
         self.release()
+
+    def __iter__(self) -> Iterator[QueueItem[T]]:
+        """
+        Returns an iterator over all items in the queue, in priority order,
+        without removing them.
+
+        Yields:
+            QueueItem: The next item in the queue (priority, timestamp, data).
+        """
+        cursor = self._db.connection.cursor()
+        cursor.execute(
+            """
+            SELECT priority, timestamp, data
+            FROM beaver_priority_queues
+            WHERE queue_name = ?
+            ORDER BY priority ASC, timestamp ASC
+            """,
+            (self._name,),
+        )
+        try:
+            for row in cursor:
+                yield QueueItem(
+                    priority=row["priority"],
+                    timestamp=row["timestamp"],
+                    data=self._deserialize(row["data"])
+                )
+        finally:
+            cursor.close()
+
+    def _get_dump_object(self) -> dict:
+        """Builds the JSON-compatible dump object."""
+
+        items_list = []
+        # Use the new __iter__ method
+        for item in self:
+            data = item.data
+
+            # Handle model instances
+            if self._model and isinstance(data, JsonSerializable):
+                data = json.loads(data.model_dump_json())
+
+            items_list.append({
+                "priority": item.priority,
+                "timestamp": item.timestamp,
+                "data": data
+            })
+
+        metadata = {
+            "type": "Queue",
+            "name": self._name,
+            "count": len(items_list),
+            "dump_date": datetime.now(timezone.utc).isoformat()
+        }
+
+        return {
+            "metadata": metadata,
+            "items": items_list
+        }
+
+    def dump(self, fp: IO[str] | None = None) -> dict | None:
+        """
+        Dumps the entire contents of the queue to a JSON-compatible
+        Python object or a file-like object.
+
+        Args:
+            fp: A file-like object opened in text mode (e.g., with 'w').
+                If provided, the JSON dump will be written to this file.
+                If None (default), the dump will be returned as a dictionary.
+
+        Returns:
+            A dictionary containing the dump if fp is None.
+            None if fp is provided.
+        """
+        dump_object = self._get_dump_object()
+
+        if fp:
+            json.dump(dump_object, fp, indent=2)
+            return None
+
+        return dump_object

beaver/types.py

@@ -20,6 +20,19 @@ class JsonSerializable[T](Protocol):
         ...
 
 
+class _ModelEncoder(json.JSONEncoder):
+    """
+    Custom JSON encoder that recursively serializes Model instances.
+    """
+    def default(self, o):
+        if isinstance(o, Model):
+            # If the object is a Model instance, return its __dict__.
+            # The JSONEncoder will then recursively serialize this dict.
+            return o.__dict__
+        # Let the base class handle built-in types
+        return super().default(o)
+
+
 class Model:
     """A lightweight base model that automatically provides JSON serialization."""
     def __init__(self, **kwargs) -> None:
@@ -28,11 +41,13 @@ class Model:
 
     def model_dump_json(self) -> str:
         """Serializes the dataclass instance to a JSON string."""
-        return json.dumps(self.__dict__)
+        # Use the custom _ModelEncoder to handle self and any nested Models
+        return json.dumps(self, cls=_ModelEncoder)
 
     @classmethod
     def model_validate_json(cls, json_data: str | bytes) -> Self:
         """Deserializes a JSON string into a new instance of the dataclass."""
+        # Note: This deserializes nested objects as dicts, not Model instances.
         return cls(**json.loads(json_data))
 
     def __repr__(self) -> str:
@@ -40,7 +55,6 @@ class Model:
         return f"{self.__class__.__name__}({attrs})"
 
 
-
 def stub(msg: str):
     class Stub:
         def __init__(self, *args, **kwargs) -> None:

{beaver_db-0.19.3.dist-info → beaver_db-0.20.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.19.3
+Version: 0.20.2
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -71,6 +71,7 @@ Description-Content-Type: text/markdown
 - **Built-in REST API Server (Optional)**: Instantly serve your database over a RESTful API with automatic OpenAPI documentation using FastAPI.
 - **Full-Featured CLI Client (Optional)**: Interact with your database directly from the command line for administrative tasks and data exploration.
 - **Optional Type-Safety:** Although the database is schemaless, you can use a minimalistic typing system for automatic serialization and deserialization that is Pydantic-compatible out of the box.
+- **Data Export & Backups:** Dump any dictionary, list, collection, queue, blob, or log structure to a portable JSON file with a single `.dump()` command.
 
 ## How Beaver is Implemented
 
@@ -203,6 +204,43 @@ beaver client --database data.db dict app_config get theme
 beaver client --database data.db list daily_tasks push "Review PRs"
 ```
 
+## Data Export for Backups
+
+All data structures (`dict`, `list`, `collection`, `queue`, `log`, and `blobs`) support a `.dump()` method for easy backups and migration. You can either write the data directly to a JSON file or get it as a Python dictionary.
+
+```python
+import json
+from beaver import BeaverDB
+
+db = BeaverDB("my_app.db")
+config = db.dict("app_config")
+
+# Add some data
+config["theme"] = "dark"
+config["user_id"] = 456
+
+# Dump the dictionary's contents to a JSON file
+with open("config_backup.json", "w") as f:
+    config.dump(f)
+
+# 'config_backup.json' now contains:
+# {
+#   "metadata": {
+#     "type": "Dict",
+#     "name": "app_config",
+#     "count": 2,
+#     "dump_date": "2025-11-02T09:05:10.123456Z"
+#   },
+#   "items": [
+#     {"key": "theme", "value": "dark"},
+#     {"key": "user_id", "value": 456}
+#   ]
+# }
+
+# You can also get the dump as a Python object
+dump_data = config.dump()
+```
+
 ## Things You Can Build with Beaver
 
 Here are a few ideas to inspire your next project, showcasing how to combine Beaver's features to build powerful local applications.
@@ -446,9 +484,9 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 These are some of the features and improvements planned for future releases:
 
 - **[Issue #2](https://github.com/syalia-srl/beaver/issues/2) Comprehensive async wrappers**: Extend the async support with on-demand wrappers for all data structures, not just channels.
-- **[Issue #9](https://github.com/syalia-srl/beaver/issues/2) Type-safe wrappers based on Pydantic-compatible models**: Enhance the built-in `Model` to handle recursive and embedded types and provide Pydantic compatibility.
-- **[Issue #6](https://github.com/syalia-srl/beaver/issues/2) Drop-in replacement for Beaver REST server client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but works against the REST API server.
-- **[Issue #7](https://github.com/syalia-srl/beaver/issues/2) Replace `faiss` with simpler, linear `numpy` vectorial search**: Investigate removing the heavy `faiss` dependency in favor of a pure `numpy` implementation to improve installation simplicity, accepting a trade-off in search performance for O(1) installation.
+- **[Issue #6](https://github.com/syalia-srl/beaver/issues/6) Drop-in replacement for Beaver REST server client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but works against the REST API server.
+- **[Issue #7](https://github.com/syalia-srl/beaver/issues/7) Replace `faiss` with simpler, linear `numpy` vectorial search**: Investigate removing the heavy `faiss` dependency in favor of a pure `numpy` implementation to improve installation simplicity, accepting a trade-off in search performance for O(1) installation.
+- **[Issue #9](https://github.com/syalia-srl/beaver/issues/9) Type-safe wrappers based on Pydantic-compatible models**: Enhance the built-in `Model` to handle recursive and embedded types and provide Pydantic compatibility.
 
 
 If you think of something that would make `beaver` more useful for your use case, please open an issue and/or submit a pull request.

beaver_db-0.20.2.dist-info/RECORD

@@ -0,0 +1,20 @@
+beaver/__init__.py,sha256=p5ObXWW5sqLrfIbuacZw2Hmafe0p513_14fueaaTJCc,125
+beaver/blobs.py,sha256=VdtjSIPrdjkmAlOZ8-wEkJsJ2KW4b9t8swHFu6d16c8,7394
+beaver/channels.py,sha256=kIuwKMDBdDQObaKT23znsMXzfpKfE7pXSxvf-u4LlpY,9554
+beaver/cli.py,sha256=Sxm-mYU3LGd4tIqw-5LHb0ektWebjV9vn51hm-CMJD0,2232
+beaver/client.py,sha256=jDX2WJHZk1LL3R2sulM4JabZQJCcoZU4Hwfeqz-1KME,12572
+beaver/collections.py,sha256=yn6Bc8zf2zYKBC0G0VsrSqSTGEia75VTIfg3NLUtKAc,28714
+beaver/core.py,sha256=5LIZiPsv7KnKmsQucABWApqgyauBJJUtBIa6Cqh2o7U,17096
+beaver/dicts.py,sha256=PhmQ_1Z0gyBlIFSCKDsnAHMA3t8BYJJCLKeQNSF_32k,8287
+beaver/lists.py,sha256=0k-5qZrO38ipYHCyYeZ8rrzkcuzbgGasUCmlhyQiTzw,12775
+beaver/locks.py,sha256=b6cHgAI1YQxKmVdLLzNw9fcGvk4V3SQS_wUaQTHSsUk,6630
+beaver/logs.py,sha256=oKbJnDNb3KPH4JcwcaXzgG9pqSAZ_gpTn23xwFlVw9k,11643
+beaver/queues.py,sha256=KRbEKsCcZ4z0poO4rwXhpjwIvLEbvSSr1Nyp1EQM0mE,10183
+beaver/server.py,sha256=At3BoEV7JfpYjNtyHMdPUF8shj4V4D5nStXWb6Bv53A,15947
+beaver/types.py,sha256=TKUW5lnqb7Q0xb51iyKGtANJ6-j9XghlhMM3PPIyFN8,2259
+beaver/vectors.py,sha256=EGZf1s364-rMubxkYoTcjBl72lRRxM1cUwypjsoC6ec,18499
+beaver_db-0.20.2.dist-info/METADATA,sha256=IzMrPGWyYSIMGl-hVh6lKNOOAl-mepoTtqBu9p-LGvw,24496
+beaver_db-0.20.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+beaver_db-0.20.2.dist-info/entry_points.txt,sha256=bd5E2s45PoBdtdR9-ToKSdLNhmHp8naV1lWP5mOzlrc,42
+beaver_db-0.20.2.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.20.2.dist-info/RECORD,,

beaver_db-0.19.3.dist-info/RECORD

@@ -1,19 +0,0 @@
-beaver/__init__.py,sha256=DBnqxMZ-ZIvX14_FoC_ZGmYqcqhQtpLG1VXjNVCcPdc,125
-beaver/blobs.py,sha256=gauxfWOCMoP6mq61JRj-TVqqkXMAcVI2taBGYnJXsxg,5527
-beaver/channels.py,sha256=kIuwKMDBdDQObaKT23znsMXzfpKfE7pXSxvf-u4LlpY,9554
-beaver/cli.py,sha256=Sxm-mYU3LGd4tIqw-5LHb0ektWebjV9vn51hm-CMJD0,2232
-beaver/collections.py,sha256=Vc5ZF5gVIACx2XeL25PxgOcW7iF6lBInO-cnfyBBUeo,27299
-beaver/core.py,sha256=JRkRvc0Sb3FT9KlR3YbmiPcqCQ686dFKmHSNZ_UJ_aE,17100
-beaver/dicts.py,sha256=0csA1fvQb3rB2yQvwuq_kzgJ0YPp-wifBLkNcuiUltI,6582
-beaver/lists.py,sha256=vKZPVRiw0BRSx4JKaboGnWXfwNGkHX8cBFH59qQX1yY,11258
-beaver/locks.py,sha256=b6cHgAI1YQxKmVdLLzNw9fcGvk4V3SQS_wUaQTHSsUk,6630
-beaver/logs.py,sha256=a5xenwl5NZeegIU0dWVEs67lvaHzzw-JRAZtEzNNO3E,9529
-beaver/queues.py,sha256=wTlxsu12grcIPbosA1S0_23Tot4Wv3BWXeKyq4dRPKk,7709
-beaver/server.py,sha256=At3BoEV7JfpYjNtyHMdPUF8shj4V4D5nStXWb6Bv53A,15947
-beaver/types.py,sha256=m0ohT7A8r0Y1a7bJEx4VanLaOUWU2VYxaLHPsVPjrIw,1651
-beaver/vectors.py,sha256=EGZf1s364-rMubxkYoTcjBl72lRRxM1cUwypjsoC6ec,18499
-beaver_db-0.19.3.dist-info/METADATA,sha256=gRJetTcWICFhi0kQUFeNt773vTZkZYF-iRFqCtUXqjE,23431
-beaver_db-0.19.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-beaver_db-0.19.3.dist-info/entry_points.txt,sha256=bd5E2s45PoBdtdR9-ToKSdLNhmHp8naV1lWP5mOzlrc,42
-beaver_db-0.19.3.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.19.3.dist-info/RECORD,,