django-bulk-hooks 0.2.9__py3-none-any.whl → 0.2.93__py3-none-any.whl

django_bulk_hooks/operations/analyzer.py

@@ -5,335 +5,462 @@ This service handles all model analysis needs:
 - Input validation
 - Field change detection
 - Field comparison
+- Expression resolution
 """
 
 import logging
+from typing import Any, Dict, List, Optional, Set
+
+from django.db.models import Expression, Model
+from django.db.models.expressions import Combinable
+
+from django_bulk_hooks.helpers import extract_pks
+
+from .field_utils import get_auto_fields, get_changed_fields, get_fk_fields
 
 logger = logging.getLogger(__name__)
 
 
+class ValidationError(Exception):
+    """Custom exception for validation errors."""
+
+    pass
+
+
 class ModelAnalyzer:
     """
     Analyzes models and validates operations.
 
-    This service combines the responsibilities of validation and field tracking
+    This service combines validation and field tracking responsibilities
     since they're closely related and often used together.
+
+    Design Principles:
+    - Single source of truth for data fetching
+    - Bulk operations to prevent N+1 queries
+    - Clear separation between validation and analysis
     """
 
-    def __init__(self, model_cls):
+    # Validation requirements per operation type
+    VALIDATION_REQUIREMENTS = {
+        "bulk_create": ["types"],
+        "bulk_update": ["types", "has_pks"],
+        "delete": ["types"],
+    }
+
+    def __init__(self, model_cls: type):
         """
         Initialize analyzer for a specific model.
 
         Args:
-            model_cls: The Django model class
+            model_cls: The Django model class to analyze
         """
         self.model_cls = model_cls
 
-    # ========== Validation Methods ==========
+    # ==================== PUBLIC VALIDATION API ====================
 
-    def validate_for_create(self, objs):
+    def validate_for_create(self, objs: List[Model]) -> bool:
         """
         Validate objects for bulk_create operation.
 
         Args:
             objs: List of model instances
 
+        Returns:
+            True if validation passes
+
         Raises:
             TypeError: If objects are not instances of model_cls
         """
-        self._check_types(objs, operation="bulk_create")
-        return True
+        return self.validate_for_operation(objs, "bulk_create")
 
-    def validate_for_update(self, objs):
+    def validate_for_update(self, objs: List[Model]) -> bool:
         """
         Validate objects for bulk_update operation.
 
         Args:
             objs: List of model instances
 
+        Returns:
+            True if validation passes
+
         Raises:
             TypeError: If objects are not instances of model_cls
             ValueError: If objects don't have primary keys
         """
-        self._check_types(objs, operation="bulk_update")
-        self._check_has_pks(objs, operation="bulk_update")
-        return True
+        return self.validate_for_operation(objs, "bulk_update")
 
-    def validate_for_delete(self, objs):
+    def validate_for_delete(self, objs: List[Model]) -> bool:
         """
         Validate objects for delete operation.
 
         Args:
             objs: List of model instances
 
+        Returns:
+            True if validation passes
+
         Raises:
             TypeError: If objects are not instances of model_cls
         """
-        self._check_types(objs, operation="delete")
-        return True
+        return self.validate_for_operation(objs, "delete")
 
-    def _check_types(self, objs, operation="operation"):
-        """Check that all objects are instances of the model class"""
-        if not objs:
-            return
+    def validate_for_operation(self, objs: List[Model], operation: str) -> bool:
+        """
+        Centralized validation method that applies operation-specific checks.
 
-        invalid_types = {
-            type(obj).__name__ for obj in objs if not isinstance(obj, self.model_cls)
-        }
+        This method routes to appropriate validation checks based on the
+        operation type, ensuring consistent validation across all operations.
 
-        if invalid_types:
-            raise TypeError(
-                f"{operation} expected instances of {self.model_cls.__name__}, "
-                f"but got {invalid_types}"
-            )
+        Args:
+            objs: List of model instances to validate
+            operation: String identifier for the operation
 
