beaver-db 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

beaver/__init__.py

@@ -1,2 +1,3 @@
 from .core import BeaverDB
-from .collections import Document, WalkDirection
+from .types import Model
+from .collections import Document, WalkDirection

beaver/core.py

@@ -1,7 +1,7 @@
 import sqlite3
 import threading
 
-
+from .types import JsonSerializable
 from .blobs import BlobManager
 from .channels import ChannelManager
 from .collections import CollectionManager
@@ -274,19 +274,31 @@ class BeaverDB:
 
         return DictManager(name, self._conn)
 
-    def list(self, name: str) -> ListManager:
-        """Returns a wrapper object for interacting with a named list."""
+    def list[T](self, name: str, model: type[T] | None = None) -> ListManager[T]:
+        """
+        Returns a wrapper object for interacting with a named list.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
         if not isinstance(name, str) or not name:
             raise TypeError("List name must be a non-empty string.")
 
+        if model and not isinstance(model, JsonSerializable):
+            raise TypeError("The model parameter must be a JsonSerializable class.")
+
         return ListManager(name, self._conn)
 
-    def queue(self, name: str) -> QueueManager:
-        """Returns a wrapper object for interacting with a persistent priority queue."""
+    def queue[T](self, name: str, model: type[T] | None = None) -> QueueManager[T]:
+        """
+        Returns a wrapper object for interacting with a persistent priority queue.
+        If model is defined, it should be a type used for automatic (de)serialization.
+        """
         if not isinstance(name, str) or not name:
             raise TypeError("Queue name must be a non-empty string.")
 
-        return QueueManager(name, self._conn)
+        if model and not isinstance(model, JsonSerializable):
+            raise TypeError("The model parameter must be a JsonSerializable class.")
+
+        return QueueManager(name, self._conn, model)
 
     def collection(self, name: str) -> CollectionManager:
         """

beaver/dicts.py

@@ -1,21 +1,38 @@
 import json
 import sqlite3
-import time  # Add this import
-from typing import Any, Iterator, Tuple
+import time
+from typing import Any, Iterator, Tuple, Type
 
+from .types import JsonSerializable
 
-class DictManager:
+
+class DictManager[T]:
     """A wrapper providing a Pythonic interface to a dictionary in the database."""
 
-    def __init__(self, name: str, conn: sqlite3.Connection):
+    def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
         self._name = name
         self._conn = conn
+        self._model = model
+
+    def _serialize(self, value: T) -> str:
+        """Serializes the given value to a JSON string."""
+        if isinstance(value, JsonSerializable):
+            return value.model_dump_json()
+
+        return json.dumps(value)
+
+    def _deserialize(self, value: str) -> T:
+        """Deserializes a JSON string into the specified model or a generic object."""
+        if self._model:
+            return self._model.model_validate_json(value)
+
+        return json.loads(value)
 
-    def set(self, key: str, value: Any, ttl_seconds: int | None = None):
+    def set(self, key: str, value: T, ttl_seconds: int | None = None):
         """Sets a value for a key, with an optional TTL."""
         self.__setitem__(key, value, ttl_seconds=ttl_seconds)
 
-    def __setitem__(self, key: str, value: Any, ttl_seconds: int | None = None):
+    def __setitem__(self, key: str, value: T, ttl_seconds: int | None = None):
         """Sets a value for a key (e.g., `my_dict[key] = value`)."""
         expires_at = None
         if ttl_seconds is not None:
@@ -26,17 +43,17 @@ class DictManager:
         with self._conn:
             self._conn.execute(
                 "INSERT OR REPLACE INTO beaver_dicts (dict_name, key, value, expires_at) VALUES (?, ?, ?, ?)",
-                (self._name, key, json.dumps(value), expires_at),
+                (self._name, key, self._serialize(value), expires_at),
             )
 
-    def get(self, key: str, default: Any = None) -> Any:
+    def get(self, key: str, default: Any = None) -> T | Any:
         """Gets a value for a key, with a default if it doesn't exist or is expired."""
         try:
             return self[key]
         except KeyError:
             return default
 
