beaver-db 0.11.0__tar.gz → 0.12.0__tar.gz

{beaver_db-0.11.0 → beaver_db-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.11.0
+Version: 0.12.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -34,6 +34,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
   - **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
   - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
   - **Persistent Priority Queue**: A high-performance, persistent queue that always returns the item with the highest priority, perfect for task management.
+  - **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
   - **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
   - **Full-Text and Fuzzy Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine, enhanced with optional fuzzy search for typo-tolerant matching.
   - **Knowledge Graph**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -199,30 +200,53 @@ with db.channel("system_events").subscribe() as listener:
         # >> Event received: {'event': 'user_login', 'user_id': 'alice'}
 ```
 
+### 7. Storing User-Uploaded Content
+
+Use the simple blob store to save files like user avatars, attachments, or generated reports directly in the database. This keeps all your data in one portable file.
+
+```python
+attachments = db.blobs("user_uploads")
+
+# Store a user's avatar
+with open("avatar.png", "rb") as f:
+    avatar_bytes = f.read()
+
+attachments.put(
+    key="user_123_avatar.png",
+    data=avatar_bytes,
+    metadata={"mimetype": "image/png"}
+)
+
+# Retrieve it later
+avatar = attachments.get("user_123_avatar.png")
+```
+
 ## More Examples
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`examples/kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`examples/list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`examples/queue.py`](examples/queue.py): A practical example of using the persistent priority queue for task management.
-  - [`examples/vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
-  - [`examples/fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`examples/graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`examples/pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
   - [`examples/async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
-  - [`examples/publisher.py`](examples/publisher.py) and [`examples/subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`examples/blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
   - [`examples/cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`examples/rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
   - [`examples/fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
-  - [`examples/stress_vectors.py](examples/stress_vectors.py): A stress test for the vector search functionality.
   - [`examples/general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
+  - [`examples/graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+  - [`examples/kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+  - [`examples/list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+  - [`examples/publisher.py`](examples/publisher.py) and [`examples/subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`examples/pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+  - [`examples/queue.py`](examples/queue.py): A practical example of using the persistent priority queue for task management.
+  - [`examples/rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+  - [`examples/vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
 These are some of the features and improvements planned for future releases:
 
   - **Full Async API**: Comprehensive async support with on-demand wrappers for all collections.
+  - **Type Hints**: Pydantic-based type hints for lists, dicts, and queues.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 

{beaver_db-0.11.0 → beaver_db-0.12.0}/README.md

@@ -23,6 +23,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
   - **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
   - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
   - **Persistent Priority Queue**: A high-performance, persistent queue that always returns the item with the highest priority, perfect for task management.
+  - **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
   - **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
   - **Full-Text and Fuzzy Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine, enhanced with optional fuzzy search for typo-tolerant matching.
   - **Knowledge Graph**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -188,33 +189,56 @@ with db.channel("system_events").subscribe() as listener:
         # >> Event received: {'event': 'user_login', 'user_id': 'alice'}
 ```
 
+### 7. Storing User-Uploaded Content
+
+Use the simple blob store to save files like user avatars, attachments, or generated reports directly in the database. This keeps all your data in one portable file.
+
+```python
+attachments = db.blobs("user_uploads")
+
+# Store a user's avatar
+with open("avatar.png", "rb") as f:
+    avatar_bytes = f.read()
+
+attachments.put(
+    key="user_123_avatar.png",
+    data=avatar_bytes,
+    metadata={"mimetype": "image/png"}
+)
+
+# Retrieve it later
+avatar = attachments.get("user_123_avatar.png")
+```
+
 ## More Examples
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`examples/kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`examples/list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`examples/queue.py`](examples/queue.py): A practical example of using the persistent priority queue for task management.
-  - [`examples/vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
-  - [`examples/fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`examples/graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`examples/pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
   - [`examples/async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
-  - [`examples/publisher.py`](examples/publisher.py) and [`examples/subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`examples/blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
   - [`examples/cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`examples/rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
   - [`examples/fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
-  - [`examples/stress_vectors.py](examples/stress_vectors.py): A stress test for the vector search functionality.
   - [`examples/general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
+  - [`examples/graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+  - [`examples/kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+  - [`examples/list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+  - [`examples/publisher.py`](examples/publisher.py) and [`examples/subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`examples/pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+  - [`examples/queue.py`](examples/queue.py): A practical example of using the persistent priority queue for task management.
+  - [`examples/rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+  - [`examples/vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
 These are some of the features and improvements planned for future releases:
 
   - **Full Async API**: Comprehensive async support with on-demand wrappers for all collections.
+  - **Type Hints**: Pydantic-based type hints for lists, dicts, and queues.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

beaver_db-0.12.0/beaver/blobs.py

@@ -0,0 +1,107 @@
+import json
+import sqlite3
+from typing import Any, Dict, Iterator, NamedTuple, Optional
+
+
+class Blob(NamedTuple):
+    """A data class representing a single blob retrieved from the store."""
+
+    key: str
+    data: bytes
+    metadata: Dict[str, Any]
+
+
+class BlobManager:
+    """A wrapper providing a Pythonic interface to a blob store in the database."""
+
+    def __init__(self, name: str, conn: sqlite3.Connection):
+        self._name = name
+        self._conn = conn
+
+    def put(self, key: str, data: bytes, metadata: Optional[Dict[str, Any]] = None):
+        """
+        Stores or replaces a blob in the store.
+
+        Args:
+            key: The unique string identifier for the blob.
+            data: The binary data to store.
+            metadata: Optional JSON-serializable dictionary for metadata.
+        """
+        if not isinstance(data, bytes):
+            raise TypeError("Blob data must be of type bytes.")
+
+        metadata_json = json.dumps(metadata) if metadata else None
+
+        with self._conn:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO beaver_blobs (store_name, key, data, metadata) VALUES (?, ?, ?, ?)",
+                (self._name, key, data, metadata_json),
+            )
+
+    def get(self, key: str) -> Optional[Blob]:
+        """
+        Retrieves a blob from the store.
+
+        Args:
+            key: The unique string identifier for the blob.
+
+        Returns:
+            A Blob object containing the data and metadata, or None if the key is not found.
+        """
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT data, metadata FROM beaver_blobs WHERE store_name = ? AND key = ?",
+            (self._name, key),
+        )
+        result = cursor.fetchone()
+        cursor.close()
+
+        if result is None:
+            return None
+
+        data, metadata_json = result
+        metadata = json.loads(metadata_json) if metadata_json else {}
+
+        return Blob(key=key, data=data, metadata=metadata)
+
+    def delete(self, key: str):
+        """
+        Deletes a blob from the store.
+
+        Raises:
+            KeyError: If the key does not exist in the store.
+        """
+        with self._conn:
+            cursor = self._conn.cursor()
+            cursor.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}'")
+
+    def __contains__(self, key: str) -> bool:
+        """
+        Checks if a key exists in the blob store (e.g., `key in blobs`).
+        """
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT 1 FROM beaver_blobs WHERE store_name = ? AND key = ? LIMIT 1",
+            (self._name, key),
+        )
+        result = cursor.fetchone()
+        cursor.close()
+        return result is not None
+
+    def __iter__(self) -> Iterator[str]:
+        """Returns an iterator over the keys in the blob store."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT key FROM beaver_blobs WHERE store_name = ?", (self._name,)
+        )
+        for row in cursor:
+            yield row["key"]
+        cursor.close()
+
+    def __repr__(self) -> str:
+        return f"BlobManager(name='{self._name}')"

{beaver_db-0.11.0 → beaver_db-0.12.0}/beaver/core.py

@@ -1,10 +1,12 @@
 import sqlite3
 import threading
 
-from .dicts import DictManager
-from .lists import ListManager
+
+from .blobs import BlobManager
 from .channels import ChannelManager
 from .collections import CollectionManager
+from .dicts import DictManager
+from .lists import ListManager
 from .queues import QueueManager
 
 
@@ -38,19 +40,34 @@ class BeaverDB:
     def _create_all_tables(self):
         """Initializes all required tables in the database file."""
         with self._conn:
-            self._create_pubsub_table()
-            self._create_list_table()
+            self._create_ann_deletions_log_table()
+            self._create_ann_id_mapping_table()
+            self._create_ann_indexes_table()
+            self._create_ann_pending_log_table()
+            self._create_blobs_table()
             self._create_collections_table()
+            self._create_dict_table()
+            self._create_edges_table()
             self._create_fts_table()
+            self._create_list_table()
+            self._create_priority_queue_table()
+            self._create_pubsub_table()
             self._create_trigrams_table()
-            self._create_edges_table()
             self._create_versions_table()
-            self._create_dict_table()
-            self._create_priority_queue_table()
-            self._create_ann_indexes_table()
-            self._create_ann_pending_log_table()
-            self._create_ann_deletions_log_table()
-            self._create_ann_id_mapping_table()
+
+    def _create_blobs_table(self):
+        """Creates the table for storing named blobs."""
+        self._conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS beaver_blobs (
+                store_name TEXT NOT NULL,
+                key TEXT NOT NULL,
+                data BLOB NOT NULL,
+                metadata TEXT,
+                PRIMARY KEY (store_name, key)
+            )
+            """
+        )
 
     def _create_ann_indexes_table(self):
         """Creates the table to store the serialized base ANN index."""
@@ -299,3 +316,10 @@ class BeaverDB:
             if name not in self._channels:
                 self._channels[name] = ChannelManager(name, self._conn, self._db_path)
             return self._channels[name]
+
+    def blobs(self, name: str) -> BlobManager:
+        """Returns a wrapper object for interacting with a named blob store."""
+        if not isinstance(name, str) or not name:
+            raise TypeError("Blob store name must be a non-empty string.")
+
+        return BlobManager(name, self._conn)

{beaver_db-0.11.0 → beaver_db-0.12.0}/beaver/dicts.py

@@ -1,8 +1,9 @@
 import json
 import sqlite3
-import time # Add this import
+import time  # Add this import
 from typing import Any, Iterator, Tuple
 
+
 class DictManager:
     """A wrapper providing a Pythonic interface to a dictionary in the database."""
 
@@ -52,14 +53,28 @@ class DictManager:
 
         if expires_at is not None and time.time() > expires_at:
             # Expired: delete the key and raise KeyError
-            cursor.execute("DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?", (self._name, key))
+            cursor.execute(
+                "DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?",
+                (self._name, key),
+            )
             self._conn.commit()
             cursor.close()
-            raise KeyError(f"Key '{key}' not found in dictionary '{self._name}' (expired)")
+            raise KeyError(
+                f"Key '{key}' not found in dictionary '{self._name}' (expired)"
+            )
 
         cursor.close()
         return json.loads(value)
 
+    def pop(self, key: str, default: Any = None):
+        """Deletes an item if it exists and returns its value."""
+        try:
+            value = self[key]
+            del self[key]
+            return value
+        except KeyError:
+            return default
+
     def __delitem__(self, key: str):
         """Deletes a key-value pair (e.g., `del my_dict[key]`)."""
         with self._conn:

{beaver_db-0.11.0 → beaver_db-0.12.0}/beaver_db.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.11.0
+Version: 0.12.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -34,6 +34,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
   - **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces with optional TTL for cache implementations.
   - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
   - **Persistent Priority Queue**: A high-performance, persistent queue that always returns the item with the highest priority, perfect for task management.
+  - **Simple Blob Storage**: A dictionary-like interface for storing medium-sized binary files (like PDFs or images) directly in the database, ensuring transactional integrity with your other data.
   - **High-Performance Vector Storage & Search**: Store vector embeddings and perform fast, crash-safe approximate nearest neighbor searches using a `faiss`-based hybrid index.
   - **Full-Text and Fuzzy Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine, enhanced with optional fuzzy search for typo-tolerant matching.
   - **Knowledge Graph**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -199,30 +200,53 @@ with db.channel("system_events").subscribe() as listener:
         # >> Event received: {'event': 'user_login', 'user_id': 'alice'}
 ```
 
+### 7. Storing User-Uploaded Content
+
+Use the simple blob store to save files like user avatars, attachments, or generated reports directly in the database. This keeps all your data in one portable file.
+
+```python
+attachments = db.blobs("user_uploads")
+
+# Store a user's avatar
+with open("avatar.png", "rb") as f:
+    avatar_bytes = f.read()
+
+attachments.put(
+    key="user_123_avatar.png",
+    data=avatar_bytes,
+    metadata={"mimetype": "image/png"}
+)
+
+# Retrieve it later
+avatar = attachments.get("user_123_avatar.png")
+```
+
 ## More Examples
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`examples/kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
-  - [`examples/list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
-  - [`examples/queue.py`](examples/queue.py): A practical example of using the persistent priority queue for task management.
-  - [`examples/vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
-  - [`examples/fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
-  - [`examples/graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
-  - [`examples/pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
   - [`examples/async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
-  - [`examples/publisher.py`](examples/publisher.py) and [`examples/subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`examples/blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
   - [`examples/cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
-  - [`examples/rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
   - [`examples/fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
-  - [`examples/stress_vectors.py](examples/stress_vectors.py): A stress test for the vector search functionality.
   - [`examples/general_test.py`](examples/general_test.py): A general-purpose test to run all operations randomly which allows testing long-running processes and synchronicity issues.
+  - [`examples/graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+  - [`examples/kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+  - [`examples/list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+  - [`examples/publisher.py`](examples/publisher.py) and [`examples/subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`examples/pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+  - [`examples/queue.py`](examples/queue.py): A practical example of using the persistent priority queue for task management.
+  - [`examples/rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`examples/stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+  - [`examples/vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
 These are some of the features and improvements planned for future releases:
 
   - **Full Async API**: Comprehensive async support with on-demand wrappers for all collections.
+  - **Type Hints**: Pydantic-based type hints for lists, dicts, and queues.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 

{beaver_db-0.11.0 → beaver_db-0.12.0}/beaver_db.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 beaver/__init__.py
+beaver/blobs.py
 beaver/channels.py
 beaver/collections.py
 beaver/core.py

{beaver_db-0.11.0 → beaver_db-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "beaver-db"
-version = "0.11.0"
+version = "0.12.0"
 description = "Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications."
 readme = "README.md"
 requires-python = ">=3.13"