django-bulk-hooks 0.1.281__py3-none-any.whl → 0.2.1__py3-none-any.whl

django_bulk_hooks/decorators.py

@@ -29,141 +29,196 @@ def select_related(*related_fields):
     - Works with instance methods (resolves `self`)
     - Avoids replacing model instances
     - Populates Django's relation cache to avoid extra queries
+    - Uses Django ORM __ notation for related field paths (e.g., 'parent__parent__value')
     """
 
     def decorator(func):
         sig = inspect.signature(func)
 
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            bound = sig.bind_partial(*args, **kwargs)
-            bound.apply_defaults()
-
-            if "new_records" not in bound.arguments:
+        def preload_related(records, *, model_cls=None):
+            if not isinstance(records, list):
                 raise TypeError(
-                    "@preload_related requires a 'new_records' argument in the decorated function"
+                    f"@select_related expects a list of model instances, got {type(records)}"
                 )
 
-            new_records = bound.arguments["new_records"]
+            if not records:
+                return
 
-            if not isinstance(new_records, list):
-                raise TypeError(
-                    f"@preload_related expects a list of model instances, got {type(new_records)}"
-                )
+            if model_cls is None:
+                model_cls = records[0].__class__
+
+            # Validate field notation upfront
+            for field in related_fields:
+                if "." in field:
+                    raise ValueError(
+                        f"Invalid field notation '{field}'. Use Django ORM __ notation (e.g., 'parent__field')"
+                    )
+
+            direct_relation_fields = {}
+            validated_fields = []
+
+            for field in related_fields:
+                if "__" in field:
+                    validated_fields.append(field)
+                    continue
 
-            if not new_records:
-                return func(*args, **kwargs)
-
-            # Determine which instances actually need preloading
-            # Allow model_cls to be passed as a keyword argument for testing
-            if "model_cls" in bound.arguments:
-                model_cls = bound.arguments["model_cls"]
-            else:
-                model_cls = new_records[0].__class__
-            ids_to_fetch = []
-            for obj in new_records:
-                if obj.pk is None:
+                try:
+                    if hasattr(model_cls, "_meta"):
+                        relation_field = model_cls._meta.get_field(field)
+                    else:
+                        continue
+                except (FieldDoesNotExist, AttributeError):
                     continue
-                # if any related field is not already cached on the instance,
-                # mark it for fetching
-                # Handle Mock objects that don't have _state.fields_cache
+
+                if (
+                    relation_field.is_relation
+                    and not relation_field.many_to_many
+                    and not relation_field.one_to_many
+                ):
+                    validated_fields.append(field)
+                    direct_relation_fields[field] = relation_field
+
+            unsaved_related_ids_by_field = {
+                field: set() for field in direct_relation_fields.keys()
+            }
+
+            saved_ids_to_fetch = []
+            for obj in records:
+                if obj.pk is not None:
+                    needs_fetch = False
+                    if hasattr(obj, "_state") and hasattr(obj._state, "fields_cache"):
+                        try:
+                            needs_fetch = any(
+                                field not in obj._state.fields_cache
+                                for field in related_fields
+                            )
+                        except (TypeError, AttributeError):
+                            needs_fetch = True
+                    else:
+                        needs_fetch = True
+
+                    if needs_fetch:
+                        saved_ids_to_fetch.append(obj.pk)
+                    continue
+
+                fields_cache = None
                 if hasattr(obj, "_state") and hasattr(obj._state, "fields_cache"):
-                    try:
-                        if any(
-                            field not in obj._state.fields_cache
-                            for field in related_fields
-                        ):
-                            ids_to_fetch.append(obj.pk)
-                    except (TypeError, AttributeError):
-                        # If _state.fields_cache is not iterable or accessible, always fetch
-                        ids_to_fetch.append(obj.pk)
-                else:
-                    # For Mock objects or objects without _state.fields_cache, always fetch
-                    ids_to_fetch.append(obj.pk)
-
-            # Always validate fields for nested field errors, regardless of whether we need to fetch
-            # Note: We allow nested fields as Django's select_related supports them
-
-            fetched = {}
-            if ids_to_fetch:
-                # Validate fields before passing to select_related
-                validated_fields = []
-                for field in related_fields:
-                    # For nested fields (containing __), let Django's select_related handle validation
-                    if "__" in field:
-                        validated_fields.append(field)
+                    fields_cache = obj._state.fields_cache
+
+                for field_name, relation_field in direct_relation_fields.items():
+                    if fields_cache is not None and field_name in fields_cache:
                         continue
 
                     try:
-                        # Handle Mock objects that don't have _meta
-                        if hasattr(model_cls, "_meta"):
-                            f = model_cls._meta.get_field(field)
-                            if not (
-                                f.is_relation
-                                and not f.many_to_many
-                                and not f.one_to_many
-                            ):
-                                continue
-                            validated_fields.append(field)
-                        else:
-                            # For Mock objects, skip validation
-                            continue
-                    except (FieldDoesNotExist, AttributeError):
+                        related_id = getattr(obj, relation_field.get_attname(), None)
+                    except AttributeError:
                         continue
 
-                if validated_fields:
-                    # Use the base manager to avoid recursion
+                    if related_id is not None:
+                        unsaved_related_ids_by_field[field_name].add(related_id)
+
+            fetched_saved = {}
+            if saved_ids_to_fetch and validated_fields:
+                base_manager = getattr(model_cls, "_base_manager", None)
+                if base_manager is not None:
                     try:
-                        fetched = model_cls._base_manager.select_related(
+                        fetched_saved = base_manager.select_related(
                             *validated_fields
-                        ).in_bulk(ids_to_fetch)
+                        ).in_bulk(saved_ids_to_fetch)
                     except Exception:
-                        # If select_related fails (e.g., invalid nested fields), skip preloading
-                        fetched = {}
+                        fetched_saved = {}
+
+            fetched_unsaved_by_field = {
+                field: {} for field in direct_relation_fields.keys()
+            }
 
-            for obj in new_records:
-                preloaded = fetched.get(obj.pk)
-                if not preloaded:
+            for field_name, relation_field in direct_relation_fields.items():
+                related_ids = unsaved_related_ids_by_field[field_name]
+                if not related_ids:
                     continue
-                for field in related_fields:
-                    # Handle Mock objects that don't have _state.fields_cache
-                    if hasattr(obj, "_state") and hasattr(obj._state, "fields_cache"):
-                        if field in obj._state.fields_cache:
-                            # don't override values that were explicitly set or already loaded
-                            continue
-                    if "." in field:
-                        # Skip fields with dots (legacy format, not supported)
+
+                related_model = getattr(relation_field.remote_field, "model", None)
+                if related_model is None:
+                    continue
+
+                manager = getattr(related_model, "_base_manager", None)
+                if manager is None:
+                    continue
+
+                try:
+                    fetched_unsaved_by_field[field_name] = manager.in_bulk(related_ids)
+                except Exception:
+                    fetched_unsaved_by_field[field_name] = {}
+
+            for obj in records:
+                fields_cache = None
+                if hasattr(obj, "_state") and hasattr(obj._state, "fields_cache"):
+                    fields_cache = obj._state.fields_cache
+
+                if obj.pk is not None:
+                    preloaded = fetched_saved.get(obj.pk)
+                    if not preloaded:
                         continue
 
-                    try:
-                        # Handle Mock objects that don't have _meta
-                        if hasattr(model_cls, "_meta"):
-                            f = model_cls._meta.get_field(field)
-                            if not (
-                                f.is_relation
-                                and not f.many_to_many
-                                and not f.one_to_many
-                            ):
-                                continue
-                        else:
-                            # For Mock objects, skip validation
+                    for field in related_fields:
+                        if fields_cache is not None and field in fields_cache:
+                            continue
+
+                        relation_field = direct_relation_fields.get(field)
+                        if relation_field is None and "__" not in field:
                             continue
-                    except (FieldDoesNotExist, AttributeError):
+
+                        try:
+                            rel_obj = getattr(preloaded, field)
+                        except AttributeError:
+                            continue
+
+                        setattr(obj, field, rel_obj)
+                        if fields_cache is not None:
+                            fields_cache[field] = rel_obj
+                    continue
+
+                for field_name, relation_field in direct_relation_fields.items():
+                    if fields_cache is not None and field_name in fields_cache:
                         continue
 
                     try:
-                        rel_obj = getattr(preloaded, field)
-                        setattr(obj, field, rel_obj)
-                        # Only set _state.fields_cache if it exists
-                        if hasattr(obj, "_state") and hasattr(
-                            obj._state, "fields_cache"
-                        ):
-                            obj._state.fields_cache[field] = rel_obj
+                        related_id = getattr(obj, relation_field.get_attname(), None)
                     except AttributeError:
-                        pass
+                        continue
+
+                    if related_id is None:
+                        continue
+
+                    rel_obj = fetched_unsaved_by_field[field_name].get(related_id)
+                    if rel_obj is None:
+                        continue
+
+                    setattr(obj, field_name, rel_obj)
+                    if fields_cache is not None:
+                        fields_cache[field_name] = rel_obj
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            bound = sig.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+
+            if "new_records" not in bound.arguments:
+                raise TypeError(
+                    "@preload_related requires a 'new_records' argument in the decorated function"
+                )
+
+            new_records = bound.arguments["new_records"]
+
+            model_cls_override = bound.arguments.get("model_cls")
+
+            preload_related(new_records, model_cls=model_cls_override)
 
             return func(*bound.args, **bound.kwargs)
 
+        wrapper._select_related_preload = preload_related
+        wrapper._select_related_fields = related_fields
+
         return wrapper
 
     return decorator

django_bulk_hooks/dispatcher.py

@@ -0,0 +1,235 @@
+"""
+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
+        for handler_cls, method_name, condition, priority in hooks:
+            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)
+
+                # 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
+                    )
+
+                # 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
+                    )
+            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.)
+        try:
+            method(
+                changeset=filtered_changeset,
+                new_records=filtered_changeset.new_records,
+                old_records=filtered_changeset.old_records,
+            )
+        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