django-bulk-hooks 0.2.2__py3-none-any.whl → 0.2.5__py3-none-any.whl

django_bulk_hooks/decorators.py

@@ -242,7 +242,7 @@ def bulk_hook(model_cls, event, when=None, priority=None):
                 self.func = func
 
             def handle(self, new_records=None, old_records=None, **kwargs):
-                return self.func(new_records, old_records)
+                return self.func(new_records, old_records, **kwargs)
 
         # Register the hook using the registry
         register_hook(

django_bulk_hooks/operations/analyzer.py

@@ -1,208 +1,277 @@
-"""
-Model analyzer service - Combines validation and field tracking.
-
-This service handles all model analysis needs:
-- Input validation
-- Field change detection
-- Field comparison
-"""
-
-import logging
-
-logger = logging.getLogger(__name__)
-
-
-class ModelAnalyzer:
-    """
-    Analyzes models and validates operations.
-
-    This service combines the responsibilities of validation and field tracking
-    since they're closely related and often used together.
-    """
-
-    def __init__(self, model_cls):
-        """
-        Initialize analyzer for a specific model.
-
-        Args:
-            model_cls: The Django model class
-        """
-        self.model_cls = model_cls
-
-    # ========== Validation Methods ==========
-
-    def validate_for_create(self, objs):
-        """
-        Validate objects for bulk_create operation.
-
-        Args:
-            objs: List of model instances
-
-        Raises:
-            TypeError: If objects are not instances of model_cls
-        """
-        self._check_types(objs, operation="bulk_create")
-        return True
-
-    def validate_for_update(self, objs):
-        """
-        Validate objects for bulk_update operation.
-
-        Args:
-            objs: List of model instances
-
-        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
-
-    def validate_for_delete(self, objs):
-        """
-        Validate objects for delete operation.
-
-        Args:
-            objs: List of model instances
-
-        Raises:
-            TypeError: If objects are not instances of model_cls
-        """
-        self._check_types(objs, operation="delete")
-        return True
-
-    def _check_types(self, objs, operation="operation"):
-        """Check that all objects are instances of the model class"""
-        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__}, "
-                f"but got {invalid_types}"
-            )
-
-    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]
-
-        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."
-            )
-
-    # ========== Data Fetching Methods ==========
-
-    def fetch_old_records_map(self, instances):
-        """
-        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.
-
-        Args:
-            instances: List of model instances
-
-        Returns:
-            Dict[pk, instance] for O(1) lookups
-        """
-        pks = [obj.pk for obj in instances if obj.pk is not None]
-        if not pks:
-            return {}
-
-        return {obj.pk: obj for obj in self.model_cls._base_manager.filter(pk__in=pks)}
-
-    # ========== Field Introspection Methods ==========
-
-    def get_auto_now_fields(self):
-        """
-        Get fields that have auto_now or auto_now_add set.
-
-        Returns:
-            list: 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
-
-    def get_fk_fields(self):
-        """
-        Get all foreign key fields for the model.
-
-        Returns:
-            list: 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
-        ]
-
-    def detect_changed_fields(self, objs):
-        """
-        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.
-
-        Args:
-            objs: List of model instances to check
-
-        Returns:
-            List of field names that changed across any object
-        """
-        if not objs:
-            return []
-
-        # Fetch old records using the 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()
-
-        # 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
-        return sorted(changed_fields_set)
+"""
+Model analyzer service - Combines validation and field tracking.
+
+This service handles all model analysis needs:
+- Input validation
+- Field change detection
+- Field comparison
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ModelAnalyzer:
+    """
+    Analyzes models and validates operations.
+
+    This service combines the responsibilities of validation and field tracking
+    since they're closely related and often used together.
+    """
+
+    def __init__(self, model_cls):
+        """
+        Initialize analyzer for a specific model.
+
+        Args:
+            model_cls: The Django model class
+        """
+        self.model_cls = model_cls
+
+    # ========== Validation Methods ==========
+
+    def validate_for_create(self, objs):
+        """
+        Validate objects for bulk_create operation.
+
+        Args:
+            objs: List of model instances
+
+        Raises:
+            TypeError: If objects are not instances of model_cls
+        """
+        self._check_types(objs, operation="bulk_create")
+        return True
+
+    def validate_for_update(self, objs):
+        """
+        Validate objects for bulk_update operation.
+
+        Args:
+            objs: List of model instances
+
+        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
+
+    def validate_for_delete(self, objs):
+        """
+        Validate objects for delete operation.
+
+        Args:
+            objs: List of model instances
+
+        Raises:
+            TypeError: If objects are not instances of model_cls
+        """
+        self._check_types(objs, operation="delete")
+        return True
+
+    def _check_types(self, objs, operation="operation"):
+        """Check that all objects are instances of the model class"""
+        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__}, "
+                f"but got {invalid_types}"
+            )
+
+    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]
+
+        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."
+            )
+
+    # ========== Data Fetching Methods ==========
+
+    def fetch_old_records_map(self, instances):
+        """
+        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.
+
+        Args:
+            instances: List of model instances
+
+        Returns:
+            Dict[pk, instance] for O(1) lookups
+        """
+        pks = [obj.pk for obj in instances if obj.pk is not None]
+        if not pks:
+            return {}
+
+        return {obj.pk: obj for obj in self.model_cls._base_manager.filter(pk__in=pks)}
+
+    # ========== Field Introspection Methods ==========
+
+    def get_auto_now_fields(self):
+        """
+        Get fields that have auto_now or auto_now_add set.
+
+        Returns:
+            list: 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
+
+    def get_fk_fields(self):
+        """
+        Get all foreign key fields for the model.
+
+        Returns:
+            list: 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
+        ]
+
+    def detect_changed_fields(self, objs):
+        """
+        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.
+
+        Args:
+            objs: List of model instances to check
+
+        Returns:
+            List of field names that changed across any object
+        """
+        if not objs:
+            return []
+
+        # Fetch old records using the 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()
+
+        # 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
+        return sorted(changed_fields_set)
+
+    def resolve_expression(self, field_name, expression, instance):
+        """
+        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
+        """
+        from django.db.models import Expression
+        from django.db.models.expressions import Combinable
+        
+        # Simple value - return as-is
+        if not isinstance(expression, (Expression, Combinable)):
+            return expression
+        
+        # For complex expressions, evaluate them in database context
+        # Use annotate() which Django properly handles for all expression types
+        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
+        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."
+            )
+            return expression
+
+    def apply_update_values(self, instances, update_kwargs):
+        """
+        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.
+        
+        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())
+        
+        for field_name, value in update_kwargs.items():
+            for instance in instances:
+                resolved_value = self.resolve_expression(field_name, value, instance)
+                setattr(instance, field_name, resolved_value)
+        
+        return fields_updated

