django-bulk-hooks 0.2.14__tar.gz → 0.2.15__tar.gz

{django_bulk_hooks-0.2.14 → django_bulk_hooks-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.2.14
+Version: 0.2.15
 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.14 → django_bulk_hooks-0.2.15}/django_bulk_hooks/operations/coordinator.py

@@ -7,7 +7,8 @@ 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.db.models import QuerySet
+from django.core.exceptions import FieldDoesNotExist
 
 from django_bulk_hooks.helpers import (
     build_changeset_for_create,
@@ -29,6 +30,7 @@ class BulkOperationCoordinator:
     Services are created lazily and cached.
     """
 
+
     def __init__(self, queryset):
         """
         Initialize coordinator for a queryset.
@@ -212,40 +214,52 @@ class BulkOperationCoordinator:
         self, update_kwargs, bypass_hooks=False, bypass_validation=False
     ):
         """
-        Execute queryset update with hooks - optimized for performance.
-        
-        ARCHITECTURE: Database-Level Update with Hook Support
-        =======================================================
-        
-        For queryset.update() operations:
-        1. Fetch old state (before DB update)
-        2. Execute native Django UPDATE (fast, direct SQL with Subquery/F() support)
-        3. Fetch new state (after DB update, with computed values)
-        4. Run BEFORE_UPDATE hooks with old/new state
-           - Hooks can see Subquery-computed values via new_records
-           - Hooks CAN modify instances (e.g., set derived fields)
-           - Modifications are auto-persisted with bulk_update
-        5. Run AFTER_UPDATE hooks (for read-only side effects)
-        
-        Total DML: 1 (queryset.update) + 1 (bulk_update if hooks modify anything)
-        
-        Note: BEFORE_UPDATE runs AFTER the primary database update.
-        This enables:
-        - HasChanged conditions to work with Subquery-computed values
-        - Cascading updates from hook modifications
-        - Optimal performance (Subquery stays in SQL)
-        
-        For true BEFORE semantics (prevent/modify before DB write), use bulk_update().
+        Execute queryset.update() with full hook support.
+        
+        ARCHITECTURE & PERFORMANCE TRADE-OFFS
+        ======================================
+        
+        To support hooks with queryset.update(), we must:
+        1. Fetch old state (SELECT all matching rows)
+        2. Execute database update (UPDATE in SQL)
+        3. Fetch new state (SELECT all rows again)
+        4. Run VALIDATE_UPDATE hooks (validation only)
+        5. Run BEFORE_UPDATE hooks (CAN modify instances)
+        6. Persist BEFORE_UPDATE modifications (bulk_update)
+        7. Run AFTER_UPDATE hooks (read-only side effects)
+        
+        Performance Cost:
+        - 2 SELECT queries (before/after)
+        - 1 UPDATE query (actual update)
+        - 1 bulk_update (if hooks modify data)
+        
+        Trade-off: Hooks require loading data into Python. If you need
+        maximum performance and don't need hooks, use bypass_hooks=True.
+        
+        Hook Semantics:
+        - BEFORE_UPDATE hooks run after the DB update and CAN modify instances
+        - Modifications are auto-persisted (framework handles complexity)
+        - AFTER_UPDATE hooks run after BEFORE_UPDATE and are read-only
+        - This enables cascade logic and computed fields based on DB values
+        - User expectation: BEFORE_UPDATE hooks can modify data
+        
+        Why this approach works well:
+        - Allows hooks to see Subquery/F() computed values
+        - Enables HasChanged conditions on complex expressions
+        - Maintains SQL performance (Subquery stays in database)
+        - Meets user expectations: BEFORE_UPDATE can modify instances
+        - Clean separation: BEFORE for modifications, AFTER for side effects
+        
+        For true "prevent write" semantics, intercept at a higher level
+        or use bulk_update() directly (which has true before semantics).
         """
-        # Check bypass early
         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)
+        # Fast path: no hooks at all
+        if bypass_hooks or get_bypass_hooks():
+            return QuerySet.update(self.queryset, **update_kwargs)
 
-        # Delegate to specialized queryset update handler
+        # Full hook lifecycle path
         return self._execute_queryset_update_with_hooks(
             update_kwargs=update_kwargs,
             bypass_validation=bypass_validation,
@@ -255,34 +269,38 @@ class BulkOperationCoordinator:
         self, update_kwargs, bypass_validation=False
     ):
         """
-        Execute queryset update with hooks - fast path using native Django update.
+        Execute queryset update with full hook lifecycle support.
         
-        This method provides full hook lifecycle support for queryset.update()
-        including BEFORE_UPDATE hooks with automatic persistence of modifications.
+        This method implements the fetch-update-fetch pattern required
+        to support hooks with queryset.update(). BEFORE_UPDATE hooks can
+        modify instances and modifications are auto-persisted.
         
         Args:
             update_kwargs: Dict of fields to update
             bypass_validation: Skip validation hooks if True
             
         Returns:
-            Number of objects updated
+            Number of rows updated
         """
