beaver-db 0.11.1__py3-none-any.whl → 0.12.0__py3-none-any.whl

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/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.1.dist-info → beaver_db-0.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.11.1
+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/async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for 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/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/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/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/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/cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
+  - [`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/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/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.1.dist-info → beaver_db-0.12.0.dist-info}/RECORD

@@ -1,13 +1,14 @@
 beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
+beaver/blobs.py,sha256=5yVDzWyqi6Fur-2r0gaeIjEKj9fUPXb9hPulCTknJJI,3355
 beaver/channels.py,sha256=jKL1sVLOe_Q_pP0q1-iceZbPe8FOi0EwqJtOMOe96f4,8675
 beaver/collections.py,sha256=CXWB8xlyazdJpnhizRkmGmLdN3yt3M2BYNFwr2Ijbas,23896
-beaver/core.py,sha256=BQsYUA99U2ZT8mXbkBidzVpmTI9KPaF19efASCHCXyM,10569
+beaver/core.py,sha256=YAi5VAMsqS0JiydchjKVPbL0A5EL9m5f_gA3n5awnr0,11360
 beaver/dicts.py,sha256=EFlrSr7oFVt0lfuEX-PsdHnJXKC6cTcgbD7Lh2gID8s,4805
 beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
 beaver/queues.py,sha256=WKpBzlXr9Hp_rOKEs_Y1Tjyj_hWx6ql1uBRKBV7rw8w,2780
 beaver/vectors.py,sha256=j7RL2Y_xMAF2tPTi6E2LdJqZerSQXlnEQJOGZkefTsA,18358
-beaver_db-0.11.1.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.11.1.dist-info/METADATA,sha256=o74KW8nGarOJqStI-YCff1XWj3jV2FB3qEwffyIEJXs,12929
-beaver_db-0.11.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.11.1.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.11.1.dist-info/RECORD,,
+beaver_db-0.12.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.12.0.dist-info/METADATA,sha256=iF5vN61PiYiNqNsm2bk3oqA-9hiSFM5jheNjPN7uPts,13847
+beaver_db-0.12.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.12.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.12.0.dist-info/RECORD,,