sqlspec 0.17.1__py3-none-any.whl → 0.19.0__py3-none-any.whl

sqlspec/core/cache.py

@@ -1,25 +1,19 @@
-"""Caching system with unified cache management.
+"""Caching system for SQL statement processing.
 
 This module provides a caching system with LRU eviction and TTL support for
 SQL statement processing, parameter processing, and expression caching.
 
 Components:
-- CacheKey: Immutable cache key with optimized hashing
-- UnifiedCache: Main cache implementation with LRU eviction and TTL
-- StatementCache: Specialized cache for compiled SQL statements
-- ExpressionCache: Specialized cache for parsed SQLGlot expressions
-- ParameterCache: Specialized cache for processed parameters
-
-Features:
-- LRU caching with configurable size and TTL
-- Thread-safe cache operations for concurrent access
-- Cached hash values to avoid recomputation
-- O(1) cache lookup and insertion operations
+- CacheKey: Immutable cache key
+- UnifiedCache: Cache implementation with LRU eviction and TTL
+- StatementCache: Cache for compiled SQL statements
+- ExpressionCache: Cache for parsed expressions
+- ParameterCache: Cache for processed parameters
 """
 
 import threading
 import time
-from typing import TYPE_CHECKING, Any, Generic, Optional
+from typing import TYPE_CHECKING, Any, Final, Optional
 
 from mypy_extensions import mypyc_attr
 from typing_extensions import TypeVar
@@ -49,29 +43,21 @@ __all__ = (
 T = TypeVar("T")
 CacheValueT = TypeVar("CacheValueT")
 
-# Cache configuration constants
-DEFAULT_MAX_SIZE = 10000  # LRU cache size limit
-DEFAULT_TTL_SECONDS = 3600  # 1 hour default TTL
-CACHE_STATS_UPDATE_INTERVAL = 100  # Update stats every N operations
 
-# Cache slots - optimized structure
-CACHE_KEY_SLOTS = ("_hash", "_key_data")
-CACHE_NODE_SLOTS = ("key", "value", "prev", "next", "timestamp", "access_count")
-UNIFIED_CACHE_SLOTS = ("_cache", "_lock", "_max_size", "_ttl", "_head", "_tail", "_stats")
-CACHE_STATS_SLOTS = ("hits", "misses", "evictions", "total_operations", "memory_usage")
+DEFAULT_MAX_SIZE: Final = 10000
+DEFAULT_TTL_SECONDS: Final = 3600
+CACHE_STATS_UPDATE_INTERVAL: Final = 100
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
-class CacheKey:
-    """Immutable cache key with optimized hashing.
+CACHE_KEY_SLOTS: Final = ("_hash", "_key_data")
+CACHE_NODE_SLOTS: Final = ("key", "value", "prev", "next", "timestamp", "access_count")
+UNIFIED_CACHE_SLOTS: Final = ("_cache", "_lock", "_max_size", "_ttl", "_head", "_tail", "_stats")
+CACHE_STATS_SLOTS: Final = ("hits", "misses", "evictions", "total_operations", "memory_usage")
 
-    This class provides an immutable cache key for consistent cache operations
-    across all cache types.
 
-    Features:
-    - Cached hash value to avoid recomputation
-    - Immutable design for safe sharing across threads
-    - Fast equality comparison with short-circuit evaluation
+@mypyc_attr(allow_interpreted_subclasses=False)
+class CacheKey:
+    """Immutable cache key.
 
     Args:
         key_data: Tuple of hashable values that uniquely identify the cached item
@@ -98,10 +84,10 @@ class CacheKey:
         return self._hash
 
     def __eq__(self, other: object) -> bool:
-        """Equality comparison with short-circuit evaluation."""
+        """Equality comparison."""
         if type(other) is not CacheKey:
             return False
-        other_key = other  # type: CacheKey
+        other_key = other
         if self._hash != other_key._hash:
             return False
         return self._key_data == other_key._key_data
@@ -111,12 +97,11 @@ class CacheKey:
         return f"CacheKey({self._key_data!r})"
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
+@mypyc_attr(allow_interpreted_subclasses=False)
 class CacheStats:
     """Cache statistics tracking.
 
