beaver-db 0.16.7__py3-none-any.whl → 0.17.0__py3-none-any.whl

beaver/dicts.py

@@ -3,15 +3,14 @@ import sqlite3
 import time
 from typing import Any, Iterator, Tuple, Type
 
-from .types import JsonSerializable
-
+from .types import JsonSerializable, IDatabase
 
 class DictManager[T]:
     """A wrapper providing a Pythonic interface to a dictionary in the database."""
 
-    def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
+    def __init__(self, name: str, db: IDatabase, model: Type[T] | None = None):
         self._name = name
-        self._conn = conn
+        self._db = db
         self._model = model
 
     def _serialize(self, value: T) -> str:
@@ -40,8 +39,8 @@ class DictManager[T]:
                 raise ValueError("ttl_seconds must be a positive integer.")
             expires_at = time.time() + ttl_seconds
 
-        with self._conn:
-            self._conn.execute(
+        with self._db.connection:
+            self._db.connection.execute(
                 "INSERT OR REPLACE INTO beaver_dicts (dict_name, key, value, expires_at) VALUES (?, ?, ?, ?)",
                 (self._name, key, self._serialize(value), expires_at),
             )
@@ -55,7 +54,7 @@ class DictManager[T]:
 
     def __getitem__(self, key: str) -> T:
         """Retrieves a value for a given key, raising KeyError if expired."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT value, expires_at FROM beaver_dicts WHERE dict_name = ? AND key = ?",
             (self._name, key),
@@ -70,7 +69,7 @@ class DictManager[T]:
 
         if expires_at is not None and time.time() > expires_at:
             # Expired: delete the key and raise KeyError
-            with self._conn:
+            with self._db.connection:
                 cursor.execute(
                     "DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?",
                     (self._name, key),
@@ -94,8 +93,8 @@ class DictManager[T]:
 
     def __delitem__(self, key: str):
         """Deletes a key-value pair (e.g., `del my_dict[key]`)."""
-        with self._conn:
-            cursor = self._conn.cursor()
+        with self._db.connection:
+            cursor = self._db.connection.cursor()
             cursor.execute(
                 "DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?",
                 (self._name, key),
@@ -105,7 +104,7 @@ class DictManager[T]:
 
     def __len__(self) -> int:
         """Returns the number of items in the dictionary."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT COUNT(*) FROM beaver_dicts WHERE dict_name = ?", (self._name,)
         )
@@ -119,7 +118,7 @@ class DictManager[T]:
 
     def keys(self) -> Iterator[str]:
         """Returns an iterator over the dictionary's keys."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT key FROM beaver_dicts WHERE dict_name = ?", (self._name,)
         )
@@ -129,7 +128,7 @@ class DictManager[T]:
 
     def values(self) -> Iterator[T]:
         """Returns an iterator over the dictionary's values."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT value FROM beaver_dicts WHERE dict_name = ?", (self._name,)
         )
@@ -139,7 +138,7 @@ class DictManager[T]:
 
     def items(self) -> Iterator[Tuple[str, T]]:
         """Returns an iterator over the dictionary's items (key-value pairs)."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT key, value FROM beaver_dicts WHERE dict_name = ?", (self._name,)
         )

beaver/lists.py

@@ -2,15 +2,15 @@ import json
 import sqlite3
 from typing import Any, Iterator, Type, Union
 
-from .types import JsonSerializable
+from .types import JsonSerializable, IDatabase
 
 
 class ListManager[T]:
     """A wrapper providing a Pythonic, full-featured interface to a list in the database."""
 
-    def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
+    def __init__(self, name: str, db: IDatabase, model: Type[T] | None = None):
         self._name = name
-        self._conn = conn
+        self._db = db
         self._model = model
 
     def _serialize(self, value: T) -> str:
@@ -27,7 +27,7 @@ class ListManager[T]:
 
     def __len__(self) -> int:
         """Returns the number of items in the list (e.g., `len(my_list)`)."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT COUNT(*) FROM beaver_lists WHERE list_name = ?", (self._name,)
         )
