cachekit 0.10.0__tar.gz → 0.11.0__tar.gz

{cachekit-0.10.0 → cachekit-0.11.0}/Cargo.lock

@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.10.0"
+version = "0.11.0"
 dependencies = [
  "cachekit-core",
  "criterion",

{cachekit-0.10.0 → cachekit-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.10.0
+Version: 0.11.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -26,15 +26,16 @@ Requires-Dist: tenacity>=8.0.0
 Requires-Dist: prometheus-client>=0.22.1
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: blake3>=1.0.5
-Requires-Dist: msgpack>=1.1.2
-Requires-Dist: orjson>=3.9.0
+Requires-Dist: msgpack>=1.2.1
 Requires-Dist: xxhash>=3.5.0
 Requires-Dist: httpx[http2]>=0.28.1
 Requires-Dist: numpy>=2.0.2 ; extra == 'data'
 Requires-Dist: pandas>=1.3.0 ; extra == 'data'
 Requires-Dist: pyarrow>=21.0.0 ; extra == 'data'
+Requires-Dist: orjson>=3.9.0 ; extra == 'json'
 Requires-Dist: pymemcache>=4.0.0 ; extra == 'memcached'
 Provides-Extra: data
+Provides-Extra: json
 Provides-Extra: memcached
 License-File: LICENSE
 Summary: Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance
@@ -302,7 +303,7 @@ def test_cached_function():
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
 | **StandardSerializer** | ★★★★☆ | General Python types, NumPy, Pandas |
-| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) |
+| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
 | **ArrowSerializer** | ★★★★★ | Large DataFrames (6-23x faster for 10K+ rows) |
 | **EncryptionWrapper** | ★★★★☆ | Wraps any serializer with AES-256-GCM |
 

{cachekit-0.10.0 → cachekit-0.11.0}/README.md

@@ -249,7 +249,7 @@ def test_cached_function():
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
 | **StandardSerializer** | ★★★★☆ | General Python types, NumPy, Pandas |
-| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) |
+| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
 | **ArrowSerializer** | ★★★★★ | Large DataFrames (6-23x faster for 10K+ rows) |
 | **EncryptionWrapper** | ★★★★☆ | Wraps any serializer with AES-256-GCM |
 