django_bulk_hooks/operations/coordinator.py

@@ -1,369 +1,385 @@
-"""
-Bulk operation coordinator - Single entry point for all bulk operations.
-
-This facade hides the complexity of wiring up multiple services and provides
-a clean, simple API for the QuerySet to use.
-"""
-
-import logging
-from django.db import transaction
-from django.db.models import QuerySet as BaseQuerySet
-
-from django_bulk_hooks.helpers import (
-    build_changeset_for_create,
-    build_changeset_for_update,
-    build_changeset_for_delete,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class BulkOperationCoordinator:
-    """
-    Single entry point for coordinating bulk operations.
-
-    This coordinator manages all services and provides a clean facade
-    for the QuerySet. It wires up services and coordinates the hook
-    lifecycle for each operation type.
-
-    Services are created lazily and cached.
-    """
-
-    def __init__(self, queryset):
-        """
-        Initialize coordinator for a queryset.
-
-        Args:
-            queryset: Django QuerySet instance
-        """
-        self.queryset = queryset
-        self.model_cls = queryset.model
-
-        # Lazy initialization
-        self._analyzer = None
-        self._mti_handler = None
-        self._executor = None
-        self._dispatcher = None
-
-    @property
-    def analyzer(self):
-        """Get or create ModelAnalyzer"""
-        if self._analyzer is None:
-            from django_bulk_hooks.operations.analyzer import ModelAnalyzer
-
-            self._analyzer = ModelAnalyzer(self.model_cls)
-        return self._analyzer
-
-    @property
-    def mti_handler(self):
-        """Get or create MTIHandler"""
-        if self._mti_handler is None:
-            from django_bulk_hooks.operations.mti_handler import MTIHandler
-
-            self._mti_handler = MTIHandler(self.model_cls)
-        return self._mti_handler
-
-    @property
-    def executor(self):
-        """Get or create BulkExecutor"""
-        if self._executor is None:
-            from django_bulk_hooks.operations.bulk_executor import BulkExecutor
-
-            self._executor = BulkExecutor(
-                queryset=self.queryset,
-                analyzer=self.analyzer,
-                mti_handler=self.mti_handler,
-            )
-        return self._executor
-
-    @property
-    def dispatcher(self):
-        """Get or create Dispatcher"""
-        if self._dispatcher is None:
-            from django_bulk_hooks.dispatcher import get_dispatcher
-
-            self._dispatcher = get_dispatcher()
-        return self._dispatcher
-
-    # ==================== PUBLIC API ====================
-
-    @transaction.atomic
-    def create(
-        self,
-        objs,
-        batch_size=None,
-        ignore_conflicts=False,
-        update_conflicts=False,
-        update_fields=None,
-        unique_fields=None,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
-        """
-        Execute bulk create with hooks.
-
-        Args:
-            objs: List of model instances to create
-            batch_size: Number of objects per batch
-            ignore_conflicts: Ignore conflicts if True
-            update_conflicts: Update on conflict if True
-            update_fields: Fields to update on conflict
-            unique_fields: Fields to check for conflicts
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            List of created objects
-        """
-        if not objs:
-            return objs
-
-        # Validate
-        self.analyzer.validate_for_create(objs)
-
-        # Build initial changeset
-        changeset = build_changeset_for_create(
-            self.model_cls,
-            objs,
-            batch_size=batch_size,
-            ignore_conflicts=ignore_conflicts,
-            update_conflicts=update_conflicts,
-            update_fields=update_fields,
-            unique_fields=unique_fields,
-        )
-
-        # Execute with hook lifecycle
-        def operation():
-            return self.executor.bulk_create(
-                objs,
-                batch_size=batch_size,
-                ignore_conflicts=ignore_conflicts,
-                update_conflicts=update_conflicts,
-                update_fields=update_fields,
-                unique_fields=unique_fields,
-            )
-
-        return self.dispatcher.execute_operation_with_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="create",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
-
-    @transaction.atomic
-    def update(
-        self,
-        objs,
-        fields,
-        batch_size=None,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
-        """
-        Execute bulk update with hooks.
-
-        Args:
-            objs: List of model instances to update
-            fields: List of field names to update
-            batch_size: Number of objects per batch
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Number of objects updated
-        """
-        if not objs:
-            return 0
-
-        # Validate
-        self.analyzer.validate_for_update(objs)
-
-        # Fetch old records using analyzer (single source of truth)
-        old_records_map = self.analyzer.fetch_old_records_map(objs)
-
-        # Build changeset
-        from django_bulk_hooks.changeset import ChangeSet, RecordChange
-
-        changes = [
-            RecordChange(
-                new_record=obj,
-                old_record=old_records_map.get(obj.pk),
-                changed_fields=fields,
-            )
-            for obj in objs
-        ]
-        changeset = ChangeSet(self.model_cls, changes, "update", {"fields": fields})
-
-        # Execute with hook lifecycle
-        def operation():
-            return self.executor.bulk_update(objs, fields, batch_size=batch_size)
-
-        return self.dispatcher.execute_operation_with_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="update",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
-
-    @transaction.atomic
-    def update_queryset(
-        self, update_kwargs, bypass_hooks=False, bypass_validation=False
-    ):
-        """
-        Execute queryset update with hooks.
-        
-        ARCHITECTURE: Database-Layer vs Application-Layer Updates
-        ==========================================================
-        
-        Unlike bulk_update(objs), queryset.update() is a pure SQL UPDATE operation.
-        The database evaluates ALL expressions (F(), Subquery, Case, functions, etc.)
-        without Python ever seeing the new values.
-        
-        To maintain Salesforce's hook contract (AFTER hooks see accurate new_records),
-        we ALWAYS refetch instances after the update for AFTER hooks.
-        
-        This is NOT a hack - it respects the fundamental architectural difference:
-        
-        1. queryset.update():  Database evaluates → Must refetch for AFTER hooks
-        2. bulk_update(objs):  Python has values → No refetch needed
-        
-        The refetch handles ALL database-level changes:
-        - F() expressions: F('count') + 1
-        - Subquery: Subquery(related.aggregate(...))
-        - Case/When: Case(When(status='A', then=Value('Active')))
-        - Database functions: Upper('name'), Concat(...)
-        - Database hooks/defaults
-        - Any other DB-evaluated expression
-        
-        Trade-off:
-        - Cost: 1 extra SELECT query per queryset.update() call
-        - Benefit: 100% correctness for ALL database expressions
-
-        Args:
-            update_kwargs: Dict of fields to update
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Number of objects updated
-        """
-        # Fetch instances BEFORE update
-        instances = list(self.queryset)
-        if not instances:
-            return 0
-
-        # Fetch old records for comparison (single bulk query)
-        old_records_map = self.analyzer.fetch_old_records_map(instances)
-
-        # Build changeset for VALIDATE and BEFORE hooks
-        # These see pre-update state, which is correct
-        changeset_before = build_changeset_for_update(
-            self.model_cls,
-            instances,
-            update_kwargs,
-            old_records_map=old_records_map,
-        )
-
-        if bypass_hooks:
-            # No hooks - just execute the update
-            return BaseQuerySet.update(self.queryset, **update_kwargs)
-
-        # Execute VALIDATE and BEFORE hooks
-        if not bypass_validation:
-            self.dispatcher.dispatch(changeset_before, "validate_update", bypass_hooks=False)
-        self.dispatcher.dispatch(changeset_before, "before_update", bypass_hooks=False)
-
-        # Execute the actual database UPDATE
-        # Database evaluates all expressions here (Subquery, F(), etc.)
-        result = BaseQuerySet.update(self.queryset, **update_kwargs)
-
-        # Refetch instances to get actual post-update values from database
-        # This ensures AFTER hooks see the real final state
-        pks = [obj.pk for obj in instances]
-        refetched_instances = list(
-            self.model_cls.objects.filter(pk__in=pks)
-        )
-
-        # Build changeset for AFTER hooks with accurate new values
-        changeset_after = build_changeset_for_update(
-            self.model_cls,
-            refetched_instances,  # Fresh from database
-            update_kwargs,
-            old_records_map=old_records_map,  # Still have old values for comparison
-        )
-
-        # Execute AFTER hooks with accurate new_records
-        self.dispatcher.dispatch(changeset_after, "after_update", bypass_hooks=False)
-
-        return result
-
-    @transaction.atomic
-    def delete(self, bypass_hooks=False, bypass_validation=False):
-        """
-        Execute delete with hooks.
-
-        Args:
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Tuple of (count, details dict)
-        """
-        # Get objects
-        objs = list(self.queryset)
-        if not objs:
-            return 0, {}
-
-        # Validate
-        self.analyzer.validate_for_delete(objs)
-
-        # Build changeset
-        changeset = build_changeset_for_delete(self.model_cls, objs)
-
-        # Execute with hook lifecycle
-        def operation():
-            # Call base Django QuerySet.delete() to avoid recursion
-            return BaseQuerySet.delete(self.queryset)
-
-        return self.dispatcher.execute_operation_with_hooks(
-            changeset=changeset,
-            operation=operation,
-            event_prefix="delete",
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
-        )
-
-    def clean(self, objs, is_create=None):
-        """
-        Execute validation hooks only (no database operations).
-
-        This is used by Django's clean() method to hook VALIDATE_* events
-        without performing the actual operation.
-
-        Args:
-            objs: List of model instances to validate
-            is_create: True for create, False for update, None to auto-detect
-
-        Returns:
-            None
-        """
-        if not objs:
-            return
-
-        # Auto-detect if is_create not specified
-        if is_create is None:
-            is_create = objs[0].pk is None
-
-        # Build changeset based on operation type
-        if is_create:
-            changeset = build_changeset_for_create(self.model_cls, objs)
-            event = "validate_create"
-        else:
-            # For update validation, no old records needed - hooks handle their own queries
-            changeset = build_changeset_for_update(self.model_cls, objs, {})
-            event = "validate_update"
-
-        # Dispatch validation event only
-        self.dispatcher.dispatch(changeset, event, bypass_hooks=False)
+"""
+Bulk operation coordinator - Single entry point for all bulk operations.
+
+This facade hides the complexity of wiring up multiple services and provides
+a clean, simple API for the QuerySet to use.
+"""
+
+import logging
+from django.db import transaction
+from django.db.models import QuerySet as BaseQuerySet
+
+from django_bulk_hooks.helpers import (
+    build_changeset_for_create,
+    build_changeset_for_update,
+    build_changeset_for_delete,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BulkOperationCoordinator:
+    """
+    Single entry point for coordinating bulk operations.
+
+    This coordinator manages all services and provides a clean facade
+    for the QuerySet. It wires up services and coordinates the hook
+    lifecycle for each operation type.
+
+    Services are created lazily and cached.
+    """
+
+    def __init__(self, queryset):
+        """
+        Initialize coordinator for a queryset.
+
+        Args:
+            queryset: Django QuerySet instance
+        """
+        self.queryset = queryset
+        self.model_cls = queryset.model
+
+        # Lazy initialization
+        self._analyzer = None
+        self._mti_handler = None
+        self._executor = None
+        self._dispatcher = None
+
+    @property
+    def analyzer(self):
+        """Get or create ModelAnalyzer"""
+        if self._analyzer is None:
+            from django_bulk_hooks.operations.analyzer import ModelAnalyzer
+
+            self._analyzer = ModelAnalyzer(self.model_cls)
+        return self._analyzer
+
+    @property
+    def mti_handler(self):
+        """Get or create MTIHandler"""
+        if self._mti_handler is None:
+            from django_bulk_hooks.operations.mti_handler import MTIHandler
+
+            self._mti_handler = MTIHandler(self.model_cls)
+        return self._mti_handler
+
+    @property
+    def executor(self):
+        """Get or create BulkExecutor"""
+        if self._executor is None:
+            from django_bulk_hooks.operations.bulk_executor import BulkExecutor
+
+            self._executor = BulkExecutor(
+                queryset=self.queryset,
+                analyzer=self.analyzer,
+                mti_handler=self.mti_handler,
+            )
+        return self._executor
+
+    @property
+    def dispatcher(self):
+        """Get or create Dispatcher"""
+        if self._dispatcher is None:
+            from django_bulk_hooks.dispatcher import get_dispatcher
+
+            self._dispatcher = get_dispatcher()
+        return self._dispatcher
+
+    # ==================== PUBLIC API ====================
+
+    @transaction.atomic
+    def create(
+        self,
+        objs,
+        batch_size=None,
+        ignore_conflicts=False,
+        update_conflicts=False,
+        update_fields=None,
+        unique_fields=None,
+        bypass_hooks=False,
+        bypass_validation=False,
+    ):
+        """
+        Execute bulk create with hooks.
+
+        Args:
+            objs: List of model instances to create
+            batch_size: Number of objects per batch
+            ignore_conflicts: Ignore conflicts if True
+            update_conflicts: Update on conflict if True
+            update_fields: Fields to update on conflict
+            unique_fields: Fields to check for conflicts
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            List of created objects
+        """
+        if not objs:
+            return objs
+
+        # Validate
+        self.analyzer.validate_for_create(objs)
+
+        # Build initial changeset
+        changeset = build_changeset_for_create(
+            self.model_cls,
+            objs,
+            batch_size=batch_size,
+            ignore_conflicts=ignore_conflicts,
+            update_conflicts=update_conflicts,
+            update_fields=update_fields,
+            unique_fields=unique_fields,
+        )
+
+        # Execute with hook lifecycle
+        def operation():
+            return self.executor.bulk_create(
+                objs,
+                batch_size=batch_size,
+                ignore_conflicts=ignore_conflicts,
+                update_conflicts=update_conflicts,
+                update_fields=update_fields,
+                unique_fields=unique_fields,
+            )
+
+        return self.dispatcher.execute_operation_with_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="create",
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
+        )
+
+    @transaction.atomic
+    def update(
+        self,
+        objs,
+        fields,
+        batch_size=None,
+        bypass_hooks=False,
+        bypass_validation=False,
+    ):
+        """
+        Execute bulk update with hooks.
+
+        Args:
+            objs: List of model instances to update
+            fields: List of field names to update
+            batch_size: Number of objects per batch
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Number of objects updated
+        """
+        if not objs:
+            return 0
+
+        # Validate
+        self.analyzer.validate_for_update(objs)
+
+        # Fetch old records using analyzer (single source of truth)
+        old_records_map = self.analyzer.fetch_old_records_map(objs)
+
+        # Build changeset
+        from django_bulk_hooks.changeset import ChangeSet, RecordChange
+
+        changes = [
+            RecordChange(
+                new_record=obj,
+                old_record=old_records_map.get(obj.pk),
+                changed_fields=fields,
+            )
+            for obj in objs
+        ]
+        changeset = ChangeSet(self.model_cls, changes, "update", {"fields": fields})
+
+        # Execute with hook lifecycle
+        def operation():
+            return self.executor.bulk_update(objs, fields, batch_size=batch_size)
+
+        return self.dispatcher.execute_operation_with_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="update",
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
+        )
+
+    @transaction.atomic
+    def update_queryset(
+        self, update_kwargs, bypass_hooks=False, bypass_validation=False
+    ):
+        """
+        Execute queryset update with hooks.
+        
+        ARCHITECTURE: Application-Layer Update with Expression Resolution
+        ===================================================================
+        
+        When hooks are enabled, queryset.update() is transformed into bulk_update()
+        to allow BEFORE hooks to modify records. This is a deliberate design choice:
+        
+        1. Fetch instances from the queryset (we need them for hooks anyway)
+        2. Resolve SQL expressions (F(), Subquery, Case, etc.) to concrete values
+        3. Apply resolved values to instances
+        4. Run BEFORE hooks (which can now modify the instances)
+        5. Use bulk_update() to persist the (possibly modified) instances
+        6. Run AFTER hooks with final state
+        
+        This approach:
+        - ✅ Allows BEFORE hooks to modify values (feature request)
+        - ✅ Preserves SQL expression semantics (materializes them correctly)
+        - ✅ Eliminates the double-fetch (was fetching before AND after)
+        - ✅ More efficient than previous implementation
+        - ✅ Maintains Salesforce-like hook contract
+        
+        SQL expressions are resolved per-instance using Django's annotate(),
+        which ensures correct evaluation of:
+        - F() expressions: F('balance') + 100
+        - Subquery: Subquery(related.aggregate(...))
+        - Case/When: Case(When(...))
+        - Database functions: Upper(), Concat(), etc.
+        - Any other Django Expression
+        
+        Trade-off:
+        - Uses bulk_update() internally (slightly different SQL than queryset.update)
+        - Expression resolution may add overhead for complex expressions
+        - But eliminates the refetch, so overall more efficient
+
+        Args:
+            update_kwargs: Dict of fields to update
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Number of objects updated
+        """
+        # Fetch instances from queryset
+        instances = list(self.queryset)
+        if not instances:
+            return 0
+
+        # Check both parameter and context for bypass_hooks
+        from django_bulk_hooks.context import get_bypass_hooks
+        should_bypass = bypass_hooks or get_bypass_hooks()
+        
+        if should_bypass:
+            # No hooks - use original queryset.update() for max performance
+            return BaseQuerySet.update(self.queryset, **update_kwargs)
+
+        # Resolve expressions and apply to instances
+        # Delegate to analyzer for expression resolution and value application
+        fields_to_update = self.analyzer.apply_update_values(instances, update_kwargs)
+        
+        # Now instances have the resolved values applied
+        # Fetch old records for comparison (single bulk query)
+        old_records_map = self.analyzer.fetch_old_records_map(instances)
+
+        # Build changeset for VALIDATE and BEFORE hooks
+        # instances now have the "intended" values from update_kwargs
+        changeset = build_changeset_for_update(
+            self.model_cls,
+            instances,
+            update_kwargs,
+            old_records_map=old_records_map,
+        )
+
+        # Execute VALIDATE and BEFORE hooks
+        # Hooks can now modify the instances and changes will persist
+        if not bypass_validation:
+            self.dispatcher.dispatch(changeset, "validate_update", bypass_hooks=False)
+        self.dispatcher.dispatch(changeset, "before_update", bypass_hooks=False)
+
+        # COORDINATION LOGIC: Determine all fields to persist
+        # Hooks may have modified fields beyond the original update_kwargs.
+        # We need to detect those changes and include them in bulk_update.
+        # This is coordination between: hooks → field detection → executor
+        additional_changed_fields = self.analyzer.detect_changed_fields(instances)
+        all_fields_to_update = list(set(fields_to_update) | set(additional_changed_fields))
+        
+        # Use bulk_update with all modified fields (original + hook modifications)
+        result = self.executor.bulk_update(instances, all_fields_to_update, batch_size=None)
+
+        # Build changeset for AFTER hooks
+        # No refetch needed! instances already have final state from bulk_update
+        changeset_after = build_changeset_for_update(
+            self.model_cls,
+            instances,
+            update_kwargs,
+            old_records_map=old_records_map,
+        )
+
+        # Execute AFTER hooks with final state
+        self.dispatcher.dispatch(changeset_after, "after_update", bypass_hooks=False)
+
+        return result
+
+    @transaction.atomic
+    def delete(self, bypass_hooks=False, bypass_validation=False):
+        """
+        Execute delete with hooks.
+
+        Args:
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Tuple of (count, details dict)
+        """
+        # Get objects
+        objs = list(self.queryset)
+        if not objs:
+            return 0, {}
+
+        # Validate
+        self.analyzer.validate_for_delete(objs)
+
+        # Build changeset
+        changeset = build_changeset_for_delete(self.model_cls, objs)
+
+        # Execute with hook lifecycle
+        def operation():
+            # Call base Django QuerySet.delete() to avoid recursion
+            return BaseQuerySet.delete(self.queryset)
+
+        return self.dispatcher.execute_operation_with_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="delete",
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
+        )
+
+    def clean(self, objs, is_create=None):
+        """
+        Execute validation hooks only (no database operations).
+
+        This is used by Django's clean() method to hook VALIDATE_* events
+        without performing the actual operation.
+
+        Args:
+            objs: List of model instances to validate
+            is_create: True for create, False for update, None to auto-detect
+
+        Returns:
+            None
+        """
+        if not objs:
+            return
+
+        # Auto-detect if is_create not specified
+        if is_create is None:
+            is_create = objs[0].pk is None
+
+        # Build changeset based on operation type
+        if is_create:
+            changeset = build_changeset_for_create(self.model_cls, objs)
+            event = "validate_create"
+        else:
+            # For update validation, no old records needed - hooks handle their own queries
+            changeset = build_changeset_for_update(self.model_cls, objs, {})
+            event = "validate_update"
+
+        # Dispatch validation event only
+        self.dispatcher.dispatch(changeset, event, bypass_hooks=False)

{django_bulk_hooks-0.2.2.dist-info → django_bulk_hooks-0.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.2.2
+Version: 0.2.5
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks

{django_bulk_hooks-0.2.2.dist-info → django_bulk_hooks-0.2.5.dist-info}/RECORD

@@ -4,7 +4,7 @@ django_bulk_hooks/conditions.py,sha256=tNnQZvcR-jOB8ZzpoVd03PVIy8rjiFdzmufD5mP7f
 django_bulk_hooks/constants.py,sha256=PxpEETaO6gdENcTPoXS586lerGKVP3nmjpDvOkmhYxI,509
 django_bulk_hooks/context.py,sha256=mqaC5-yESDTA5ruI7fuXlt8qSgKuOFp0mjq7h1-4HdQ,1926
 django_bulk_hooks/debug_utils.py,sha256=6T32E_Pms6gbCl94A55fJAe_ynFsK_CJBTaPcsG8tik,4578
-django_bulk_hooks/decorators.py,sha256=UXvQ_tlEbHpmafLG2LZ9WsrvvoQlVACs8aNe8UrtPFE,9601
+django_bulk_hooks/decorators.py,sha256=B1mzXjVx9XWB8kwvJ97ZvBsgnVcpvtQWBpDHytVRtYo,9611
 django_bulk_hooks/dispatcher.py,sha256=L5_hSqENuKXDftJOdMetfjdZkiakUgkheqU8HpWKaOI,8214
 django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
 django_bulk_hooks/factory.py,sha256=JmjQiJPfAnytXrO6r6qOadX5yX0-sfpbZ9V8nwX3MAg,20013
@@ -13,14 +13,14 @@ django_bulk_hooks/helpers.py,sha256=Yopvl588VbKOi2kHEsQcEcI5jw5jiNA2MuF6Ce1VP0c,
 django_bulk_hooks/manager.py,sha256=3mFzB0ZzHHeXWdKGObZD_H0NlskHJc8uYBF69KKdAXU,4068
 django_bulk_hooks/models.py,sha256=62tn5wL55EjJVOsZofMluhEJB8bH7CzBvH0vd214_RY,2570
 django_bulk_hooks/operations/__init__.py,sha256=5L5NnwiFw8Yn5WO6-38eGdCYBkA0URpwyDcAdeYfc5w,550
-django_bulk_hooks/operations/analyzer.py,sha256=S9qcLRM_VBR6Cy_ObUq0Mok8bp07ALLPDF_S0Yypi2k,6507
+django_bulk_hooks/operations/analyzer.py,sha256=s6FM53ho1raPdKU-VjjW0SWymXyrJe0I_Wu8XsXFdSY,9065
 django_bulk_hooks/operations/bulk_executor.py,sha256=PuRVS5OlOysZ3qEHMsadr06rZt5CoZL6tgzqBAvDQxY,17825
-django_bulk_hooks/operations/coordinator.py,sha256=HMJyvntKXo4aAOwElrvS0F05zoOllfPvYakdAr6JCkk,12326
+django_bulk_hooks/operations/coordinator.py,sha256=SYKvbS1hsz1sJUUEFU3q5nSSsJZfLGpcQvUUPu7uXDA,13084
 django_bulk_hooks/operations/mti_handler.py,sha256=eIH-tImMqcWR5lLQr6Ca-HeVYta-UkXk5X5fcpS885Y,18245
 django_bulk_hooks/operations/mti_plans.py,sha256=fHUYbrUAHq8UXqxgAD43oHdTxOnEkmpxoOD4Qrzfqk8,2878
 django_bulk_hooks/queryset.py,sha256=ody4MXrRREL27Ts2ey1UpS0tb5Dxnw-6kN3unxPQ3zY,5860
 django_bulk_hooks/registry.py,sha256=UPerNhtVz_9tKZqrYSZD2LhjAcs4F6hVUuk8L5oOeHc,8821
-django_bulk_hooks-0.2.2.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
-django_bulk_hooks-0.2.2.dist-info/METADATA,sha256=m8XX5tJbiTgwP9fMCajuhOEvDJRxoqJqiiyzTUpdY50,9264
-django_bulk_hooks-0.2.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-django_bulk_hooks-0.2.2.dist-info/RECORD,,
+django_bulk_hooks-0.2.5.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
+django_bulk_hooks-0.2.5.dist-info/METADATA,sha256=OMVuW7PeRzeHrJi7ksrf0BEpjB4A2vXBJNRBGZ0qutA,9264
+django_bulk_hooks-0.2.5.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+django_bulk_hooks-0.2.5.dist-info/RECORD,,