-    Tracks cache performance metrics including hit rates, evictions,
-    and memory usage.
+    Tracks cache metrics including hit rates, evictions, and memory usage.
     """
 
     __slots__ = CACHE_STATS_SLOTS
@@ -171,13 +156,9 @@ class CacheStats:
         )
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
+@mypyc_attr(allow_interpreted_subclasses=False)
 class CacheNode:
-    """Internal cache node for LRU linked list implementation.
-
-    This class represents a node in the doubly-linked list used for
-    LRU cache implementation with O(1) operations.
-    """
+    """Internal cache node for LRU linked list implementation."""
 
     __slots__ = CACHE_NODE_SLOTS
 
@@ -196,20 +177,10 @@ class CacheNode:
         self.access_count = 1
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
-class UnifiedCache(Generic[CacheValueT]):
+@mypyc_attr(allow_interpreted_subclasses=False)
+class UnifiedCache:
     """Cache with LRU eviction and TTL support.
 
-    This class provides a thread-safe cache implementation with LRU eviction
-    and time-based expiration.
-
-    Features:
-    - O(1) cache lookup, insertion, and deletion operations
-    - LRU eviction policy with configurable size limits
-    - TTL-based expiration for cache entries
-    - Thread-safe operations
-    - Statistics tracking
-
     Args:
         max_size: Maximum number of items to cache (LRU eviction when exceeded)
         ttl_seconds: Time-to-live in seconds (None for no expiration)
@@ -235,8 +206,8 @@ class UnifiedCache(Generic[CacheValueT]):
         self._head.next = self._tail
         self._tail.prev = self._head
 
-    def get(self, key: CacheKey) -> Optional[CacheValueT]:
-        """Get value from cache with LRU update.
+    def get(self, key: CacheKey) -> Optional[Any]:
+        """Get value from cache.
 
         Args:
             key: Cache key to lookup
@@ -250,7 +221,6 @@ class UnifiedCache(Generic[CacheValueT]):
                 self._stats.record_miss()
                 return None
 
-            # Optimize TTL check with early variable assignment
             ttl = self._ttl
             if ttl is not None:
                 current_time = time.time()
@@ -264,10 +234,10 @@ class UnifiedCache(Generic[CacheValueT]):
             self._move_to_head(node)
             node.access_count += 1
             self._stats.record_hit()
-            return node.value  # type: ignore[no-any-return]
+            return node.value
 
-    def put(self, key: CacheKey, value: CacheValueT) -> None:
-        """Put value in cache with LRU management.
+    def put(self, key: CacheKey, value: Any) -> None:
+        """Put value in cache.
 
         Args:
             key: Cache key
@@ -286,7 +256,6 @@ class UnifiedCache(Generic[CacheValueT]):
             self._cache[key] = new_node
             self._add_to_head(new_node)
 
-            # Optimize size check with cached length
             if len(self._cache) > self._max_size:
                 tail_node = self._tail.prev
                 if tail_node is not None and tail_node is not self._head:
@@ -326,14 +295,14 @@ class UnifiedCache(Generic[CacheValueT]):
 
     def is_empty(self) -> bool:
         """Check if cache is empty."""
-        return len(self._cache) == 0
+        return not self._cache
 
     def get_stats(self) -> CacheStats:
         """Get cache statistics."""
         return self._stats
 
     def _add_to_head(self, node: CacheNode) -> None:
-        """Add node after head."""
+        """Add node to head of list."""
         node.prev = self._head
         head_next: Optional[CacheNode] = self._head.next
         node.next = head_next
@@ -351,7 +320,7 @@ class UnifiedCache(Generic[CacheValueT]):
             node_next.prev = node_prev
 
     def _move_to_head(self, node: CacheNode) -> None:
-        """Move existing node to head."""
+        """Move node to head of list."""
         self._remove_node(node)
         self._add_to_head(node)
 