-    def __getitem__(self, key: str) -> Any:
+    def __getitem__(self, key: str) -> T:
         """Retrieves a value for a given key, raising KeyError if expired."""
         cursor = self._conn.cursor()
         cursor.execute(
@@ -53,20 +70,20 @@ class DictManager:
 
         if expires_at is not None and time.time() > expires_at:
             # Expired: delete the key and raise KeyError
-            cursor.execute(
-                "DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?",
-                (self._name, key),
-            )
-            self._conn.commit()
+            with self._conn:
+                cursor.execute(
+                    "DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?",
+                    (self._name, key),
+                )
             cursor.close()
             raise KeyError(
                 f"Key '{key}' not found in dictionary '{self._name}' (expired)"
             )
 
         cursor.close()
-        return json.loads(value)
+        return self._deserialize(value)
 
-    def pop(self, key: str, default: Any = None):
+    def pop(self, key: str, default: Any = None) -> T | Any:
         """Deletes an item if it exists and returns its value."""
         try:
             value = self[key]
@@ -110,25 +127,25 @@ class DictManager:
             yield row["key"]
         cursor.close()
 
-    def values(self) -> Iterator[Any]:
+    def values(self) -> Iterator[T]:
         """Returns an iterator over the dictionary's values."""
         cursor = self._conn.cursor()
         cursor.execute(
             "SELECT value FROM beaver_dicts WHERE dict_name = ?", (self._name,)
         )
         for row in cursor:
-            yield json.loads(row["value"])
+            yield self._deserialize(row["value"])
         cursor.close()
 
-    def items(self) -> Iterator[Tuple[str, Any]]:
+    def items(self) -> Iterator[Tuple[str, T]]:
         """Returns an iterator over the dictionary's items (key-value pairs)."""
         cursor = self._conn.cursor()
         cursor.execute(
             "SELECT key, value FROM beaver_dicts WHERE dict_name = ?", (self._name,)
         )
         for row in cursor:
-            yield (row["key"], json.loads(row["value"]))
+            yield (row["key"], self._deserialize(row["value"]))
         cursor.close()
 
     def __repr__(self) -> str:
-        return f"DictWrapper(name='{self._name}')"
+        return f"DictManager(name='{self._name}')"

beaver/lists.py

@@ -1,13 +1,29 @@
 import json
 import sqlite3
-from typing import Any, Union, Iterator
+from typing import Any, Iterator, Type, Union
 
-class ListManager:
+from .types import JsonSerializable
+
+
+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):
+    def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
         self._name = name
         self._conn = conn
+        self._model = model
+
+    def _serialize(self, value: T) -> str:
+        """Serializes the given value to a JSON string."""
+        if isinstance(value, JsonSerializable):
+            return value.model_dump_json()
+        return json.dumps(value)
+
+    def _deserialize(self, value: str) -> T:
+        """Deserializes a JSON string into the specified model or a generic object."""
+        if self._model:
+            return self._model.model_validate_json(value)
+        return json.loads(value)
 
     def __len__(self) -> int:
         """Returns the number of items in the list (e.g., `len(my_list)`)."""
@@ -19,7 +35,7 @@ class ListManager:
         cursor.close()
         return count
 
-    def __getitem__(self, key: Union[int, slice]) -> Any:
+    def __getitem__(self, key: Union[int, slice]) -> T | list[T]:
         """
         Retrieves an item or slice from the list (e.g., `my_list[0]`, `my_list[1:3]`).
         """
@@ -37,7 +53,7 @@ class ListManager:
                 "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC LIMIT ? OFFSET ?",
                 (self._name, limit, start),
             )
-            results = [json.loads(row["item_value"]) for row in cursor.fetchall()]
+            results = [self._deserialize(row["item_value"]) for row in cursor.fetchall()]
             cursor.close()
             return results
 
@@ -55,12 +71,12 @@ class ListManager:
             )
             result = cursor.fetchone()
             cursor.close()
-            return json.loads(result["item_value"]) if result else None
+            return self._deserialize(result["item_value"])
 
         else:
             raise TypeError("List indices must be integers or slices.")
 