@@ -40,7 +40,7 @@ class ListManager[T]:
         Retrieves an item or slice from the list (e.g., `my_list[0]`, `my_list[1:3]`).
         """
         if isinstance(key, slice):
-            with self._conn:
+            with self._db.connection:
                 start, stop, step = key.indices(len(self))
                 if step != 1:
                     raise ValueError("Slicing with a step is not supported.")
@@ -49,7 +49,7 @@ class ListManager[T]:
                 if limit <= 0:
                     return []
 
-                cursor = self._conn.cursor()
+                cursor = self._db.connection.cursor()
                 cursor.execute(
                     "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT ? OFFSET ?",
                     (self._name, limit, start),
@@ -59,14 +59,14 @@ class ListManager[T]:
                 return results
 
         elif isinstance(key, int):
-            with self._conn:
+            with self._db.connection:
                 list_len = len(self)
                 if key < -list_len or key >= list_len:
                     raise IndexError("List index out of range.")
 
                 offset = key if key >= 0 else list_len + key
 
-                cursor = self._conn.cursor()
+                cursor = self._db.connection.cursor()
                 cursor.execute(
                     "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
                     (self._name, offset),
@@ -83,14 +83,14 @@ class ListManager[T]:
         if not isinstance(key, int):
             raise TypeError("List indices must be integers.")
 
-        with self._conn:
+        with self._db.connection:
             list_len = len(self)
             if key < -list_len or key >= list_len:
                 raise IndexError("List index out of range.")
 
             offset = key if key >= 0 else list_len + key
 
-            cursor = self._conn.cursor()
+            cursor = self._db.connection.cursor()
             # Find the rowid of the item to update
             cursor.execute(
                 "SELECT rowid FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
@@ -112,14 +112,14 @@ class ListManager[T]:
         if not isinstance(key, int):
             raise TypeError("List indices must be integers.")
 
-        with self._conn:
+        with self._db.connection:
             list_len = len(self)
             if key < -list_len or key >= list_len:
                 raise IndexError("List index out of range.")
 
             offset = key if key >= 0 else list_len + key
 
-            cursor = self._conn.cursor()
+            cursor = self._db.connection.cursor()
             # Find the rowid of the item to delete
             cursor.execute(
                 "SELECT rowid FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
@@ -135,7 +135,7 @@ class ListManager[T]:
 
     def __iter__(self) -> Iterator[T]:
         """Returns an iterator for the list."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC",
             (self._name,)
@@ -146,7 +146,7 @@ class ListManager[T]:
 
     def __contains__(self, value: T) -> bool:
         """Checks for the existence of an item in the list (e.g., `'item' in my_list`)."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT 1 FROM beaver_lists WHERE list_name = ? AND item_value = ? LIMIT 1",
             (self._name, self._serialize(value))
@@ -161,7 +161,7 @@ class ListManager[T]:
 
     def _get_order_at_index(self, index: int) -> float:
         """Helper to get the float `item_order` at a specific index."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT item_order FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1 OFFSET ?",
             (self._name, index),
@@ -176,8 +176,8 @@ class ListManager[T]:
 
     def push(self, value: T):
         """Pushes an item to the end of the list."""
