beaver-db 0.1.0__py3-none-any.whl

beaver/__init__.py

@@ -0,0 +1 @@
+from .core import BeaverDB, Subscriber

beaver/core.py

@@ -0,0 +1,163 @@
+import asyncio
+import json
+import sqlite3
+import time
+from typing import Any, AsyncIterator
+
+# --- SQL Schema ---
+# These statements are executed once to set up the database.
+
+PUBSUB_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS _beaver_pubsub_log (
+    timestamp REAL PRIMARY KEY,
+    channel_name TEXT NOT NULL,
+    message_payload TEXT NOT NULL
+);
+"""
+
+PUBSUB_INDEX_SQL = """
+CREATE INDEX IF NOT EXISTS _beaver_idx_pubsub_channel_timestamp
+ON _beaver_pubsub_log (channel_name, timestamp);
+"""
+
+
+class Subscriber(AsyncIterator):
+    """
+    A stateful, async context manager for receiving messages from a channel.
+
+    This object is returned by `BeaverDB.subscribe()` and is designed to
+    be used with `async with` and `async for`.
+    """
+    def __init__(self, db_path: str, channel_name: str, poll_interval: float = 0.1):
+        self._db_path = db_path
+        self._channel = channel_name
+        self._poll_interval = poll_interval
+        self._queue = asyncio.Queue()
+        self._last_seen_timestamp = time.time()
+        self._polling_task = None
+
+    async def _poll_for_messages(self):
+        """A background task that polls SQLite for new messages."""
+        while True:
+            try:
+                # Run the synchronous DB query in a thread to avoid blocking asyncio
+                new_messages = await asyncio.to_thread(
+                    self._fetch_new_messages_from_db
+                )
+
+                if new_messages:
+                    for timestamp, payload_str in new_messages:
+                        payload = json.loads(payload_str)
+                        await self._queue.put(payload)
+                        self._last_seen_timestamp = timestamp
+
+                await asyncio.sleep(self._poll_interval)
+            except asyncio.CancelledError:
+                # Gracefully exit when the task is cancelled
+                break
+            except Exception as e:
+                # In a real app, you'd add more robust logging/error handling
+                print(f"ERROR: Pub/sub polling task failed: {e}")
+                await asyncio.sleep(self._poll_interval * 5) # Back off on error
+
+    def _fetch_new_messages_from_db(self) -> list[tuple[float, str]]:
+        """The actual synchronous database query using sqlite3."""
+        # Each call in a separate thread gets its own connection object.
+        with sqlite3.connect(self._db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT timestamp, message_payload FROM _beaver_pubsub_log "
+                "WHERE channel_name = ? AND timestamp > ? "
+                "ORDER BY timestamp ASC",
+                (self._channel, self._last_seen_timestamp)
+            )
+            return cursor.fetchall()
+
+    async def __aenter__(self):
+        """Starts the background task when entering an 'async with' block."""
+        if not self._polling_task:
+            self._polling_task = asyncio.create_task(self._poll_for_messages())
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Stops the background task when exiting the 'async with' block."""
+        if self._polling_task:
+            self._polling_task.cancel()
+            await asyncio.gather(self._polling_task, return_exceptions=True)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> Any:
+        """Allows 'async for' to pull messages from the internal queue."""
+        return await self._queue.get()
+
+
+class BeaverDB:
+    """
+    A single-file, multi-modal database for Python.
+
+    Currently provides asynchronous pub/sub functionality using the standard
+    sqlite3 library.
+    """
+    def __init__(self, db_path: str = "beaver.db"):
+        """
+        Initializes the database.
+
+        Args:
+            db_path: The path to the SQLite database file.
+        """
+        self.db_path = db_path
+        self._setup_database()
+
+    def _setup_database(self):
+        """Creates the necessary tables and indices if they don't exist."""
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(PUBSUB_TABLE_SQL)
+            cursor.execute(PUBSUB_INDEX_SQL)
+            conn.commit()
+
+    async def publish(self, channel_name: str, payload: Any):
+        """
+        Publishes a JSON-serializable message to a channel.
+
+        Args:
+            channel_name: The name of the channel.
+            payload: A JSON-serializable Python object (e.g., dict, list).
+        """
+        if not isinstance(channel_name, str) or not channel_name:
+            raise ValueError("Channel name must be a non-empty string.")
+
+        try:
+            json_payload = json.dumps(payload)
+        except TypeError as e:
+            raise TypeError("Message payload must be JSON-serializable.") from e
+
+        # Run the blocking DB write in a thread to keep this method non-blocking
+        await asyncio.to_thread(
+            self._write_publish_to_db, channel_name, json_payload
+        )
+
+    def _write_publish_to_db(self, channel_name: str, json_payload: str):
+        """The synchronous part of the publish operation using sqlite3."""
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "INSERT INTO _beaver_pubsub_log (timestamp, channel_name, message_payload) "
+                "VALUES (?, ?, ?)",
+                (time.time(), channel_name, json_payload)
+            )
+            conn.commit()
+
+    def subscribe(self, channel_name: str) -> Subscriber:
+        """
+        Subscribes to a channel.
+
+        Returns a 'Subscriber' object that can be used in an 'async with'
+        block and `async for` loop to receive messages.
+
+        Args:
+            channel_name: The name of the channel to subscribe to.
+        """
+        return Subscriber(self.db_path, channel_name)

