beaver-db 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

beaver/{subscribers.py → channels.py}

@@ -4,7 +4,7 @@ import time
 from typing import Any, Iterator
 
 
-class SubWrapper(Iterator):
+class ChannelManager(Iterator):
     """
     A synchronous, blocking iterator that polls a channel for new messages.
     """
@@ -25,7 +25,7 @@ class SubWrapper(Iterator):
         self._poll_interval = poll_interval
         self._last_seen_timestamp = time.time()
 
-    def __iter__(self) -> "SubWrapper":
+    def __iter__(self) -> "ChannelManager":
         """Returns the iterator object itself."""
         return self
 

beaver/collections.py

@@ -45,7 +45,7 @@ class Document:
         return f"Document(id='{self.id}', {metadata_str})"
 
 
-class CollectionWrapper:
+class CollectionManager:
     """
     A wrapper for multi-modal collection operations with an in-memory ANN index,
     FTS, and graph capabilities.

beaver/core.py

@@ -3,10 +3,10 @@ import sqlite3
 import time
 from typing import Any
 
-from .dicts import DictWrapper
-from .lists import ListWrapper
-from .subscribers import SubWrapper
-from .collections import CollectionWrapper
+from .dicts import DictManager
+from .lists import ListManager
+from .channels import ChannelManager
+from .collections import CollectionManager
 
 
 class BeaverDB:
@@ -48,6 +48,7 @@ class BeaverDB:
                     dict_name TEXT NOT NULL,
                     key TEXT NOT NULL,
                     value TEXT NOT NULL,
+                    expires_at REAL,
                     PRIMARY KEY (dict_name, key)
                 )
             """
@@ -151,21 +152,21 @@ class BeaverDB:
 
     # --- Factory and Passthrough Methods ---
 
-    def dict(self, name: str) -> DictWrapper:
+    def dict(self, name: str) -> DictManager:
         """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)
+        return DictManager(name, self._conn)
 
-    def list(self, name: str) -> ListWrapper:
+    def list(self, name: str) -> ListManager:
         """Returns a wrapper object for interacting with a named list."""
         if not isinstance(name, str) or not name:
             raise TypeError("List name must be a non-empty string.")
-        return ListWrapper(name, self._conn)
+        return ListManager(name, self._conn)
 
-    def collection(self, name: str) -> CollectionWrapper:
+    def collection(self, name: str) -> CollectionManager:
         """Returns a wrapper for interacting with a document collection."""
-        return CollectionWrapper(name, self._conn)
+        return CollectionManager(name, self._conn)
 
     def publish(self, channel_name: str, payload: Any):
         """Publishes a JSON-serializable message to a channel. This is synchronous."""
@@ -182,6 +183,6 @@ class BeaverDB:
                 (time.time(), channel_name, json_payload),
             )
 
-    def subscribe(self, channel_name: str) -> SubWrapper:
+    def subscribe(self, channel_name: str) -> ChannelManager:
         """Subscribes to a channel, returning a synchronous iterator."""
-        return SubWrapper(self._conn, channel_name)
+        return ChannelManager(self._conn, channel_name)

beaver/dicts.py

@@ -1,46 +1,64 @@
 import json
 import sqlite3
+import time # Add this import
 from typing import Any, Iterator, Tuple
 
-
-class DictWrapper:
+class DictManager:
     """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):
-        """Sets a value for a key in the dictionary."""
-        self.__setitem__(key, value)
+    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):
+    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) VALUES (?, ?, ?)",
-                (self._name, key, json.dumps(value)),
+                "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."""
+        """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 (e.g., `my_dict[key]`)."""
+        """Retrieves a value for a given key, raising KeyError if expired."""
         cursor = self._conn.cursor()
         cursor.execute(
-            "SELECT value FROM beaver_dicts WHERE dict_name = ? AND key = ?",
+            "SELECT value, expires_at FROM beaver_dicts WHERE dict_name = ? AND key = ?",
             (self._name, key),
         )
         result = cursor.fetchone()
