django-bulk-hooks 0.2.11__tar.gz → 0.2.12__tar.gz

{django_bulk_hooks-0.2.11 → django_bulk_hooks-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.2.11
+Version: 0.2.12
 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.11 → django_bulk_hooks-0.2.12}/django_bulk_hooks/dispatcher.py

@@ -1,246 +1,246 @@
-"""
-HookDispatcher: Single execution path for all hooks.
-
-Provides deterministic, priority-ordered hook execution,
-similar to Salesforce's hook framework.
-"""
-
-import logging
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-class HookDispatcher:
-    """
-    Single execution path for all hooks.
-
-    Responsibilities:
-    - Execute hooks in priority order
-    - Filter records based on conditions
-    - Provide ChangeSet context to hooks
-    - Fail-fast error propagation
-    - Manage complete operation lifecycle (VALIDATE, BEFORE, AFTER)
-    """
-
-    def __init__(self, registry):
-        """
-        Initialize the dispatcher.
-
-        Args:
-            registry: The hook registry (provides get_hooks method)
-        """
-        self.registry = registry
-
-    def execute_operation_with_hooks(
-        self,
-        changeset,
-        operation,
-        event_prefix,
-        bypass_hooks=False,
-        bypass_validation=False,
-    ):
-        """
-        Execute operation with full hook lifecycle.
-
-        This is the high-level method that coordinates the complete lifecycle:
-        1. VALIDATE_{event}
-        2. BEFORE_{event}
-        3. Actual operation
-        4. AFTER_{event}
-
-        Args:
-            changeset: ChangeSet for the operation
-            operation: Callable that performs the actual DB operation
-            event_prefix: 'create', 'update', or 'delete'
-            bypass_hooks: Skip all hooks if True
-            bypass_validation: Skip validation hooks if True
-
-        Returns:
-            Result of operation
-        """
-        if bypass_hooks:
-            return operation()
-
-        # VALIDATE phase
-        if not bypass_validation:
-            self.dispatch(changeset, f"validate_{event_prefix}", bypass_hooks=False)
-
-        # BEFORE phase
-        self.dispatch(changeset, f"before_{event_prefix}", bypass_hooks=False)
-
-        # Execute the actual operation
-        result = operation()
-
-        # AFTER phase - use result if operation returns modified data
-        if result and isinstance(result, list) and event_prefix == "create":
-            # For create, rebuild changeset with assigned PKs
-            from django_bulk_hooks.helpers import build_changeset_for_create
-
-            changeset = build_changeset_for_create(changeset.model_cls, result)
-
-        self.dispatch(changeset, f"after_{event_prefix}", bypass_hooks=False)
-
-        return result
-
-    def dispatch(self, changeset, event, bypass_hooks=False):
-        """
-        Dispatch hooks for a changeset with deterministic ordering.
-
-        This is the single execution path for ALL hooks in the system.
-
-        Args:
-            changeset: ChangeSet instance with record changes
-            event: Event name (e.g., 'after_update', 'before_create')
-            bypass_hooks: If True, skip all hook execution
-
-        Raises:
-            Exception: Any exception raised by a hook (fails fast)
-            RecursionError: If hooks create an infinite loop (Python's built-in limit)
-        """
-        if bypass_hooks:
-            return
-
-        # Get hooks sorted by priority (deterministic order)
-        hooks = self.registry.get_hooks(changeset.model_cls, event)
-
-        if not hooks:
-            return
-
-        # Execute hooks in priority order
-        logger.info(f"🔥 HOOKS: Executing {len(hooks)} hooks for {changeset.model_cls.__name__}.{event}")
-        for handler_cls, method_name, condition, priority in hooks:
-            logger.info(f"  → {handler_cls.__name__}.{method_name} (priority={priority})")
-            self._execute_hook(handler_cls, method_name, condition, changeset)
-
-    def _execute_hook(self, handler_cls, method_name, condition, changeset):
-        """
-        Execute a single hook with condition checking.
-
-        Args:
-            handler_cls: The hook handler class
-            method_name: Name of the method to call
-            condition: Optional condition to filter records
-            changeset: ChangeSet with all record changes
-        """
-        # Filter records based on condition
-        if condition:
-            filtered_changes = [
-                change
-                for change in changeset.changes
-                if condition.check(change.new_record, change.old_record)
-            ]
-
-            if not filtered_changes:
-                # No records match condition, skip this hook
-                return
-
-            # Create filtered changeset
-            from django_bulk_hooks.changeset import ChangeSet
-
-            filtered_changeset = ChangeSet(
-                changeset.model_cls,
-                filtered_changes,
-                changeset.operation_type,
-                changeset.operation_meta,
-            )
-        else:
-            # No condition, use full changeset
-            filtered_changeset = changeset
-
-        # Use DI factory to create handler instance
-        from django_bulk_hooks.factory import create_hook_instance
-
-        handler = create_hook_instance(handler_cls)
-        method = getattr(handler, method_name)
-
-        # Check if method has @select_related decorator
-        preload_func = getattr(method, "_select_related_preload", None)
-        if preload_func:
-            # Preload relationships to prevent N+1 queries
-            try:
-                model_cls_override = getattr(handler, "model_cls", None)
-
-                # Get FK fields being updated to avoid preloading conflicting relationships
-                skip_fields = changeset.operation_meta.get('fk_fields_being_updated', set())
-
-                # Preload for new_records
-                if filtered_changeset.new_records:
-                    logger.debug(
-                        f"Preloading relationships for {len(filtered_changeset.new_records)} "
-                        f"new_records for {handler_cls.__name__}.{method_name}"
-                    )
-                    preload_func(
-                        filtered_changeset.new_records,
-                        model_cls=model_cls_override,
-                        skip_fields=skip_fields
-                    )
-
-                # Also preload for old_records (for conditions that check previous values)
-                if filtered_changeset.old_records:
-                    logger.debug(
-                        f"Preloading relationships for {len(filtered_changeset.old_records)} "
-                        f"old_records for {handler_cls.__name__}.{method_name}"
-                    )
-                    preload_func(
-                        filtered_changeset.old_records,
-                        model_cls=model_cls_override,
-                        skip_fields=skip_fields
-                    )
-            except Exception:
-                logger.debug(
-                    "select_related preload failed for %s.%s",
-                    handler_cls.__name__,
-                    method_name,
-                    exc_info=True,
-                )
-
-        # Execute hook with ChangeSet
-        # 
-        # ARCHITECTURE NOTE: Hook Contract
-        # ====================================
-        # All hooks must accept **kwargs for forward compatibility.
-        # We pass: changeset, new_records, old_records
-        # 
-        # Old hooks that don't use changeset: def hook(self, new_records, old_records, **kwargs)
-        # New hooks that do use changeset:    def hook(self, changeset, new_records, old_records, **kwargs)
-        # 
-        # This is standard Python framework design (see Django signals, Flask hooks, etc.)
-        logger.info(f"    🚀 Executing: {handler_cls.__name__}.{method_name}")
-        try:
-            method(
-                changeset=filtered_changeset,
-                new_records=filtered_changeset.new_records,
-                old_records=filtered_changeset.old_records,
-            )
-            logger.info(f"    ✅ Completed: {handler_cls.__name__}.{method_name}")
-        except Exception as e:
-            # Fail-fast: re-raise to rollback transaction
-            logger.error(
-                f"Hook {handler_cls.__name__}.{method_name} failed: {e}",
-                exc_info=True,
-            )
-            raise
-
-
-# Global dispatcher instance
-_dispatcher: Optional[HookDispatcher] = None
-
-
-def get_dispatcher():
-    """
-    Get the global dispatcher instance.
-
-    Creates the dispatcher on first access (singleton pattern).
-
-    Returns:
-        HookDispatcher instance
-    """
-    global _dispatcher
-    if _dispatcher is None:
-        # Import here to avoid circular dependency
-        from django_bulk_hooks.registry import get_registry
-
-        # Create dispatcher with the registry instance
-        _dispatcher = HookDispatcher(get_registry())
-    return _dispatcher
+"""
+HookDispatcher: Single execution path for all hooks.
+
+Provides deterministic, priority-ordered hook execution,
+similar to Salesforce's hook framework.
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class HookDispatcher:
+    """
+    Single execution path for all hooks.
+
+    Responsibilities:
+    - Execute hooks in priority order
+    - Filter records based on conditions
+    - Provide ChangeSet context to hooks
+    - Fail-fast error propagation
+    - Manage complete operation lifecycle (VALIDATE, BEFORE, AFTER)
+    """
+
+    def __init__(self, registry):
+        """
+        Initialize the dispatcher.
+
+        Args:
+            registry: The hook registry (provides get_hooks method)
+        """
+        self.registry = registry
+
+    def execute_operation_with_hooks(
+        self,
+        changeset,
+        operation,
+        event_prefix,
+        bypass_hooks=False,
+        bypass_validation=False,
+    ):
+        """
+        Execute operation with full hook lifecycle.
+
+        This is the high-level method that coordinates the complete lifecycle:
+        1. VALIDATE_{event}
+        2. BEFORE_{event}
+        3. Actual operation
+        4. AFTER_{event}
+
+        Args:
+            changeset: ChangeSet for the operation
+            operation: Callable that performs the actual DB operation
+            event_prefix: 'create', 'update', or 'delete'
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Result of operation
+        """
+        if bypass_hooks:
+            return operation()
+
+        # VALIDATE phase
+        if not bypass_validation:
+            self.dispatch(changeset, f"validate_{event_prefix}", bypass_hooks=False)
+
+        # BEFORE phase
+        self.dispatch(changeset, f"before_{event_prefix}", bypass_hooks=False)
+
+        # Execute the actual operation
+        result = operation()
+
+        # AFTER phase - use result if operation returns modified data
+        if result and isinstance(result, list) and event_prefix == "create":
+            # For create, rebuild changeset with assigned PKs
+            from django_bulk_hooks.helpers import build_changeset_for_create
+
+            changeset = build_changeset_for_create(changeset.model_cls, result)
+
+        self.dispatch(changeset, f"after_{event_prefix}", bypass_hooks=False)
+
+        return result
+
+    def dispatch(self, changeset, event, bypass_hooks=False):
+        """
+        Dispatch hooks for a changeset with deterministic ordering.
+
+        This is the single execution path for ALL hooks in the system.
+
+        Args:
+            changeset: ChangeSet instance with record changes
+            event: Event name (e.g., 'after_update', 'before_create')
+            bypass_hooks: If True, skip all hook execution
+
+        Raises:
+            Exception: Any exception raised by a hook (fails fast)
+            RecursionError: If hooks create an infinite loop (Python's built-in limit)
+        """
+        if bypass_hooks:
+            return
+
+        # Get hooks sorted by priority (deterministic order)
+        hooks = self.registry.get_hooks(changeset.model_cls, event)
+
+        if not hooks:
+            return
+
+        # Execute hooks in priority order
+        logger.info(f"🔥 HOOKS: Executing {len(hooks)} hooks for {changeset.model_cls.__name__}.{event}")
+        for handler_cls, method_name, condition, priority in hooks:
+            logger.info(f"  → {handler_cls.__name__}.{method_name} (priority={priority})")
+            self._execute_hook(handler_cls, method_name, condition, changeset)
+
+    def _execute_hook(self, handler_cls, method_name, condition, changeset):
+        """
+        Execute a single hook with condition checking.
+
+        Args:
+            handler_cls: The hook handler class
+            method_name: Name of the method to call
+            condition: Optional condition to filter records
+            changeset: ChangeSet with all record changes
+        """
+        # Filter records based on condition
+        if condition:
+            filtered_changes = [
+                change
+                for change in changeset.changes
+                if condition.check(change.new_record, change.old_record)
+            ]
+
+            if not filtered_changes:
+                # No records match condition, skip this hook
+                return
+
+            # Create filtered changeset
+            from django_bulk_hooks.changeset import ChangeSet
+
+            filtered_changeset = ChangeSet(
+                changeset.model_cls,
+                filtered_changes,
+                changeset.operation_type,
+                changeset.operation_meta,
+            )
+        else:
+            # No condition, use full changeset
+            filtered_changeset = changeset
+
+        # Use DI factory to create handler instance
+        from django_bulk_hooks.factory import create_hook_instance
+
+        handler = create_hook_instance(handler_cls)
+        method = getattr(handler, method_name)
+
+        # Check if method has @select_related decorator
+        preload_func = getattr(method, "_select_related_preload", None)
+        if preload_func:
+            # Preload relationships to prevent N+1 queries
+            try:
+                model_cls_override = getattr(handler, "model_cls", None)
+
+                # Get FK fields being updated to avoid preloading conflicting relationships
+                skip_fields = changeset.operation_meta.get('fk_fields_being_updated', set())
+
+                # Preload for new_records
+                if filtered_changeset.new_records:
+                    logger.debug(
+                        f"Preloading relationships for {len(filtered_changeset.new_records)} "
+                        f"new_records for {handler_cls.__name__}.{method_name}"
+                    )
+                    preload_func(
+                        filtered_changeset.new_records,
+                        model_cls=model_cls_override,
+                        skip_fields=skip_fields
+                    )
+
+                # Also preload for old_records (for conditions that check previous values)
+                if filtered_changeset.old_records:
+                    logger.debug(
+                        f"Preloading relationships for {len(filtered_changeset.old_records)} "
+                        f"old_records for {handler_cls.__name__}.{method_name}"
+                    )
+                    preload_func(
+                        filtered_changeset.old_records,
+                        model_cls=model_cls_override,
+                        skip_fields=skip_fields
+                    )
+            except Exception:
+                logger.debug(
+                    "select_related preload failed for %s.%s",
+                    handler_cls.__name__,
+                    method_name,
+                    exc_info=True,
+                )
+
+        # Execute hook with ChangeSet
+        # 
+        # ARCHITECTURE NOTE: Hook Contract
+        # ====================================
+        # All hooks must accept **kwargs for forward compatibility.
+        # We pass: changeset, new_records, old_records
+        # 
+        # Old hooks that don't use changeset: def hook(self, new_records, old_records, **kwargs)
+        # New hooks that do use changeset:    def hook(self, changeset, new_records, old_records, **kwargs)
+        # 
+        # This is standard Python framework design (see Django signals, Flask hooks, etc.)
+        logger.info(f"    🚀 Executing: {handler_cls.__name__}.{method_name}")
+        try:
+            method(
+                changeset=filtered_changeset,
+                new_records=filtered_changeset.new_records,
+                old_records=filtered_changeset.old_records,
+            )
+            logger.info(f"    ✅ Completed: {handler_cls.__name__}.{method_name}")
+        except Exception as e:
+            # Fail-fast: re-raise to rollback transaction
+            logger.error(
+                f"Hook {handler_cls.__name__}.{method_name} failed: {e}",
+                exc_info=True,
+            )
+            raise
+
+
+# Global dispatcher instance
+_dispatcher: Optional[HookDispatcher] = None
+
+
+def get_dispatcher():
+    """
+    Get the global dispatcher instance.
+
+    Creates the dispatcher on first access (singleton pattern).
+
+    Returns:
+        HookDispatcher instance
+    """
+    global _dispatcher
+    if _dispatcher is None:
+        # Import here to avoid circular dependency
+        from django_bulk_hooks.registry import get_registry
+
+        # Create dispatcher with the registry instance
+        _dispatcher = HookDispatcher(get_registry())
+    return _dispatcher

{django_bulk_hooks-0.2.11 → django_bulk_hooks-0.2.12}/django_bulk_hooks/operations/coordinator.py

@@ -212,40 +212,23 @@ class BulkOperationCoordinator:
         self, update_kwargs, bypass_hooks=False, bypass_validation=False
     ):
         """
-        Execute queryset update with hooks.
+        Execute queryset update with hooks - optimized for performance.
         
-        ARCHITECTURE: Application-Layer Update with Expression Resolution
-        ===================================================================
+        ARCHITECTURE: Database-Level Update with AFTER-Only Hooks
+        ==========================================================
         
-        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
+        Uses native Django queryset.update() for maximum performance,
+        then fetches results and runs AFTER hooks.
         
         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
+        - ✅ Uses native SQL UPDATE (fastest for aggregations, F(), Subquery)
+        - ✅ Maintains framework patterns (MTI support, changeset building)
+        - ✅ Runs AFTER_UPDATE hooks with old/new state
+        - ❌ BEFORE_UPDATE hooks cannot modify values (use bulk_update() instead)
         
-        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
+        For cases where BEFORE hooks need to modify values, use bulk_update():
+        - MyModel.objects.bulk_update(objs, fields)  # Allows BEFORE modifications
+        - MyModel.objects.update(...)                 # Fast, AFTER hooks only
 
         Args:
             update_kwargs: Dict of fields to update
@@ -255,12 +238,7 @@ class BulkOperationCoordinator:
         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
+        # Check bypass early
         from django_bulk_hooks.context import get_bypass_hooks
         should_bypass = bypass_hooks or get_bypass_hooks()
         
@@ -268,58 +246,65 @@ class BulkOperationCoordinator:
             # 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)
-
-        # Detect FK fields being updated to prevent @select_related conflicts
-        fk_fields_being_updated = self._get_fk_fields_being_updated(update_kwargs)
-
-        # 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,
+        # Delegate to specialized queryset update handler
+        return self._execute_queryset_update_with_hooks(
+            update_kwargs=update_kwargs,
+            bypass_validation=bypass_validation,
         )
 
-        # Add FK field info to changeset meta for dispatcher to use
-        if fk_fields_being_updated:
-            changeset.operation_meta['fk_fields_being_updated'] = fk_fields_being_updated
-
-        # 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))
+    def _execute_queryset_update_with_hooks(
+        self, update_kwargs, bypass_validation=False
+    ):
+        """
+        Execute queryset update with hooks - fast path using native Django update.
         
-        # 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(
+        This method follows framework patterns but is optimized for database-level
+        operations where BEFORE hooks cannot modify values.
+        
+        Args:
+            update_kwargs: Dict of fields to update
+            bypass_validation: Skip validation hooks if True
+            
+        Returns:
+            Number of objects updated
+        """
+        # 1. Fetch old state (before DB 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)
+        
+        if result == 0:
+            return 0
+        
+        # 3. Fetch new state (after DB update)
+        new_instances = list(self.queryset)
+        
+        # 4. Build changeset (using framework helper)
+        changeset = build_changeset_for_update(
             self.model_cls,
-            instances,
+            new_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)
-
+        
+        # Mark that this is a queryset update (for potential hook inspection)
+        changeset.operation_meta['is_queryset_update'] = True
+        changeset.operation_meta['allows_before_modifications'] = False
+        
+        # 5. Get MTI chain (follow framework pattern)
+        models_in_chain = [self.model_cls]
+        if self.mti_handler.is_mti_model():
+            models_in_chain.extend(self.mti_handler.get_parent_models())
+        
+        # 6. AFTER hooks only (following MTI pattern from _execute_with_mti_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)
+        
         return result
 
     @transaction.atomic

{django_bulk_hooks-0.2.11 → django_bulk_hooks-0.2.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.2.11"
+version = "0.2.12"
 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"