-    def __setitem__(self, key: int, value: Any):
+    def __setitem__(self, key: int, value: T):
         """Sets the value of an item at a specific index (e.g., `my_list[0] = 'new'`)."""
         if not isinstance(key, int):
             raise TypeError("List indices must be integers.")
@@ -86,7 +102,7 @@ class ListManager:
             # Update the value for that specific row
             cursor.execute(
                 "UPDATE beaver_lists SET item_value = ? WHERE rowid = ?",
-                (json.dumps(value), rowid_to_update)
+                (self._serialize(value), rowid_to_update)
             )
 
     def __delitem__(self, key: int):
@@ -115,7 +131,7 @@ class ListManager:
             # Delete that specific row
             cursor.execute("DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,))
 
-    def __iter__(self) -> Iterator[Any]:
+    def __iter__(self) -> Iterator[T]:
         """Returns an iterator for the list."""
         cursor = self._conn.cursor()
         cursor.execute(
@@ -123,15 +139,15 @@ class ListManager:
             (self._name,)
         )
         for row in cursor:
-            yield json.loads(row['item_value'])
+            yield self._deserialize(row['item_value'])
         cursor.close()
 
-    def __contains__(self, value: Any) -> bool:
+    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.execute(
             "SELECT 1 FROM beaver_lists WHERE list_name = ? AND item_value = ? LIMIT 1",
-            (self._name, json.dumps(value))
+            (self._name, self._serialize(value))
         )
         result = cursor.fetchone()
         cursor.close()
@@ -139,7 +155,7 @@ class ListManager:
 
     def __repr__(self) -> str:
         """Returns a developer-friendly representation of the object."""
-        return f"ListWrapper(name='{self._name}')"
+        return f"ListManager(name='{self._name}')"
 
     def _get_order_at_index(self, index: int) -> float:
         """Helper to get the float `item_order` at a specific index."""
@@ -156,7 +172,7 @@ class ListManager:
 
         raise IndexError(f"{index} out of range.")
 
-    def push(self, value: Any):
+    def push(self, value: T):
         """Pushes an item to the end of the list."""
         with self._conn:
             cursor = self._conn.cursor()
@@ -169,10 +185,10 @@ class ListManager:
 
             cursor.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
-                (self._name, new_order, json.dumps(value)),
+                (self._name, new_order, self._serialize(value)),
             )
 
-    def prepend(self, value: Any):
+    def prepend(self, value: T):
         """Prepends an item to the beginning of the list."""
         with self._conn:
             cursor = self._conn.cursor()
@@ -185,10 +201,10 @@ class ListManager:
 
             cursor.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
-                (self._name, new_order, json.dumps(value)),
+                (self._name, new_order, self._serialize(value)),
             )
 
-    def insert(self, index: int, value: Any):
+    def insert(self, index: int, value: T):
         """Inserts an item at a specific index."""
         list_len = len(self)
         if index <= 0:
@@ -206,10 +222,10 @@ class ListManager:
         with self._conn:
             self._conn.execute(
                 "INSERT INTO beaver_lists (list_name, item_order, item_value) VALUES (?, ?, ?)",
-                (self._name, new_order, json.dumps(value)),
+                (self._name, new_order, self._serialize(value)),
             )
 
-    def pop(self) -> Any:
+    def pop(self) -> T | None:
         """Removes and returns the last item from the list."""
         with self._conn:
             cursor = self._conn.cursor()
@@ -225,9 +241,9 @@ class ListManager:
             cursor.execute(
                 "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
             )
-            return json.loads(value_to_return)
+            return self._deserialize(value_to_return)
 
-    def deque(self) -> Any:
+    def deque(self) -> T | None:
         """Removes and returns the first item from the list."""
         with self._conn:
             cursor = self._conn.cursor()
@@ -243,4 +259,4 @@ class ListManager:
             cursor.execute(
                 "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
             )
-            return json.loads(value_to_return)
+            return self._deserialize(value_to_return)

beaver/queues.py

@@ -1,25 +1,42 @@
 import json
 import sqlite3
 import time
