sqlspec 0.17.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

sqlspec/core/hashing.py

@@ -1,9 +1,7 @@
 """Statement hashing utilities for cache key generation.
 
-This module provides centralized hashing logic for SQL statements,
-including expressions, parameters, filters, and complete SQL objects.
-
-Also supports fine-grained AST sub-expression caching.
+Provides hashing functions for SQL statements, expressions, parameters,
+filters, and AST sub-expressions.
 """
 
 from typing import TYPE_CHECKING, Any, Optional
@@ -26,14 +24,14 @@ __all__ = (
 
 
 def hash_expression(expr: Optional[exp.Expression], _seen: Optional[set[int]] = None) -> int:
-    """Generate deterministic hash from AST structure.
+    """Generate hash from AST structure.
 
     Args:
         expr: SQLGlot Expression to hash
         _seen: Set of seen object IDs to handle circular references
 
     Returns:
-        Deterministic hash of the AST structure
+        Hash of the AST structure
     """
     if expr is None:
         return hash(None)
@@ -47,7 +45,6 @@ def hash_expression(expr: Optional[exp.Expression], _seen: Optional[set[int]] =
 
     _seen.add(expr_id)
 
-    # Build hash from type and args
     components: list[Any] = [type(expr).__name__]
 
     for key, value in sorted(expr.args.items()):
@@ -57,14 +54,14 @@ def hash_expression(expr: Optional[exp.Expression], _seen: Optional[set[int]] =
 
 
 def _hash_value(value: Any, _seen: set[int]) -> int:
-    """Hash different value types consistently.
+    """Hash different value types.
 
     Args:
         value: Value to hash (can be Expression, list, dict, or primitive)
         _seen: Set of seen object IDs to handle circular references
 
     Returns:
-        Deterministic hash of the value
+        Hash of the value
     """
     if isinstance(value, exp.Expression):
         return hash_expression(value, _seen)
@@ -75,7 +72,7 @@ def _hash_value(value: Any, _seen: set[int]) -> int:
         return hash(tuple(items))
     if isinstance(value, tuple):
         return hash(tuple(_hash_value(v, _seen) for v in value))
-    # Primitives: str, int, bool, None, etc.
+
     return hash(value)
 
 
@@ -96,7 +93,6 @@ def hash_parameters(
     """
     param_hash = 0
 
-    # Hash positional parameters
     if positional_parameters:
         from sqlspec.core.parameters import TypedParameter
 
@@ -108,25 +104,20 @@ def hash_parameters(
                 else:
                     hashable_parameters.append((param.value, param.original_type))
             elif isinstance(param, (list, dict)):
-                # Convert unhashable types to hashable representations
                 hashable_parameters.append((repr(param), "unhashable"))
             else:
-                # Check if param itself contains unhashable types
                 try:
                     hash(param)
                     hashable_parameters.append((param, "primitive"))
                 except TypeError:
-                    # If unhashable, convert to string representation
                     hashable_parameters.append((repr(param), "unhashable_repr"))
 
         param_hash ^= hash(tuple(hashable_parameters))
 
     if named_parameters:
-        # Handle unhashable types in named parameters
         hashable_items = []
         for key, value in sorted(named_parameters.items()):
             if is_typed_parameter(value):
-                # For TypedParameter, hash its value with type info
                 if isinstance(value.value, (list, dict)):
                     hashable_items.append((key, (repr(value.value), value.original_type)))
                 else:
@@ -137,13 +128,10 @@ def hash_parameters(
                 hashable_items.append((key, (value, "primitive")))
         param_hash ^= hash(tuple(hashable_items))
 
-    # Hash original parameters (important for execute_many)
     if original_parameters is not None:
         if isinstance(original_parameters, list):
-            # For execute_many, hash the count and first few items to avoid
             param_hash ^= hash(("original_count", len(original_parameters)))
             if original_parameters:
-                # Hash first 3 items as representatives
                 sample_size = min(3, len(original_parameters))
                 sample_hash = hash(repr(original_parameters[:sample_size]))
                 param_hash ^= hash(("original_sample", sample_hash))
@@ -172,14 +160,10 @@ def hash_filters(filters: Optional[list["StatementFilter"]] = None) -> int:
     if not filters:
         return 0
 
-    # Use class names and any hashable attributes
     filter_components = []
     for f in filters:
-        # Use class name as primary identifier
         components: list[Any] = [f.__class__.__name__]
 
-        # Add any hashable attributes if available
-        # Use getattr with default instead of hasattr for mypyc compatibility
         filter_dict = getattr(f, "__dict__", None)
         if filter_dict is not None:
             for key, value in sorted(filter_dict.items()):
@@ -191,10 +175,7 @@ def hash_filters(filters: Optional[list["StatementFilter"]] = None) -> int:
 
 
 def hash_sql_statement(statement: "SQL") -> str:
-    """Generate a complete cache key for a SQL statement.
-
-    This centralizes all the complex hashing logic that was previously
-    scattered across different parts of the codebase.
+    """Generate cache key for a SQL statement.
 
     Args:
         statement: SQL statement object
@@ -204,23 +185,19 @@ def hash_sql_statement(statement: "SQL") -> str:
     """
     from sqlspec.utils.type_guards import is_expression
 
-    # Hash the expression or raw SQL
     if is_expression(statement._statement):
         expr_hash = hash_expression(statement._statement)
     else:
         expr_hash = hash(statement._raw_sql)
 
-    # Hash all parameters
     param_hash = hash_parameters(
         positional_parameters=statement._positional_parameters,
         named_parameters=statement._named_parameters,
         original_parameters=statement._original_parameters,
     )
 
-    # Hash filters
     filter_hash = hash_filters(statement._filters)
 
-    # Combine with other state
     state_components = [
         expr_hash,
         param_hash,
@@ -234,10 +211,7 @@ def hash_sql_statement(statement: "SQL") -> str:
 
 
 def hash_expression_node(node: exp.Expression, include_children: bool = True, dialect: Optional[str] = None) -> str:
-    """Generate a cache key for an individual expression node.
-
-    This is used for sub-expression caching where we want to cache
-    frequently used SQL fragments like complex JOIN clauses or WHERE conditions.
+    """Generate cache key for an expression node.
 
     Args:
         node: The expression node to hash
@@ -248,14 +222,11 @@ def hash_expression_node(node: exp.Expression, include_children: bool = True, di
         Cache key string for the expression node
     """
     if include_children:
-        # Full structural hash including all children
         node_hash = hash_expression(node)
     else:
-        # Shallow hash - just the node type and immediate args
         components: list[Any] = [type(node).__name__]
         for key, value in sorted(node.args.items()):
             if not isinstance(value, (list, exp.Expression)):
-                # Only include primitive values, not child expressions
                 components.extend((key, hash(value)))
         node_hash = hash(tuple(components))
 
@@ -269,11 +240,10 @@ def hash_optimized_expression(
     schema: Optional[dict[str, Any]] = None,
     optimizer_settings: Optional[dict[str, Any]] = None,
 ) -> str:
-    """Generate a cache key for optimized expressions.
+    """Generate cache key for optimized expressions.
 
-    This creates a unique key that captures the expression structure,
-    dialect, schema context, and optimizer settings to ensure we only
-    reuse optimized expressions when all context matches.
+    Creates a key that includes expression structure, dialect, schema
+    context, and optimizer settings.
 
     Args:
         expr: The unoptimized expression
@@ -284,13 +254,11 @@ def hash_optimized_expression(
     Returns:
         Cache key string for the optimized expression
     """
-    # Base expression hash
+
     expr_hash = hash_expression(expr)
 
-    # Schema hash - simplified representation
     schema_hash = 0
     if schema:
-        # Hash table names and column counts to avoid deep schema hashing
         schema_items = []
         for table_name, table_schema in sorted(schema.items()):
             if isinstance(table_schema, dict):
@@ -299,12 +267,10 @@ def hash_optimized_expression(
                 schema_items.append((table_name, hash("unknown")))
         schema_hash = hash(tuple(schema_items))
 
-    # Optimizer settings hash
     settings_hash = 0
     if optimizer_settings:
         settings_items = sorted(optimizer_settings.items())
         settings_hash = hash(tuple(settings_items))
 
-    # Combine all components
     components = (expr_hash, dialect, schema_hash, settings_hash)
     return f"opt:{hash(components)}"