beaver-db 0.9.0__py3-none-any.whl → 0.9.2__py3-none-any.whl

beaver/channels.py

@@ -1,14 +1,44 @@
+import asyncio
 import json
 import sqlite3
 import threading
 import time
 from queue import Empty, Queue
-from typing import Any, Iterator, Set
+from typing import Any, AsyncIterator, Iterator, Set
 
 # A special message object used to signal the listener to gracefully shut down.
 _SHUTDOWN_SENTINEL = object()
 
 
+class AsyncSubscriber:
+    """A thread-safe async message receiver for a specific channel subscription."""
+
+    def __init__(self, subscriber: "Subscriber"):
+        self._subscriber = subscriber
+
+    async def __aenter__(self) -> "AsyncSubscriber":
+        """Registers the listener's queue with the channel to start receiving messages."""
+        await asyncio.to_thread(self._subscriber.__enter__)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Unregisters the listener's queue from the channel to stop receiving messages."""
+        await asyncio.to_thread(self._subscriber.__exit__, exc_type, exc_val, exc_tb)
+
+    async def listen(self, timeout: float | None = None) -> AsyncIterator[Any]:
+        """
+        Returns a blocking async iterator that yields messages as they arrive.
+        """
+        while True:
+            try:
+                msg = await asyncio.to_thread(self._subscriber._queue.get, timeout=timeout)
+                if msg is _SHUTDOWN_SENTINEL:
+                    break
+                yield msg
+            except Empty:
+                raise TimeoutError(f"Timeout {timeout}s expired.")
+
+
 class Subscriber:
     """
     A thread-safe message receiver for a specific channel subscription.
@@ -54,6 +84,27 @@ class Subscriber:
             except Empty:
                 raise TimeoutError(f"Timeout {timeout}s expired.")
 
+    def as_async(self) -> "AsyncSubscriber":
+        """Returns an async version of the subscriber."""
+        return AsyncSubscriber(self)
+
+
+class AsyncChannelManager:
+    """The central async hub for a named pub/sub channel."""
+
+    def __init__(self, channel: "ChannelManager"):
+        self._channel = channel
+
+    async def publish(self, payload: Any):
+        """
+        Publishes a JSON-serializable message to the channel asynchronously.
+        """
+        await asyncio.to_thread(self._channel.publish, payload)
+
+    def subscribe(self) -> "AsyncSubscriber":
+        """Creates a new async subscription, returning an AsyncSubscriber context manager."""
+        return self._channel.subscribe().as_async()
+
 
 class ChannelManager:
     """
@@ -183,3 +234,7 @@ class ChannelManager:
                 "INSERT INTO beaver_pubsub_log (timestamp, channel_name, message_payload) VALUES (?, ?, ?)",
                 (time.time(), self._name, json_payload),
             )
+
+    def as_async(self) -> "AsyncChannelManager":
+        """Returns an async version of the channel manager."""
+        return AsyncChannelManager(self)

{beaver_db-0.9.0.dist-info → beaver_db-0.9.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.9.0
+Version: 0.9.2
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -9,10 +9,6 @@ Requires-Dist: numpy>=2.3.3
 Requires-Dist: scipy>=1.16.2
 Dynamic: license-file
 
-I've updated the README to highlight the new high-efficiency, thread-safe, and process-safe pub/sub system. I've also added an example of how you can use it to build real-time, event-driven applications.
-
-Here are the changes:
-
 # beaver 🦫
 
 A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
@@ -31,7 +27,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 ## Core Features
 
-  - **High-Efficiency Pub/Sub**: A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture.
+  - **Sync/Async High-Efficiency Pub/Sub**: A powerful, thread and process-safe publish-subscribe system for real-time messaging with a fan-out architecture. Sync by default, but with an `as_async` wrapper for async applications.
   - **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.
@@ -194,6 +190,7 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
   - [`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/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.

{beaver_db-0.9.0.dist-info → beaver_db-0.9.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
 beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
-beaver/channels.py,sha256=6Fr6uyp_1TtVzNzQobgCa_-c8KS285Z2fyC7OzUOd34,6611
+beaver/channels.py,sha256=jKL1sVLOe_Q_pP0q1-iceZbPe8FOi0EwqJtOMOe96f4,8675
 beaver/collections.py,sha256=R4bVmP37s_ZnCkb3Jdck2H8dRvD3-ihFV4mEsA14YeE,15716
 beaver/core.py,sha256=l5hI55vc2VlF1b_a6CP7ZP5r7H-MQdTNV4zr2lSumcs,7864
 beaver/dicts.py,sha256=y4z632XKWU29ekP_vdFSOP-MAG9Z8b79kBEHA88gO7E,4463
 beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
 beaver/queues.py,sha256=WKpBzlXr9Hp_rOKEs_Y1Tjyj_hWx6ql1uBRKBV7rw8w,2780
-beaver_db-0.9.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.9.0.dist-info/METADATA,sha256=Fd_Qvcs5a_wbCVMCvfmxOXAKBX4FbtQKJwrWwFAxjrE,9732
-beaver_db-0.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.9.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.9.0.dist-info/RECORD,,
+beaver_db-0.9.2.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.9.2.dist-info/METADATA,sha256=vUT6BRbtpQ-lY_FatTiNx2z8ZaxDwOepFPuhF-NRHvA,9725
+beaver_db-0.9.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.9.2.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.9.2.dist-info/RECORD,,