cachekit 0.2.3__tar.gz → 0.3.1__tar.gz

{cachekit-0.2.3 → cachekit-0.3.1}/Cargo.lock

@@ -202,9 +202,9 @@ checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
 [[package]]
 name = "bytes"
-version = "1.10.1"
+version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
@@ -231,7 +231,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.2.3"
+version = "0.3.1"
 dependencies = [
  "cachekit-core",
  "criterion",

{cachekit-0.2.3 → cachekit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.2.3
+Version: 0.3.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -43,11 +43,11 @@ Maintainer-email: cachekit Contributors <noreply@cachekit.io>
 License: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Homepage, https://github.com/cachekit-io/cachekit-py
+Project-URL: Changelog, https://github.com/cachekit-io/cachekit-py/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/cachekit-io/cachekit-py#readme
-Project-URL: Repository, https://github.com/cachekit-io/cachekit-py.git
+Project-URL: Homepage, https://github.com/cachekit-io/cachekit-py
 Project-URL: Issues, https://github.com/cachekit-io/cachekit-py/issues
-Project-URL: Changelog, https://github.com/cachekit-io/cachekit-py/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/cachekit-io/cachekit-py.git
 
 <div align="center">
 

{cachekit-0.2.3 → cachekit-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.2.3"
+version = "0.3.1"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}

{cachekit-0.2.3 → cachekit-0.3.1}/rust/Cargo.toml

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

{cachekit-0.2.3 → cachekit-0.3.1}/src/cachekit/__init__.py

@@ -62,7 +62,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.2.3"
+__version__ = "0.3.1"
 
 from typing import Any, Callable, TypeVar
 

{cachekit-0.2.3 → cachekit-0.3.1}/src/cachekit/config/decorator.py

@@ -172,6 +172,9 @@ class DecoratorConfig:
         integrity_checking: Enable checksums for corruption detection (default: True)
                            All serializers use xxHash3-64 (8 bytes).
                            Set to False for @cache.minimal (speed-first, no integrity guarantee)
+        key: Custom key function for complex types. Receives (*args, **kwargs) and returns str.
+             Use for numpy arrays, DataFrames, or cross-language cache sharing.
+             Example: @cache(key=lambda arr: hashlib.blake2b(arr.tobytes()).hexdigest())
         refresh_ttl_on_get: Extend TTL on cache hit
         ttl_refresh_threshold: Minimum remaining TTL fraction (0.0-1.0) to trigger refresh
         backend: L2 backend (RedisBackend, HTTPBackend, None for L1-only)
@@ -183,12 +186,13 @@ class DecoratorConfig:
         encryption: Client-side encryption configuration
     """
 
-    # Core settings (5 fields)
+    # Core settings (6 fields)
     ttl: int | None = None
     namespace: str | None = None
     serializer: Union[str, SerializerProtocol] = "default"  # type: ignore[assignment]  # String name or protocol instance
     safe_mode: bool = False
     integrity_checking: bool = True  # Checksums for corruption detection (xxHash3-64 for all serializers)
+    key: Callable[..., str] | None = None  # Custom key function (escape hatch for complex types)
 
     # Performance (2 fields)
     refresh_ttl_on_get: bool = False
@@ -251,6 +255,7 @@ class DecoratorConfig:
             "namespace": self.namespace,
             "serializer": self.serializer,
             "safe_mode": self.safe_mode,
+            "key": self.key,
             "refresh_ttl_on_get": self.refresh_ttl_on_get,
             "ttl_refresh_threshold": self.ttl_refresh_threshold,
             "backend": self.backend,

{cachekit-0.2.3 → cachekit-0.3.1}/src/cachekit/decorators/wrapper.py

@@ -412,6 +412,15 @@ def create_cache_wrapper(
         deployment_uuid = config.encryption.deployment_uuid
         master_key = config.encryption.master_key
 
+        # Custom key function (escape hatch for complex types)
+        custom_key_func = config.key
+    else:
+        custom_key_func = None
+
+    # Re-scope custom_key_func for closure
+    if "custom_key_func" not in dir():
+        custom_key_func = None
+
     # Fast mode: Disable monitoring overhead, keep performance features
     use_circuit_breaker = circuit_breaker and not fast_mode
     use_adaptive_timeout = adaptive_timeout and not fast_mode
@@ -541,7 +550,13 @@ def create_cache_wrapper(
 
         # Key generation - needed for both L1-only and L1+L2 modes
         try:
-            if fast_mode:
+            # Custom key function takes priority (escape hatch for complex types)
+            if custom_key_func is not None:
+                custom_key = custom_key_func(*args, **kwargs)
+                if not isinstance(custom_key, str):
+                    raise TypeError(f"key function must return str, got {type(custom_key).__name__}")
+                cache_key = f"{namespace or 'default'}:{custom_key}"
+            elif fast_mode:
                 # Minimal key generation - no string formatting overhead
                 from ..hash_utils import cache_key_hash
 
@@ -878,12 +893,17 @@ def create_cache_wrapper(
             cache_key = None
             func_start_time: float | None = None  # Initialize for exception handlers
             try:
-                # Fast key generation path (for simple types)
-                if fast_mode:
+                # Custom key function takes priority (escape hatch for complex types)
+                if custom_key_func is not None:
+                    custom_key = custom_key_func(*args, **kwargs)
+                    if not isinstance(custom_key, str):
+                        raise TypeError(f"key function must return str, got {type(custom_key).__name__}")
+                    cache_key = f"{namespace or 'default'}:{custom_key}"
+                elif fast_mode:
                     # Ultra-fast key generation for hot paths (10-50μs savings)
                     from ..hash_utils import cache_key_hash
 
-                    cache_namespace = namespace or namespace or "default"
+                    cache_namespace = namespace or "default"
                     args_kwargs_str = str(args) + str(kwargs)
                     cache_key = cache_namespace + ":" + func_hash + ":" + cache_key_hash(args_kwargs_str)
                 else:
@@ -1372,7 +1392,9 @@ def create_cache_wrapper(
         """Clear cache statistics and invalidate all cached entries."""
         _stats.clear()
         # Also invalidate actual cache entries
-        invalidate_cache() if not inspect.iscoroutinefunction(func) else ainvalidate_cache()
+        if inspect.iscoroutinefunction(func):
+            raise TypeError("cache_clear() cannot clear cache for async functions. Use 'await fn.ainvalidate_cache()' instead.")
+        invalidate_cache()
 
     if inspect.iscoroutinefunction(func):
         async_wrapper.invalidate_cache = ainvalidate_cache  # type: ignore[attr-defined]

cachekit-0.3.1/src/cachekit/key_generator.py

@@ -0,0 +1,348 @@
+"""Cache key generation functionality."""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path, PurePath
+from typing import TYPE_CHECKING, Any, Callable, NoReturn, cast
+from uuid import UUID
+
+import msgpack
+
+if TYPE_CHECKING:
+    pass
+
+# Constants for constrained array support (per round-table review 2025-12-18)
+ARRAY_MAX_BYTES = 100_000  # 100KB per array
+ARRAY_AGGREGATE_MAX = 5_000_000  # 5MB total across all args
+SUPPORTED_ARRAY_DTYPES = {"int32", "int64", "float32", "float64"}
+DTYPE_MAP = {"int32": "i32", "int64": "i64", "float32": "f32", "float64": "f64"}
+
+
+class CacheKeyGenerator:
+    """Generates consistent cache keys from function calls.
+
+    Uses MessagePack + Blake2b-256 for cross-language compatibility.
+    Implements protocol-v1.0.md Section 3.3 (MessagePack-based approach).
+    """
+
+    # Key length constants
+    MAX_KEY_LENGTH = 250  # Practical cache key length limit (Redis, Memcached, etc.)
+    KEY_PREFIX_LENGTH = 50  # Length of prefix to keep when shortening keys
+
+    # Serializer codes for compact metadata encoding (1 char each)
+    SERIALIZER_CODES = {
+        "std": "s",  # StandardSerializer (multi-language MessagePack)
+        "auto": "a",  # AutoSerializer (Python-specific, NumPy/pandas)
+        "orjson": "o",  # OrjsonSerializer (JSON-based)
+        "arrow": "w",  # ArrowSerializer (columnar format, w=arroW)
+    }
+
+    def __init__(self):
+        """Initialize the key generator.
+
+        Uses MessagePack + Blake2b-256 per protocol-v1.0.md Section 3.3.
+        """
+        pass
+
+    def generate_key(
+        self,
+        func: Callable[..., Any],
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        namespace: str | None = None,
+        integrity_checking: bool = True,
+        serializer_type: str = "std",
+    ) -> str:
+        """Generate a cache key from function and arguments.
+
+        Args:
+            func: The function being cached
+            args: Positional arguments passed to the function
+            kwargs: Keyword arguments passed to the function
+            namespace: Optional namespace prefix for the key
+            integrity_checking: Whether integrity checking is enabled (ByteStorage vs plain MessagePack)
+            serializer_type: Serializer type code ("std", "auto", "orjson", "arrow")
+
+        Returns:
+            A consistent string key for caching
+
+        Note:
+            Uses compact metadata suffix format: :<ic><serializer_code>
+            Example: ":1s" = integrity_checking=True, serializer=StandardSerializer
+        """
+        # Build key components efficiently (avoid f-strings in hot path)
+        key_parts = []
+
+        # Add namespace if provided
+        if namespace:
+            key_parts.extend(["ns:", namespace, ":"])
+
+        # Add function identifier (module + name) - single string operation
+        key_parts.extend(["func:", func.__module__, ".", func.__qualname__, ":"])
+
+        # Generate args hash using Blake2b-256
+        args_hash = self._blake2b_hash(args, kwargs)
+
+        key_parts.extend(["args:", args_hash, ":"])
+
+        # Add compact metadata suffix: :<ic><serializer_code>
+        # Example: ":1s" = integrity_checking=True, serializer=std
+        ic_flag = "1" if integrity_checking else "0"
+        serializer_code = self.SERIALIZER_CODES.get(serializer_type, "s")  # Default to "s" if unknown
+        key_parts.extend([ic_flag, serializer_code])
+
+        # Single join operation reduces string allocations
+        key = "".join(key_parts)
+
+        # Ensure key is within practical limits and contains no problematic characters
+        return self._normalize_key(key)
+
+    def _blake2b_hash(self, args: tuple, kwargs: dict) -> str:
+        """Generate hash using MessagePack + Blake2b-256.
+
+        Blake2b-256 (32 bytes = 64 hex chars) for collision resistance.
+        MessagePack ensures cross-language compatibility.
+
+        Raises:
+            TypeError: If args/kwargs contain unsupported types (custom objects, numpy arrays, etc.)
+        """
+        # Track aggregate array bytes for DoS prevention
+        array_bytes_seen: list[int] = [0]
+
+        # Step 1: Normalize recursively
+        normalized_args = [self._normalize(arg, array_bytes_seen) for arg in args]
+        normalized_kwargs = {k: self._normalize(v, array_bytes_seen) for k, v in sorted(kwargs.items())}
+
+        # Step 2: Serialize with MessagePack
+        try:
+            msgpack_bytes = cast(
+                bytes, msgpack.packb([normalized_args, normalized_kwargs], use_bin_type=True, strict_types=True)
+            )
+        except TypeError as e:
+            # Wrap msgpack's TypeError with a more descriptive message
+            raise TypeError(f"Unsupported type for cache key generation: {e}") from e
+
+        # Step 3: Hash with Blake2b-256
+        return hashlib.blake2b(msgpack_bytes, digest_size=32).hexdigest()
+
+    def _normalize(self, obj: Any, _array_bytes_seen: list[int] | None = None) -> Any:
+        """Normalize object for deterministic MessagePack encoding.
+
+        CRITICAL: Cross-language compatible types ONLY per Protocol v1.1.
+
+        Supported types (per round-table review 2025-12-18):
+        - Primitives: int, str, bytes, bool, None, float
+        - Collections: dict (sorted keys), list, tuple
+        - Extended: Path, UUID, Decimal, Enum, datetime (UTC only)
+        - Arrays: numpy.ndarray (1D, ≤100KB, i32/i64/f32/f64)
+
+        Args:
+            obj: Object to normalize
+            _array_bytes_seen: Internal tracker for aggregate array size (DoS prevention)
+
+        Returns:
+            Normalized object safe for MessagePack serialization
+
+        Raises:
+            TypeError: For unsupported types with helpful guidance
+        """
+        # Initialize aggregate tracker if not provided
+        if _array_bytes_seen is None:
+            _array_bytes_seen = [0]
+
+        # === COLLECTIONS (recursive) ===
+        if isinstance(obj, dict):
+            return {k: self._normalize(v, _array_bytes_seen) for k, v in sorted(obj.items())}
+
+        if isinstance(obj, (list, tuple)):
+            return [self._normalize(x, _array_bytes_seen) for x in obj]
+
+        # === FLOAT (cross-language compat) ===
+        if isinstance(obj, float):
+            # CRITICAL: Normalize -0.0 → 0.0 for cross-language compatibility
+            return 0.0 if obj == 0.0 else obj
+
+        # === EXTENDED TYPES ===
+
+        # Path: normalize to POSIX format for cross-platform consistency
+        if isinstance(obj, (Path, PurePath)):
+            return obj.as_posix()
+
+        # UUID: standard string format
+        if isinstance(obj, UUID):
+            return str(obj)
+
+        # Decimal: exact string representation
+        if isinstance(obj, Decimal):
+            return str(obj)
+
+        # Enum: use value (recursively normalize in case value is complex)
+        if isinstance(obj, Enum):
+            return self._normalize(obj.value, _array_bytes_seen)
+
+        # datetime: UTC only, reject naive datetimes
+        if isinstance(obj, datetime):
+            if obj.tzinfo is None:
+                raise TypeError(
+                    "Naive datetime not allowed in cache keys (timezone ambiguity). "
+                    "Use timezone-aware datetime: datetime(..., tzinfo=timezone.utc)"
+                )
+            return obj.isoformat()
+
+        # === NUMPY ARRAY (constrained support) ===
+        if self._is_numpy_array(obj):
+            return self._normalize_array(obj, _array_bytes_seen)
+
+        # === PRIMITIVES (pass through) ===
+        if isinstance(obj, (int, str, bytes, bool, type(None))):
+            return obj
+
+        # === UNSUPPORTED: Fail fast with helpful message ===
+        return self._raise_unsupported_type(obj)
+
+    def _is_numpy_array(self, obj: Any) -> bool:
+        """Check if object is numpy array without importing numpy."""
+        return type(obj).__module__ == "numpy" and type(obj).__name__ == "ndarray"
+
+    def _normalize_array(self, arr: Any, _array_bytes_seen: list[int]) -> list[Any]:
+        """Normalize numpy array with strict constraints.
+
+        Constraints (per round-table review 2025-12-18):
+        - 1D only (cross-language simplicity)
+        - ≤100KB (memory safety)
+        - 4 dtypes: i32, i64, f32, f64 (cross-language compatibility)
+        - Little-endian byte order (platform determinism)
+        - 256-bit Blake2b hash (collision resistance)
+        - Version prefix for future protocol changes
+
+        Args:
+            arr: numpy.ndarray to normalize
+            _array_bytes_seen: Aggregate byte counter for DoS prevention
+
+        Returns:
+            List of ["__array_v1__", shape_list, dtype_str, content_hash]
+            (list format for MessagePack compatibility with strict_types=True)
+
+        Raises:
+            TypeError: If array doesn't meet constraints
+        """
+        import numpy as np
+
+        # Constraint 1: Size limit per array
+        if arr.nbytes > ARRAY_MAX_BYTES:
+            raise TypeError(
+                f"Array too large ({arr.nbytes:,} bytes, max {ARRAY_MAX_BYTES:,}). Use key= parameter for large arrays."
+            )
+
+        # Constraint 2: Aggregate size limit (DoS prevention)
+        _array_bytes_seen[0] += arr.nbytes
+        if _array_bytes_seen[0] > ARRAY_AGGREGATE_MAX:
+            raise TypeError(
+                f"Total array size exceeds {ARRAY_AGGREGATE_MAX:,} bytes. Use key= parameter for batch array operations."
+            )
+
+        # Constraint 3: 1D only
+        if arr.ndim != 1:
+            raise TypeError(
+                f"Only 1D arrays supported in cache keys (got {arr.ndim}D). "
+                f"Use key= parameter for multidimensional arrays, or flatten with arr.ravel()."
+            )
+
+        # Constraint 4: Supported dtypes only
+        dtype_name = arr.dtype.name
+        if dtype_name not in SUPPORTED_ARRAY_DTYPES:
+            raise TypeError(
+                f"Unsupported array dtype '{dtype_name}'. "
+                f"Supported: {', '.join(sorted(SUPPORTED_ARRAY_DTYPES))}. "
+                f"Cast with arr.astype(np.float64) or use key= parameter."
+            )
+
+        # Ensure C-contiguous memory layout
+        arr = np.ascontiguousarray(arr)
+
+        # Force little-endian byte order for cross-platform determinism
+        if arr.dtype.byteorder not in ("=", "<", "|"):
+            arr = arr.astype(arr.dtype.newbyteorder("<"))
+        elif arr.dtype.byteorder == "=" and sys.byteorder == "big":
+            arr = arr.byteswap().newbyteorder("<")
+
+        # 256-bit Blake2b hash (per security review)
+        content_hash = hashlib.blake2b(arr.tobytes(), digest_size=32).hexdigest()
+
+        # Standardized dtype string for cross-language compatibility
+        dtype_str = DTYPE_MAP[dtype_name]
+
+        # Version prefix for protocol evolution
+        # Return as list (not tuple) for MessagePack compatibility with strict_types=True
+        # Shape converted to list as well
+        return ["__array_v1__", list(arr.shape), dtype_str, content_hash]
+
+    def _raise_unsupported_type(self, obj: Any) -> NoReturn:
+        """Raise helpful TypeError for unsupported types.
+
+        Args:
+            obj: The unsupported object
+
+        Raises:
+            TypeError: Always, with guidance on how to handle the type
+        """
+        type_name = type(obj).__module__ + "." + type(obj).__qualname__
+
+        # Specific guidance for numpy arrays that don't meet constraints
+        if "numpy" in type_name and "ndarray" in type_name:
+            raise TypeError(
+                "numpy array doesn't meet cache key constraints. "
+                "Requirements: 1D, ≤100KB, dtype in (i32, i64, f32, f64). "
+                "Use key= parameter for other arrays."
+            )
+
+        if "pandas" in type_name:
+            raise TypeError(
+                "pandas objects not supported as cache key arguments "
+                "(Parquet serialization is non-deterministic). "
+                "Recommended patterns:\n"
+                "  1. Pass identifier, return DataFrame: @cache def load(id: int) -> pd.DataFrame\n"
+                "  2. Use explicit key: @cache(key=lambda df: hashlib.blake2b(df.to_parquet()).hexdigest())"
+            )
+
+        if isinstance(obj, (set, frozenset)):
+            raise TypeError(
+                "set/frozenset not supported in cache keys (mixed-type sorting crashes). "
+                "Convert to sorted list: sorted(list(your_set))"
+            )
+
+        raise TypeError(
+            f"Unsupported type '{type_name}' for cache key. "
+            f"Supported: dict, list, tuple, int, float, str, bytes, bool, None, "
+            f"Path, UUID, Decimal, Enum, datetime (UTC), 1D numpy arrays (≤100KB, i32/i64/f32/f64). "
+            f"For custom types, use key= parameter."
+        )
+
+    def _normalize_key(self, key: str) -> str:
+        """Normalize key to ensure it's valid for cache backends.
+
+        Args:
+            key: Raw cache key
+
+        Returns:
+            Normalized key safe for cache backends (Redis, Memcached, etc.)
+        """
+        # Replace problematic characters
+        normalized = key.replace(" ", "_").replace("\n", "_").replace("\r", "_")
+
+        # Ensure key length is within practical limits for cache backends
+        if len(normalized) > self.MAX_KEY_LENGTH:
+            # If too long, hash the key to get consistent shorter version
+            # Use Blake2b-256 (32 bytes) for consistency
+            key_hash = hashlib.blake2b(normalized.encode("utf-8"), digest_size=32).hexdigest()
+
+            # Keep first part of original key for readability + hash
+            prefix = normalized[: self.KEY_PREFIX_LENGTH] if len(normalized) > self.KEY_PREFIX_LENGTH else normalized
+            normalized = f"{prefix}:{key_hash[:32]}"
+
+        return normalized

{cachekit-0.2.3 → cachekit-0.3.1}/src/cachekit/logging.py

@@ -7,6 +7,7 @@ that reduces overhead from 570% to <5% while maintaining functionality.
 import json
 import logging
 import os
+import platform
 import random
 import threading
 import time
@@ -170,7 +171,7 @@ class UltraOptimizedStructuredLogger:
 
         # Pre-computed values for performance
         self._sampling_threshold = int(SAMPLING_RATE * 100)
-        self._hostname = os.uname().nodename
+        self._hostname = platform.node()
         self._pid = os.getpid()
 
         # PII patterns to mask (pre-compiled for speed)

{cachekit-0.2.3 → cachekit-0.3.1}/src/cachekit/serializers/__init__.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 import logging
 from threading import Lock
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from cachekit._rust_serializer import ByteStorage
 
-from .arrow_serializer import ArrowSerializer
 from .auto_serializer import AutoSerializer
 from .base import (
     SerializationError,
@@ -16,8 +17,25 @@ from .encryption_wrapper import EncryptionWrapper
 from .orjson_serializer import OrjsonSerializer
 from .standard_serializer import StandardSerializer
 
+if TYPE_CHECKING:
+    from .arrow_serializer import ArrowSerializer
+
 logger = logging.getLogger(__name__)
 
+# Lazy import for optional ArrowSerializer (requires pyarrow from [data] extra)
+_ArrowSerializer: type | None = None
+
+
+def _get_arrow_serializer() -> type:
+    """Lazy-load ArrowSerializer. Raises ImportError if pyarrow not installed."""
+    global _ArrowSerializer
+    if _ArrowSerializer is None:
+        from .arrow_serializer import ArrowSerializer
+
+        _ArrowSerializer = ArrowSerializer
+    return _ArrowSerializer
+
+
 # Validate ByteStorage works correctly
 test_storage = ByteStorage("msgpack")
 test_data = b"test validation data"
@@ -36,7 +54,7 @@ SERIALIZER_REGISTRY = {
     "auto": AutoSerializer,  # Python-specific types (NumPy, pandas, datetime optimization)
     "default": StandardSerializer,  # Language-agnostic MessagePack for multi-language caches
     "std": StandardSerializer,  # Explicit StandardSerializer alias
-    "arrow": ArrowSerializer,
+    "arrow": None,  # Lazy-loaded: requires pyarrow from [data] extra
     "orjson": OrjsonSerializer,
     "encrypted": EncryptionWrapper,  # AutoSerializer + AES-256-GCM encryption
 }
@@ -96,8 +114,13 @@ def get_serializer(name: str, enable_integrity_checking: bool = True) -> Seriali
                 f"@cache(serializer=MySerializer())"
             )
 
+        # Get serializer class (lazy-load arrow if needed)
+        if name == "arrow":
+            serializer_class = _get_arrow_serializer()
+        else:
+            serializer_class = SERIALIZER_REGISTRY[name]
+
         # Instantiate with integrity checking configuration
-        serializer_class = SERIALIZER_REGISTRY[name]
         if name in ("default", "std", "auto", "arrow", "orjson"):
             # All core serializers use enable_integrity_checking parameter
             serializer = serializer_class(enable_integrity_checking=enable_integrity_checking)
@@ -167,9 +190,9 @@ def get_available_serializers() -> dict[str, Any]:
 def benchmark_serializers() -> dict[str, Any]:
     """Get instantiated serializers for benchmarking."""
     serializers = {}
-    for name, cls in get_available_serializers().items():
+    for name in SERIALIZER_REGISTRY:
         try:
-            serializers[name] = cls()
+            serializers[name] = get_serializer(name)
         except Exception as e:
             logger.warning(f"Failed to instantiate {name} serializer: {e}")
     return serializers
@@ -178,28 +201,42 @@ def benchmark_serializers() -> dict[str, Any]:
 def get_serializer_info() -> dict[str, dict[str, Any]]:
     """Get information about available serializers."""
     info = {}
-    for name, cls in get_available_serializers().items():
+    for name in SERIALIZER_REGISTRY:
         try:
-            instance = cls()
+            instance = get_serializer(name)
             info[name] = {
-                "class": cls.__name__,
-                "module": cls.__module__,
+                "class": type(instance).__name__,
+                "module": type(instance).__module__,
                 "available": True,
-                "description": cls.__doc__ or "No description available",
+                "description": type(instance).__doc__ or "No description available",
             }
             # Add method info if available
             if hasattr(instance, "get_info"):
-                info[name].update(instance.get_info())
+                info[name].update(instance.get_info())  # type: ignore[attr-defined]
+        except ImportError as e:
+            info[name] = {
+                "class": "ArrowSerializer" if name == "arrow" else "Unknown",
+                "module": "cachekit.serializers.arrow_serializer",
+                "available": False,
+                "error": str(e),
+            }
         except Exception as e:
             info[name] = {
-                "class": cls.__name__,
-                "module": cls.__module__,
+                "class": "Unknown",
+                "module": "unknown",
                 "available": False,
                 "error": str(e),
             }
     return info
 
 
+def __getattr__(name: str) -> Any:
+    """Lazy attribute access for optional ArrowSerializer."""
+    if name == "ArrowSerializer":
+        return _get_arrow_serializer()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 # Export the main interface
 __all__ = [
     "ArrowSerializer",

{cachekit-0.2.3 → cachekit-0.3.1}/src/cachekit/serializers/auto_serializer.py

@@ -131,6 +131,7 @@ def _auto_default(obj: Any) -> Any:
     - datetime/date/time → ISO-8601 strings
     - UUID → string representation
     - set/frozenset → list (with type marker for roundtrip)
+    - NumPy arrays → dict with binary data, shape, and dtype (nested in dicts/lists)
 
     Provides helpful errors for:
     - Pydantic models (suggest .model_dump())
@@ -162,6 +163,10 @@ def _auto_default(obj: Any) -> Any:
     if isinstance(obj, (set, frozenset)):
         return {"__set__": True, "value": list(obj), "frozen": isinstance(obj, frozenset)}
 
+    # NumPy array support (nested in dicts/lists via msgpack custom encoder)
+    if HAS_NUMPY and isinstance(obj, np.ndarray):
+        return {"__ndarray__": True, "data": obj.tobytes(), "shape": list(obj.shape), "dtype": str(obj.dtype)}
+
     # NEW: Helpful error detection for common unsupported types
     if _safe_hasattr(obj, "model_dump"):  # Pydantic BaseModel
         raise TypeError(PYDANTIC_ERROR_MESSAGE)
@@ -184,6 +189,7 @@ def _auto_object_hook(obj: Any) -> Any:
     - datetime/date/time from ISO-8601 strings
     - UUID from string representation
     - set/frozenset from list (type-safe roundtrip)
+    - NumPy arrays from binary data with shape and dtype
 
     Args:
         obj: Object from MessagePack decoder
@@ -232,6 +238,13 @@ def _auto_object_hook(obj: Any) -> Any:
             else:
                 return set(value_list)
 
+        if obj.get("__ndarray__") is True:
+            if not HAS_NUMPY:
+                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"])
+
     return obj
 
 

cachekit-0.2.3/src/cachekit/key_generator.py

@@ -1,158 +0,0 @@
-"""Cache key generation functionality."""
-
-from __future__ import annotations
-
-import hashlib
-from typing import Any, Callable, cast
-
-import msgpack
-
-
-class CacheKeyGenerator:
-    """Generates consistent cache keys from function calls.
-
-    Uses MessagePack + Blake2b-256 for cross-language compatibility.
-    Implements protocol-v1.0.md Section 3.3 (MessagePack-based approach).
-    """
-
-    # Key length constants
-    MAX_KEY_LENGTH = 250  # Practical cache key length limit (Redis, Memcached, etc.)
-    KEY_PREFIX_LENGTH = 50  # Length of prefix to keep when shortening keys
-
-    # Serializer codes for compact metadata encoding (1 char each)
-    SERIALIZER_CODES = {
-        "std": "s",  # StandardSerializer (multi-language MessagePack)
-        "auto": "a",  # AutoSerializer (Python-specific, NumPy/pandas)
-        "orjson": "o",  # OrjsonSerializer (JSON-based)
-        "arrow": "w",  # ArrowSerializer (columnar format, w=arroW)
-    }
-
-    def __init__(self):
-        """Initialize the key generator.
-
-        Uses MessagePack + Blake2b-256 per protocol-v1.0.md Section 3.3.
-        """
-        pass
-
-    def generate_key(
-        self,
-        func: Callable[..., Any],
-        args: tuple[Any, ...],
-        kwargs: dict[str, Any],
-        namespace: str | None = None,
-        integrity_checking: bool = True,
-        serializer_type: str = "std",
-    ) -> str:
-        """Generate a cache key from function and arguments.
-
-        Args:
-            func: The function being cached
-            args: Positional arguments passed to the function
-            kwargs: Keyword arguments passed to the function
-            namespace: Optional namespace prefix for the key
-            integrity_checking: Whether integrity checking is enabled (ByteStorage vs plain MessagePack)
-            serializer_type: Serializer type code ("std", "auto", "orjson", "arrow")
-
-        Returns:
-            A consistent string key for caching
-
-        Note:
-            Uses compact metadata suffix format: :<ic><serializer_code>
-            Example: ":1s" = integrity_checking=True, serializer=StandardSerializer
-        """
-        # Build key components efficiently (avoid f-strings in hot path)
-        key_parts = []
-
-        # Add namespace if provided
-        if namespace:
-            key_parts.extend(["ns:", namespace, ":"])
-
-        # Add function identifier (module + name) - single string operation
-        key_parts.extend(["func:", func.__module__, ".", func.__qualname__, ":"])
-
-        # Generate args hash using Blake2b-256
-        args_hash = self._blake2b_hash(args, kwargs)
-
-        key_parts.extend(["args:", args_hash, ":"])
-
-        # Add compact metadata suffix: :<ic><serializer_code>
-        # Example: ":1s" = integrity_checking=True, serializer=std
-        ic_flag = "1" if integrity_checking else "0"
-        serializer_code = self.SERIALIZER_CODES.get(serializer_type, "s")  # Default to "s" if unknown
-        key_parts.extend([ic_flag, serializer_code])
-
-        # Single join operation reduces string allocations
-        key = "".join(key_parts)
-
-        # Ensure key is within practical limits and contains no problematic characters
-        return self._normalize_key(key)
-
-    def _blake2b_hash(self, args: tuple, kwargs: dict) -> str:
-        """Generate hash using MessagePack + Blake2b-256.
-
-        Blake2b-256 (32 bytes = 64 hex chars) for collision resistance.
-        MessagePack ensures cross-language compatibility.
-
-        Raises:
-            TypeError: If args/kwargs contain unsupported types (custom objects, numpy arrays, etc.)
-        """
-        # Step 1: Normalize recursively
-        normalized_args = [self._normalize(arg) for arg in args]
-        normalized_kwargs = {k: self._normalize(v) for k, v in sorted(kwargs.items())}
-
-        # Step 2: Serialize with MessagePack
-        try:
-            msgpack_bytes = cast(
-                bytes, msgpack.packb([normalized_args, normalized_kwargs], use_bin_type=True, strict_types=True)
-            )
-        except TypeError as e:
-            # Wrap msgpack's TypeError with a more descriptive message
-            raise TypeError(f"Unsupported type for cache key generation: {e}") from e
-
-        # Step 3: Hash with Blake2b-256
-        return hashlib.blake2b(msgpack_bytes, digest_size=32).hexdigest()
-
-    def _normalize(self, obj: Any) -> Any:
-        """Normalize object for deterministic MessagePack encoding.
-
-        CRITICAL: Ensures identical serialization across Python, TypeScript, Go, PHP.
-        """
-        if isinstance(obj, dict):
-            # Recursively normalize dict with sorted keys
-            return {k: self._normalize(v) for k, v in sorted(obj.items())}
-
-        elif isinstance(obj, (list, tuple)):
-            # Recursively normalize collections (tuple→list)
-            return [self._normalize(x) for x in obj]
-
-        elif isinstance(obj, float):
-            # CRITICAL: Normalize -0.0 → 0.0 for cross-language compatibility
-            return 0.0 if obj == 0.0 else obj
-
-        else:
-            # Primitives (int, str, bytes, bool, None) pass through unchanged
-            return obj
-
-    def _normalize_key(self, key: str) -> str:
-        """Normalize key to ensure it's valid for cache backends.
-
-        Args:
-            key: Raw cache key
-
-        Returns:
-            Normalized key safe for cache backends (Redis, Memcached, etc.)
-        """
-        # Replace problematic characters
-        normalized = key.replace(" ", "_").replace("\n", "_").replace("\r", "_")
-
-        # Ensure key length is within practical limits for cache backends
-        if len(normalized) > self.MAX_KEY_LENGTH:
-            # If too long, hash the key to get consistent shorter version
-            # Use Blake2b-256 (32 bytes) for consistency
-            key_hash = hashlib.blake2b(normalized.encode("utf-8"), digest_size=32).hexdigest()
-
-            # Keep first part of original key for readability + hash
-            prefix = normalized[: self.KEY_PREFIX_LENGTH] if len(normalized) > self.KEY_PREFIX_LENGTH else normalized
-            normalized = f"{prefix}:{key_hash[:32]}"
-
-        return normalized