-    def _check_has_pks(self, objs, operation="operation"):
-        """Check that all objects have primary keys"""
-        missing_pks = [obj for obj in objs if obj.pk is None]
+        Returns:
+            True if validation passes
 
-        if missing_pks:
-            raise ValueError(
-                f"{operation} cannot operate on unsaved {self.model_cls.__name__} instances. "
-                f"{len(missing_pks)} object(s) have no primary key."
-            )
+        Raises:
+            TypeError: If type validation fails
+            ValueError: If PK validation fails
+        """
+        requirements = self.VALIDATION_REQUIREMENTS.get(operation, [])
+
+        if "types" in requirements:
+            self._validate_types(objs, operation)
+
+        if "has_pks" in requirements:
+            self._validate_has_pks(objs, operation)
+
+        return True
 
-    # ========== Data Fetching Methods ==========
+    # ==================== DATA FETCHING ====================
 
-    def fetch_old_records_map(self, instances):
+    def fetch_old_records_map(self, instances: List[Model]) -> Dict[Any, Model]:
         """
         Fetch old records for instances in a single bulk query.
 
-        This is the SINGLE point of truth for fetching old records.
-        All other methods should delegate to this.
+        This is the SINGLE source of truth for fetching old records.
+        All other methods should delegate to this to ensure consistency
+        and prevent duplicate queries.
+
+        Performance: O(1) queries regardless of number of instances.
 
         Args:
             instances: List of model instances
 
         Returns:
-            Dict[pk, instance] for O(1) lookups
+            Dict mapping pk -> old instance for O(1) lookups
         """
-        pks = [obj.pk for obj in instances if obj.pk is not None]
+        pks = extract_pks(instances)
         if not pks:
             return {}
 
-        return {obj.pk: obj for obj in self.model_cls._base_manager.filter(pk__in=pks)}
+        old_records = self.model_cls._base_manager.filter(pk__in=pks)
+        return {obj.pk: obj for obj in old_records}
 
-    # ========== Field Introspection Methods ==========
+    # ==================== FIELD INTROSPECTION ====================
 
-    def get_auto_now_fields(self):
+    def get_auto_now_fields(self) -> List[str]:
         """
         Get fields that have auto_now or auto_now_add set.
 
+        These fields are automatically updated by Django and should
+        typically be excluded from manual change tracking.
+
         Returns:
-            list: Field names with auto_now behavior
+            List of field names with auto_now behavior
         """
-        auto_now_fields = []
-        for field in self.model_cls._meta.fields:
-            if getattr(field, "auto_now", False) or getattr(
-                field, "auto_now_add", False
-            ):
-                auto_now_fields.append(field.name)
-        return auto_now_fields
+        return get_auto_fields(self.model_cls, include_auto_now_add=True)
 
-    def get_fk_fields(self):
+    def get_fk_fields(self) -> List[str]:
         """
         Get all foreign key fields for the model.
 
         Returns:
-            list: FK field names
+            List of FK field names
         """
-        return [
-            field.name
-            for field in self.model_cls._meta.concrete_fields
-            if field.is_relation and not field.many_to_many
-        ]
+        return get_fk_fields(self.model_cls)
 
-    def detect_changed_fields(self, objs):
+    def detect_changed_fields(self, objs: List[Model]) -> List[str]:
         """
         Detect which fields have changed across a set of objects.
 
         This method fetches old records from the database in a SINGLE bulk query
         and compares them with the new objects to determine changed fields.
 
-        PERFORMANCE: Uses bulk query (O(1) queries) not N queries.
+        Performance: Uses bulk query (O(1) queries) not N queries.
 
         Args:
             objs: List of model instances to check
 
         Returns:
