tinykv 0.1.2__tar.gz → 0.2.1__tar.gz

tinykv-0.2.1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic
+Versioning](https://semver.org/spec/v2.0.0.html).
+
+Entries marked as **BC BREAK** indicate backward-incompatible changes.
+
+## [Unreleased]
+
+## [0.2.1] - 2026-03-11
+
+### Changed
+- Added an optional `if_not_exists` parameter to `create_schema()` to support
+  idempotent table creation when needed while preserving the default error on
+  existing tables. Close #1.
+
+## [0.2.0] - 2026-03-11
+
+### Changed
+- **BC BREAK** Minimum Python version is now 3.11 (was 3.7). This enables
+  modern type hint syntax and removes compatibility code for older Python
+  versions.
+- **BC BREAK** Keys are now case-sensitive. Previously, the database used
+  case-insensitive collation, so `'Foo'` and `'foo'` referred to the same key.
+  Existing tables using the old schema will continue to work with the old
+  behavior, but new tables created with `create_schema()` will use
+  case-sensitive keys.
+- Tables created with `create_schema()` now use SQLite `WITHOUT ROWID` storage
+  for better performance and smaller database size
+
+## [0.1.3] - 2026-03-11
+
+Pickle safety improvements and bug fixes.
+
+### Added
+- Add explicit pickle safety mode with user-facing warning
+- Enforce string key contract: non-string keys raise `TypeError`, empty
+  strings raise `ValueError`
+
+### Security
+- Validate table names to prevent SQL injection via table identifier
+
+### Fixed
+- Fix precision loss when roundtripping large integers through the database
+- Fix NaN roundtrip crash by storing as pickle and always deserializing
+- Fix `set_many({})` crash by making empty batch a no-op
+- Fix `remove_many([])` crash by making empty batch a no-op
+- Fix integral float type loss (e.g., `1.0` returned as `1`)
+
+## [0.1.2] - 2025-07-28
+
+Package reorganization for better pip compatibility.
+
+### Changed
+- Reorganize package into standard "src" layout for better pip install
+  experience
+
+## [0.1.1] - 2023-03-14
+
+Initial release of tinykv.
+
+### Added
+- Initial release

{tinykv-0.1.2 → tinykv-0.2.1}/PKG-INFO

@@ -1,11 +1,15 @@
 Metadata-Version: 2.4
 Name: tinykv
-Version: 0.1.2
-Summary: A tiny key-value store using SQLite3.
+Version: 0.2.1
+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>
-Requires-Python: >=3.7
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 License-File: LICENSE
 Requires-Dist: codespell ; extra == "dev"
 Requires-Dist: flake8-bugbear ; extra == "dev"
@@ -18,17 +22,35 @@ Requires-Dist: flit ; extra == "dev"
 Requires-Dist: mypy ; extra == "dev"
 Requires-Dist: pylint ; extra == "dev"
 Requires-Dist: taskipy ; extra == "dev"
+Project-URL: Homepage, https://github.com/flaviovs/tinykv
+Project-URL: Issues, https://github.com/flaviovs/tinykv/issues
+Project-URL: Repository, https://github.com/flaviovs/tinykv
 Provides-Extra: dev
 
-TinyKV - a minimal key-value database for Python using SQLite3
-==============================================================
+TinyKV: Python SQLite key-value store
+=====================================
 
-TinyKV implements a key-value database interface for Python 3 using
+TinyKV is a lightweight Python SQLite key-value store built on top of
 the [sqlite3](https://docs.python.org/3/library/sqlite3.html) module
-from the standard library. There is no dependency on external
-packages.
+from the standard library. It provides a small key-value database API
+for Python applications that need persistent local storage without
+external dependencies.
 
-TinyKV requires Python 3.7 or above.
+Use TinyKV when you want an embedded SQLite-backed key-value database
+for configuration data, local caches, application state, or small
+metadata stores.
+
+TinyKV requires Python 3.11 or above.
+
+
+Why TinyKV?
+-----------
+
+- Python key-value store backed by SQLite
+- Uses the standard library `sqlite3` module
+- Works with in-memory and file-based SQLite databases
+- Stores strings, numbers, bytes, and other Python objects
+- Keeps connection and transaction control with the caller
 
 
 Installation
@@ -37,7 +59,7 @@ Installation
     pip install tinykv
 
 
-Basic usage
+Quick start
 -----------
 
 First let’s import _sqlite3_ and the TinyKV module:
@@ -45,15 +67,15 @@ First let’s import _sqlite3_ and the TinyKV module:
     >>> import sqlite3
     >>> import tinykv
 
-TinyKV does not create a SQLite3 database to operate on. Instead, it
-operate on connections managed by the caller. So let’s create a
-database for using in the examples:
+TinyKV does not create a SQLite database connection for you. Instead,
+it operates on connections managed by the caller. So let’s create a
+database to use in the examples:
 
     >>> conn = sqlite3.connect(':memory:')
 
 This is how you create a TinyKV object:
 
-    >>> kv = tinykv.TinyKV(conn)
+    >>> kv = tinykv.TinyKV(conn, allow_pickle=True)
     Traceback (most recent call last):
         ...
     RuntimeError: Table 'kv' not found in the database
@@ -65,12 +87,20 @@ that the application can use `create_schema()`:
 
 Let’s try again:
 
-    >>> kv = tinykv.TinyKV(conn)
+    >>> kv = tinykv.TinyKV(conn, allow_pickle=True)
     >>> kv  # doctest: +ELLIPSIS
     <tinykv.TinyKV object at 0x...>
 
 Now it works!
 
+By default, TinyKV currently allows pickle-based value
+serialization/deserialization for compatibility.
+If `allow_pickle` is omitted, TinyKV currently behaves as if
+`allow_pickle=True` and emits a `FutureWarning`.
+Applications should not rely on this behavior and should explicitly set
+`allow_pickle=False` when handling databases that might be untrusted.
+The default is expected to change to `False` in a future release.
+
 
 ## Storing and retrieving data
 
@@ -111,13 +141,19 @@ You can store any regular Python scalar in the key-value database:
     >>> kv.get('pi')
     3.1415926
 
+    >>> kv.set('nan', float('nan'))
+    >>> import math
+    >>> math.isnan(kv.get('nan'))
+    True
+
 Same for container objects:
 
     >>> kv.set('a_list', ['one', 'two', 'three'])
     >>> kv.get('a_list')
     ['one', 'two', 'three']
 
-In fact, you can store any pickable object:
+In fact, you can store any pickable object when
+`allow_pickle=True` (the current default):
 
     >>> import datetime
     >>>
@@ -131,6 +167,10 @@ In fact, you can store any pickable object:
     >>> type(a_long_time_ago)
     <class 'datetime.datetime'>
 
+For safer behavior with untrusted database contents, disable pickle:
+
+    >>> safe_kv = tinykv.TinyKV(conn, allow_pickle=False)
+
 
 ## Removing entries
 
@@ -179,11 +219,11 @@ You can also use `get_glob()` to fetch entries based a glob pattern:
     {'bar:123': 3}
 
 Notice that `get_many()` and `get_glob()` never raise _KeyError_ for
-nonexistent keys. Instead, those keys are simple not present in the
+nonexistent keys. Instead, those keys are simply not present in the
 returned _dict_.
 
 You can also remove many entries in one call with
-`remove_many()`. Nonexistent keys are silently ignored:
+`remove_many()`. Nonexistent keys are silently ignored.
 
     >>> kv.get('one')
     1
@@ -195,10 +235,54 @@ You can also remove many entries in one call with
     KeyError: 'one'
 
 
+## Using glob patterns
+
+Use `get_glob()` to fetch entries using a shell-like wildcard pattern
+from the SQLite key-value store:
+
+The pattern uses SQLite's [GLOB](https://www.sqlite.org/lang_expr.html#glob)
+syntax: `*` matches any sequence of characters, and `?` matches a single
+character. Note that patterns are case-sensitive and use literal character
+matching (not regex).
+
+
+## Database setup
+
+TinyKV requires the database table to exist before use. Create it with
+`create_schema()`:
+
+    >>> import sqlite3
+    >>> conn = sqlite3.connect(':memory:')
+    >>> tinykv.create_schema(conn)
+
+If you need idempotent setup, pass `if_not_exists=True`:
+
+    >>> tinykv.create_schema(conn, if_not_exists=True)
+
+You can use a custom table name:
+
+    >>> tinykv.create_schema(conn, table='my_keys')
+
+See the Miscellaneous section for table name requirements.
+
+
+## Use cases
+
+TinyKV is a good fit when you need a Python SQLite key-value store for:
+
+- application configuration and settings
+- local cache data
+- lightweight metadata storage
+- persistent state for command-line tools
+- embedded storage in desktop scripts or services
+
+
 Miscellaneous
 -------------
 
-- TinyKV keys must be string scalars.
+- TinyKV keys must be non-empty string scalars. Non-string keys raise
+  `TypeError`, and empty strings raise `ValueError`. Keys are case-sensitive
+  (since v0.1.4).
 
 - TinyKV does not open or manage transactions. Also, it operates both
   in autocommit and non-autocommit mode. All operations are atomic.
@@ -220,7 +304,14 @@ Miscellaneous
         >>>
         >>> tinykv.create_schema(conn, table=CUSTOM_TABLE)
         >>>
-        >>> custom_kv = tinykv.TinyKV(conn, table=CUSTOM_TABLE)
+        >>> custom_kv = tinykv.TinyKV(
+        ...     conn,
+        ...     table=CUSTOM_TABLE,
+        ...     allow_pickle=True,
+        ... )
+
+  Table names must match the pattern `[a-zA-Z_][a-zA-Z0-9_]*`. Invalid
+  names raise `ValueError`.
 
 
 Questions? Bugs? Suggestions?

{tinykv-0.1.2 → tinykv-0.2.1}/README.md

@@ -1,12 +1,27 @@
-TinyKV - a minimal key-value database for Python using SQLite3
-==============================================================
+TinyKV: Python SQLite key-value store
+=====================================
 
-TinyKV implements a key-value database interface for Python 3 using
+TinyKV is a lightweight Python SQLite key-value store built on top of
 the [sqlite3](https://docs.python.org/3/library/sqlite3.html) module
-from the standard library. There is no dependency on external
-packages.
+from the standard library. It provides a small key-value database API
+for Python applications that need persistent local storage without
+external dependencies.
 
-TinyKV requires Python 3.7 or above.
+Use TinyKV when you want an embedded SQLite-backed key-value database
+for configuration data, local caches, application state, or small
+metadata stores.
+
+TinyKV requires Python 3.11 or above.
+
+
+Why TinyKV?
+-----------
+
+- Python key-value store backed by SQLite
+- Uses the standard library `sqlite3` module
+- Works with in-memory and file-based SQLite databases
+- Stores strings, numbers, bytes, and other Python objects
+- Keeps connection and transaction control with the caller
 
 
 Installation
@@ -15,7 +30,7 @@ Installation
     pip install tinykv
 
 
-Basic usage
+Quick start
 -----------
 
 First let’s import _sqlite3_ and the TinyKV module:
@@ -23,15 +38,15 @@ First let’s import _sqlite3_ and the TinyKV module:
     >>> import sqlite3
     >>> import tinykv
 
-TinyKV does not create a SQLite3 database to operate on. Instead, it
-operate on connections managed by the caller. So let’s create a
-database for using in the examples:
+TinyKV does not create a SQLite database connection for you. Instead,
+it operates on connections managed by the caller. So let’s create a
+database to use in the examples:
 
     >>> conn = sqlite3.connect(':memory:')
 
 This is how you create a TinyKV object:
 
-    >>> kv = tinykv.TinyKV(conn)
+    >>> kv = tinykv.TinyKV(conn, allow_pickle=True)
     Traceback (most recent call last):
         ...
     RuntimeError: Table 'kv' not found in the database
@@ -43,12 +58,20 @@ that the application can use `create_schema()`:
 
 Let’s try again:
 
-    >>> kv = tinykv.TinyKV(conn)
+    >>> kv = tinykv.TinyKV(conn, allow_pickle=True)
     >>> kv  # doctest: +ELLIPSIS
     <tinykv.TinyKV object at 0x...>
 
 Now it works!
 
+By default, TinyKV currently allows pickle-based value
+serialization/deserialization for compatibility.
+If `allow_pickle` is omitted, TinyKV currently behaves as if
+`allow_pickle=True` and emits a `FutureWarning`.
+Applications should not rely on this behavior and should explicitly set
+`allow_pickle=False` when handling databases that might be untrusted.
+The default is expected to change to `False` in a future release.
+
 
 ## Storing and retrieving data
 
@@ -89,13 +112,19 @@ You can store any regular Python scalar in the key-value database:
     >>> kv.get('pi')
     3.1415926
 
+    >>> kv.set('nan', float('nan'))
+    >>> import math
+    >>> math.isnan(kv.get('nan'))
+    True
+
 Same for container objects:
 
     >>> kv.set('a_list', ['one', 'two', 'three'])
     >>> kv.get('a_list')
     ['one', 'two', 'three']
 
-In fact, you can store any pickable object:
+In fact, you can store any pickable object when
+`allow_pickle=True` (the current default):
 
     >>> import datetime
     >>>
@@ -109,6 +138,10 @@ In fact, you can store any pickable object:
     >>> type(a_long_time_ago)
     <class 'datetime.datetime'>
 
+For safer behavior with untrusted database contents, disable pickle:
+
+    >>> safe_kv = tinykv.TinyKV(conn, allow_pickle=False)
+
 
 ## Removing entries
 
@@ -157,11 +190,11 @@ You can also use `get_glob()` to fetch entries based a glob pattern:
     {'bar:123': 3}
 
 Notice that `get_many()` and `get_glob()` never raise _KeyError_ for
-nonexistent keys. Instead, those keys are simple not present in the
+nonexistent keys. Instead, those keys are simply not present in the
 returned _dict_.
 
 You can also remove many entries in one call with
-`remove_many()`. Nonexistent keys are silently ignored:
+`remove_many()`. Nonexistent keys are silently ignored.
 
     >>> kv.get('one')
     1
@@ -173,10 +206,54 @@ You can also remove many entries in one call with
     KeyError: 'one'
 
 
+## Using glob patterns
+
+Use `get_glob()` to fetch entries using a shell-like wildcard pattern
+from the SQLite key-value store:
+
+The pattern uses SQLite's [GLOB](https://www.sqlite.org/lang_expr.html#glob)
+syntax: `*` matches any sequence of characters, and `?` matches a single
+character. Note that patterns are case-sensitive and use literal character
+matching (not regex).
+
+
+## Database setup
+
+TinyKV requires the database table to exist before use. Create it with
+`create_schema()`:
+
+    >>> import sqlite3
+    >>> conn = sqlite3.connect(':memory:')
+    >>> tinykv.create_schema(conn)
+
+If you need idempotent setup, pass `if_not_exists=True`:
+
+    >>> tinykv.create_schema(conn, if_not_exists=True)
+
+You can use a custom table name:
+
+    >>> tinykv.create_schema(conn, table='my_keys')
+
+See the Miscellaneous section for table name requirements.
+
+
+## Use cases
+
+TinyKV is a good fit when you need a Python SQLite key-value store for:
+
+- application configuration and settings
+- local cache data
+- lightweight metadata storage
+- persistent state for command-line tools
+- embedded storage in desktop scripts or services
+
+
 Miscellaneous
 -------------
 
-- TinyKV keys must be string scalars.
+- TinyKV keys must be non-empty string scalars. Non-string keys raise
+  `TypeError`, and empty strings raise `ValueError`. Keys are case-sensitive
+  (since v0.1.4).
 
 - TinyKV does not open or manage transactions. Also, it operates both
   in autocommit and non-autocommit mode. All operations are atomic.
@@ -198,7 +275,14 @@ Miscellaneous
         >>>
         >>> tinykv.create_schema(conn, table=CUSTOM_TABLE)
         >>>
-        >>> custom_kv = tinykv.TinyKV(conn, table=CUSTOM_TABLE)
+        >>> custom_kv = tinykv.TinyKV(
+        ...     conn,
+        ...     table=CUSTOM_TABLE,
+        ...     allow_pickle=True,
+        ... )
+
+  Table names must match the pattern `[a-zA-Z_][a-zA-Z0-9_]*`. Invalid
+  names raise `ValueError`.
 
 
 Questions? Bugs? Suggestions?

{tinykv-0.1.2 → tinykv-0.2.1}/pyproject.toml

@@ -7,13 +7,22 @@ name = "tinykv"
 authors = [{name = "Flavio Veloso Soares", email = "flaviovs@magnux.com"}]
 license = {file = "LICENSE"}
 readme = "README.md"
+keywords = ["python", "sqlite", "sqlite3", "key-value store", "kv"]
 classifiers = [
   "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-requires-python = ">=3.7"
+requires-python = ">=3.11"
 
 dynamic = ["version", "description"]
 
+[project.urls]
+Homepage = "https://github.com/flaviovs/tinykv"
+Repository = "https://github.com/flaviovs/tinykv"
+Issues = "https://github.com/flaviovs/tinykv/issues"
+
 [project.optional-dependencies]
 dev = [
   "codespell",
@@ -40,7 +49,7 @@ pre-commit = "task spellcheck && task test && task lint"
 
 [tool.mypy]
 files = "."
-python_version = "3.7"
+python_version = "3.11"
 exclude = [".git", ".venv"]
 strict = true
 warn_redundant_casts = true
@@ -72,4 +81,5 @@ disable = [
   "missing-function-docstring",
   "missing-module-docstring",
   "missing-class-docstring",
+  "too-many-return-statements",
 ]

{tinykv-0.1.2 → tinykv-0.2.1}/src/tinykv/__init__.py

@@ -1,32 +1,66 @@
-"""A tiny key-value store using SQLite3."""
+"""A lightweight Python SQLite key-value store built on sqlite3."""
 import enum
 import logging
+import math
 import pickle
+import re
 import sqlite3
+import warnings
 
-from typing import Any, Optional, Union, Iterable, Mapping, Tuple, Dict
+from collections.abc import Iterable, Mapping
+from typing import Any
 
-__version__ = '0.1.2'
+_TABLE_NAME_RE = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]*$')
+
+
+def _validate_table_name(table: str) -> None:
+    if not isinstance(table, str):
+        raise ValueError(
+            f'table name must be a string, got {type(table).__name__}'
+        )
+    if not _TABLE_NAME_RE.match(table):
+        raise ValueError(
+            f'Invalid table name {table!r}: must match pattern '
+            r'[a-zA-Z_][a-zA-Z0-9_]*'
+        )
+
+
+def _validate_key(key: str) -> None:
+    if not isinstance(key, str):
+        raise TypeError(
+            f'key must be a string, got {type(key).__name__}'
+        )
+    if not key:
+        raise ValueError('key must not be empty')
+
+
+__version__ = '0.2.1'
 
 _DEF_TABLE = 'kv'
+_ALLOW_PICKLE_DEFAULT = object()
 
 logger = logging.getLogger(__name__)
 
 
-def create_schema(conn: sqlite3.Connection, table: str = _DEF_TABLE) -> None:
+def create_schema(conn: sqlite3.Connection, table: str = _DEF_TABLE,
+                  if_not_exists: bool = False) -> None:
     """Create a database table for use with tinykv.
 
     Args:
         conn: The SQLite3 connection object.
         table: The table name (default: 'kv').
+        if_not_exists: If true, include SQLite's `IF NOT EXISTS` clause so
+            repeated schema creation is a no-op.
 
     """
-    conn.execute(f'CREATE TABLE {table} ('
-                 'k TEXT NOT NULL COLLATE NOCASE, '
-                 't TINYINT NOT NULL CHECK (t BETWEEN 1 AND 6), '
+    _validate_table_name(table)
+    if_not_exists_sql = 'IF NOT EXISTS ' if if_not_exists else ''
+    conn.execute(f'CREATE TABLE {if_not_exists_sql}{table} ('
+                 'k TEXT NOT NULL, '
+                 't TINYINT NOT NULL CHECK (t BETWEEN 1 AND 7), '
                  'v BLOB, '
                  'PRIMARY KEY (k)'
-                 ')')
+                 ') WITHOUT ROWID')
 
 
 class _DType(enum.IntEnum):
@@ -36,6 +70,7 @@ class _DType(enum.IntEnum):
     BOOL = 4
     NUMBER = 5
     PICKLE = 6
+    LONG = 7
 
 
 class TinyKV:
@@ -49,16 +84,35 @@ class TinyKV:
     >>>
     >>> create_schema(conn)
     >>>
-    >>> kv = TinyKV(conn)
+    >>> kv = TinyKV(conn, allow_pickle=True)
 
     Args:
         conn: The SQLite3 connection object.
         table: The table name (default: 'kv').
+        allow_pickle: If true, unsupported values are serialized with pickle.
+            If omitted, TinyKV currently behaves as true and emits a
+            FutureWarning because the default is expected to change in a
+            future release. Set to false to disable pickle-based
+            storage/deserialization for safer handling of untrusted database
+            content.
 
     """
 
-    def __init__(self, conn: sqlite3.Connection, table: str = _DEF_TABLE):
-        """Initialize the key-value object."""
+    def __init__(self, conn: sqlite3.Connection, table: str = _DEF_TABLE,
+                 allow_pickle: bool | object = _ALLOW_PICKLE_DEFAULT) -> None:
+        """Initialize the key-value object.
+
+        Args:
+            conn: The SQLite3 connection object.
+            table: The table name (default: 'kv').
+            allow_pickle: If true, fallback to pickle for unsupported value
+                types and unpickle stored pickle rows. If omitted, TinyKV
+                currently behaves as true and emits a FutureWarning because the
+                default is expected to change to false in a future release. If
+                false, both operations raise ValueError.
+
+        """
+        _validate_table_name(table)
         cur = conn.execute('SELECT name FROM sqlite_master '
                            "WHERE type = 'table' AND name = ?",
                            (table,))
@@ -67,6 +121,15 @@ class TinyKV:
 
         self._conn = conn
         self._table = table
+        if allow_pickle is _ALLOW_PICKLE_DEFAULT:
+            warnings.warn('allow_pickle currently defaults to True but this '
+                          'will change to False in a future release; pass '
+                          'allow_pickle explicitly',
+                          FutureWarning,
+                          stacklevel=2)
+            self._allow_pickle = True
+        else:
+            self._allow_pickle = bool(allow_pickle)
 
     @property
     def conn(self) -> sqlite3.Connection:
@@ -77,8 +140,7 @@ class TinyKV:
         """
         return self._conn
 
-    def _serialize(self, data: Any) -> Tuple[_DType,
-                                             Optional[Union[float, bytes]]]:
+    def _serialize(self, data: Any) -> tuple[_DType, float | bytes | None]:
         if data is None:
             return (_DType.NONE, None)
 
@@ -91,10 +153,20 @@ class TinyKV:
         if isinstance(data, bool):
             return (_DType.BOOL, int(data))
 
-        if isinstance(data, (int, float)):
+        if isinstance(data, int):
+            return (_DType.LONG, str(data).encode('utf-8'))
+
+        if isinstance(data, float):
+            if math.isnan(data):
+                return (_DType.PICKLE, pickle.dumps(data))
             return (_DType.NUMBER, data)
 
-        return (_DType.PICKLE, pickle.dumps(data))
+        if self._allow_pickle:
+            return (_DType.PICKLE, pickle.dumps(data))
+
+        raise ValueError('Cannot store value type without pickle support; '
+                         'initialize TinyKV with allow_pickle=True to enable '
+                         'legacy pickled values')
 
     def _unserialize(self, dtype: _DType, data: bytes) -> Any:
         if dtype == _DType.NONE:
@@ -110,16 +182,35 @@ class TinyKV:
             return bool(data)
 
         if dtype == _DType.NUMBER:
-            number = float(data)
-            return int(number) if number.is_integer() else number
+            return float(data)
+
+        if dtype == _DType.LONG:
+            return int(data.decode('utf-8'))
 
         if dtype == _DType.PICKLE:
+            if not self._allow_pickle:
+                value = pickle.loads(data)
+                if isinstance(value, float) and math.isnan(value):
+                    return value
+                raise ValueError('Cannot deserialize pickled value with '
+                                 'allow_pickle=False')
             return pickle.loads(data)
 
-        raise ValueError('Unsupported data type {dtype}')
+        raise ValueError(f'Unsupported data type {dtype}')
 
     def set(self, key: str, value: Any) -> None:
-        """Store a value in the database."""
+        """Store a value in the database.
+
+        Args:
+            key: The key to store the value under.
+            value: The value to store.
+
+        Raises:
+            TypeError: If key is not a string.
+            ValueError: If key is an empty string.
+
+        """
+        _validate_key(key)
         assert self._conn
         dtype, data = self._serialize(value)
         self._conn.execute(f'INSERT OR REPLACE INTO {self._table} (k, t, v) '
@@ -136,7 +227,7 @@ class TinyKV:
             >>> conn = sqlite3.connect(':memory:')
             >>>
             >>> create_schema(conn)
-            >>> kv = TinyKV(conn)
+            >>> kv = TinyKV(conn, allow_pickle=True)
             >>>
             >>> kv.set('foo', 'bar')
             >>> kv.get('foo')
@@ -152,8 +243,11 @@ class TinyKV:
         Raises:
             KeyError: if the key does not exist and no default is
                 provided.
+            TypeError: If key is not a string.
+            ValueError: If key is an empty string.
 
         """
+        _validate_key(key)
         assert self._conn
         cur = self._conn.execute(f'SELECT t, v FROM {self._table} '
                                  'WHERE k = ?', (key,))
@@ -164,7 +258,7 @@ class TinyKV:
             raise KeyError(key)
         return self._unserialize(_DType(row[0]), row[1])
 
-    def get_many(self, keys: Iterable[str]) -> Dict[str, Any]:
+    def get_many(self, keys: Iterable[str]) -> dict[str, Any]:
         """Get many values from the database.
 
         Args:
@@ -174,16 +268,22 @@ class TinyKV:
             A dict where with only the keys found on the database, and their
             respective values.
 
+        Raises:
+            TypeError: If any key is not a string.
+            ValueError: If any key is an empty string.
+
         """
         assert self._conn
         tkeys = tuple(keys)
+        for k in tkeys:
+            _validate_key(k)
         rows = self._conn.execute(f'SELECT k, t, v FROM {self._table} WHERE '
                                   f'k IN ({", ".join(["?"] * len(tkeys))})',
                                   tkeys)
         return {r[0]: self._unserialize(_DType(r[1]), r[2])
                 for r in rows.fetchall()}
 
-    def get_glob(self, glob_key: str) -> Dict[str, Any]:
+    def get_glob(self, glob_key: str) -> dict[str, Any]:
         """Get many values using a glob pattern.
 
         Similar to `get_many()`, but using a glob pattern.
@@ -195,7 +295,12 @@ class TinyKV:
             A dict where keys are the keys matching `glob_key` found
             on the database, and their respective values.
 
+        Raises:
+            TypeError: If glob_key is not a string.
+            ValueError: If glob_key is an empty string.
+
         """
+        _validate_key(glob_key)
         assert self._conn
         rows = self._conn.execute('SELECT k, t, v '
                                   f'FROM {self._table} '
@@ -209,8 +314,16 @@ class TinyKV:
         Args:
             kvdict: A mapping of keys to values.
 
+        Raises:
+            TypeError: If any key is not a string.
+            ValueError: If any key is an empty string.
+
         """
         assert self._conn
+        if not kvdict:
+            return
+        for k in kvdict:
+            _validate_key(k)
         self._conn.execute(f'INSERT OR REPLACE INTO {self._table} (k, t, v) '
                            f'VALUES {", ".join(["(?, ?, ?)"] * len(kvdict))}',
                            tuple(p[i]
@@ -228,8 +341,11 @@ class TinyKV:
 
         Raises:
             KeyError: If the key is not found.
+            TypeError: If key is not a string.
+            ValueError: If key is an empty string.
 
         """
+        _validate_key(key)
         assert self._conn
         cur = self._conn.execute(f'DELETE FROM {self._table} WHERE k = ?',
                                  (key,))
@@ -243,9 +359,17 @@ class TinyKV:
 
         Args:
             keys: Iterable of keys to remove.
+
+        Raises:
+            TypeError: If any key is not a string.
+            ValueError: If any key is an empty string.
         """
         assert self._conn
         tkeys = tuple(keys)
+        if not tkeys:
+            return
+        for k in tkeys:
+            _validate_key(k)
         self._conn.execute(f'DELETE FROM {self._table} WHERE '
                            f'k IN ({", ".join(["?"] * len(tkeys))})',
                            tkeys)

tinykv-0.2.1/tests/test_tinykv.py

@@ -0,0 +1,321 @@
+import datetime
+import math
+import pickle
+import sqlite3
+import secrets
+import tempfile
+import unittest
+import warnings
+from pathlib import Path
+from tinykv import TinyKV, create_schema
+
+_TEST_DATA = {
+    'none': None,
+    'foo': 'bar',
+    'bytes': secrets.token_bytes(20),
+    'maybe': True,
+    'one': 1,
+    'pi': 3.1415926,
+    'complex': complex(1, 2),
+    'now':  datetime.datetime.now(),
+}
+
+
+class TestKV(unittest.TestCase):  # pylint: disable=too-many-public-methods
+
+    def setUp(self) -> None:
+        # pylint: disable-next=consider-using-with
+        self._tempdir = tempfile.TemporaryDirectory()
+        self._path = Path(self._tempdir.name) / 'db.sqlite3'
+        self._conn = sqlite3.connect(self._path)
+        create_schema(self._conn)
+
+    def tearDown(self) -> None:
+        self._conn.close()
+        self._tempdir.cleanup()
+
+    def test_set_get(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        for k, v in _TEST_DATA.items():
+            with self.subTest(k=k):
+                db.set(k, v)
+                self.assertEqual(db.get(k), v)
+
+    def test_create_schema_existing_table_raises_by_default(self) -> None:
+        with self.assertRaises(sqlite3.OperationalError):
+            create_schema(self._conn)
+
+    def test_create_schema_if_not_exists(self) -> None:
+        create_schema(self._conn, if_not_exists=True)
+
+    def test_set_replace(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('foo', 1)
+        db.set('foo', 'bar')
+
+        self.assertEqual(db.get('foo'), 'bar')
+
+    def test_get_default(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        self.assertEqual(db.get('foo', 'bar'), 'bar')
+        self.assertIsNone(db.get('foo', None))
+
+    def test_set_get_persist(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        for k, v in _TEST_DATA.items():
+            db.set(k, v)
+
+        self._conn.commit()
+        self._conn.close()
+
+        self._conn = sqlite3.connect(self._path)
+        db2 = TinyKV(self._conn, allow_pickle=True)
+        for k, v in _TEST_DATA.items():
+            with self.subTest(k=k):
+                self.assertEqual(db2.get(k), v)
+
+    def test_get_many(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        for k, v in _TEST_DATA.items():
+            db.set(k, v)
+
+        self.assertEqual(db.get_many(_TEST_DATA.keys()), _TEST_DATA)
+
+    def test_get_many_nonexisting(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('foo', 1)
+        db.set('bar', 2)
+
+        self.assertEqual(db.get_many(('foo', 'bar', 'not-there')),
+                         {'foo': 1, 'bar': 2})
+
+    def test_get_glob(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('foo:abc', 1)
+        db.set('foo:xyz', 2)
+        db.set('bar:abc', 3)
+
+        self.assertEqual(db.get_glob('foo:*'), {'foo:abc': 1, 'foo:xyz': 2})
+
+    def test_set_many(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set_many(_TEST_DATA)
+
+        for k, v in _TEST_DATA.items():
+            with self.subTest(k=k):
+                self.assertEqual(db.get(k), v)
+
+    def test_set_many_empty_mapping(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set_many({})
+
+    def test_remove(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('foo', 'bar')
+
+        db.remove('foo')
+
+        with self.assertRaises(KeyError):
+            db.get('foo')
+
+    def test_remove_nonexistent(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaises(KeyError):
+            db.remove('nonexistent')
+
+    def test_remove_many(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('foo', 'bar')
+        db.set('bar', 'bar')
+
+        db.remove_many(('foo', 'bar'))
+
+        with self.assertRaises(KeyError):
+            db.get('foo')
+
+        with self.assertRaises(KeyError):
+            db.get('bar')
+
+    def test_remove_many_empty(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.remove_many([])
+
+    def test_safe_mode_rejects_pickle_on_set(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=False)
+
+        with self.assertRaisesRegex(ValueError, 'allow_pickle=True'):
+            db.set('now', datetime.datetime.now())
+
+    def test_safe_mode_rejects_existing_pickled_row(self) -> None:
+        payload = pickle.dumps(datetime.datetime(2022, 3, 19, 20, 15, 5))
+        self._conn.execute('INSERT INTO kv (k, t, v) VALUES (?, ?, ?)',
+                           ('pickled', 6, payload))
+
+        db = TinyKV(self._conn, allow_pickle=False)
+        with self.assertRaisesRegex(ValueError, 'allow_pickle=False'):
+            db.get('pickled')
+
+    def test_compat_mode_allows_pickle_roundtrip(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        dt = datetime.datetime(2022, 3, 19, 20, 15, 5)
+
+        db.set('dt', dt)
+
+        self.assertEqual(db.get('dt'), dt)
+
+    def test_implicit_allow_pickle_warns(self) -> None:
+        with self.assertWarnsRegex(FutureWarning, 'allow_pickle'):
+            TinyKV(self._conn)
+
+    def test_explicit_allow_pickle_true_does_not_warn(self) -> None:
+        with warnings.catch_warnings(record=True) as warns:
+            warnings.simplefilter('always')
+            TinyKV(self._conn, allow_pickle=True)
+        self.assertEqual(warns, [])
+
+    def test_explicit_allow_pickle_false_does_not_warn(self) -> None:
+        with warnings.catch_warnings(record=True) as warns:
+            warnings.simplefilter('always')
+            TinyKV(self._conn, allow_pickle=False)
+        self.assertEqual(warns, [])
+
+    def test_large_int_roundtrip(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        test_cases = [
+            (2**53 - 1, 'max safe integer'),
+            (2**53, 'just over max safe integer'),
+            (2**53 + 1, 'larger than max safe integer'),
+            (10**20, 'very large positive'),
+            (-(10**20), 'very large negative'),
+            (0, 'zero'),
+            (1, 'small positive'),
+            (-1, 'small negative'),
+        ]
+
+        for value, description in test_cases:
+            with self.subTest(value=value, description=description):
+                db.set('large_int', value)
+                self.assertEqual(db.get('large_int'), value)
+
+    def test_integral_float_roundtrip(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        test_cases = [
+            (1.0, 'one as float'),
+            (0.0, 'zero as float'),
+            (-0.0, 'negative zero as float'),
+            (1.5, 'one point five'),
+            (-2.5, 'negative two point five'),
+        ]
+
+        for value, description in test_cases:
+            with self.subTest(value=value, description=description):
+                db.set('integral_float', value)
+                result = db.get('integral_float')
+                self.assertEqual(result, value)
+                self.assertIsInstance(result, float)
+
+    def test_nan_roundtrip(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('nan', float('nan'))
+        result = db.get('nan')
+        self.assertTrue(math.isnan(result))
+
+    def test_nan_roundtrip_safe_mode(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=False)
+
+        db.set('nan', float('nan'))
+        result = db.get('nan')
+        self.assertTrue(math.isnan(result))
+
+    def test_inf_roundtrip(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+
+        db.set('inf', float('inf'))
+        self.assertEqual(db.get('inf'), float('inf'))
+
+        db.set('neg_inf', float('-inf'))
+        self.assertEqual(db.get('neg_inf'), float('-inf'))
+
+    def test_set_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.set(123, 'value')  # type: ignore[arg-type]
+
+    def test_set_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.set('', 'value')
+
+    def test_get_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.get(123)  # type: ignore[arg-type]
+
+    def test_get_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.get('')
+
+    def test_remove_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.remove(123)  # type: ignore[arg-type]
+
+    def test_remove_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.remove('')
+
+    def test_get_many_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.get_many([123])  # type: ignore[list-item]
+
+    def test_get_many_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.get_many([''])
+
+    def test_set_many_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.set_many({123: 'value'})  # type: ignore[dict-item]
+
+    def test_set_many_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.set_many({'': 'value'})
+
+    def test_remove_many_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.remove_many([123])  # type: ignore[list-item]
+
+    def test_remove_many_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.remove_many([''])
+
+    def test_get_glob_rejects_non_string_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(TypeError, 'must be a string'):
+            db.get_glob(123)  # type: ignore[arg-type]
+
+    def test_get_glob_rejects_empty_key(self) -> None:
+        db = TinyKV(self._conn, allow_pickle=True)
+        with self.assertRaisesRegex(ValueError, 'must not be empty'):
+            db.get_glob('')

tinykv-0.1.2/tests/test_tinykv.py

@@ -1,132 +0,0 @@
-import datetime
-import unittest
-import sqlite3
-import secrets
-import tempfile
-from pathlib import Path
-from tinykv import TinyKV, create_schema
-
-_TEST_DATA = {
-    'none': None,
-    'foo': 'bar',
-    'bytes': secrets.token_bytes(20),
-    'maybe': True,
-    'one': 1,
-    'pi': 3.1415926,
-    'complex': complex(1, 2),
-    'now':  datetime.datetime.now(),
-}
-
-
-class TestKV(unittest.TestCase):
-
-    def setUp(self) -> None:
-        # pylint: disable-next=consider-using-with
-        self._tempdir = tempfile.TemporaryDirectory()
-        self._path = Path(self._tempdir.name) / 'db.sqlite3'
-        self._conn = sqlite3.connect(self._path)
-        create_schema(self._conn)
-
-    def tearDown(self) -> None:
-        self._conn.close()
-        self._tempdir.cleanup()
-
-    def test_set_get(self) -> None:
-        db = TinyKV(self._conn)
-
-        for k, v in _TEST_DATA.items():
-            with self.subTest(k=k):
-                db.set(k, v)
-                self.assertEqual(db.get(k), v)
-
-    def test_set_replace(self) -> None:
-        db = TinyKV(self._conn)
-
-        db.set('foo', 1)
-        db.set('foo', 'bar')
-
-        self.assertEqual(db.get('foo'), 'bar')
-
-    def test_get_default(self) -> None:
-        db = TinyKV(self._conn)
-        self.assertEqual(db.get('foo', 'bar'), 'bar')
-        self.assertIsNone(db.get('foo', None))
-
-    def test_set_get_persist(self) -> None:
-        db = TinyKV(self._conn)
-
-        for k, v in _TEST_DATA.items():
-            db.set(k, v)
-
-        self._conn.commit()
-        self._conn.close()
-
-        self._conn = sqlite3.connect(self._path)
-        db2 = TinyKV(self._conn)
-        for k, v in _TEST_DATA.items():
-            with self.subTest(k=k):
-                self.assertEqual(db2.get(k), v)
-
-    def test_get_many(self) -> None:
-        db = TinyKV(self._conn)
-
-        for k, v in _TEST_DATA.items():
-            db.set(k, v)
-
-        self.assertEqual(db.get_many(_TEST_DATA.keys()), _TEST_DATA)
-
-    def test_get_many_nonexisting(self) -> None:
-        db = TinyKV(self._conn)
-
-        db.set('foo', 1)
-        db.set('bar', 2)
-
-        self.assertEqual(db.get_many(('foo', 'bar', 'not-there')),
-                         {'foo': 1, 'bar': 2})
-
-    def test_get_glob(self) -> None:
-        db = TinyKV(self._conn)
-
-        db.set('foo:abc', 1)
-        db.set('foo:xyz', 2)
-        db.set('bar:abc', 3)
-
-        self.assertEqual(db.get_glob('foo:*'), {'foo:abc': 1, 'foo:xyz': 2})
-
-    def test_set_many(self) -> None:
-        db = TinyKV(self._conn)
-
-        db.set_many(_TEST_DATA)
-
-        for k, v in _TEST_DATA.items():
-            with self.subTest(k=k):
-                self.assertEqual(db.get(k), v)
-
-    def test_remove(self) -> None:
-        db = TinyKV(self._conn)
-
-        db.set('foo', 'bar')
-
-        db.remove('foo')
-
-        with self.assertRaises(KeyError):
-            db.get('foo')
-
-    def test_remove_nonexistent(self) -> None:
-        db = TinyKV(self._conn)
-        with self.assertRaises(KeyError):
-            db.remove('nonexistent')
-
-    def test_remove_many(self) -> None:
-        db = TinyKV(self._conn)
-
-        db.set('foo', 'bar')
-        db.set('bar', 'bar')
-
-        db.remove_many(('foo', 'bar'))
-
-        with self.assertRaises(KeyError):
-            db.get('foo')
-
-        with self.assertRaises(KeyError):
-            db.get('bar')