@@ -366,17 +335,13 @@ class UnifiedCache(Generic[CacheValueT]):
             if node is None:
                 return False
 
-            # Optimize TTL check
             ttl = self._ttl
             return not (ttl is not None and time.time() - node.timestamp > ttl)
 
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class StatementCache:
-    """Specialized cache for compiled SQL statements.
-
-    Caches compiled SQL statements and their execution parameters.
-    """
+    """Cache for compiled SQL statements."""
 
     def __init__(self, max_size: int = DEFAULT_MAX_SIZE) -> None:
         """Initialize statement cache.
@@ -384,7 +349,7 @@ class StatementCache:
         Args:
             max_size: Maximum number of statements to cache
         """
-        self._cache: UnifiedCache[tuple[str, Any]] = UnifiedCache(max_size)
+        self._cache: UnifiedCache = UnifiedCache(max_size)
 
     def get_compiled(self, statement: "SQL") -> Optional[tuple[str, Any]]:
         """Get compiled SQL and parameters from cache.
@@ -393,7 +358,7 @@ class StatementCache:
             statement: SQL statement to lookup
 
         Returns:
-            Tuple of (compiled_sql, parameters) or None if not cached
+            Tuple of (compiled_sql, parameters) or None if not found
         """
         cache_key = self._create_statement_key(statement)
         return self._cache.get(cache_key)
@@ -418,11 +383,11 @@ class StatementCache:
         Returns:
             Cache key for the statement
         """
-        # Create key from SQL text, parameters, and configuration
+
         key_data = (
             "statement",
             statement._raw_sql,
-            hash(statement),  # Includes parameters and flags
+            hash(statement),
             str(statement.dialect) if statement.dialect else None,
             statement.is_many,
             statement.is_script,
@@ -440,10 +405,7 @@ class StatementCache:
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class ExpressionCache:
-    """Specialized cache for parsed SQLGlot expressions.
-
-    Caches parsed SQLGlot expressions to avoid redundant parsing operations.
-    """
+    """Cache for parsed expressions."""
 
     def __init__(self, max_size: int = DEFAULT_MAX_SIZE) -> None:
         """Initialize expression cache.
@@ -451,7 +413,7 @@ class ExpressionCache:
         Args:
             max_size: Maximum number of expressions to cache
         """
-        self._cache: UnifiedCache[exp.Expression] = UnifiedCache(max_size)
+        self._cache: UnifiedCache = UnifiedCache(max_size)
 
     def get_expression(self, sql: str, dialect: Optional[str] = None) -> "Optional[exp.Expression]":
         """Get parsed expression from cache.
@@ -461,7 +423,7 @@ class ExpressionCache:
             dialect: SQL dialect
 
         Returns:
-            Parsed expression or None if not cached
+            Parsed expression or None if not found
         """
         cache_key = self._create_expression_key(sql, dialect)
         return self._cache.get(cache_key)
@@ -501,10 +463,7 @@ class ExpressionCache:
 
 @mypyc_attr(allow_interpreted_subclasses=False)
 class ParameterCache:
-    """Specialized cache for processed parameters.
-
-    Caches processed parameter transformations.
-    """
+    """Cache for processed parameters."""
 
     def __init__(self, max_size: int = DEFAULT_MAX_SIZE) -> None:
         """Initialize parameter cache.
@@ -512,7 +471,7 @@ class ParameterCache:
         Args:
             max_size: Maximum number of parameter sets to cache
         """
-        self._cache: UnifiedCache[Any] = UnifiedCache(max_size)
+        self._cache: UnifiedCache = UnifiedCache(max_size)
 
     def get_parameters(self, original_params: Any, config_hash: int) -> Optional[Any]:
         """Get processed parameters from cache.
@@ -522,7 +481,7 @@ class ParameterCache:
             config_hash: Hash of parameter processing configuration
 
         Returns:
-            Processed parameters or None if not cached
+            Processed parameters or None if not found
         """
         cache_key = self._create_parameter_key(original_params, config_hash)
         return self._cache.get(cache_key)
@@ -548,9 +507,8 @@ class ParameterCache:
         Returns:
             Cache key for the parameters
         """
-        # Create stable key from parameters and configuration
+
         try:
-            # Optimize type checking order
             param_key: tuple[Any, ...]
             if isinstance(params, dict):
                 param_key = tuple(sorted(params.items()))
@@ -561,7 +519,6 @@ class ParameterCache:
 
             return CacheKey(("parameters", param_key, config_hash))
         except (TypeError, ValueError):
-            # Fallback for unhashable types
             param_key_fallback = (str(params), type(params).__name__)
             return CacheKey(("parameters", param_key_fallback, config_hash))
 
@@ -574,14 +531,14 @@ class ParameterCache:
         return self._cache.get_stats()
 
 
-_default_cache: Optional[UnifiedCache[Any]] = None
+_default_cache: Optional[UnifiedCache] = None
 _statement_cache: Optional[StatementCache] = None
 _expression_cache: Optional[ExpressionCache] = None
 _parameter_cache: Optional[ParameterCache] = None
 _cache_lock = threading.Lock()
 
 
-def get_default_cache() -> UnifiedCache[Any]:
+def get_default_cache() -> UnifiedCache:
     """Get the default unified cache instance.
 
     Returns:
@@ -591,7 +548,7 @@ def get_default_cache() -> UnifiedCache[Any]:
     if _default_cache is None:
         with _cache_lock:
             if _default_cache is None:
-                _default_cache = UnifiedCache[Any]()
+                _default_cache = UnifiedCache()
     return _default_cache
 
 
@@ -670,12 +627,9 @@ def get_cache_statistics() -> dict[str, CacheStats]:
 _global_cache_config: "Optional[CacheConfig]" = None
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
+@mypyc_attr(allow_interpreted_subclasses=False)
 class CacheConfig:
-    """Global cache configuration for SQLSpec.
-
-    Controls caching behavior across the SQLSpec system.
-    """
+    """Global cache configuration for SQLSpec."""
 
     def __init__(
         self,
@@ -723,8 +677,7 @@ def get_cache_config() -> CacheConfig:
 def update_cache_config(config: CacheConfig) -> None:
     """Update the global cache configuration.
 
-    This clears all existing caches when configuration changes to ensure
-    consistency with the new settings.
+    Clears all existing caches when configuration changes.
 
     Args:
         config: New cache configuration to apply globally
@@ -752,9 +705,9 @@ def update_cache_config(config: CacheConfig) -> None:
     )
 
 
-@mypyc_attr(allow_interpreted_subclasses=True)
+@mypyc_attr(allow_interpreted_subclasses=False)
 class CacheStatsAggregate:
-    """Aggregated cache statistics from all cache instances."""
+    """Cache statistics from all cache instances."""
 
     __slots__ = (
         "fragment_capacity",
@@ -775,7 +728,7 @@ class CacheStatsAggregate:
     )
 
     def __init__(self) -> None:
-        """Initialize aggregated cache statistics."""
+        """Initialize cache statistics."""
         self.sql_hit_rate = 0.0
         self.fragment_hit_rate = 0.0
         self.optimized_hit_rate = 0.0
@@ -794,10 +747,10 @@ class CacheStatsAggregate:
 
 
 def get_cache_stats() -> CacheStatsAggregate:
-    """Get current cache statistics from all caches.
+    """Get cache statistics from all caches.
 
     Returns:
-        Combined cache statistics object
+        Cache statistics object
     """
     stats_dict = get_cache_statistics()
     stats = CacheStatsAggregate()
@@ -841,7 +794,7 @@ def reset_cache_stats() -> None:
 
 
 def log_cache_stats() -> None:
-    """Log current cache statistics using the configured logger."""
+    """Log cache statistics."""
     logger = get_logger("sqlspec.cache")
     stats = get_cache_stats()
     logger.info("Cache Statistics: %s", stats)