{cachekit-0.10.0 → cachekit-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.10.0"
+version = "0.11.0"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}
@@ -64,8 +64,7 @@ dependencies = [
     "psutil>=7.0.0",
     # Serialization and hashing
     "blake3>=1.0.5",
-    "msgpack>=1.1.2",
-    "orjson>=3.9.0",
+    "msgpack>=1.2.1",
     "xxhash>=3.5.0",
     # HTTP client for SaaS backend (cachekit.io)
     "httpx[http2]>=0.28.1",
@@ -78,6 +77,10 @@ data = [
     "pandas>=1.3.0",
     "pyarrow>=21.0.0",
 ]
+json = [
+    # OrjsonSerializer (serializer="orjson") — fast JSON via orjson
+    "orjson>=3.9.0",
+]
 memcached = [
     "pymemcache>=4.0.0",
 ]
@@ -228,6 +231,9 @@ dev = [
     "numpy>=2.0.2",
     "pandas>=1.3.0",
     "pyarrow>=21.0.0",
+    # OrjsonSerializer support — now the [json] optional extra; kept here so the
+    # orjson tests, doctests, and markdown-docs still resolve it in dev/CI.
+    "orjson>=3.9.0",
     "pytest-xdist>=3.8.0",
     "time-machine>=2.19.0",
 ]

{cachekit-0.10.0 → cachekit-0.11.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.10.0"
+version = "0.11.0"
 edition = "2021"
 authors = ["cachekit Contributors"]
 description = "High-performance storage engine for caching with compression and encryption"

{cachekit-0.10.0 → cachekit-0.11.0}/rust/README.md

@@ -249,7 +249,7 @@ def test_cached_function():
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
 | **StandardSerializer** | ★★★★☆ | General Python types, NumPy, Pandas |
-| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) |
+| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
 | **ArrowSerializer** | ★★★★★ | Large DataFrames (6-23x faster for 10K+ rows) |
 | **EncryptionWrapper** | ★★★★☆ | Wraps any serializer with AES-256-GCM |
 

{cachekit-0.10.0 → cachekit-0.11.0}/src/cachekit/__init__.py

@@ -68,7 +68,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.10.0"
+__version__ = "0.11.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar

{cachekit-0.10.0 → cachekit-0.11.0}/src/cachekit/cache_handler.py

@@ -32,6 +32,11 @@ if TYPE_CHECKING:
 # Python-specific type tags that no other-language SDK can decode.
 CROSS_SDK_SERIALIZER_NAMES = ("default", "std", "standard", "orjson", "arrow")
 
+# Serializer-name aliases collapsed to one canonical frame tag so interchangeable names stay
+# cache-compatible: an entry written as 'auto' must read back under 'pythonic' (its documented
+# alias) and vice-versa, instead of a serializer-mismatch that recomputes on every read (#167).
+_SERIALIZER_NAME_ALIASES = {"std": "default", "standard": "default", "pythonic": "auto"}
+
 # Global DI container instance with default registrations
 container = DIContainer()
 container.register(LoggerProvider, DefaultLoggerProvider)
@@ -348,7 +353,7 @@ class CacheSerializationHandler:
         # Extract string name for metadata storage (for protocol instances, use class name)
         if isinstance(serializer_name, str):
             # Canonicalize aliases to prevent envelope mismatch on deserialize
-            self._serializer_string_name = "default" if serializer_name in ("std", "standard") else serializer_name
+            self._serializer_string_name = _SERIALIZER_NAME_ALIASES.get(serializer_name, serializer_name)
         else:
             # Protocol instance - use class name for metadata
             self._serializer_string_name = type(serializer_name).__name__

{cachekit-0.10.0 → cachekit-0.11.0}/src/cachekit/serializers/__init__.py

@@ -15,11 +15,11 @@ from .base import (
     SerializerProtocol,
 )
 from .encryption_wrapper import EncryptionWrapper
-from .orjson_serializer import OrjsonSerializer
 from .standard_serializer import StandardSerializer
 
 if TYPE_CHECKING:
     from .arrow_serializer import ArrowSerializer
+    from .orjson_serializer import OrjsonSerializer
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +37,20 @@ def _get_arrow_serializer() -> type:
     return _ArrowSerializer
 
 
+# Lazy import for optional OrjsonSerializer (requires orjson from [json] extra)
+_OrjsonSerializer: type | None = None
+
+
+def _get_orjson_serializer() -> type:
+    """Lazy-load OrjsonSerializer. Raises ImportError if orjson not installed."""
+    global _OrjsonSerializer
+    if _OrjsonSerializer is None:
+        from .orjson_serializer import OrjsonSerializer
+
+        _OrjsonSerializer = OrjsonSerializer
+    return _OrjsonSerializer
+
+
 # Validate ByteStorage works correctly
 test_storage = ByteStorage("msgpack")
 test_data = b"test validation data"
@@ -57,7 +71,7 @@ SERIALIZER_REGISTRY = {
     "default": StandardSerializer,  # Language-agnostic MessagePack for multi-language caches
     "std": StandardSerializer,  # Explicit StandardSerializer alias
     "arrow": None,  # Lazy-loaded: requires pyarrow from [data] extra
-    "orjson": OrjsonSerializer,
+    "orjson": None,  # Lazy-loaded: requires orjson from [json] extra
     "encrypted": EncryptionWrapper,  # StandardSerializer + AES-256-GCM encryption
 }
 
@@ -116,9 +130,11 @@ def get_serializer(name: str, enable_integrity_checking: bool = True) -> Seriali
                 f"@cache(serializer=MySerializer())"
             )
 
-        # Get serializer class (lazy-load arrow if needed)
+        # Get serializer class (lazy-load optional serializers if needed)
         if name == "arrow":
             serializer_class = _get_arrow_serializer()
+        elif name == "orjson":
+            serializer_class = _get_orjson_serializer()
         else:
             serializer_class = SERIALIZER_REGISTRY[name]
 
@@ -177,9 +193,15 @@ def get_serializer_info() -> dict[str, dict[str, Any]]:
             if hasattr(instance, "get_info"):
                 info[name].update(instance.get_info())  # type: ignore[attr-defined]
         except ImportError as e:
+            # Optional serializer whose backing dependency (pyarrow / orjson) is absent.
+            optional_modules = {
+                "arrow": ("ArrowSerializer", "cachekit.serializers.arrow_serializer"),
+                "orjson": ("OrjsonSerializer", "cachekit.serializers.orjson_serializer"),
+            }
+            cls, module = optional_modules.get(name, ("Unknown", "unknown"))
             info[name] = {
-                "class": "ArrowSerializer" if name == "arrow" else "Unknown",
-                "module": "cachekit.serializers.arrow_serializer",
+                "class": cls,
+                "module": module,
                 "available": False,
                 "error": str(e),
             }
@@ -194,9 +216,11 @@ def get_serializer_info() -> dict[str, dict[str, Any]]:
 
 
 def __getattr__(name: str) -> Any:
-    """Lazy attribute access for optional ArrowSerializer."""
+    """Lazy attribute access for optional ArrowSerializer / OrjsonSerializer."""
     if name == "ArrowSerializer":
         return _get_arrow_serializer()
+    if name == "OrjsonSerializer":
+        return _get_orjson_serializer()
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 

{cachekit-0.10.0 → cachekit-0.11.0}/src/cachekit/serializers/auto_serializer.py

@@ -26,6 +26,7 @@ from typing import TYPE_CHECKING, Any, ClassVar, Optional
 from uuid import UUID
 
 import msgpack
+import xxhash
 
 if TYPE_CHECKING:
     import numpy as np
@@ -295,7 +296,8 @@ def _auto_object_hook(obj: Any) -> Any:
                 raise SerializationError("Cannot deserialize numpy array: numpy is not installed")
             if "data" not in obj or "shape" not in obj or "dtype" not in obj:
                 raise SerializationError("Invalid ndarray format: missing required fields in cached data")
-            return np.frombuffer(obj["data"], dtype=obj["dtype"]).reshape(obj["shape"])
+            # .copy(): writable result that does not alias the source buffer (the L1-cached bytes on a hit) — #157.
+            return np.frombuffer(obj["data"], dtype=obj["dtype"]).reshape(obj["shape"]).copy()
 
     return obj
 