-        # 1. Fetch old state (before DB update)
+        # Step 1: Fetch old state (before database update)
         old_instances = list(self.queryset)
         if not old_instances:
             return 0
+            
         old_records_map = {inst.pk: inst for inst in old_instances}
         
-        # 2. Execute native Django update (FAST)
-        result = BaseQuerySet.update(self.queryset, **update_kwargs)
+        # Step 2: Execute native Django update
+        # Use stored reference to parent class method - clean and simple
+        update_count = QuerySet.update(self.queryset, **update_kwargs)
         
-        if result == 0:
+        if update_count == 0:
             return 0
         
-        # 3. Fetch new state (after DB update)
+        # Step 3: Fetch new state (after database update)
+        # This captures any Subquery/F() computed values
         new_instances = list(self.queryset)
         
-        # 4. Build changeset (using framework helper)
+        # Step 4: Build changeset
         changeset = build_changeset_for_update(
             self.model_cls,
             new_instances,
@@ -290,65 +308,157 @@ class BulkOperationCoordinator:
             old_records_map=old_records_map,
         )
         
-        # Mark that this is a queryset update (for potential hook inspection)
+        # Mark as queryset update for potential hook inspection
         changeset.operation_meta['is_queryset_update'] = True
-        changeset.operation_meta['allows_before_modifications'] = True
+        changeset.operation_meta['allows_modifications'] = True
         
-        # 5. Get MTI chain (follow framework pattern)
+        # Step 5: Get MTI inheritance chain
         models_in_chain = [self.model_cls]
         if self.mti_handler.is_mti_model():
             models_in_chain.extend(self.mti_handler.get_parent_models())
         
-        # 6. BEFORE_UPDATE hooks (with auto-persistence)
-        # Snapshot state before hooks
-        pre_hook_state = {}
-        for instance in new_instances:
-            if instance.pk is not None:
-                pre_hook_values = {}
-                for field in self.model_cls._meta.fields:
-                    try:
-                        pre_hook_values[field.name] = getattr(instance, field.name, None)
-                    except Exception:
-                        pre_hook_values[field.name] = None
-                pre_hook_state[instance.pk] = pre_hook_values
-        
-        # Dispatch BEFORE_UPDATE hooks
+        # Step 6: Run VALIDATE hooks (if not bypassed)
+        if not bypass_validation:
+            for model_cls in models_in_chain:
+                model_changeset = self._build_changeset_for_model(changeset, model_cls)
+                self.dispatcher.dispatch(
+                    model_changeset, 
+                    "validate_update", 
+                    bypass_hooks=False
+                )
+        
+        # Step 7: Run BEFORE_UPDATE hooks with modification tracking
+        modified_fields = self._run_before_update_hooks_with_tracking(
+            new_instances, 
+            models_in_chain, 
+            changeset
+        )
+        
+        # Step 8: Auto-persist BEFORE_UPDATE modifications
+        if modified_fields:
+            self._persist_hook_modifications(new_instances, modified_fields)
+        
+        # Step 9: Run AFTER_UPDATE hooks (read-only side effects)
         for model_cls in models_in_chain:
             model_changeset = self._build_changeset_for_model(changeset, model_cls)