-            List of field names that changed across any object
+            Sorted list of field names that changed across any object
         """
         if not objs:
             return []
 
-        # Fetch old records using the single source of truth
+        # Fetch old records using single source of truth
         old_records_map = self.fetch_old_records_map(objs)
         if not old_records_map:
             return []
 
-        # Track which fields changed across ALL objects
-        changed_fields_set = set()
+        # Collect all changed fields across objects
+        changed_fields_set: Set[str] = set()
 
-        # Compare each object with its database state
         for obj in objs:
             if obj.pk is None:
                 continue
 
             old_obj = old_records_map.get(obj.pk)
             if old_obj is None:
-                # Object doesn't exist in DB, skip
                 continue
 
-            # Check each field for changes
-            for field in self.model_cls._meta.fields:
-                # Skip primary key and auto fields
-                if field.primary_key or field.auto_created:
-                    continue
-
-                old_val = getattr(old_obj, field.name, None)
-                new_val = getattr(obj, field.name, None)
-
-                # Use field's get_prep_value for proper comparison
-                try:
-                    old_prep = field.get_prep_value(old_val)
-                    new_prep = field.get_prep_value(new_val)
-                    if old_prep != new_prep:
-                        changed_fields_set.add(field.name)
-                except (TypeError, ValueError):
-                    # Fallback to direct comparison
-                    if old_val != new_val:
-                        changed_fields_set.add(field.name)
-
-        # Return as sorted list for deterministic behavior
+            # Use canonical field comparison (skips auto_created fields)
+            changed_fields = get_changed_fields(old_obj, obj, self.model_cls, skip_auto_fields=True)
+            changed_fields_set.update(changed_fields)
+
+        # Return sorted list for deterministic behavior
         return sorted(changed_fields_set)
 
-    def resolve_expression(self, field_name, expression, instance):
+    # ==================== EXPRESSION RESOLUTION ====================
+
+    def resolve_expression(self, field_name: str, expression: Any, instance: Model) -> Any:
         """
         Resolve a SQL expression to a concrete value for a specific instance.
-        
+
         This method materializes database expressions (F(), Subquery, Case, etc.)
         into concrete values by using Django's annotate() mechanism.
-        
+
         Args:
             field_name: Name of the field being updated
             expression: The expression or value to resolve
             instance: The model instance to resolve for
-            
+
         Returns:
-            The resolved concrete value
+            The resolved concrete value, or original expression if resolution fails
         """
-        from django.db.models import Expression
-        from django.db.models.expressions import Combinable
-        
         # Simple value - return as-is
-        if not isinstance(expression, (Expression, Combinable)):
+        if not self._is_expression(expression):
             return expression
-        
-        # For complex expressions, evaluate them in database context
-        # Use annotate() which Django properly handles for all expression types
+
+        # Complex expression - resolve in database context
         try:
-            # Create a queryset for just this instance
-            instance_qs = self.model_cls.objects.filter(pk=instance.pk)
-            
-            # Use annotate with the expression and let Django resolve it
-            resolved_value = instance_qs.annotate(
-                _resolved_value=expression
-            ).values_list('_resolved_value', flat=True).first()
-            
-            return resolved_value
+            return self._resolve_expression_for_instance(field_name, expression, instance)
         except Exception as e:
-            # If expression resolution fails, log and return original
             logger.warning(
-                f"Failed to resolve expression for field '{field_name}' "
-                f"on {self.model_cls.__name__}: {e}. Using original value."
+                "Failed to resolve expression for field '%s' on %s: %s. Using original value.", field_name, self.model_cls.__name__, e
             )
             return expression
 
-    def apply_update_values(self, instances, update_kwargs):
+    def apply_update_values(self, instances: List[Model], update_kwargs: Dict[str, Any]) -> List[str]:
         """
         Apply update_kwargs to instances, resolving any SQL expressions.
-        
+
         This method transforms queryset.update()-style kwargs (which may contain
         F() expressions, Subquery, Case, etc.) into concrete values and applies
         them to the instances.
-        
-        CRITICAL: When setting FK fields by their attname (e.g., business_id),
-        we must manually clear the relationship cache (e.g., business) to match
-        Django's ForeignKey descriptor behavior.
-        
+
+        Performance: Resolves complex expressions in bulk queries where possible.
+
         Args:
             instances: List of model instances to update
             update_kwargs: Dict of {field_name: value_or_expression}
