beaver-db 0.14.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

beaver/queues.py

@@ -1,3 +1,4 @@
+import asyncio
 import json
 import sqlite3
 import time
@@ -14,8 +15,34 @@ class QueueItem[T](NamedTuple):
     data: T
 
 
+class AsyncQueueManager[T]:
+    """An async wrapper for the producer-consumer priority queue."""
+
+    def __init__(self, queue: "QueueManager[T]"):
+        self._queue = queue
+
+    async def put(self, data: T, priority: float):
+        """Asynchronously adds an item to the queue with a specific priority."""
+        await asyncio.to_thread(self._queue.put, data, priority)
+
+    @overload
+    async def get(self, block: Literal[True] = True, timeout: float | None = None) -> QueueItem[T]: ...
+    @overload
+    async def get(self, block: Literal[False]) -> QueueItem[T]: ...
+
+    async def get(self, block: bool = True, timeout: float | None = None) -> QueueItem[T]:
+        """
+        Asynchronously and atomically retrieves the highest-priority item.
+        This method will run the synchronous blocking logic in a separate thread.
+        """
+        return await asyncio.to_thread(self._queue.get, block=block, timeout=timeout)
+
+
 class QueueManager[T]:
-    """A wrapper providing a Pythonic interface to a persistent priority queue."""
+    """
+    A wrapper providing a Pythonic interface to a persistent, multi-process
+    producer-consumer priority queue.
+    """
 
     def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
         self._name = name
@@ -50,19 +77,13 @@ class QueueManager[T]:
                 (self._name, priority, time.time(), self._serialize(data)),
             )
 
-    @overload
-    def get(self, safe:Literal[True]) -> QueueItem[T] | None: ...
-    @overload
-    def get(self) -> QueueItem[T]: ...
-
-    def get(self, safe:bool=False) -> QueueItem[T] | None:
+    def _get_item_atomically(self) -> QueueItem[T] | None:
         """
-        Atomically retrieves and removes the highest-priority item from the queue.
-        If the queue is empty, returns None if safe is True, otherwise (the default) raises IndexError.
+        Performs a single, atomic attempt to retrieve and remove the
+        highest-priority item from the queue. Returns None if the queue is empty.
         """
         with self._conn:
             cursor = self._conn.cursor()
