beaver-db 0.5.3__tar.gz → 0.6.2__tar.gz

beaver_db-0.6.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alejandro Piad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{beaver_db-0.5.3 → beaver_db-0.6.2}/PKG-INFO

@@ -1,14 +1,20 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.5.3
+Version: 0.6.2
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: numpy>=2.3.3
 Requires-Dist: scipy>=1.16.2
+Dynamic: license-file
 
 # beaver 🦫
 
+![PyPI - Downloads](https://img.shields.io/pypi/dm/beaver-db)
+![PyPI](https://img.shields.io/pypi/v/beaver-db)
+![License](https://img.shields.io/github/license/apiad/beaver)
+
 A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
 
 `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.
@@ -26,8 +32,8 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 ## Core Features
 
   - **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
-  - **Persistent Key-Value Store**: A simple `set`/`get` interface for storing any JSON-serializable object.
-  - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
+  - **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, with all operations in constant time.
   - **Efficient Vector Storage & Search**: Store vector embeddings and perform fast approximate nearest neighbor searches using an in-memory k-d tree.
   - **Full-Text Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine.
   - **Graph Traversal**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -51,17 +57,21 @@ from beaver import BeaverDB, Document
 db = BeaverDB("my_application.db")
 ```
 
-### Key-Value Store
+### Namespaced Dictionaries
 
-Use `set()` and `get()` for simple data storage. The value can be any JSON-encodable object.
+Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
 
 ```python
-# Set a value
-db.set("app_config", {"theme": "dark", "user_id": 123})
+# Get a handle to the 'app_config' namespace
+config = db.dict("app_config")
+
+# Set values using standard dictionary syntax
+config["theme"] = "dark"
+config["user_id"] = 123
 
 # Get a value
-config = db.get("app_config")
-print(f"Theme: {config.get('theme')}") # Output: Theme: dark
+theme = config.get("theme")
+print(f"Theme: {theme}") # Output: Theme: dark
 ```
 
 ### List Management

{beaver_db-0.5.3 → beaver_db-0.6.2}/README.md

@@ -1,5 +1,9 @@
 # beaver 🦫
 
+![PyPI - Downloads](https://img.shields.io/pypi/dm/beaver-db)
+![PyPI](https://img.shields.io/pypi/v/beaver-db)
+![License](https://img.shields.io/github/license/apiad/beaver)
+
 A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
 
 `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.
@@ -17,8 +21,8 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 ## Core Features
 
   - **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
-  - **Persistent Key-Value Store**: A simple `set`/`get` interface for storing any JSON-serializable object.
-  - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
+  - **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, with all operations in constant time.
   - **Efficient Vector Storage & Search**: Store vector embeddings and perform fast approximate nearest neighbor searches using an in-memory k-d tree.
   - **Full-Text Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine.
   - **Graph Traversal**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -42,17 +46,21 @@ from beaver import BeaverDB, Document
 db = BeaverDB("my_application.db")
 ```
 
-### Key-Value Store
+### Namespaced Dictionaries
 
-Use `set()` and `get()` for simple data storage. The value can be any JSON-encodable object.
+Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
 
 ```python
-# Set a value
-db.set("app_config", {"theme": "dark", "user_id": 123})
+# Get a handle to the 'app_config' namespace
+config = db.dict("app_config")
+
+# Set values using standard dictionary syntax
+config["theme"] = "dark"
+config["user_id"] = 123
 
 # Get a value
-config = db.get("app_config")
-print(f"Theme: {config.get('theme')}") # Output: Theme: dark
+theme = config.get("theme")
+print(f"Theme: {theme}") # Output: Theme: dark
 ```
 
 ### List Management

{beaver_db-0.5.3 → beaver_db-0.6.2}/beaver/core.py

@@ -3,6 +3,7 @@ import sqlite3
 import time
 from typing import Any
 
+from .dicts import DictWrapper
 from .lists import ListWrapper
 from .subscribers import SubWrapper
 from .collections import CollectionWrapper
@@ -30,22 +31,25 @@ class BeaverDB:
 
     def _create_all_tables(self):
         """Initializes all required tables in the database file."""
-        self._create_kv_table()
         self._create_pubsub_table()
         self._create_list_table()
         self._create_collections_table()
         self._create_fts_table()
         self._create_edges_table()
         self._create_versions_table()
+        self._create_dict_table()
 
-    def _create_kv_table(self):
-        """Creates the key-value store table."""
+    def _create_dict_table(self):
+        """Creates the namespaced dictionary table."""
         with self._conn:
             self._conn.execute(
                 """
-                CREATE TABLE IF NOT EXISTS _beaver_kv_store (
-                    key TEXT PRIMARY KEY,
-                    value TEXT NOT NULL
+                CREATE TABLE IF NOT EXISTS beaver_dicts (
+                    dict_name TEXT NOT NULL,
+                    key TEXT NOT NULL,
+                    value TEXT NOT NULL,
+                    expires_at REAL,
+                    PRIMARY KEY (dict_name, key)
                 )
             """
             )
@@ -148,39 +152,11 @@ class BeaverDB:
 
     # --- Factory and Passthrough Methods ---
 
-    def set(self, key: str, value: Any):
-        """
-        Stores a JSON-serializable value for a given key.
-        This operation is synchronous.
-        """
-        if not isinstance(key, str):
-            raise TypeError("Key must be a string.")
-
-        try:
-            json_value = json.dumps(value)
-        except TypeError as e:
-            raise TypeError("Value must be JSON-serializable.") from e
-
-        with self._conn:
-            self._conn.execute(
-                "INSERT OR REPLACE INTO _beaver_kv_store (key, value) VALUES (?, ?)",
-                (key, json_value),
-            )
-
-    def get(self, key: str) -> Any:
-        """
-        Retrieves a value for a given key.
-        This operation is synchronous.
-        """
-        if not isinstance(key, str):
-            raise TypeError("Key must be a string.")
-
-        cursor = self._conn.cursor()
-        cursor.execute("SELECT value FROM _beaver_kv_store WHERE key = ?", (key,))
-        result = cursor.fetchone()
-        cursor.close()
-
-        return json.loads(result["value"]) if result else None
+    def dict(self, name: str) -> DictWrapper:
+        """Returns a wrapper object for interacting with a named dictionary."""
+        if not isinstance(name, str) or not name:
+            raise TypeError("Dictionary name must be a non-empty string.")
+        return DictWrapper(name, self._conn)
 
     def list(self, name: str) -> ListWrapper:
         """Returns a wrapper object for interacting with a named list."""

beaver_db-0.6.2/beaver/dicts.py

@@ -0,0 +1,119 @@
+import json
+import sqlite3
+import time # Add this import
+from typing import Any, Iterator, Tuple
+
+class DictWrapper:
+    """A wrapper providing a Pythonic interface to a dictionary in the database."""
+
+    def __init__(self, name: str, conn: sqlite3.Connection):
+        self._name = name
+        self._conn = conn
+
+    def set(self, key: str, value: Any, 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):
+        """Sets a value for a key (e.g., `my_dict[key] = value`)."""
+        expires_at = None
+        if ttl_seconds is not None:
+            if not isinstance(ttl_seconds, int) or ttl_seconds <= 0:
+                raise ValueError("ttl_seconds must be a positive integer.")
+            expires_at = time.time() + ttl_seconds
+
+        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),
+            )
+
+    def get(self, key: str, default: Any = None) -> 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:
+        """Retrieves a value for a given key, raising KeyError if expired."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT value, expires_at FROM beaver_dicts WHERE dict_name = ? AND key = ?",
+            (self._name, key),
+        )
+        result = cursor.fetchone()
+
+        if result is None:
+            cursor.close()
+            raise KeyError(f"Key '{key}' not found in dictionary '{self._name}'")
+
+        value, expires_at = result["value"], result["expires_at"]
+
+        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()
+            cursor.close()
+            raise KeyError(f"Key '{key}' not found in dictionary '{self._name}' (expired)")
+
+        cursor.close()
+        return json.loads(value)
+
+    def __delitem__(self, key: str):
+        """Deletes a key-value pair (e.g., `del my_dict[key]`)."""
+        with self._conn:
+            cursor = self._conn.cursor()
+            cursor.execute(
+                "DELETE FROM beaver_dicts WHERE dict_name = ? AND key = ?",
+                (self._name, key),
+            )
+            if cursor.rowcount == 0:
+                raise KeyError(f"Key '{key}' not found in dictionary '{self._name}'")
+
+    def __len__(self) -> int:
+        """Returns the number of items in the dictionary."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT COUNT(*) FROM beaver_dicts WHERE dict_name = ?", (self._name,)
+        )
+        count = cursor.fetchone()[0]
+        cursor.close()
+        return count
+
+    def __iter__(self) -> Iterator[str]:
+        """Returns an iterator over the keys of the dictionary."""
+        return self.keys()
+
+    def keys(self) -> Iterator[str]:
+        """Returns an iterator over the dictionary's keys."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT key FROM beaver_dicts WHERE dict_name = ?", (self._name,)
+        )
+        for row in cursor:
+            yield row["key"]
+        cursor.close()
+
+    def values(self) -> Iterator[Any]:
+        """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"])
+        cursor.close()
+
+    def items(self) -> Iterator[Tuple[str, Any]]:
+        """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"]))
+        cursor.close()
+
+    def __repr__(self) -> str:
+        return f"DictWrapper(name='{self._name}')"

{beaver_db-0.5.3 → beaver_db-0.6.2}/beaver/lists.py

@@ -1,10 +1,9 @@
 import json
 import sqlite3
-from typing import Any, Union
-
+from typing import Any, Union, Iterator
 
 class ListWrapper:
-    """A wrapper providing a Pythonic interface to a list in the database."""
+    """A wrapper providing a Pythonic, full-featured interface to a list in the database."""
 
     def __init__(self, name: str, conn: sqlite3.Connection):
         self._name = name
@@ -61,6 +60,87 @@ class ListWrapper:
         else:
             raise TypeError("List indices must be integers or slices.")
 
+    def __setitem__(self, key: int, value: Any):
+        """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.")
+
+        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
+
+        with self._conn:
+            cursor = self._conn.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 ?",
+                (self._name, offset)
+            )
+            result = cursor.fetchone()
+            if not result:
+                raise IndexError("List index out of range during update.")
+
+            rowid_to_update = result['rowid']
+            # Update the value for that specific row
+            cursor.execute(
+                "UPDATE beaver_lists SET item_value = ? WHERE rowid = ?",
+                (json.dumps(value), rowid_to_update)
+            )
+
+    def __delitem__(self, key: int):
+        """Deletes an item at a specific index (e.g., `del my_list[0]`)."""
+        if not isinstance(key, int):
+            raise TypeError("List indices must be integers.")
+
+        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
+
+        with self._conn:
+            cursor = self._conn.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 ?",
+                (self._name, offset)
+            )
+            result = cursor.fetchone()
+            if not result:
+                raise IndexError("List index out of range during delete.")
+
+            rowid_to_delete = result['rowid']
+            # Delete that specific row
+            cursor.execute("DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,))
+
+    def __iter__(self) -> Iterator[Any]:
+        """Returns an iterator for the list."""
+        cursor = self._conn.cursor()
+        cursor.execute(
+            "SELECT item_value FROM beaver_lists WHERE list_name = ? ORDER BY item_order ASC",
+            (self._name,)
+        )
+        for row in cursor:
+            yield json.loads(row['item_value'])
+        cursor.close()
+
+    def __contains__(self, value: Any) -> 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))
+        )
+        result = cursor.fetchone()
+        cursor.close()
+        return result is not None
+
+    def __repr__(self) -> str:
+        """Returns a developer-friendly representation of the object."""
+        return f"ListWrapper(name='{self._name}')"
+
     def _get_order_at_index(self, index: int) -> float:
         """Helper to get the float `item_order` at a specific index."""
         cursor = self._conn.cursor()