-            
+
         Returns:
             List of field names that were updated
         """
         if not instances or not update_kwargs:
             return []
-        
+
         fields_updated = list(update_kwargs.keys())
-        
+
+        # Get instances with PKs
+        instances_with_pks = [inst for inst in instances if inst.pk is not None]
+        if not instances_with_pks:
+            return fields_updated
+
+        # Process each field
         for field_name, value in update_kwargs.items():
-            # Determine if this is a FK field being set by its attname
-            field_info = self._get_fk_field_info(field_name)
-            
-            for instance in instances:
-                resolved_value = self.resolve_expression(field_name, value, instance)
-                setattr(instance, field_name, resolved_value)
-                
-                # Clear relationship cache when FK field is set directly
-                # This replicates Django's ForeignKey descriptor behavior
-                if field_info and field_info['is_fk_attname']:
-                    self._clear_fk_cache(instance, field_info['accessor_name'])
-        
+            if self._is_expression(value):
+                self._apply_expression_value(field_name, value, instances_with_pks)
+            else:
+                self._apply_simple_value(field_name, value, instances)
+
         return fields_updated
 
-    def _get_fk_field_info(self, field_name):
+    # ==================== PRIVATE VALIDATION METHODS ====================
+
+    def _validate_types(self, objs: List[Model], operation: str = "operation") -> None:
+        """
+        Validate that all objects are instances of the model class.
+
+        Args:
+            objs: List of objects to validate
+            operation: Name of the operation (for error messages)
+
+        Raises:
+            TypeError: If any object is not an instance of model_cls
+        """
+        if not objs:
+            return
+
+        invalid_types = {type(obj).__name__ for obj in objs if not isinstance(obj, self.model_cls)}
+
+        if invalid_types:
+            raise TypeError(f"{operation} expected instances of {self.model_cls.__name__}, but got {invalid_types}")
+
+    def _validate_has_pks(self, objs: List[Model], operation: str = "operation") -> None:
         """
-        Get information about a FK field if field_name is a FK attname.
-        
+        Validate that all objects have primary keys.
+
         Args:
-            field_name: Field name to check
-            
+            objs: List of objects to validate
+            operation: Name of the operation (for error messages)
+
+        Raises:
+            ValueError: If any object is missing a primary key
+        """
+        missing_pks = [obj for obj in objs if obj.pk is None]
+
+        if missing_pks:
+            raise ValueError(
+                f"{operation} cannot operate on unsaved {self.model_cls.__name__} "
+                f"instances. {len(missing_pks)} object(s) have no primary key."
+            )
+
+    # ==================== PRIVATE EXPRESSION METHODS ====================
+
+    def _is_expression(self, value: Any) -> bool:
+        """
+        Check if a value is a Django database expression.
+
+        Args:
+            value: Value to check
+
         Returns:
-            Dict with FK info or None if not a FK field
+            True if value is an Expression or Combinable
         """
-        try:
-            # Check all fields to find if this is a FK attname
-            for field in self.model_cls._meta.get_fields():
-                if (field.is_relation and 
-                    not field.many_to_many and 
-                    not field.one_to_many and
-                    hasattr(field, 'attname') and 
-                    field.attname == field_name):
-                    # This is a FK field being set by its attname (e.g., business_id)
-                    return {
-                        'is_fk_attname': True,
-                        'accessor_name': field.name,  # e.g., 'business'
-                        'field': field
-                    }
-        except Exception as e:
-            logger.debug(f"Error checking FK field info for {field_name}: {e}")
-        
-        return None
+        return isinstance(value, (Expression, Combinable))
 
-    def _clear_fk_cache(self, instance, accessor_name):
+    def _resolve_expression_for_instance(self, field_name: str, expression: Any, instance: Model) -> Any:
         """
-        Clear cached relationship when FK field is set directly.
-        
-        This replicates what Django's ForeignKey descriptor __set__ does:
-        when you set a FK field, Django clears the cached related object.
-        
+        Resolve an expression for a single instance using database query.
+
         Args:
