beaver-db 0.18.6__tar.gz → 0.19.1__tar.gz

{beaver_db-0.18.6 → beaver_db-0.19.1}/.gitignore

@@ -10,3 +10,4 @@ wheels/
 .venv
 *.db*
 .env
+.issues-sync-state

{beaver_db-0.18.6 → beaver_db-0.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.18.6
+Version: 0.19.1
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
@@ -36,7 +36,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `beaver` is the **B**ackend for **E**mbedded, **A**ll-in-one **V**ector, **E**ntity, and **R**elationship storage. It's a simple, local, and embedded database designed to manage complex, modern data types without requiring a database server, built on top of SQLite.
 
-> If you like beaver's minimalist, no-bullshit philosophy, check out [castor](https://github.com/apiad/castor) for an equally minimalistic approach to task orchestration.
+> If you like beaver's minimalist, no-bullshit philosophy, check out [castor](https://github.com/apiad/castor "null") for an equally minimalistic approach to task orchestration.
 
 ## Design Philosophy
 
@@ -55,6 +55,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 priority queue perfect for task orchestration across multiple processes. Also with optional async support.
+- **Inter-Process Locking**: A robust, deadlock-proof, and fair (FIFO) distributed lock (`db.lock()`) to coordinate multiple processes and prevent race conditions.
 - **Time-Indexed Log for Monitoring**: A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view of the most recent events for real-time dashboards.
 - **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 (Optional)**: Store vector embeddings and perform fast approximate nearest neighbor searches using a `faiss`-based hybrid index.
@@ -103,14 +104,14 @@ pip install "beaver-db[full]"
 ```
 
 ### Running with Docker
+
 For a fully embedded and lightweight solution, you can run the BeaverDB REST API server using Docker. This is the easiest way to get a self-hosted instance up and running.
 
 ```bash
 docker run -p 8000:8000 -v $(pwd)/data:/app apiad/beaverdb
 ```
 
-This command will start the BeaverDB server, and your database file will be stored in the data directory on your host machine. You can access the API at <http://localhost:8000>.
-
+This command will start the BeaverDB server, and your database file will be stored in the data directory on your host machine. You can access the API at [http://localhost:8000](http://localhost:8000").
 
 ## Quickstart
 
@@ -172,12 +173,12 @@ Here are a couple of examples using `curl`:
 
 ```bash
 # Set a value in the 'app_config' dictionary
-curl -X PUT http://127.0.0.1:8000/dicts/app_config/api_key
+curl -X PUT [http://127.0.0.1:8000/dicts/app_config/api_key](http://127.0.0.1:8000/dicts/app_config/api_key)
      -H "Content-Type: application/json"
      -d '"your-secret-api-key"'
 
 # Get the value back
-curl http://127.0.0.1:8000/dicts/app_config/api_key
+curl [http://127.0.0.1:8000/dicts/app_config/api_key](http://127.0.0.1:8000/dicts/app_config/api_key)
 # Output: "your-secret-api-key"
 ```
 
@@ -341,6 +342,34 @@ for summary in live_summary:
     print(f"Live Stats (10s window): Count={summary['count']}, Mean={summary['mean']:.2f}")
 ```
 
+### 9. Coordinate Distributed Web Scrapers
+
+Run multiple scraper processes in parallel and use `db.lock()` to coordinate them. You can ensure only one process refreshes a shared API token or sitemap, preventing race conditions and rate-limiting.
+
+```python
+import time
+
+scrapers_state = db.dict("scraper_state")
+
+last_refresh = scrapers_state.get("last_sitemap_refresh", 0)
+if time.time() - last_refresh > 3600: # Only refresh once per hour
+    try:
+        # Try to get a lock to refresh the shared sitemap, but don't wait long
+        with db.lock("refresh_sitemap", timeout=1):
+            # We got the lock. Check if it's time to refresh.
+            print(f"PID {os.getpid()} is refreshing the sitemap...")
+            scrapers_state["sitemap"] = ["/page1", "/page2"] # Your fetch_sitemap()
+            scrapers_state["last_sitemap_refresh"] = time.time()
+
+    except TimeoutError:
+        # Another process is already refreshing, so we can skip
+        print(f"PID {os.getpid()} letting other process handle refresh.")
+
+# All processes can now safely use the shared sitemap
+sitemap = scrapers_state.get("sitemap")
+# ... proceed with scraping ...
+```
+
 ## Type-Safe Data Models
 
 For enhanced data integrity and a better developer experience, BeaverDB supports type-safe operations for all modalities. By associating a model with these data structures, you get automatic serialization and deserialization, complete with autocompletion in your editor.
@@ -348,7 +377,6 @@ For enhanced data integrity and a better developer experience, BeaverDB supports
 This feature is designed to be flexible and works seamlessly with two kinds of models:
 
 - **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
-
 - **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
 
 
@@ -393,10 +421,11 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 - [`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.
+- [`locks.py`](examples/lock_test.py): Demonstrates how to use the inter-process lock to create critical sections.
 - [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
 - [`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.p) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+- [`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.
@@ -410,14 +439,13 @@ 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-Safe Models**: Enhance built-in `Model` to handle recursive and embedded types.
-- **Drop-in REST Client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but instead of a local database file, it works against a REST API server.
+- **[Issue #2](https://github.com/syalia-srl/beaver/issues/2) Comprehensive async wrappers**: Extend the async support with on-demand wrappers for all data structures, not just channels.
+- **[Issue #9](https://github.com/syalia-srl/beaver/issues/2) Type-safe wrappers based on Pydantic-compatible models**: Enhance the built-in `Model` to handle recursive and embedded types and provide Pydantic compatibility.
+- **[Issue #6](https://github.com/syalia-srl/beaver/issues/2) Drop-in replacement for Beaver REST server client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but works against the REST API server.
+- **[Issue #7](https://github.com/syalia-srl/beaver/issues/2) Replace `faiss` with simpler, linear `numpy` vectorial search**: Investigate removing the heavy `faiss` dependency in favor of a pure `numpy` implementation to improve installation simplicity, accepting a trade-off in search performance for O(1) installation.
 
-Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
 If you think of something that would make `beaver` more useful for your use case, please open an issue and/or submit a pull request.
-
 ## License
 
 This project is licensed under the MIT License.

{beaver_db-0.18.6 → beaver_db-0.19.1}/README.md

@@ -11,7 +11,7 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 
 `beaver` is the **B**ackend for **E**mbedded, **A**ll-in-one **V**ector, **E**ntity, and **R**elationship storage. It's a simple, local, and embedded database designed to manage complex, modern data types without requiring a database server, built on top of SQLite.
 
-> If you like beaver's minimalist, no-bullshit philosophy, check out [castor](https://github.com/apiad/castor) for an equally minimalistic approach to task orchestration.
+> If you like beaver's minimalist, no-bullshit philosophy, check out [castor](https://github.com/apiad/castor "null") for an equally minimalistic approach to task orchestration.
 
 ## Design Philosophy
 
@@ -30,6 +30,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 priority queue perfect for task orchestration across multiple processes. Also with optional async support.
+- **Inter-Process Locking**: A robust, deadlock-proof, and fair (FIFO) distributed lock (`db.lock()`) to coordinate multiple processes and prevent race conditions.
 - **Time-Indexed Log for Monitoring**: A specialized data structure for structured, time-series logs. Query historical data by time range or create a live, aggregated view of the most recent events for real-time dashboards.
 - **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 (Optional)**: Store vector embeddings and perform fast approximate nearest neighbor searches using a `faiss`-based hybrid index.
@@ -78,14 +79,14 @@ pip install "beaver-db[full]"
 ```
 
 ### Running with Docker
+
 For a fully embedded and lightweight solution, you can run the BeaverDB REST API server using Docker. This is the easiest way to get a self-hosted instance up and running.
 
 ```bash
 docker run -p 8000:8000 -v $(pwd)/data:/app apiad/beaverdb
 ```
 
-This command will start the BeaverDB server, and your database file will be stored in the data directory on your host machine. You can access the API at <http://localhost:8000>.
-
+This command will start the BeaverDB server, and your database file will be stored in the data directory on your host machine. You can access the API at [http://localhost:8000](http://localhost:8000").
 
 ## Quickstart
 
@@ -147,12 +148,12 @@ Here are a couple of examples using `curl`:
 
 ```bash
 # Set a value in the 'app_config' dictionary
-curl -X PUT http://127.0.0.1:8000/dicts/app_config/api_key
+curl -X PUT [http://127.0.0.1:8000/dicts/app_config/api_key](http://127.0.0.1:8000/dicts/app_config/api_key)
      -H "Content-Type: application/json"
      -d '"your-secret-api-key"'
 
 # Get the value back
-curl http://127.0.0.1:8000/dicts/app_config/api_key
+curl [http://127.0.0.1:8000/dicts/app_config/api_key](http://127.0.0.1:8000/dicts/app_config/api_key)
 # Output: "your-secret-api-key"
 ```
 
@@ -316,6 +317,34 @@ for summary in live_summary:
     print(f"Live Stats (10s window): Count={summary['count']}, Mean={summary['mean']:.2f}")
 ```
 
+### 9. Coordinate Distributed Web Scrapers
+
+Run multiple scraper processes in parallel and use `db.lock()` to coordinate them. You can ensure only one process refreshes a shared API token or sitemap, preventing race conditions and rate-limiting.
+
+```python
+import time
+
+scrapers_state = db.dict("scraper_state")
+
+last_refresh = scrapers_state.get("last_sitemap_refresh", 0)
+if time.time() - last_refresh > 3600: # Only refresh once per hour
+    try:
+        # Try to get a lock to refresh the shared sitemap, but don't wait long
+        with db.lock("refresh_sitemap", timeout=1):
+            # We got the lock. Check if it's time to refresh.
+            print(f"PID {os.getpid()} is refreshing the sitemap...")
+            scrapers_state["sitemap"] = ["/page1", "/page2"] # Your fetch_sitemap()
+            scrapers_state["last_sitemap_refresh"] = time.time()
+
+    except TimeoutError:
+        # Another process is already refreshing, so we can skip
+        print(f"PID {os.getpid()} letting other process handle refresh.")
+
+# All processes can now safely use the shared sitemap
+sitemap = scrapers_state.get("sitemap")
+# ... proceed with scraping ...
+```
+
 ## Type-Safe Data Models
 
 For enhanced data integrity and a better developer experience, BeaverDB supports type-safe operations for all modalities. By associating a model with these data structures, you get automatic serialization and deserialization, complete with autocompletion in your editor.
@@ -323,7 +352,6 @@ For enhanced data integrity and a better developer experience, BeaverDB supports
 This feature is designed to be flexible and works seamlessly with two kinds of models:
 
 - **Pydantic Models**: If you're already using Pydantic, your `BaseModel` classes will work out of the box.
-
 - **Lightweight `beaver.Model`**: For a zero-dependency solution, you can inherit from the built-in `beaver.Model` class, which is a standard Python class with serialization methods automatically included.
 
 
@@ -368,10 +396,11 @@ For more in-depth examples, check out the scripts in the `examples/` directory:
 - [`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.
+- [`locks.py`](examples/lock_test.py): Demonstrates how to use the inter-process lock to create critical sections.
 - [`logs.py`](examples/logs.py): A short example showing how to build a realtime dashboard with the logging feature.
 - [`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.p) and [`subscriber.py`](examples/subscriber.py): A pair of examples demonstrating inter-process message passing with the publish/subscribe system.
+- [`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.
@@ -385,14 +414,13 @@ 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-Safe Models**: Enhance built-in `Model` to handle recursive and embedded types.
-- **Drop-in REST Client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but instead of a local database file, it works against a REST API server.
+- **[Issue #2](https://github.com/syalia-srl/beaver/issues/2) Comprehensive async wrappers**: Extend the async support with on-demand wrappers for all data structures, not just channels.
+- **[Issue #9](https://github.com/syalia-srl/beaver/issues/2) Type-safe wrappers based on Pydantic-compatible models**: Enhance the built-in `Model` to handle recursive and embedded types and provide Pydantic compatibility.
+- **[Issue #6](https://github.com/syalia-srl/beaver/issues/2) Drop-in replacement for Beaver REST server client**: Implement a `BeaverClient` class that acts as a drop-in replacement for `BeaverDB` but works against the REST API server.
+- **[Issue #7](https://github.com/syalia-srl/beaver/issues/2) Replace `faiss` with simpler, linear `numpy` vectorial search**: Investigate removing the heavy `faiss` dependency in favor of a pure `numpy` implementation to improve installation simplicity, accepting a trade-off in search performance for O(1) installation.
 
-Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
 
 If you think of something that would make `beaver` more useful for your use case, please open an issue and/or submit a pull request.
-
 ## License
 
 This project is licensed under the MIT License.

{beaver_db-0.18.6 → beaver_db-0.19.1}/beaver/__init__.py

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

{beaver_db-0.18.6 → beaver_db-0.19.1}/beaver/core.py

@@ -9,6 +9,7 @@ from .channels import ChannelManager
 from .collections import CollectionManager, Document
 from .dicts import DictManager
 from .lists import ListManager
+from .locks import LockManager
 from .logs import LogManager
 from .queues import QueueManager
 
@@ -99,6 +100,35 @@ class BeaverDB:
             self._create_pubsub_table()
             self._create_trigrams_table()
             self._create_versions_table()
+            self._create_locks_table()
+
+    def _create_locks_table(self):  # <-- Add this new method
+        """Creates the table for managing inter-process lock waiters."""
+        self.connection.execute(
+            """
+            CREATE TABLE IF NOT EXISTS beaver_lock_waiters (
+                lock_name TEXT NOT NULL,
+                waiter_id TEXT NOT NULL,
+                requested_at REAL NOT NULL,
+                expires_at REAL NOT NULL,
+                PRIMARY KEY (lock_name, requested_at)
+            )
+            """
+        )
+        # Index for fast cleanup of expired locks
+        self.connection.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_lock_expires
+            ON beaver_lock_waiters (lock_name, expires_at)
+            """
+        )
+        # Index for fast deletion by the lock holder
+        self.connection.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_lock_waiter_id
+            ON beaver_lock_waiters (lock_name, waiter_id)
+            """
+        )
 
     def _create_logs_table(self):
         """Creates the table for time-indexed logs."""
@@ -421,3 +451,24 @@ class BeaverDB:
             raise TypeError("The model parameter must be a JsonSerializable class.")
 
         return LogManager(name, self, self._db_path, model)
+
+    def lock(
+        self,
+        name: str,
+        timeout: float | None = None,
+        lock_ttl: float = 60.0,
+        poll_interval: float = 0.1,
+    ) -> LockManager:
+        """
+        Returns an inter-process lock manager for a given lock name.
+
+        Args:
+            name: The unique name of the lock (e.g., "run_compaction").
+            timeout: Max seconds to wait to acquire the lock.
+                    If None, it will wait forever.
+            lock_ttl: Max seconds the lock can be held. If the process crashes,
+                    the lock will auto-expire after this time.
+            poll_interval: Seconds to wait between polls. Shorter intervals
+                        are more responsive but create more DB I/O.
+        """
+        return LockManager(self, name, timeout, lock_ttl, poll_interval)

beaver_db-0.19.1/beaver/locks.py

@@ -0,0 +1,173 @@
+import random
+import time
+import os
+import uuid
+from typing import Optional
+from .types import IDatabase
+
+
+class LockManager:
+    """
+    An inter-process, deadlock-proof, and fair (FIFO) lock built on SQLite.
+
+    This class provides a context manager (`with` statement) to ensure that
+    only one process (among many) can enter a critical section of code at a
+    time.
+
+    It is "fair" because it uses a FIFO queue (based on insertion time).
+    It is "deadlock-proof" because locks have a Time-To-Live (TTL); if a
+    process crashes, its lock will eventually expire and be cleaned up.
+    """
+
+    def __init__(
+        self,
+        db: IDatabase,
+        name: str,
+        timeout: Optional[float] = None,
+        lock_ttl: float = 60.0,
+        poll_interval: float = 0.1,
+    ):
+        """
+        Initializes the lock manager.
+
+        Args:
+            db: The BeaverDB instance.
+            name: The unique name of the lock (e.g., "run_compaction").
+            timeout: Max seconds to wait to acquire the lock. If None,
+                     it will wait forever.
+            lock_ttl: Max seconds the lock can be held. If the process crashes,
+                      the lock will auto-expire after this time.
+            poll_interval: Seconds to wait between polls.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("Lock name must be a non-empty string.")
+        if lock_ttl <= 0:
+            raise ValueError("lock_ttl must be positive.")
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be positive.")
+
+        self._db = db
+        self._lock_name = name
+        self._timeout = timeout
+        self._lock_ttl = lock_ttl
+        self._poll_interval = poll_interval
+        # A unique ID for this specific lock instance across all processes
+        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":
+        """
+        Blocks until the lock is acquired or the timeout expires.
+
+        Raises:
+            TimeoutError: If the lock cannot be acquired within the specified timeout.
+        """
+        if self._acquired:
+            # This instance already holds the lock
+            return self
+
+        start_time = time.time()
+        requested_at = time.time()
+        expires_at = requested_at + self._lock_ttl
+
+        conn = self._db.connection
+
+        try:
+            # 1. Add self to the FIFO queue (atomic)
+            with conn:
+                conn.execute(
+                    """
+                    INSERT INTO beaver_lock_waiters (lock_name, waiter_id, requested_at, expires_at)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (self._lock_name, self._waiter_id, requested_at, expires_at),
+                )
+
+            # 2. Start polling loop
+            while True:
+                with conn:
+                    # 3. Clean up expired locks from crashed processes
+                    now = time.time()
+                    conn.execute(
+                        "DELETE FROM beaver_lock_waiters WHERE lock_name = ? AND expires_at < ?",
+                        (self._lock_name, now),
+                    )
+
+                    # 4. Check who is at the front of the queue
+                    cursor = conn.cursor()
+                    cursor.execute(
+                        """
+                        SELECT waiter_id FROM beaver_lock_waiters
+                        WHERE lock_name = ?
+                        ORDER BY requested_at ASC
+                        LIMIT 1
+                        """,
+                        (self._lock_name,),
+                    )
+                    result = cursor.fetchone()
+                    cursor.close()
+
+                    if result and result["waiter_id"] == self._waiter_id:
+                        # We are at the front. We own the lock.
+                        self._acquired = True
+                        return self
+
+                # 5. Check for timeout
+                if self._timeout is not None:
+                    if (time.time() - start_time) > self._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."
+                        )
+
+                # 6. Wait politely before polling again
+                # Add +/- 10% jitter to the poll interval to avoid thundering herd
+                jitter = self._poll_interval * 0.1
+                sleep_time = random.uniform(
+                    self._poll_interval - jitter, self._poll_interval + jitter
+                )
+                time.sleep(sleep_time)
+
+        except Exception:
+            # If anything goes wrong, try to clean up our waiter entry
+            self._release_from_queue()
+            raise
+
+    def _release_from_queue(self):
+        """
+        Atomically removes this instance's entry from the waiter queue.
+        This is a best-effort, fire-and-forget operation.
+        """
+        try:
+            with self._db.connection:
+                self._db.connection.execute(
+                    "DELETE FROM beaver_lock_waiters WHERE lock_name = ? AND waiter_id = ?",
+                    (self._lock_name, self._waiter_id),
+                )
+        except Exception:
+            # Don't raise errors during release/cleanup
+            pass
+
+    def release(self):
+        """
+        Releases the lock, allowing the next process in the queue to acquire it.
+        This is safe to call multiple times.
+        """
+        if not self._acquired:
+            # We don't hold the lock, so nothing to do.
+            return
+
+        self._release_from_queue()
+        self._acquired = False
+
+    def __enter__(self) -> "LockManager":
+        """Acquires the lock when 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 __repr__(self) -> str:
+        return f"LockManager(name='{self._lock_name}', acquired={self._acquired})"

beaver_db-0.19.1/examples/locks.py

@@ -0,0 +1,52 @@
+import os
+import time
+from datetime import datetime
+from beaver import BeaverDB
+
+DB_PATH = "lock_test.db"
+LOCK_NAME = "critical_task_lock"
+SHARED_LOG_NAME = "shared_work_log"
+
+
+def run_lock_demo():
+    """
+    A test function that demonstrates the inter-process lock.
+    """
+    pid = os.getpid()
+    db = BeaverDB(DB_PATH)
+
+    while True:
+        print(f"[PID {pid}] Trying to acquire lock '{LOCK_NAME}' (timeout=5s)...")
+
+        try:
+            # Try to acquire the lock with a 5-second timeout
+            # We use a short poll_interval for a responsive test
+            with db.lock(LOCK_NAME, timeout=5.0, poll_interval=0.2):
+                # --- CRITICAL SECTION START ---
+                # Only one process can be in this block at a time.
+                print(f"--------------------------------------------------")
+                print(f"[PID {pid}] ✅ Lock ACQUIRED.")
+                log_time = datetime.now().isoformat()
+
+                print(f"[PID {pid}] 👷 Starting work (simulating 3 seconds)...")
+                time.sleep(3)
+                print(f"[PID {pid}] 🏁 Work finished.")
+
+                print(f"[PID {pid}] 🔑 Releasing lock.")
+                # --- CRITICAL SECTION END ---
+                # Lock is automatically released when the 'with' block exits
+                print(f"--------------------------------------------------")
+
+        except TimeoutError:
+            # This happens if we couldn't get the lock within the 5-second timeout
+            print(f"[PID {pid}] ❌ Lock acquisition TIMED OUT. Another process is busy.")
+        except Exception as e:
+            print(f"[PID {pid}] An error occurred: {e}")
+
+
+if __name__ == "__main__":
+    print("--- BeaverDB Lock Test ---")
+    print(f"To test, run this script in 2 or more terminals at the same time.")
+    print("Database file: " + DB_PATH)
+    print("------------------------\n")
+    run_lock_demo()

beaver_db-0.19.1/issues/2-comprehensive-async-wrappers.md

@@ -0,0 +1,52 @@
+---
+number: 2
+title: "Comprehensive async wrappers"
+state: open
+labels:
+---
+
+## Tasks
+
+- [ ] Dictionary wrapper
+- [ ] List wrapper
+- [ ] Queue wrapper
+- [ ] Collections wrapper
+
+### 1. Concept
+
+A **Comprehensive Async API** will be introduced to allow seamless integration of `beaver-db` into modern `asyncio`-based applications. Instead of making the core library asynchronous, this feature will provide an elegant, on-demand way to get an async-compatible version of any core `beaver-db` object.
+
+The core of the library will remain fully synchronous, respecting its design principle of a "Synchronous Core with Async Potential". The async functionality will be provided through thin, type-safe wrappers that run the blocking database calls in a background thread pool, ensuring the `asyncio` event loop is never blocked.
+
+### 2. Use Cases
+
+This feature is essential for developers using modern Python frameworks and for building highly concurrent applications:
+
+* **Modern Web Backends**: Natively integrate `beaver-db` with frameworks like FastAPI or Starlette without needing to manage a separate thread pool executor for database calls.
+* **High-Concurrency Tools**: Use `beaver-db` in applications that manage thousands of concurrent I/O operations (like websocket servers, scrapers, or chatbots) without sacrificing responsiveness.
+* **Ergonomic Developer Experience**: Allow developers working in an `async` codebase to use the familiar `await` syntax for all database operations, leading to cleaner and more consistent code.
+
+### 3. Proposed API
+
+The API is designed to be flexible and explicit, allowing the developer to "opt-in" to the async version of an object whenever needed.
+
+* `docs = db.collection("articles")`: The developer starts with the standard, synchronous object.
+* `async_docs = docs.as_async()`: A new `.as_async()` method on any synchronous wrapper (`CollectionWrapper`, `ListWrapper`, etc.) will return a parallel `Async` version of that object.
+* `await async_docs.index(my_doc)`: All methods on the `Async` wrapper are `async def` and must be awaited. The method names are identical to their synchronous counterparts, providing a clean and consistent API.
+* `await docs.as_async().search(vector)`: For one-off calls, the developer can chain the methods for a concise, non-blocking operation.
+
+### 4. Implementation Design: Type-Safe Parallel Wrappers
+
+The implementation will prioritize correctness, flexibility, and compatibility with developer tooling.
+
+1.  **Parallel Class Hierarchy**: For each core wrapper (e.g., `CollectionWrapper`), there will be a corresponding `AsyncCollectionWrapper`. This new class will hold a reference to the original synchronous object.
+2.  **Explicit `async def` Methods**: Every method on the `Async` wrapper will be explicitly defined with `async def`. This ensures that type checkers (like Mypy) and IDEs can correctly identify them as awaitable, preventing common runtime errors and providing proper autocompletion.
+3.  **`asyncio.to_thread` Execution**: The implementation of each `async` method will simply call the corresponding synchronous method on the original object using `asyncio.to_thread`. This delegates the blocking I/O to a background thread, keeping the `asyncio` event loop free.
+
+### 5. Alignment with Philosophy
+
+This feature perfectly aligns with the library's guiding principles:
+
+* **Synchronous Core with Async Potential**: It adds a powerful `async` layer without altering the simple, robust, and synchronous foundation of the library.
+* **Simplicity and Pythonic API**: The `.as_async()` method is an intuitive and Pythonic way to opt into asynchronous behavior, and the chained-call syntax is elegant and clean.
+* **Developer Experience**: By ensuring the `async` wrappers are explicitly typed, the design prioritizes compatibility with modern developer tools, preventing bugs and improving productivity.