@@ -163,4 +243,4 @@ class ListWrapper:
             cursor.execute(
                 "DELETE FROM beaver_lists WHERE rowid = ?", (rowid_to_delete,)
             )
-            return json.loads(value_to_return)
+            return json.loads(value_to_return)

{beaver_db-0.5.3 → beaver_db-0.6.2}/beaver_db.egg-info/PKG-INFO

@@ -1,14 +1,20 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.5.3
+Version: 0.6.2
 Summary: Fast, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: numpy>=2.3.3
 Requires-Dist: scipy>=1.16.2
+Dynamic: license-file
 
 # beaver 🦫
 
+![PyPI - Downloads](https://img.shields.io/pypi/dm/beaver-db)
+![PyPI](https://img.shields.io/pypi/v/beaver-db)
+![License](https://img.shields.io/github/license/apiad/beaver)
+
 A fast, single-file, multi-modal database for Python, built with the standard `sqlite3` library.
 
 `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.
@@ -26,8 +32,8 @@ A fast, single-file, multi-modal database for Python, built with the standard `s
 ## Core Features
 
   - **Synchronous Pub/Sub**: A simple, thread-safe, Redis-like publish-subscribe system for real-time messaging.
-  - **Persistent Key-Value Store**: A simple `set`/`get` interface for storing any JSON-serializable object.
-  - **Pythonic List Management**: A fluent, Redis-like interface for managing persistent, ordered lists.
+  - **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, with all operations in constant time.
   - **Efficient Vector Storage & Search**: Store vector embeddings and perform fast approximate nearest neighbor searches using an in-memory k-d tree.
   - **Full-Text Search**: Automatically index and search through document metadata using SQLite's powerful FTS5 engine.
   - **Graph Traversal**: Create relationships between documents and traverse the graph to find neighbors or perform multi-hop walks.
@@ -51,17 +57,21 @@ from beaver import BeaverDB, Document
 db = BeaverDB("my_application.db")
 ```
 
-### Key-Value Store
+### Namespaced Dictionaries
 
-Use `set()` and `get()` for simple data storage. The value can be any JSON-encodable object.
+Use `db.dict()` to get a dictionary-like object for a specific namespace. The value can be any JSON-encodable object.
 
 ```python
-# Set a value
-db.set("app_config", {"theme": "dark", "user_id": 123})
+# Get a handle to the 'app_config' namespace
+config = db.dict("app_config")
+
+# Set values using standard dictionary syntax
+config["theme"] = "dark"
+config["user_id"] = 123
 
 # Get a value
-config = db.get("app_config")
-print(f"Theme: {config.get('theme')}") # Output: Theme: dark
+theme = config.get("theme")
+print(f"Theme: {theme}") # Output: Theme: dark
 ```
 
 ### List Management

{beaver_db-0.5.3 → beaver_db-0.6.2}/beaver_db.egg-info/SOURCES.txt

@@ -1,8 +1,10 @@
+LICENSE
 README.md
 pyproject.toml
 beaver/__init__.py
 beaver/collections.py
 beaver/core.py
+beaver/dicts.py
 beaver/lists.py
 beaver/subscribers.py
 beaver_db.egg-info/PKG-INFO

{beaver_db-0.5.3 → beaver_db-0.6.2}/pyproject.toml

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