-            instance: Model instance
-            accessor_name: Name of the relationship accessor (e.g., 'business')
+            field_name: Field name being resolved
+            expression: Django expression to resolve
+            instance: Model instance to resolve for
+
+        Returns:
+            Resolved concrete value
+
+        Raises:
+            Exception: If expression cannot be resolved
+        """
+        instance_qs = self.model_cls.objects.filter(pk=instance.pk)
+
+        resolved_value = instance_qs.annotate(_resolved_value=expression).values_list("_resolved_value", flat=True).first()
+
+        return resolved_value
+
+    def _apply_simple_value(self, field_name: str, value: Any, instances: List[Model]) -> None:
+        """
+        Apply a simple (non-expression) value to all instances.
+
+        Args:
+            field_name: Name of field to update
+            value: Simple value to apply
+            instances: List of instances to update
+        """
+        for instance in instances:
+            setattr(instance, field_name, value)
+
+    def _apply_expression_value(self, field_name: str, expression: Any, instances: List[Model]) -> None:
+        """
+        Resolve and apply an expression value to all instances in bulk.
+
+        This method resolves the expression for all instances in a single
+        database query for optimal performance.
+
+        Args:
+            field_name: Name of field to update
+            expression: Django expression to resolve
+            instances: List of instances to update
         """
         try:
-            if hasattr(instance, '_state') and hasattr(instance._state, 'fields_cache'):
-                instance._state.fields_cache.pop(accessor_name, None)
-                logger.debug(
-                    f"Cleared FK cache for '{accessor_name}' on {self.model_cls.__name__}"
-                )
+            # Resolve expression for all instances in single query
+            value_map = self._bulk_resolve_expression(expression, instances)
+
+            # Apply resolved values to instances
+            for instance in instances:
+                if instance.pk in value_map:
+                    setattr(instance, field_name, value_map[instance.pk])
+
         except Exception as e:
-            # Don't fail the operation, just log
-            logger.debug(f"Could not clear FK cache for {accessor_name}: {e}")
+            logger.warning(
+                "Failed to resolve expression for field '%s' on %s: %s. Using original value.", field_name, self.model_cls.__name__, e
+            )
+            # Fallback: apply original expression value
+            self._apply_simple_value(field_name, expression, instances)
+
+    def _bulk_resolve_expression(self, expression: Any, instances: List[Model]) -> Dict[Any, Any]:
+        """
+        Resolve an expression for multiple instances in a single query.
+
+        Args:
+            expression: Django expression to resolve
+            instances: List of instances to resolve for
+
+        Returns:
+            Dict mapping pk -> resolved value
+
+        Raises:
+            Exception: If expression cannot be resolved
+        """
+        pks = extract_pks(instances)
+        if not pks:
+            return {}
+
+        # Query all instances with annotated expression
+        qs = self.model_cls.objects.filter(pk__in=pks)
+        results = qs.annotate(_resolved_value=expression).values_list("pk", "_resolved_value")
+
+        return dict(results)
+
+
+# ==================== CONVENIENCE FUNCTIONS ====================
+
+
+def create_analyzer(model_cls: type) -> ModelAnalyzer:
+    """
+    Factory function to create a ModelAnalyzer instance.
+
+    This provides a convenient entry point and allows for future
+    extensibility (e.g., analyzer caching, subclass selection).
+
+    Args:
+        model_cls: The Django model class to analyze
+
+    Returns:
+        ModelAnalyzer instance for the model
+    """
+    return ModelAnalyzer(model_cls)
+
+
+def validate_instances(instances: List[Model], model_cls: type, operation: str) -> bool:
+    """
+    Convenience function to validate instances for an operation.
+
+    Args:
+        instances: List of model instances to validate
+        model_cls: Expected model class
+        operation: Operation type ('bulk_create', 'bulk_update', 'delete')
+
+    Returns:
+        True if validation passes
+
+    Raises:
+        TypeError: If type validation fails
+        ValueError: If PK validation fails
+    """
+    analyzer = create_analyzer(model_cls)
+    return analyzer.validate_for_operation(instances, operation)