tinykv 0.3.0__tar.gz → 0.4.0__tar.gz

{tinykv-0.3.0 → tinykv-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tinykv
-Version: 0.3.0
+Version: 0.4.0
 Summary: A lightweight Python SQLite key-value store built on sqlite3.
 Keywords: python,sqlite,sqlite3,key-value store,kv
 Author-email: Flavio Veloso Soares <flaviovs@magnux.com>
@@ -97,6 +97,21 @@ database, respectively:
     >>> kv.get('foo')
     'bar'
 
+Use `inc()`, `dec()`, and `add()` to update integer counters atomically:
+
+    >>> kv.inc('visits')
+    1
+    >>> kv.inc('visits', 2)
+    3
+    >>> kv.dec('visits')
+    2
+    >>> kv.add('visits', -5)
+    -3
+
+Missing keys start at zero. Amounts must be integers (not booleans), and
+`inc()` and `dec()` require nonnegative amounts. An existing value must be an
+integer; otherwise the operation raises `TypeError`.
+
 Trying to get a nonexistent key raises _KeyError_:
 
     >>> kv.get('not-there')

{tinykv-0.3.0 → tinykv-0.4.0}/README.md

@@ -79,6 +79,21 @@ database, respectively:
     >>> kv.get('foo')
     'bar'
 
+Use `inc()`, `dec()`, and `add()` to update integer counters atomically:
+
+    >>> kv.inc('visits')
+    1
+    >>> kv.inc('visits', 2)
+    3
+    >>> kv.dec('visits')
+    2
+    >>> kv.add('visits', -5)
+    -3
+
+Missing keys start at zero. Amounts must be integers (not booleans), and
+`inc()` and `dec()` require nonnegative amounts. An existing value must be an
+integer; otherwise the operation raises `TypeError`.
+
 Trying to get a nonexistent key raises _KeyError_:
 
     >>> kv.get('not-there')

{tinykv-0.3.0 → tinykv-0.4.0}/src/tinykv/__init__.py

@@ -8,6 +8,7 @@ import pickle
 import re
 import sqlite3
 from collections.abc import Iterable, Mapping
+from types import TracebackType
 from typing import Any
 
 _TABLE_NAME_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*\Z")
@@ -54,15 +55,45 @@ def _validate_key(key: str) -> None:
         raise ValueError("key must not be empty")
 
 
-__version__ = "0.3.0"
+def _validate_int(value: Any, name: str) -> None:  # noqa: ANN401
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(
+            f"{name} must be an integer, got {type(value).__name__}"
+        )
+
+
+__version__ = "0.4.0"
 
 _DEF_TABLE = "kv"
 _NAN_PICKLE = pickle.dumps(float("nan"))
 _MISSING = object()
+_SAVEPOINT_IDS = itertools.count()
 
 logger = logging.getLogger(__name__)
 
 
+class _Savepoint:
+    """Manage an atomic operation using a uniquely named savepoint."""
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+        self._name = f"__tinykv_{next(_SAVEPOINT_IDS)}"
+
+    def __enter__(self) -> "_Savepoint":
+        self._conn.execute(f"SAVEPOINT {self._name}")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if exc_type is not None:
+            self._conn.execute(f"ROLLBACK TO {self._name}")
+        self._conn.execute(f"RELEASE {self._name}")
+
+
 def create_schema(
     conn: sqlite3.Connection,
     table: str = _DEF_TABLE,
@@ -293,6 +324,94 @@ class TinyKV:
             (key, dtype, data),
         )
 
+    def add(self, key: str, n: int) -> int:
+        """Add an integer amount to the value stored under ``key``.
+
+        If the key does not exist, it is treated as having value zero.
+        Existing values must be integers; booleans and other types are not
+        accepted. The operation is atomic and returns the new value.
+
+        Args:
+            key: The key to update.
+            n: A signed integer amount to add.
+
+        Returns:
+            The updated integer value.
+
+        Raises:
+            TypeError: If ``key`` or ``n`` has an invalid type, or if the
+                existing value is not an integer.
+            ValueError: If ``key`` is empty or the stored row is malformed.
+
+        """
+        _validate_key(key)
+        _validate_int(n, "n")
+
+        assert self._conn
+        with _Savepoint(self._conn):
+            cur = self._conn.execute(
+                f"SELECT t, v FROM {self._quoted_table} WHERE k = ?", (key,)
+            )
+            row = cur.fetchone()
+            if row is None:
+                value = 0
+            else:
+                value = self._decode_row(row[0], row[1])
+                _validate_int(value, f"value for key {key!r}")
+
+            result = value + n
+            dtype, data = self._serialize(result)
+            self._conn.execute(
+                f"INSERT OR REPLACE INTO {self._quoted_table} (k, t, v) "
+                "VALUES (?, ?, ?)",
+                (key, dtype, data),
+            )
+        return result
+
+    def inc(self, key: str, n: int = 1) -> int:
+        """Increment the integer value stored under ``key`` by ``n``.
+
+        Args:
+            key: The key to update.
+            n: A nonnegative integer amount to add.
+
+        Returns:
+            The updated integer value.
+
+        Raises:
+            TypeError: If ``key`` or ``n`` has an invalid type, or if the
+                existing value is not an integer.
+            ValueError: If ``key`` is empty, ``n`` is negative, or the stored
+                row is malformed.
+
+        """
+        _validate_int(n, "n")
+        if n < 0:
+            raise ValueError("n must be nonnegative")
+        return self.add(key, n)
+
+    def dec(self, key: str, n: int = 1) -> int:
+        """Decrement the integer value stored under ``key`` by ``n``.
+
+        Args:
+            key: The key to update.
+            n: A nonnegative integer amount to subtract.
+
+        Returns:
+            The updated integer value.
+
+        Raises:
+            TypeError: If ``key`` or ``n`` has an invalid type, or if the
+                existing value is not an integer.
+            ValueError: If ``key`` is empty, ``n`` is negative, or the stored
+                row is malformed.
+
+        """
+        _validate_int(n, "n")
+        if n < 0:
+            raise ValueError("n must be nonnegative")
+        return self.add(key, -n)
+
     def get(
         self,
         key: str,
@@ -362,20 +481,24 @@ class TinyKV:
             1,
             self._conn.getlimit(sqlite3.SQLITE_LIMIT_VARIABLE_NUMBER),
         )
-        while True:
-            tkeys = tuple(itertools.islice(key_iter, chunk_size))
-            if not tkeys:
-                break
-            for k in tkeys:
-                _validate_key(k)
-            rows = self._conn.execute(
-                f"SELECT k, t, v FROM {self._quoted_table} WHERE "
-                f"k IN ({', '.join(['?'] * len(tkeys))})",
-                tkeys,
-            )
-            result.update(
-                {r[0]: self._decode_row(r[1], r[2]) for r in rows.fetchall()}
-            )
+        with _Savepoint(self._conn):
+            while True:
+                tkeys = tuple(itertools.islice(key_iter, chunk_size))
+                if not tkeys:
+                    break
+                for k in tkeys:
+                    _validate_key(k)
+                rows = self._conn.execute(
+                    f"SELECT k, t, v FROM {self._quoted_table} WHERE "
+                    f"k IN ({', '.join(['?'] * len(tkeys))})",
+                    tkeys,
+                )
+                result.update(
+                    {
+                        r[0]: self._decode_row(r[1], r[2])
+                        for r in rows.fetchall()
+                    }
+                )
         return result
 
     def get_glob(self, glob_key: str) -> dict[str, Any]:
@@ -424,8 +547,7 @@ class TinyKV:
             1,
             self._conn.getlimit(sqlite3.SQLITE_LIMIT_VARIABLE_NUMBER) // 3,
         )
