beaver-db 0.20.1__tar.gz → 0.20.2__tar.gz

{beaver_db-0.20.1 → beaver_db-0.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.20.1
+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.1 → beaver_db-0.20.2}/README.md

@@ -46,6 +46,7 @@
 - **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
 
@@ -178,6 +179,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.
@@ -421,9 +459,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.1 → beaver_db-0.20.2}/beaver/__init__.py

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

{beaver_db-0.20.1 → beaver_db-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_db-0.20.2/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_db-0.20.1 → beaver_db-0.20.2}/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