-        cursor.close()
+
         if result is None:
+            cursor.close()
             raise KeyError(f"Key '{key}' not found in dictionary '{self._name}'")
-        return json.loads(result["value"])
+
+        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]`)."""

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."""
+class ListManager:
+    """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.6.0.dist-info → beaver_db-0.7.0.dist-info}/METADATA

@@ -1,14 +1,20 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 0.6.0
+Version: 0.7.0
 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.
-  - **Namespaced Key-Value Dictionaries**: A Pythonic, dictionary-like interface for storing any JSON-serializable object within separate namespaces.
-  - **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.
@@ -174,6 +180,18 @@ listener_thread.join()
 publisher_thread.join()
 ```
 
+## Roadmap
+
+These are some of the features and improvements planned for future releases:
+
+- **Fuzzy search**: Implement fuzzy matching capabilities for text search.
+- **Faster ANN**: Explore integrating more advanced ANN libraries like `faiss` for improved vector search performance.
+- **Priority Queues**: Introduce a priority queue data structure for task management.
+- **Improved Pub/Sub**: Fan-out implementation with a more Pythonic API.
+- **Async API**: Comprehensive async support with on-demand wrappers for all collections.
+
+Check out the [roadmap](roadmap.md) for a detailed list of upcoming features and design ideas.
+
 ## License
 
 This project is licensed under the MIT License.

beaver_db-0.7.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
+beaver/channels.py,sha256=2lem2_yEFMc7cjdSx4FbFZQOaeT-HtbSvon3WYYRYzY,1952
+beaver/collections.py,sha256=htlOnjQl8YwjNKkDsK74c805PQQO9Zq2kIhnKxekLds,15064
+beaver/core.py,sha256=K_abD1RiAMT1jYv6T11fpckNljjqcotu3lkLkCz0bHg,6670
+beaver/dicts.py,sha256=y4z632XKWU29ekP_vdFSOP-MAG9Z8b79kBEHA88gO7E,4463
+beaver/lists.py,sha256=jFlDWwyaYycG0ZFVm58rMChefUaVZhaP1UeQ-hVo3Sg,9082
+beaver_db-0.7.0.dist-info/licenses/LICENSE,sha256=1xrIY5JnMk_QDQzsqmVzPIIyCgZAkWCC8kF2Ddo1UT0,1071
+beaver_db-0.7.0.dist-info/METADATA,sha256=MmlUva8ILoEMDdXyoujG1N-iGwMSScFuEx3qqF_vGyU,7196
+beaver_db-0.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+beaver_db-0.7.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
+beaver_db-0.7.0.dist-info/RECORD,,

beaver_db-0.7.0.dist-info/licenses/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.6.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-beaver/__init__.py,sha256=-z5Gj6YKMOswpJOOn5Gej8z5i6k3c0Xs00DIYLA-bMI,75
-beaver/collections.py,sha256=II26aeXelbtfs0zkcHImvPDtoyDhPCCP8bsosEqoKvw,15064
-beaver/core.py,sha256=CDAnIF1InFLb_JxMiO_bWo8coXIemhB68_WBkSTTKzU,6624
-beaver/dicts.py,sha256=XgkflJegQAY0YnkxnwWw_LGAeRtGFHzGtuaLAK2GfZg,3558
-beaver/lists.py,sha256=JG1JOkaYCUldADUzPJhaNi93w-k3S8mUzcCw574uht4,5915
-beaver/subscribers.py,sha256=tCty2iDbeE9IXcPicbxj2CB5gqfLufMB9-nLQwqNBUU,1944
-beaver_db-0.6.0.dist-info/METADATA,sha256=TwpfIsOef1GXpRdCpVEaQLVWtK1Ql11M9L7QLpSkphk,6265
-beaver_db-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-beaver_db-0.6.0.dist-info/top_level.txt,sha256=FxA4XnX5Qm5VudEXCduFriqi4dQmDWpQ64d7g69VQKI,7
-beaver_db-0.6.0.dist-info/RECORD,,