-            self.dispatcher.dispatch(model_changeset, "before_update", bypass_hooks=False)
-        
-        # Detect modifications made by BEFORE_UPDATE hooks
-        hook_modified_fields = set()
-        for instance in new_instances:
-            if instance.pk in pre_hook_state:
-                for field_name, pre_value in pre_hook_state[instance.pk].items():
-                    try:
-                        current_value = getattr(instance, field_name, None)
-                    except Exception:
-                        current_value = None
-                    
-                    if current_value != pre_value:
-                        hook_modified_fields.add(field_name)
-        
-        # Auto-persist hook modifications
-        if hook_modified_fields:
-            logger.info(
-                f"BEFORE_UPDATE hooks modified {len(hook_modified_fields)} fields: {hook_modified_fields}"
+            self.dispatcher.dispatch(
+                model_changeset, 
+                "after_update", 
+                bypass_hooks=False
             )
-            logger.info("Auto-persisting modifications with bulk_update")
-            
-            # Use bulk_update to persist changes
-            # This will trigger another hook cycle (Salesforce-style cascading)
-            from django.db.models import QuerySet as BaseQuerySet
-            base_qs = BaseQuerySet(model=self.model_cls, using=self.queryset.db)
-            base_qs.bulk_update(new_instances, list(hook_modified_fields))
         
-        # 7. AFTER_UPDATE hooks (read-only side effects)
+        return update_count
+
+    def _run_before_update_hooks_with_tracking(self, instances, models_in_chain, changeset):
+        """
+        Run BEFORE_UPDATE hooks and detect modifications.
+        
+        This is what users expect - BEFORE_UPDATE hooks can modify instances
+        and those modifications will be automatically persisted. The framework
+        handles the complexity internally.
+        
+        Returns:
+            Set of field names that were modified by hooks
+        """
+        # Snapshot current state
+        pre_hook_state = self._snapshot_instance_state(instances)
+        
+        # Run BEFORE_UPDATE hooks
         for model_cls in models_in_chain:
             model_changeset = self._build_changeset_for_model(changeset, model_cls)
-            self.dispatcher.dispatch(model_changeset, "after_update", bypass_hooks=False)
+            self.dispatcher.dispatch(
+                model_changeset, 
+                "before_update", 
+                bypass_hooks=False
+            )
         
-        return result
+        # Detect modifications
+        return self._detect_modifications(instances, pre_hook_state)
+
+    def _snapshot_instance_state(self, instances):
+        """
+        Create a snapshot of current instance field values.
+        
+        Args:
+            instances: List of model instances
+            
+        Returns:
+            Dict mapping pk -> {field_name: value}
+        """
+        snapshot = {}
+        
+        for instance in instances:
+            if instance.pk is None:
+                continue
+                
+            field_values = {}
+            for field in self.model_cls._meta.get_fields():
+                # Skip relations that aren't concrete fields
+                if field.many_to_many or field.one_to_many:
+                    continue
+                    
+                field_name = field.name
+                try:
+                    field_values[field_name] = getattr(instance, field_name)
+                except (AttributeError, FieldDoesNotExist):
+                    # Field not accessible (e.g., deferred field)
+                    field_values[field_name] = None
+                    
+            snapshot[instance.pk] = field_values
+            
+        return snapshot
+
+    def _detect_modifications(self, instances, pre_hook_state):
+        """
+        Detect which fields were modified by comparing to snapshot.
+        
+        Args:
+            instances: List of model instances
+            pre_hook_state: Previous state snapshot from _snapshot_instance_state
+            
+        Returns:
+            Set of field names that were modified
+        """
+        modified_fields = set()
+        
+        for instance in instances:
+            if instance.pk not in pre_hook_state:
+                continue
+                
+            old_values = pre_hook_state[instance.pk]
+            
+            for field_name, old_value in old_values.items():
+                try:
+                    current_value = getattr(instance, field_name)
+                except (AttributeError, FieldDoesNotExist):
+                    current_value = None
+                
+                # Compare values
+                if current_value != old_value:
+                    modified_fields.add(field_name)
+        
+        return modified_fields
+
+    def _persist_hook_modifications(self, instances, modified_fields):
+        """
+        Persist modifications made by hooks using bulk_update.
+        
+        This creates a "cascade" effect similar to Salesforce workflows.
+        
+        Args:
+            instances: List of modified instances
+            modified_fields: Set of field names that were modified
+        """
+        logger.info(
+            f"Hooks modified {len(modified_fields)} field(s): "
+            f"{', '.join(sorted(modified_fields))}"
+        )
+        logger.info("Auto-persisting modifications via bulk_update")
+        
+        # Use Django's bulk_update directly (not our hook version)
+        # Create a fresh QuerySet to avoid recursion
+        fresh_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
+        QuerySet.bulk_update(fresh_qs, instances, list(modified_fields))
 
     @transaction.atomic
     def delete(self, bypass_hooks=False, bypass_validation=False):
@@ -375,8 +485,8 @@ class BulkOperationCoordinator:
 
         # Execute with hook lifecycle
         def operation():
-            # Call base Django QuerySet.delete() to avoid recursion
-            return BaseQuerySet.delete(self.queryset)
+            # Use stored reference to parent method - clean and simple
+            return QuerySet.delete(self.queryset)
 
         return self._execute_with_mti_hooks(
             changeset=changeset,
@@ -532,8 +642,8 @@ class BulkOperationCoordinator:
                     # This is a FK field being updated by its attname (e.g., business_id)
                     # Add the relationship name (e.g., 'business') to skip list
                     fk_relationships.add(field.name)
-            except Exception:
+            except FieldDoesNotExist:
                 # If field lookup fails, skip it
                 continue
 
-        return fk_relationships
+        return fk_relationships

{django_bulk_hooks-0.2.14 → django_bulk_hooks-0.2.15}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.2.14"
+version = "0.2.15"
 description = "Hook-style hooks for Django bulk operations like bulk_create and bulk_update."
 authors = ["Konrad Beck <konrad.beck@merchantcapital.co.za>"]
 readme = "README.md"