-from typing import Any, NamedTuple
+from typing import Any, Literal, NamedTuple, Type, overload
 
+from .types import JsonSerializable
 
-class QueueItem(NamedTuple):
+
+class QueueItem[T](NamedTuple):
     """A data class representing a single item retrieved from the queue."""
 
     priority: float
     timestamp: float
-    data: Any
+    data: T
 
 
-class QueueManager:
+class QueueManager[T]:
     """A wrapper providing a Pythonic interface to a persistent priority queue."""
 
-    def __init__(self, name: str, conn: sqlite3.Connection):
+    def __init__(self, name: str, conn: sqlite3.Connection, model: Type[T] | None = None):
         self._name = name
         self._conn = conn
+        self._model = model
+
+    def _serialize(self, value: T) -> str:
+        """Serializes the given value to a JSON string."""
+        if isinstance(value, JsonSerializable):
+            return value.model_dump_json()
+
+        return json.dumps(value)
+
+    def _deserialize(self, value: str) -> T:
+        """Deserializes a JSON string into the specified model or a generic object."""
+        if self._model is not None:
+            return self._model.model_validate_json(value) # type: ignore
 
-    def put(self, data: Any, priority: float):
+        return json.loads(value)
+
+    def put(self, data: T, priority: float):
         """
         Adds an item to the queue with a specific priority.
 
@@ -30,17 +47,18 @@ class QueueManager:
         with self._conn:
             self._conn.execute(
                 "INSERT INTO beaver_priority_queues (queue_name, priority, timestamp, data) VALUES (?, ?, ?, ?)",
-                (self._name, priority, time.time(), json.dumps(data)),
+                (self._name, priority, time.time(), self._serialize(data)),
             )
 
-    def get(self) -> QueueItem:
+    @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:
         """
         Atomically retrieves and removes the highest-priority item from the queue.