@@ -492,15 +494,19 @@ class AutoSerializer:
         """
         # coerce unwrap's zero-copy memoryview; no-op when already bytes (enables .startswith below + Rust retrieve)
         data = bytes(data)
-        # Check for custom NumPy format
-        if data.startswith(b"NUMPY_RAW"):
+        # Custom NumPy format — raw [NUMPY_RAW...] or checksummed [8-byte xxHash3-64][NUMPY_RAW...].
+        # Detect by structure (like ArrowSerializer) so it is caught here, before the lossy
+        # retrieve()/msgpack fallback below — _deserialize_numpy strips + verifies the optional
+        # checksum and fails closed on mismatch (#155), even when no metadata is supplied.
+        if data.startswith(b"NUMPY_RAW") or (len(data) >= 17 and data[8:17] == b"NUMPY_RAW"):
             return self._deserialize_numpy(data)
 
         # Use metadata for format detection if available
         if metadata and hasattr(metadata, "original_type"):
             detected_format = metadata.original_type
 
-            # For specialized formats, call type-specific deserializers
+            # For specialized formats, call type-specific deserializers.
+            # _deserialize_numpy strips + verifies the optional xxHash3-64 checksum prefix itself.
             if detected_format == "numpy":
                 return self._deserialize_numpy(data)
             elif detected_format == "arrow":
@@ -513,31 +519,31 @@ class AutoSerializer:
                         "Install with: pip install 'cachekit[data]'"
                     )
             elif detected_format == "dataframe":
-                # For DataFrame and Series, we need to handle both Rust envelope and direct data
                 if self.enable_integrity_checking and len(data) > 4:
+                    # Unwrap the ByteStorage envelope. A checksum mismatch (raised by retrieve) fails
+                    # closed with a clear corruption error instead of being swallowed and re-parsed as
+                    # raw msgpack, which lost the diagnostic and produced a confusing error (#156).
+                    # The unpack/build sits OUTSIDE this guard so a genuine post-retrieve error surfaces
+                    # as itself rather than being mistaken for corruption.
                     try:
-                        # Try Rust envelope first
                         original_data, _ = self._byte_storage.retrieve(data)
-                        unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
-                        return self._deserialize_dataframe(unpacked_data)
-                    except Exception as e:
-                        # Fall back to direct unpacking
-                        logger.debug(f"Rust envelope parsing failed for DataFrame, falling back to direct unpacking: {e}")
-                # Direct msgpack data
+                    except (ValueError, SerializationError) as e:
+                        raise SerializationError(f"DataFrame integrity check failed (corrupted cache entry): {e}") from e
+                    unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
+                    return self._deserialize_dataframe(unpacked_data)
+                # Integrity off: data is direct msgpack (no envelope)
                 unpacked_data = msgpack.unpackb(data, **self._msgpack_unpack_opts)
                 return self._deserialize_dataframe(unpacked_data)
             elif detected_format == "series":
-                # For DataFrame and Series, we need to handle both Rust envelope and direct data
                 if self.enable_integrity_checking and len(data) > 4:
+                    # Same fail-closed contract as the DataFrame branch above (#156).
                     try:
-                        # Try Rust envelope first
                         original_data, _ = self._byte_storage.retrieve(data)
-                        unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
-                        return self._deserialize_series(unpacked_data)
-                    except Exception as e:
-                        # Fall back to direct unpacking
-                        logger.debug(f"Rust envelope parsing failed for Series, falling back to direct unpacking: {e}")
-                # Direct msgpack data
+                    except (ValueError, SerializationError) as e:
+                        raise SerializationError(f"Series integrity check failed (corrupted cache entry): {e}") from e
+                    unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
+                    return self._deserialize_series(unpacked_data)
+                # Integrity off: data is direct msgpack (no envelope)
                 unpacked_data = msgpack.unpackb(data, **self._msgpack_unpack_opts)
                 return self._deserialize_series(unpacked_data)
 
@@ -603,17 +609,20 @@ class AutoSerializer:
             return self._deserialize_numpy(data)
 
     def _serialize_numpy(self, arr: np.ndarray) -> bytes:  # type: ignore[name-defined]
-        """Serialize NumPy array with metadata, bypassing Rust ByteStorage.
+        """Serialize a NumPy array into the ``NUMPY_RAW`` binary format.
 
         Requires: numpy installed (HAS_NUMPY=True)
 
         Raises:
             RuntimeError: If numpy not installed
 
-        Skips Rust layer because:
-        - Compression ineffective on NumPy's random data patterns
-        - Native serialization already fast (~2ms)
-        - Rust overhead adds ~8ms with minimal benefit
+        When ``enable_integrity_checking`` is on (the default / ``@cache``), an 8-byte
+        xxHash3-64 checksum is prepended to the ``NUMPY_RAW`` payload with NO compression,
+        mirroring ``ArrowSerializer`` ([checksum][payload]). The numpy branch used to return
+        these bytes *unchecked*, so a corrupted entry was reconstructed as silently-wrong data
+        on read (#155). Compression is deliberately skipped: numpy is large, often-incompressible
+        binary, and LZ4 here measured ~100x slower with no size benefit. When integrity is off
+        (``@cache.minimal``), the raw payload is returned without a checksum (msgpack-off parity).
         """
         if not HAS_NUMPY:
             raise RuntimeError("NumPy not installed. Install with: pip install cachekit[data]")
@@ -627,7 +636,18 @@ class AutoSerializer:
         shape_len = len(shape_data).to_bytes(2, byteorder="little")
 
         # Combine: header + raw numpy bytes (zero-copy from NumPy)
