beaver-db 0.19.2__tar.gz → 0.19.3__tar.gz

{beaver_db-0.19.2 → beaver_db-0.19.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.19.2
+Version: 0.19.3
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/__init__.py

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

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/blobs.py

@@ -1,8 +1,8 @@
 import json
 import sqlite3
 from typing import Any, Dict, Iterator, NamedTuple, Optional, Type, TypeVar
-
 from .types import JsonSerializable, IDatabase
+from .locks import LockManager
 
 
 class Blob[M](NamedTuple):
@@ -16,10 +16,13 @@ class Blob[M](NamedTuple):
 class BlobManager[M]:
     """A wrapper providing a Pythonic interface to a blob store in the database."""
 
+# In beaver/blobs.py, inside class BlobManager[M]:
     def __init__(self, name: str, db: IDatabase, model: Type[M] | None = None):
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__blob__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: M) -> str | None:
         """Serializes the given value to a JSON string."""
@@ -135,3 +138,35 @@ class BlobManager[M]:
 
     def __repr__(self) -> str:
         return f"BlobManager(name='{self._name}')"
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "BlobManager[M]":
+        """
+        Acquires an inter-process lock on this blob store, blocking until acquired.
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this blob store.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "BlobManager[M]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/collections.py

@@ -3,15 +3,16 @@ import sqlite3
 import threading
 import uuid
 from enum import Enum
-from typing import Any, Iterator, List, Literal, Tuple, Type, TypeVar
+from typing import Any, Iterator, List, Literal, Tuple, Type, TypeVar, Optional
 from .types import Model, stub, IDatabase
+from .locks import LockManager
 
 try:
     import numpy as np
     from .vectors import VectorIndex
 except ImportError:
-    np = stub("This feature requires to install beaver-db[faiss]")()
-    VectorIndex = stub("This feature requires to install beaver-db[faiss]")
+    np = stub("This feature requires to install beaver-db[vector]")()
+    VectorIndex = stub("This feature requires to install beaver-db[vector]")
 
 # --- Fuzzy Search Helper Functions ---
 
@@ -135,6 +136,9 @@ class CollectionManager[D: Document]:
         self._compaction_lock = threading.Lock()
         self._compaction_thread: threading.Thread | None = None
 
+        lock_name = f"__lock__collection__{name}"
+        self._lock = LockManager(db, lock_name)
+
     def _flatten_metadata(self, metadata: dict, prefix: str = "") -> dict[str, Any]:
         """Flattens a nested dictionary for indexing."""
         flat_dict = {}
@@ -643,6 +647,38 @@ class CollectionManager[D: Document]:
         cursor.close()
         return count
 
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "CollectionManager[D]":
+        """
+        Acquires an inter-process lock on this collection, blocking until acquired.
+        This guarantees exclusive access for multi-step atomic operations
+        (e.g., index + connect).
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout, lock_ttl=lock_ttl, poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this collection.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "CollectionManager[D]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()
+
 
 def rerank[D: Document](
     *results: list[D], weights: list[float] | None = None, k: int = 60

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/dicts.py

@@ -1,9 +1,9 @@
 import json
 import sqlite3
 import time
-from typing import Any, Iterator, Tuple, Type
-
+from typing import Any, Iterator, Tuple, Type, Optional
 from .types import JsonSerializable, IDatabase
+from .locks import LockManager
 
 class DictManager[T]:
     """A wrapper providing a Pythonic interface to a dictionary in the database."""
@@ -12,6 +12,8 @@ class DictManager[T]:
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__dict__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
@@ -147,4 +149,35 @@ class DictManager[T]:
         cursor.close()
 
     def __repr__(self) -> str:
-        return f"DictManager(name='{self._name}')"
+        return f"DictManager(name='{self._name}')"
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "DictManager[T]":
+        """
+        Acquires an inter-process lock on this dictionary, blocking until acquired.
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this dictionary.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "DictManager[T]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/lists.py

@@ -1,8 +1,8 @@
 import json
 import sqlite3
-from typing import Any, Iterator, Type, Union
-
+from typing import Any, Iterator, Type, Union, Optional
 from .types import JsonSerializable, IDatabase
+from .locks import LockManager
 
 
 class ListManager[T]:
@@ -12,6 +12,8 @@ class ListManager[T]:
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__list__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
@@ -261,4 +263,36 @@ class ListManager[T]:
             cursor.execute(
                 "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
             )
-            return self._deserialize(value_to_return)
+            return self._deserialize(value_to_return)
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "ListManager[T]":
+        """
+        Acquires an inter-process lock on this list, blocking until acquired.
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this list, allowing the next waiting process access.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "ListManager[T]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/locks.py

@@ -55,7 +55,11 @@ class LockManager:
         self._waiter_id = f"pid:{os.getpid()}:id:{uuid.uuid4()}"
         self._acquired = False  # State to track if this instance holds the lock
 
-    def acquire(self) -> "LockManager":
+    def acquire(self,
+                timeout: float|None = None,
+        lock_ttl: float |None = None,
+        poll_interval: float |None = None,
+        ) -> "LockManager":
         """
         Blocks until the lock is acquired or the timeout expires.
 
@@ -66,9 +70,18 @@ class LockManager:
             # This instance already holds the lock
             return self
 
+        if timeout is None:
+            timeout = self._timeout
+
+        if lock_ttl is None:
+            lock_ttl = self._lock_ttl
+
+        if poll_interval is None:
+            poll_interval = self._poll_interval
+
         start_time = time.time()
         requested_at = time.time()
-        expires_at = requested_at + self._lock_ttl
+        expires_at = requested_at + lock_ttl
 
         conn = self._db.connection
 
@@ -113,19 +126,19 @@ class LockManager:
                         return self
 
                 # 5. Check for timeout
-                if self._timeout is not None:
-                    if (time.time() - start_time) > self._timeout:
+                if timeout is not None:
+                    if (time.time() - start_time) > timeout:
                         # We timed out. Remove ourselves from the queue and raise.
                         self._release_from_queue()
                         raise TimeoutError(
-                            f"Failed to acquire lock '{self._lock_name}' within {self._timeout}s."
+                            f"Failed to acquire lock '{self._lock_name}' within {timeout}s."
                         )
 
                 # 6. Wait politely before polling again
                 # Add +/- 10% jitter to the poll interval to avoid thundering herd
-                jitter = self._poll_interval * 0.1
+                jitter = poll_interval * 0.1
                 sleep_time = random.uniform(
-                    self._poll_interval - jitter, self._poll_interval + jitter
+                    poll_interval - jitter, poll_interval + jitter
                 )
                 time.sleep(sleep_time)
 

{beaver_db-0.19.2 → beaver_db-0.19.3}/beaver/queues.py

@@ -2,10 +2,9 @@ import asyncio
 import json
 import sqlite3
 import time
-from typing import Any, Literal, NamedTuple, Type, overload
-
+from typing import Any, Literal, NamedTuple, Type, overload, Optional
 from .types import JsonSerializable, IDatabase
-
+from .locks import LockManager
 
 class QueueItem[T](NamedTuple):
     """A data class representing a single item retrieved from the queue."""
@@ -54,6 +53,8 @@ class QueueManager[T]:
         self._name = name
         self._db = db
         self._model = model
+        lock_name = f"__lock__queue__{name}"
+        self._lock = LockManager(db, lock_name)
 
     def _serialize(self, value: T) -> str:
         """Serializes the given value to a JSON string."""
@@ -184,3 +185,37 @@ class QueueManager[T]:
 
     def __repr__(self) -> str:
         return f"QueueManager(name='{self._name}')"
+
+    def acquire(
+        self,
+        timeout: Optional[float] = None,
+        lock_ttl: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+    ) -> "QueueManager[T]":
+        """
+        Acquires an inter-process lock on this queue, blocking until acquired.
+        This ensures that a sequence of operations (e.g., batch-getting tasks)
+        is performed atomically without interruption from other processes.
+
+        Parameters override the default settings of the underlying LockManager.
+        """
+        self._lock.acquire(
+            timeout=timeout,
+            lock_ttl=lock_ttl,
+            poll_interval=poll_interval
+        )
+        return self
+
+    def release(self):
+        """
+        Releases the inter-process lock on this queue.
+        """
+        self._lock.release()
+
+    def __enter__(self) -> "QueueManager[T]":
+        """Acquires the lock upon entering a 'with' statement."""
+        return self.acquire()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Releases the lock when exiting a 'with' statement."""
+        self.release()

beaver_db-0.19.3/issues/10-expose-dblock-functionality-on-all-high-level-data-managers.md

@@ -0,0 +1,86 @@
+---
+number: 10
+title: "Expose `db.lock()` functionality on all high-level data managers"
+state: open
+labels:
+---
+
+### 1. Concept
+
+This feature proposes adding explicit, inter-process synchronization to all core state-mutating data managers: `DictManager`, `ListManager`, `CollectionManager`, **`QueueManager`**, and `BlobManager`.
+
+This will be achieved by:
+
+1.  Making each manager class a **Python context manager** (implementing `__enter__` and `__exit__`).
+2.  Adding public `acquire()` and `release()` methods to each manager.
+3.  Internally, these methods will be thin wrappers around the existing `db.lock()` primitive, using a reserved naming convention (e.g., `__lock__dict__<name>`).
+
+This will allow users to perform complex, multi-step operations on a single data structure as a process-safe, atomic unit.
+
+### 2. Use Cases
+
+* **Atomic Read-Modify-Write (Dicts/Blobs):** Guarantee that a process can safely read, modify, and write a value back without another process interfering.
+* **Batch Task Processing (Queues):** Allow a worker to **atomically retrieve a batch of multiple tasks** from the queue (e.g., calling `q.get()` five times) without another worker jumping in and stealing tasks in the middle of the batch operation.
+* **List Manipulation (Lists):** Safely perform multi-step modifications like checking list length, popping the last item, and prepending a new item without race conditions.
+* **Consistent State for Collections (Collections):** A process could lock a collection to perform a series of related operations (e.g., `index`, `drop`, and `connect`) and ensure that other processes only see the final, consistent state.
+
+### 3. Proposed API
+
+The primary change would be enabling a `with` statement directly on the manager object.
+
+```python
+db = BeaverDB("my.db")
+
+# Example for a Dictionary (Atomic Read-Modify-Write)
+try:
+    with db.dict("config", timeout=5) as config:
+        count = config.get("counter", 0)
+        count += 1
+        config["counter"] = count
+except TimeoutError:
+    print("Could not acquire lock for config.")
+
+# Example for a Queue (Atomic Batch Processing)
+try:
+    with db.queue("tasks", timeout=10) as q:
+        task1 = q.get()
+        task2 = q.get()
+        print(f"Retrieved two tasks atomically: {task1} and {task2}")
+except IndexError:
+    print("Queue did not have two tasks.")
+except TimeoutError:
+    print("Could not acquire lock for queue.")
+```
+
+### 4. Implementation Design (High-Level)
+
+**Manager `__init__` Modification:**
+
+* The `__init__` method for all targeted managers (`DictManager`, `ListManager`, `CollectionManager`, **`QueueManager`**, and `BlobManager`) will be updated.
+* Each manager will initialize and store an internal `LockManager` instance, which is provided by `db.lock()`.
+* The lock name will use a standardized internal format based on the manager type and the manager's name, e.g., `f"__lock__queue__{self._name}"`.
+
+**Lock Methods Implementation:**
+
+* `acquire(self, timeout=None, ...)`: Calls `self._lock.acquire(timeout=timeout, ...)` internally.
+* `release(self)`: Calls `self._lock.release()` internally.
+* `__enter__(self)`: Calls `self.acquire()`.
+* `__exit__(self, exc_type, exc_val, exc_tb)`: Calls `self.release()`.
+
+**Targeted Manager Classes:**
+
+* `DictManager` (`beaver/dicts.py`)
+* `ListManager` (`beaver/lists.py`)
+* `QueueManager` (`beaver/queues.py`)
+* `CollectionManager` (`beaver/collections.py`)
+* `BlobManager` (`beaver/blobs.py`)
+
+**Exclusions:** `ChannelManager` and `LogManager` will **not** be modified, as their core write operations are already atomic, and imposing a lock would create an unnecessary performance bottleneck for their high-concurrency design.
+
+### 5. Alignment with Philosophy
+
+This feature aligns with `beaver-db`'s core principles:
+
+* **Simplicity and Pythonic API:** Provides the most intuitive `with` statement syntax for concurrency control.
+* **Developer Experience:** Solves complex multi-process problems (like batch race conditions) with a simple, high-level primitive.
+* **Synchronous Core:** Builds entirely on the existing, dependency-free `db.lock()` primitive, maintaining the project's architectural integrity.

beaver_db-0.19.3/issues/closed/11-a-new-issue-for-gabriel.md

@@ -0,0 +1,8 @@
+---
+number: 11
+title: "A new issue for Gabriel"
+state: closed
+labels:
+---
+
+This is a test issue.

{beaver_db-0.19.2 → beaver_db-0.19.3}/pyproject.toml

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