-        self._conn.execute("SAVEPOINT tinykv_batch")
-        try:
+        with _Savepoint(self._conn):
             chunk = first_chunk
             while chunk:
                 params: list[Any] = []
@@ -438,11 +560,6 @@ class TinyKV:
                     params,
                 )
                 chunk = list(itertools.islice(item_iter, chunk_size))
-        except Exception:
-            self._conn.execute("ROLLBACK TO tinykv_batch")
-            self._conn.execute("RELEASE tinykv_batch")
-            raise
-        self._conn.execute("RELEASE tinykv_batch")
 
     def remove(self, key: str) -> None:
         """Remove a key from the database.
@@ -485,8 +602,7 @@ class TinyKV:
             1,
             self._conn.getlimit(sqlite3.SQLITE_LIMIT_VARIABLE_NUMBER),
         )
-        self._conn.execute("SAVEPOINT tinykv_batch")
-        try:
+        with _Savepoint(self._conn):
             tkeys = first_chunk
             while tkeys:
                 for k in tkeys:
@@ -497,8 +613,3 @@ class TinyKV:
                     tkeys,
                 )
                 tkeys = tuple(itertools.islice(key_iter, chunk_size))
-        except Exception:
-            self._conn.execute("ROLLBACK TO tinykv_batch")
-            self._conn.execute("RELEASE tinykv_batch")
-            raise
-        self._conn.execute("RELEASE tinykv_batch")