-            # The compound index on (queue_name, priority, timestamp) makes this query efficient.
             cursor.execute(
                 """
                 SELECT rowid, priority, timestamp, data
@@ -76,19 +97,61 @@ class QueueManager[T]:
             result = cursor.fetchone()
 
             if result is None:
-                if safe:
-                    return None
-                else:
-                    raise IndexError("No item available.")
+                return None
 
             rowid, priority, timestamp, data = result
-            # Delete the retrieved item to ensure it's processed only once.
             cursor.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
 
             return QueueItem(
                 priority=priority, timestamp=timestamp, data=self._deserialize(data)
             )
 
+    @overload
+    def get(self, block: Literal[True] = True, timeout: float | None = None) -> QueueItem[T]: ...
+    @overload
+    def get(self, block: Literal[False]) -> QueueItem[T]: ...
+
+    def get(self, block: bool = True, timeout: float | None = None) -> QueueItem[T]:
+        """
+        Atomically retrieves and removes the highest-priority item from the queue.
+
+        This method is designed for producer-consumer patterns and can block
+        until an item becomes available.
+
+        Args:
+            block: If True (default), the method will wait until an item is available.
+            timeout: If `block` is True, this specifies the maximum number of seconds
+                     to wait. If the timeout is reached, `TimeoutError` is raised.
+
+        Returns:
+            A `QueueItem` containing the retrieved data.
+
+        Raises:
+            IndexError: If `block` is False and the queue is empty.
+            TimeoutError: If `block` is True and the timeout expires.
+        """
+        if not block:
+            item = self._get_item_atomically()
+            if item is None:
+                raise IndexError("get from an empty queue.")
+            return item
+
+        start_time = time.time()
+        while True:
+            item = self._get_item_atomically()
+            if item is not None:
+                return item
+
+            if timeout is not None and (time.time() - start_time) > timeout:
+                raise TimeoutError("Timeout expired while waiting for an item.")
+
+            # Sleep for a short interval to avoid busy-waiting and consuming CPU.
+            time.sleep(0.1)
+
+    def as_async(self) -> "AsyncQueueManager[T]":
+        """Returns an async version of the queue manager."""
+        return AsyncQueueManager(self)
+
     def __len__(self) -> int:
         """Returns the current number of items in the queue."""
         cursor = self._conn.cursor()

{beaver_db-0.14.0.dist-info → beaver_db-0.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.14.0
+Version: 0.15.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -31,12 +31,13 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
   - **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.
+  - **Persistent Priority Queue**: A high-performance, persistent priority queue perfect for task orchestration across multiple processes. Also with optional async support.
   - **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.
   - **Single-File & Portable**: All data is stored in a single SQLite file, making it incredibly easy to move, back up, or embed in your application.
+  - **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.
 
 ## How Beaver is Implemented
 
@@ -260,21 +261,24 @@ Basically everywhere you can store or get some object in BeaverDB, you can use a
 
 For more in-depth examples, check out the scripts in the `examples/` directory:
 
-  - [`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/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.
+  - [`async_pubsub.py`](examples/async_pubsub.py): A demonstration of the asynchronous wrapper for the publish/subscribe system.
+  - [`blobs.py`](examples/blobs.py): Demonstrates how to store and retrieve binary data in the database.
+  - [`cache.py`](examples/cache.py): A practical example of using a dictionary with TTL as a cache for API calls.
+  - [`fts.py`](examples/fts.py): A detailed look at full-text search, including targeted searches on specific metadata fields.
+  - [`fuzzy.py`](examples/fuzzy.py): Demonstrates fuzzy search capabilities for text search.
+  - [`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.
+  - [`graph.py`](examples/graph.py): Shows how to create relationships between documents and perform multi-hop graph traversals.
+  - [`kvstore.py`](examples/kvstore.py): A comprehensive demo of the namespaced dictionary feature.
+  - [`list.py`](examples/list.py): Shows the full capabilities of the persistent list, including slicing and in-place updates.
+  - [`pqueue.py`](examples/pqueue.py): A practical example of using the persistent priority queue for task management.
+  - [`producer_consumer.py`](examples/producer_consumer.py): A demonstration of the distributed task queue system in a multi-process environment.
+  - [`publisher.py`](examples/publisher.py) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+  - [`pubsub.py`](examples/pubsub.py): A demonstration of the synchronous, thread-safe publish/subscribe system in a single process.
+  - [`rerank.py`](examples/rerank.py): Shows how to combine results from vector and text search for more refined results.
+  - [`stress_vectors.py`](examples/stress_vectors.py): A stress test for the vector search functionality.
+  - [`textual_chat.py`](examples/textual_chat.py): A chat application built with `textual` and `beaver` to illustrate the use of several primitives (lists, dicts, and channels) at the same time.
+  - [`type_hints.py](examples/type_hints.py): Shows how to use type hints with `beaver` to get better IDE support and type safety.
+  - [`vector.py`](examples/vector.py): Demonstrates how to index and search vector embeddings, including upserts.
 
 ## Roadmap
 
@@ -283,7 +287,6 @@ 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:
 
   - **Async API**: Extend the async support with on-demand wrappers for all features besides channels.
-  - **Type Hints**: Extend type hints for channels and documents.
 
 Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 

{beaver_db-0.14.0.dist-info → beaver_db-0.15.0.dist-info}/RECORD

@@ -5,11 +5,11 @@ beaver/collections.py,sha256=Uz241TSs0xRABPYeKenDYmkbaM0PKfvcBX5j0lMzMMA,24306
 beaver/core.py,sha256=zAPlym786_sOpRkP6LfKkd5BH2DXPwdOPTdAkSYojvQ,12469
 beaver/dicts.py,sha256=1BQ9A_cMkJ7l5ayWbDG-4Wi3WtQ-9BKd7Wj_CB7dGlU,5410
 beaver/lists.py,sha256=0LT2XjuHs8pDgvW48kk_lfVc-Y-Ulmym0gcVWRESPtA,9708
-beaver/queues.py,sha256=SFu2180ONotnZOcYp1Ld5d8kxzYxaOlgDdcr70ZoBL8,3641
+beaver/queues.py,sha256=IQoeNhcYrVZTuH_4bWhtiEa-EYbFx_2iVKkR254XPnE,5953
 beaver/types.py,sha256=65rDdj97EegghEkKCNjI67bPYtTTI_jyB-leHdIypx4,1249
 beaver/vectors.py,sha256=j7RL2Y_xMAF2tPTi6E2LdJqZerSQXlnEQJOGZkefTsA,18358
-beaver_db-0.14.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.14.0.dist-info/METADATA,sha256=vnsXMoILckkEY7YPrppHQbkvK4MP4qfNQLTjvjcEGBU,15621
-beaver_db-0.14.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.14.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.14.0.dist-info/RECORD,,
+beaver_db-0.15.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.15.0.dist-info/METADATA,sha256=bbeIcJMu28cG3KLBiraaGHEypZJ0h52JIMGBj0u85_U,16101
+beaver_db-0.15.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.15.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.15.0.dist-info/RECORD,,