-
-        Returns:
-            A QueueItem containing the data and its metadata.
-
-        Raises IndexError if queue is empty.
+        If the queue is empty, returns None if safe is True, otherwise (the default) raises IndexError.
         """
         with self._conn:
             cursor = self._conn.cursor()
@@ -58,14 +76,17 @@ class QueueManager:
             result = cursor.fetchone()
 
             if result is None:
-                raise IndexError("Queue is empty")
+                if safe:
+                    return None
+                else:
+                    raise IndexError("No item available.")
 
             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=json.loads(data)
+                priority=priority, timestamp=timestamp, data=self._deserialize(data)
             )
 
     def __len__(self) -> int:
@@ -79,7 +100,7 @@ class QueueManager:
         cursor.close()
         return count
 
-    def __nonzero__(self) -> bool:
+    def __bool__(self) -> bool:
         """Returns True if the queue is not empty."""
         return len(self) > 0
 

beaver/types.py

@@ -0,0 +1,39 @@
+import json
+from typing import Protocol, Type, runtime_checkable, Self
+
+
+@runtime_checkable
+class JsonSerializable[T](Protocol):
+    """
+    A protocol for objects that can be serialized to and from JSON,
+    compatible with Pydantic's `BaseModel`.
+    """
+
+    def model_dump_json(self) -> str:
+        """Serializes the model to a JSON string."""
+        ...
+
+    @classmethod
+    def model_validate_json(cls: Type[T], json_data: str | bytes) -> T:
+        """Deserializes a JSON string into a model instance."""
+        ...
+
+
+class Model:
+    """A lightweight base model that automatically provides JSON serialization."""
+    def __init__(self, **kwargs) -> None:
+        for k,v in kwargs.items():
+            setattr(self, k, v)
+
+    def model_dump_json(self) -> str:
+        """Serializes the dataclass instance to a JSON string."""
+        return json.dumps(self.__dict__)
+
+    @classmethod
+    def model_validate_json(cls, json_data: str | bytes) -> Self:
+        """Deserializes a JSON string into a new instance of the dataclass."""
+        return cls(**json.loads(json_data))
+
+    def __repr__(self) -> str:
+        attrs = ", ".join(f"{k}={repr(v)}" for k,v in self.__dict__.items())
+        return f"{self.__class__.__name__}({attrs})"

{beaver_db-0.12.2.dist-info → beaver_db-0.13.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.12.2
+Version: 0.13.0
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -219,6 +219,39 @@ attachments.put(
 avatar = attachments.get("user_123_avatar.png")
 ```
 
+
+## Type-Safe Data Models
+
+For enhanced data integrity and a better developer experience, BeaverDB supports type-safe operations for dictionaries, lists, and queues. By associating a model with these data structures, you get automatic serialization and deserialization, complete with autocompletion in your editor.
+
+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.
+
+Here’s a quick example of how to use it:
+
+```python
+from beaver import BeaverDB, Model
+
+# Inherit from beaver.Model for a lightweight, dependency-free model
+class User(Model):
+    name: str
+    email: str
+
+db = BeaverDB("user_data.db")
+
+# Associate the User model with a dictionary
+users = db.dict("user_profiles", model=User)
+
+# BeaverDB now handles serialization automatically
+users["alice"] = User(name="Alice", email="alice@example.com")
+
+# The retrieved object is a proper instance of the User class
+retrieved_user = users["alice"]
+print(f"Retrieved: {retrieved_user.name}") # Your editor will provide autocompletion here
+```
+
 ## More Examples
 
 For more in-depth examples, check out the scripts in the `examples/` directory:

beaver_db-0.13.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+beaver/__init__.py,sha256=qyEzF1Os7w4b4Hijgz0Y0R4zTrRBrHIGT1mEkZFl2YM,101
+beaver/blobs.py,sha256=5yVDzWyqi6Fur-2r0gaeIjEKj9fUPXb9hPulCTknJJI,3355
+beaver/channels.py,sha256=jKL1sVLOe_Q_pP0q1-iceZbPe8FOi0EwqJtOMOe96f4,8675
+beaver/collections.py,sha256=SZcaZnhcTpKb2OfpZOpFiVxh4-joYAJc6U98UeIhMuU,24247
+beaver/core.py,sha256=xoWqmumhm969UPwzqb40Tl--KSqumMN4tyP_WVfu8GQ,11980
+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/types.py,sha256=65rDdj97EegghEkKCNjI67bPYtTTI_jyB-leHdIypx4,1249
+beaver/vectors.py,sha256=j7RL2Y_xMAF2tPTi6E2LdJqZerSQXlnEQJOGZkefTsA,18358
+beaver_db-0.13.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.13.0.dist-info/METADATA,sha256=zGcAeV9HSyTaAuQO0YYEzB7SfqJeRVjR3tBoX3HPiaY,14928
+beaver_db-0.13.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.13.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.13.0.dist-info/RECORD,,

beaver_db-0.12.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
-beaver/blobs.py,sha256=5yVDzWyqi6Fur-2r0gaeIjEKj9fUPXb9hPulCTknJJI,3355
-beaver/channels.py,sha256=jKL1sVLOe_Q_pP0q1-iceZbPe8FOi0EwqJtOMOe96f4,8675
-beaver/collections.py,sha256=SZcaZnhcTpKb2OfpZOpFiVxh4-joYAJc6U98UeIhMuU,24247
-beaver/core.py,sha256=YAi5VAMsqS0JiydchjKVPbL0A5EL9m5f_gA3n5awnr0,11360
-beaver/dicts.py,sha256=EFlrSr7oFVt0lfuEX-PsdHnJXKC6cTcgbD7Lh2gID8s,4805
-beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
-beaver/queues.py,sha256=WKpBzlXr9Hp_rOKEs_Y1Tjyj_hWx6ql1uBRKBV7rw8w,2780
-beaver/vectors.py,sha256=j7RL2Y_xMAF2tPTi6E2LdJqZerSQXlnEQJOGZkefTsA,18358
-beaver_db-0.12.2.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
-beaver_db-0.12.2.dist-info/METADATA,sha256=LqnC9Q2YgMtuPuOPOTLBYiTUB5a5u0Dxz3fxF8McmDU,13571
-beaver_db-0.12.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.12.2.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.12.2.dist-info/RECORD,,