-        with self._conn:
-            cursor = self._conn.cursor()
+        with self._db.connection:
+            cursor = self._db.connection.cursor()
             cursor.execute(
                 "SELECT MAX(item_order) FROM beaver_lists WHERE list_name = ?",
                 (self._name,),
@@ -192,8 +192,8 @@ class ListManager[T]:
 
     def prepend(self, value: T):
         """Prepends an item to the beginning of the list."""
-        with self._conn:
-            cursor = self._conn.cursor()
+        with self._db.connection:
+            cursor = self._db.connection.cursor()
             cursor.execute(
                 "SELECT MIN(item_order) FROM beaver_lists WHERE list_name = ?",
                 (self._name,),
@@ -208,7 +208,7 @@ class ListManager[T]:
 
     def insert(self, index: int, value: T):
         """Inserts an item at a specific index."""
-        with self._conn:
+        with self._db.connection:
             list_len = len(self)
             if index <= 0:
                 self.prepend(value)
@@ -222,15 +222,15 @@ class ListManager[T]:
             order_after = self._get_order_at_index(index)
             new_order = order_before + (order_after - order_before) / 2.0
 
-            self._conn.execute(
+            self._db.connection.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
                 (self._name, new_order, self._serialize(value)),
             )
 
     def pop(self) -> T | None:
         """Removes and returns the last item from the list."""
-        with self._conn:
-            cursor = self._conn.cursor()
+        with self._db.connection:
+            cursor = self._db.connection.cursor()
             cursor.execute(
                 "SELECT rowid, item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order DESC LIMIT 1",
                 (self._name,),
@@ -247,8 +247,8 @@ class ListManager[T]:
 
     def deque(self) -> T | None:
         """Removes and returns the first item from the list."""
-        with self._conn:
-            cursor = self._conn.cursor()
+        with self._db.connection:
+            cursor = self._db.connection.cursor()
             cursor.execute(
                 "SELECT rowid, item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT 1",
                 (self._name,),

beaver/logs.py

@@ -8,7 +8,7 @@ from datetime import datetime, timedelta, timezone
 from queue import Empty, Queue
 from typing import Any, AsyncIterator, Callable, Iterator, Type, TypeVar
 
-from .types import JsonSerializable
+from .types import JsonSerializable, IDatabase
 
 
 # A special message object used to signal the iterator to gracefully shut down.
@@ -23,14 +23,14 @@ class LiveIterator[T,R]:
 
     def __init__(
         self,
-        db_path: str,
+        db: IDatabase,
         log_name: str,
         window: timedelta,
         period: timedelta,
         aggregator: Callable[[list[T]], R],
         deserializer: Callable[[str], T],
     ):
-        self._db_path = db_path
+        self._db = db
         self._log_name = log_name
         self._window_duration_seconds = window.total_seconds()
         self._sampling_period_seconds = period.total_seconds()
@@ -43,9 +43,7 @@ class LiveIterator[T,R]:
     def _polling_loop(self):
         """The main loop for the background thread that queries and aggregates data."""
         # Each thread needs its own database connection.
-        thread_conn = sqlite3.connect(self._db_path, check_same_thread=False)
-        thread_conn.row_factory = sqlite3.Row
-
+        thread_conn = self._db.connection
         window_deque: collections.deque[tuple[float, T]] = collections.deque()
         last_seen_timestamp = 0.0
 
@@ -179,13 +177,11 @@ class LogManager[T]:
     def __init__(
         self,
         name: str,
-        conn: sqlite3.Connection,
-        db_path: str,
+        db,
         model: Type[T] | None = None,
     ):
         self._name = name
-        self._conn = conn
-        self._db_path = db_path
+        self._db = db
         self._model = model
 
     def _serialize(self, value: T) -> str:
@@ -215,8 +211,8 @@ class LogManager[T]:
         ts = timestamp or datetime.now(timezone.utc)
         ts_float = ts.timestamp()
 
-        with self._conn:
-            self._conn.execute(
+        with self._db.connection:
+            self._db.connection.execute(
                 "INSERT INTO beaver_logs (log_name, timestamp, data) VALUES (?, ?, ?)",
                 (self._name, ts_float, self._serialize(data)),
             )
@@ -235,7 +231,7 @@ class LogManager[T]:
         start_ts = start.timestamp()
         end_ts = end.timestamp()
 
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT data FROM beaver_logs WHERE log_name = ? AND timestamp BETWEEN ? AND ? ORDER BY timestamp ASC",
             (self._name, start_ts, end_ts),
@@ -265,7 +261,7 @@ class LogManager[T]:
             An iterator that yields the results of the aggregator.
         """
         return LiveIterator(
-            db_path=self._db_path,
+            db=self._db,
             log_name=self._name,
             window=window,
             period=period,

beaver/queues.py

@@ -4,7 +4,7 @@ import sqlite3
 import time
 from typing import Any, Literal, NamedTuple, Type, overload
 
-from .types import JsonSerializable
+from .types import JsonSerializable, IDatabase
 
 
 class QueueItem[T](NamedTuple):
@@ -50,9 +50,9 @@ class QueueManager[T]:
     producer-consumer priority queue.
     """
 
-    def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
+    def __init__(self, name: str, db: IDatabase, model: Type[T] | None = None):
         self._name = name
-        self._conn = conn
+        self._db = db
         self._model = model
 
     def _serialize(self, value: T) -> str:
@@ -77,8 +77,8 @@ class QueueManager[T]:
             data: The JSON-serializable data to store.
             priority: The priority of the item (lower numbers are higher priority).
         """
-        with self._conn:
-            self._conn.execute(
+        with self._db.connection:
+            self._db.connection.execute(
                 "INSERT INTO beaver_priority_queues (queue_name, priority, timestamp, data) VALUES (?, ?, ?, ?)",
                 (self._name, priority, time.time(), self._serialize(data)),
             )
@@ -88,8 +88,8 @@ class QueueManager[T]:
         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()
+        with self._db.connection:
+            cursor = self._db.connection.cursor()
             cursor.execute(
                 """
                 SELECT rowid, priority, timestamp, data
@@ -108,11 +108,11 @@ class QueueManager[T]:
             rowid, priority, timestamp, data = result
 
             if pop:
-                cursor.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
+                self._db.connection.execute("DELETE FROM beaver_priority_queues WHERE rowid = ?", (rowid,))
 
-            return QueueItem(
-                priority=priority, timestamp=timestamp, data=self._deserialize(data)
-            )
+        return QueueItem(
+            priority=priority, timestamp=timestamp, data=self._deserialize(data)
+        )
 
     def peek(self) -> QueueItem[T] | None:
         """
@@ -169,7 +169,7 @@ class QueueManager[T]:
 
     def __len__(self) -> int:
         """Returns the current number of items in the queue."""
-        cursor = self._conn.cursor()
+        cursor = self._db.connection.cursor()
         cursor.execute(
             "SELECT COUNT(*) FROM beaver_priority_queues WHERE queue_name = ?",
             (self._name,),

beaver/server.py

@@ -0,0 +1,132 @@
+try:
+    from fastapi import FastAPI, HTTPException, Body
+    import uvicorn
+except ImportError:
+    raise ImportError(
+        "FastAPI and Uvicorn are required to serve the database. "
+        'Please install them with `pip install "beaver-db[server]"`'
+    )
+from typing import Any
+from .core import BeaverDB
+
+
+def build(db: BeaverDB) -> FastAPI:
+    """
+    Constructs a FastAPI application instance for a given BeaverDB instance.
+
+    Args:
+        db: An active BeaverDB instance.
+
+    Returns:
+        A FastAPI application with all endpoints configured.
+    """
+    app = FastAPI(
+        title="BeaverDB",
+        description="A RESTful API for a BeaverDB instance.",
+        version="0.1.0",
+    )
+
+    # --- Dicts Endpoints ---
+
+    @app.get("/dicts/{name}")
+    def get_all_dict_items(name: str) -> dict:
+        """Retrieves all key-value pairs in a dictionary."""
+        d = db.dict(name)
+        return {k: v for k, v in d.items()}
+
+    @app.get("/dicts/{name}/{key}")
+    def get_dict_item(name: str, key: str) -> Any:
+        """Retrieves the value for a specific key."""
+        d = db.dict(name)
+        try:
+            return d[key]
+        except KeyError:
+            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
+
+    @app.post("/dicts/{name}/{key}")
+    def set_dict_item(name: str, key: str, value: Any = Body(...)):
+        """Sets the value for a specific key."""
+        d = db.dict(name)
+        d[key] = value
+        return {"status": "ok"}
+
+    @app.delete("/dicts/{name}/{key}")
+    def delete_dict_item(name: str, key: str):
+        """Deletes a key-value pair."""
+        d = db.dict(name)
+        try:
+            del d[key]
+            return {"status": "ok"}
+        except KeyError:
+            raise HTTPException(status_code=404, detail=f"Key '{key}' not found in dictionary '{name}'")
+
+    # --- Lists Endpoints ---
+
+    @app.get("/lists/{name}")
+    def get_list(name: str) -> list:
+        """Retrieves all items in the list."""
+        l = db.list(name)
+        return l[:]
+
+    @app.get("/lists/{name}/{index}")
+    def get_list_item(name: str, index: int) -> Any:
+        """Retrieves the item at a specific index."""
+        l = db.list(name)
+        try:
+            return l[index]
+        except IndexError:
+            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+
+    @app.post("/lists/{name}")
+    def push_list_item(name: str, value: Any = Body(...)):
+        """Adds an item to the end of the list."""
+        l = db.list(name)
+        l.push(value)
+        return {"status": "ok"}
+
+    @app.put("/lists/{name}/{index}")
+    def update_list_item(name: str, index: int, value: Any = Body(...)):
+        """Updates the item at a specific index."""
+        l = db.list(name)
+        try:
+            l[index] = value
+            return {"status": "ok"}
+        except IndexError:
+            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+
+    @app.delete("/lists/{name}/{index}")
+    def delete_list_item(name: str, index: int):
+        """Deletes the item at a specific index."""
+        l = db.list(name)
+        try:
+            del l[index]
+            return {"status": "ok"}
+        except IndexError:
+            raise HTTPException(status_code=404, detail=f"Index {index} out of bounds for list '{name}'")
+
+    # TODO: Add endpoints for all BeaverDB modalities
+    # - Queues
+    # - Collections
+    # - Channels
+    # - Logs
+    # - Blobs
+
+    @app.get("/")
+    def read_root():
+        return {"message": "Welcome to the BeaverDB API"}
+
+    return app
+
+
+def serve(db_path: str, host: str, port: int):
+    """
+    Initializes a BeaverDB instance and runs a Uvicorn server for it.
+
+    Args:
+        db_path: The path to the SQLite database file.
+        host: The host to bind the server to.
+        port: The port to run the server on.
+    """
+    db = BeaverDB(db_path)
+    app = build(db)
+    uvicorn.run(app, host=host, port=port)

beaver/types.py

@@ -1,4 +1,5 @@
 import json
+import sqlite3
 from typing import Protocol, Type, runtime_checkable, Self
 
 
@@ -49,3 +50,9 @@ def stub(msg: str):
             raise TypeError(msg)
 
     return Stub()
+
+
+class IDatabase(Protocol):
+    @property
+    def connection(self) -> sqlite3.Connection:
+        ...