-        return b"NUMPY_RAW" + dtype_len + dtype_str + shape_len + shape_data + arr.tobytes()
+        raw = b"NUMPY_RAW" + dtype_len + dtype_str + shape_len + shape_data + arr.tobytes()
+
+        if self.enable_integrity_checking:
+            # Checksum-only envelope: prepend the 8-byte xxHash3-64 of the payload, NO compression.
+            # numpy arrays are large, often-incompressible binary; routing them through ByteStorage's
+            # LZ4 measured ~100x slower to serialize, ~400x slower to read, and inflated incompressible
+            # data ~1.56x. This mirrors ArrowSerializer's [8-byte xxHash3-64][payload] scheme, giving
+            # the #155 integrity guarantee at ~0 cost. The read side strips + verifies in
+            # _deserialize_numpy. (No LZ4 here means numpy is genuinely uncompressed, so the
+            # metadata.compressed=False set in serialize() is correct — sidesteps #166 entirely.)
+            return xxhash.xxh3_64_digest(raw) + raw
+        return raw
 
     def _deserialize_numpy(self, data: bytes) -> np.ndarray:
         """Deserialize NumPy array from NUMPY_RAW binary format.
@@ -641,6 +661,16 @@ class AutoSerializer:
         if not HAS_NUMPY:
             raise RuntimeError("NumPy not installed. Install with: pip install cachekit[data]")
 
+        # Strip + verify the optional 8-byte xxHash3-64 checksum prefix written by integrity-on
+        # serialization. Detect by structure (like ArrowSerializer): a checksummed entry is
+        # [8-byte checksum][NUMPY_RAW...]; a raw entry (integrity-off / legacy) is [NUMPY_RAW...].
+        # A mismatch fails closed (#155) — never reconstructs the corrupted array.
+        if not data.startswith(b"NUMPY_RAW") and len(data) >= 17 and data[8:17] == b"NUMPY_RAW":
+            body = data[8:]
+            if xxhash.xxh3_64_digest(body) != data[:8]:
+                raise SerializationError("NumPy integrity check failed: xxHash3-64 checksum mismatch (corrupted cache entry)")
+            data = body
+
         if not data.startswith(b"NUMPY_RAW"):
             raise SerializationError("Invalid NumPy data format - expected NUMPY_RAW header")
 
@@ -666,9 +696,11 @@ class AutoSerializer:
                 shape.append(dim)
             shape = tuple(shape)
 
-            # Extract raw numpy bytes and reconstruct
+            # Extract raw numpy bytes and reconstruct. .copy() so the result is writable and does
+            # not alias the source bytes (the L1-cached buffer on a hit) — see #157. frombuffer alone
+            # returns a read-only view aliasing the input.
             raw_bytes = data[offset:]
-            arr = np.frombuffer(raw_bytes, dtype=dtype_str)
+            arr = np.frombuffer(raw_bytes, dtype=dtype_str).copy()
             return arr.reshape(shape)
         except (ValueError, IndexError, UnicodeDecodeError) as e:
             raise SerializationError(f"Failed to deserialize NumPy array: {e}") from e
@@ -729,8 +761,8 @@ class AutoSerializer:
         columns_data = {}
         for col, col_info in serialized["data"].items():
             if col_info["type"] == "numeric":
-                # Reconstruct from NumPy bytes
-                arr = np.frombuffer(col_info["data"], dtype=col_info["dtype"])
+                # Reconstruct from NumPy bytes; .copy() → writable, non-aliasing column (#157).
+                arr = np.frombuffer(col_info["data"], dtype=col_info["dtype"]).copy()
                 columns_data[col] = arr
             else:
                 # Use object data directly
@@ -793,7 +825,8 @@ class AutoSerializer:
             serialized = msgpack.unpackb(data, **self._msgpack_unpack_opts)
 
         if serialized["type"] == "numeric":
-            values = np.frombuffer(serialized["data"], dtype=serialized["dtype"])
+            # .copy() → writable Series values that do not alias the source buffer (#157).
+            values = np.frombuffer(serialized["data"], dtype=serialized["dtype"]).copy()
         else:
             values = serialized["data"]
 

{cachekit-0.10.0 → cachekit-0.11.0}/src/cachekit/serializers/orjson_serializer.py

@@ -14,7 +14,12 @@ from __future__ import annotations
 
 from typing import Any, ClassVar
 
-import orjson
+# Required dependency: orjson (fail-fast with install hint when the [json] extra is absent)
+try:
+    import orjson
+except ImportError as e:  # pragma: no cover - only reachable without the [json] extra (behavior tested via subprocess)
+    raise ImportError("orjson is not installed. OrjsonSerializer requires the [json] extra: pip install 'cachekit[json]'") from e
+
 import xxhash
 
 from .base import SerializationError, SerializationFormat, SerializationMetadata