beaver_db-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: beaver-db
+Version: 0.1.0
+Summary: Asynchronous, embedded, modern DB based on SQLite.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# beaver 🦫
+
+A single-file, multi-modal database for Python, built with the standard sqlite3 library.
+
+`beaver` is the **B**ackend for **E**mbedded **A**synchronous **V**ector & **E**vent **R**etrieval. It's an industrious, all-in-one database designed to manage complex, modern data types without leaving the comfort of a single file.
+
+This project is currently in its initial phase, with the core asynchronous pub/sub functionality fully implemented.
+
+## Core Features (Current)
+
+- **Zero Dependencies:** Built using only the standard Python `sqlite3` and `asyncio` libraries. No external packages to install.
+- **Async Pub/Sub:** A fully asynchronous, Redis-like publish-subscribe system for real-time messaging between components of your application.
+- **Single-File & Persistent:** All data is stored in a single SQLite file, making it incredibly portable and easy to back up. Your event log persists across application restarts.
+- **Works with Existing Databases:** `beaver` can be pointed at an existing SQLite file and will create its tables without disturbing other data.
+
+## Use Cases
+
+I built `beaver` to have a local, embedded database for building small AI-powered projects without having to pay for a server-based database.
+
+Examples include:
+
+- Streaming messages and tokens from a local FastAPI to a local Streamlit app.
+- Storing user files for Retrieval Augmented Generation in single-user applications.
+
+## Installation
+
+To use `beaver`, just run `pip install beaver-db` and import the main class.
+
+```python
+import asyncio
+from beaver import BeaverDB
+
+
+# --- Example Usage ---
+async def listener(db: BeaverDB):
+    """A sample task that listens for messages."""
+    print("LISTENER: Waiting for messages on the 'system_events' channel...")
+    try:
+        async with db.subscribe("system_events") as subscriber:
+            async for message in subscriber:
+                print(f"LISTENER: Received -> {message}")
+    except asyncio.CancelledError:
+        print("LISTENER: Shutting down.")
+
+
+async def publisher(db: BeaverDB):
+    """A sample task that publishes messages."""
+    print("PUBLISHER: Ready to send events.")
+    await asyncio.sleep(1) # Give the listener a moment to start
+
+    print("PUBLISHER: Sending user login event.")
+    await db.publish(
+        "system_events",
+        {"event": "user_login", "username": "alice", "status": "success"}
+    )
+
+    await asyncio.sleep(2)
+
+    print("PUBLISHER: Sending system alert.")
+    await db.publish(
+        "system_events",
+        {"event": "system_alert", "level": "warning", "detail": "CPU usage at 85%"}
+    )
+    await asyncio.sleep(1)
+
+
+async def main():
+    """Runs the listener and publisher concurrently."""
+    db = BeaverDB("demo.db")
+
+    # Run both tasks and wait for them to complete
+    listener_task = asyncio.create_task(listener(db))
+    publisher_task = asyncio.create_task(publisher(db))
+
+    await asyncio.sleep(5) # Let them run for a bit
+    listener_task.cancel() # Cleanly shut down the listener
+    await asyncio.gather(listener_task, publisher_task, return_exceptions=True)
+    print("\nDemo finished.")
+
+
+if __name__ == "__main__":
+    # To run this demo, save the file as beaver.py and run `python beaver.py`
+    print("--- BeaverDB Pub/Sub Demo ---")
+    asyncio.run(main())
+```
+
+## Roadmap
+
+`beaver` aims to be a complete, self-contained data toolkit for modern Python applications. The following features are planned for future releases, all accessible through a high-level API while still allowing direct SQL access:
+
+- **Vector Storage & Search:** Store numpy vector embeddings alongside your data and perform efficient k-nearest neighbor (k-NN) searches.
+- **Persistent Key-Value Store:** A simple get/set interface for storing configuration, session data, or any other JSON-serializable object.
+- **JSON Document Store with Full-Text Search:** Store flexible JSON documents and get powerful full-text search across all text fields by default, powered by SQLite's FTS5 extension.
+- **Standard Relational Interface:** While beaver provides high-level features, you will always be able to use the underlying SQLite connection for normal relational tasks, such as creating and managing users or products tables with standard SQL.
+
+## Performance
+
+Despite its local, embedded nature, `beaver` is highly performant by small use cases. Here are some metrics, measured on a single laptop, Intel Core i7, 7th generation.
+
+- Process 100,000 messages (1000 messages times 100 asynchronous clients) in less than 30 seconds, giving over 3K messages per second with an average latency of only 100 ms (time elapsed between message generation and client processing).
+
+## Why Beaver?
+
+Beavers are nature's engineers. They build a single, robust, and complex home—the lodge—from many different materials.
+
+Similarly, beaver builds a powerful, multi-modal database but contains it all within a single, self-contained file. It's an industrious, no-nonsense tool for building modern applications.
+
+## License
+
+This project is licensed under the MIT License.

beaver_db-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+beaver/__init__.py,sha256=pE1JdpHVni2Hv6igs5VrKPlHkkKMik3ZiwhR23KRBkk,38
+beaver/core.py,sha256=gWuuPwpT7yWgOulv_uwhOvJniltFO8K5-dfqjfA0jNk,5888
+beaver_db-0.1.0.dist-info/METADATA,sha256=b0gaV6IuXw2F_B4NOjKAP6Wj7dzHi7DjIYYg-0R_Q1Q,5243
+beaver_db-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.1.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.1.0.dist-info/RECORD,,

beaver_db-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

beaver_db-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+beaver