django-bulk-hooks 0.1.228__py3-none-any.whl → 0.1.230__py3-none-any.whl

django_bulk_hooks/conditions.py

@@ -1,11 +1,14 @@
 import logging
+from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
 
-def resolve_dotted_attr(instance, dotted_path):
+def resolve_dotted_attr(instance: Any, dotted_path: str) -> Any:
     """
     Recursively resolve a dotted attribute path, e.g., "type.category".
+
+    Returns None if any intermediate value is None or missing.
     """
     for attr in dotted_path.split("."):
         if instance is None:
@@ -15,29 +18,29 @@ def resolve_dotted_attr(instance, dotted_path):
 
 
 class HookCondition:
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         raise NotImplementedError
 
-    def __call__(self, instance, original_instance=None):
+    def __call__(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         return self.check(instance, original_instance)
 
-    def __and__(self, other):
+    def __and__(self, other: "HookCondition") -> "HookCondition":
         return AndCondition(self, other)
 
-    def __or__(self, other):
+    def __or__(self, other: "HookCondition") -> "HookCondition":
         return OrCondition(self, other)
 
-    def __invert__(self):
+    def __invert__(self) -> "HookCondition":
         return NotCondition(self)
 
 
 class IsNotEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
+    def __init__(self, field: str, value: Any, only_on_change: bool = False):
         self.field = field
         self.value = value
         self.only_on_change = only_on_change
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         current = resolve_dotted_attr(instance, self.field)
         if self.only_on_change:
             if original_instance is None:
@@ -49,12 +52,12 @@ class IsNotEqual(HookCondition):
 
 
 class IsEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
+    def __init__(self, field: str, value: Any, only_on_change: bool = False):
         self.field = field
         self.value = value
         self.only_on_change = only_on_change
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         current = resolve_dotted_attr(instance, self.field)
         if self.only_on_change:
             if original_instance is None:
@@ -66,11 +69,11 @@ class IsEqual(HookCondition):
 
 
 class HasChanged(HookCondition):
-    def __init__(self, field, has_changed=True):
+    def __init__(self, field: str, has_changed: bool = True):
         self.field = field
         self.has_changed = has_changed
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         if not original_instance:
             return False
         
@@ -85,7 +88,7 @@ class HasChanged(HookCondition):
 
 
 class WasEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
+    def __init__(self, field: str, value: Any, only_on_change: bool = False):
         """
         Check if a field's original value was `value`.
         If only_on_change is True, only return True when the field has changed away from that value.
@@ -94,7 +97,7 @@ class WasEqual(HookCondition):
         self.value = value
         self.only_on_change = only_on_change
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         if original_instance is None:
             return False
         previous = resolve_dotted_attr(original_instance, self.field)
@@ -106,7 +109,7 @@ class WasEqual(HookCondition):
 
 
 class ChangesTo(HookCondition):
-    def __init__(self, field, value):
+    def __init__(self, field: str, value: Any):
         """
         Check if a field's value has changed to `value`.
         Only returns True when original value != value and current value == value.
@@ -114,7 +117,7 @@ class ChangesTo(HookCondition):
         self.field = field
         self.value = value
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         if original_instance is None:
             return False
         previous = resolve_dotted_attr(original_instance, self.field)
@@ -123,70 +126,70 @@ class ChangesTo(HookCondition):
 
 
 class IsGreaterThan(HookCondition):
-    def __init__(self, field, value):
+    def __init__(self, field: str, value: Any):
         self.field = field
         self.value = value
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         current = resolve_dotted_attr(instance, self.field)
         return current is not None and current > self.value
 
 
 class IsGreaterThanOrEqual(HookCondition):
-    def __init__(self, field, value):
+    def __init__(self, field: str, value: Any):
         self.field = field
         self.value = value
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         current = resolve_dotted_attr(instance, self.field)
         return current is not None and current >= self.value
 
 
 class IsLessThan(HookCondition):
-    def __init__(self, field, value):
+    def __init__(self, field: str, value: Any):
         self.field = field
         self.value = value
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         current = resolve_dotted_attr(instance, self.field)
         return current is not None and current < self.value
 
 
 class IsLessThanOrEqual(HookCondition):
-    def __init__(self, field, value):
+    def __init__(self, field: str, value: Any):
         self.field = field
         self.value = value
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         current = resolve_dotted_attr(instance, self.field)
         return current is not None and current <= self.value
 
 
 class AndCondition(HookCondition):
-    def __init__(self, cond1, cond2):
+    def __init__(self, cond1: HookCondition, cond2: HookCondition):
         self.cond1 = cond1
         self.cond2 = cond2
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         return self.cond1.check(instance, original_instance) and self.cond2.check(
             instance, original_instance
         )
 
 
 class OrCondition(HookCondition):
-    def __init__(self, cond1, cond2):
+    def __init__(self, cond1: HookCondition, cond2: HookCondition):
         self.cond1 = cond1
         self.cond2 = cond2
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         return self.cond1.check(instance, original_instance) or self.cond2.check(
             instance, original_instance
         )
 
 
 class NotCondition(HookCondition):
-    def __init__(self, cond):
+    def __init__(self, cond: HookCondition):
         self.cond = cond
 
-    def check(self, instance, original_instance=None):
+    def check(self, instance: Any, original_instance: Optional[Any] = None) -> bool:
         return not self.cond.check(instance, original_instance)

django_bulk_hooks/context.py

@@ -1,36 +1,61 @@
 import threading
-from collections import deque
-from django_bulk_hooks.handler import hook_vars
+from typing import Deque, Optional
+from django_bulk_hooks.handler import hook_vars, get_hook_queue as _handler_get_hook_queue
 
 
 _hook_context = threading.local()
 
 
-def get_hook_queue():
-    if not hasattr(_hook_context, "queue"):
-        _hook_context.queue = deque()
-    return _hook_context.queue
+def get_hook_queue() -> Deque:
+    """
+    Return the per-thread hook execution queue used by the handler.
 
+    This proxies to the centralized queue in the handler module to avoid
+    divergent queues.
+    """
+    return _handler_get_hook_queue()
 
-def set_bypass_hooks(bypass_hooks):
+
+def set_bypass_hooks(bypass_hooks: bool) -> None:
     """Set the current bypass_hooks state for the current thread."""
     _hook_context.bypass_hooks = bypass_hooks
 
 
-def get_bypass_hooks():
+def get_bypass_hooks() -> bool:
     """Get the current bypass_hooks state for the current thread."""
     return getattr(_hook_context, 'bypass_hooks', False)
 
 
 class HookContext:
-    def __init__(self, model, bypass_hooks=False):
-        self.model = model
-        self.bypass_hooks = bypass_hooks
-        # Set the thread-local bypass state when creating a context
+    """
+    Hook execution context helper.
+
+    - Carries the model and bypass_hooks flag.
+    - On construction sets thread-local bypass state;
+      when used as a context manager, restores previous state on exit.
+    """
+
+    def __init__(self, model: type, bypass_hooks: bool = False):
+        self.model: type = model
+        self.bypass_hooks: bool = bypass_hooks
+        self._prev_bypass: Optional[bool] = None
+        # Preserve legacy behavior: set bypass state at construction
         set_bypass_hooks(bypass_hooks)
 
+    def __enter__(self) -> "HookContext":
+        self._prev_bypass = get_bypass_hooks()
+        set_bypass_hooks(self.bypass_hooks)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        # Restore previous bypass state
+        if self._prev_bypass is not None:
+            set_bypass_hooks(self._prev_bypass)
+        # Do not suppress exceptions
+        return False
+
     @property
-    def is_executing(self):
+    def is_executing(self) -> bool:
         """
         Check if we're currently in a hook execution context.
         Similar to Salesforce's Trigger.isExecuting.
@@ -39,15 +64,18 @@ class HookContext:
         return hasattr(hook_vars, 'event') and hook_vars.event is not None
 
     @property
-    def current_event(self):
+    def current_event(self) -> Optional[str]:
         """
         Get the current hook event being executed.
         """
         return getattr(hook_vars, 'event', None)
 
     @property
-    def execution_depth(self):
+    def execution_depth(self) -> int:
         """
         Get the current execution depth to detect deep recursion.
         """
         return getattr(hook_vars, 'depth', 0)
+
+    def __repr__(self) -> str:
+        return f"HookContext(model={getattr(self.model, '__name__', self.model)!r}, bypass_hooks={self.bypass_hooks})"

django_bulk_hooks/decorators.py

@@ -1,18 +1,28 @@
+"""
+Decorators for defining and optimizing hook handlers.
+
+Notes:
+- Hook registration occurs at import time; importing modules that define Hook
+  subclasses or use @hook will register handlers in the global registry.
+- The preload helpers below are safe, in-place optimizations to avoid N+1s.
+"""
+
 import inspect
 from functools import wraps
+from typing import Any, Callable, Optional
 
 from django.core.exceptions import FieldDoesNotExist
 from django_bulk_hooks.enums import DEFAULT_PRIORITY
 from django_bulk_hooks.registry import register_hook
 
 
-def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
+def hook(event: str, *, model: type, condition: Optional[Callable] = None, priority: int = DEFAULT_PRIORITY):
     """
     Decorator to annotate a method with multiple hooks hook registrations.
     If no priority is provided, uses Priority.NORMAL (50).
     """
 
-    def decorator(fn):
+    def decorator(fn: Callable):
         if not hasattr(fn, "hooks_hooks"):
             fn.hooks_hooks = []
         fn.hooks_hooks.append((model, event, condition, priority))
@@ -21,7 +31,7 @@ def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
     return decorator
 
 
-def select_related(*related_fields):
+def select_related(*related_fields: str):
     """
     Decorator that preloads related fields in-place on `new_records`, before the hook logic runs.
 
@@ -30,11 +40,14 @@ def select_related(*related_fields):
     - Populates Django's relation cache to avoid extra queries
     """
 
-    def decorator(func):
+    def decorator(func: Callable):
+        # No-op if no fields specified
+        if not related_fields:
+            return func
         sig = inspect.signature(func)
 
         @wraps(func)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: Any, **kwargs: Any):
             bound = sig.bind_partial(*args, **kwargs)
             bound.apply_defaults()
 
@@ -105,7 +118,7 @@ def select_related(*related_fields):
     return decorator
 
 
-def bulk_hook(model_cls, event, when=None, priority=None):
+def bulk_hook(model_cls: type, event: str, when: Optional[Callable] = None, priority: Optional[int] = None):
     """
     Decorator to register a bulk hook for a model.
     
@@ -115,13 +128,13 @@ def bulk_hook(model_cls, event, when=None, priority=None):
         when: Optional condition for when the hook should run
         priority: Optional priority for hook execution order
     """
-    def decorator(func):
+    def decorator(func: Callable):
         # Create a simple handler class for the function
         class FunctionHandler:
             def __init__(self):
                 self.func = func
             
-            def handle(self, new_instances, original_instances):
+            def handle(self, new_instances: list, original_instances: Optional[list]):
                 return self.func(new_instances, original_instances)
         
         # Register the hook using the registry
@@ -135,3 +148,82 @@ def bulk_hook(model_cls, event, when=None, priority=None):
         )
         return func
     return decorator
+
+
+def prefetch_related(*related_fields: str):
+    """
+    Decorator that prefetches related collections on `new_records` in-place,
+    populating Django's prefetch cache to avoid extra queries in hooks.
+
+    - Supports many-to-many and one-to-many relationships
+    - Preserves instance identity; does not replace objects
+    - Uses the base manager to avoid recursive hook triggering
+    """
+
+    def decorator(func: Callable):
+        # No-op if no fields specified
+        if not related_fields:
+            return func
+
+        sig = inspect.signature(func)
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any):
+            bound = sig.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+
+            if "new_records" not in bound.arguments:
+                raise TypeError(
+                    "@prefetch_related requires a 'new_records' argument in the decorated function"
+                )
+
+            new_records = bound.arguments["new_records"]
+
+            if not isinstance(new_records, list):
+                raise TypeError(
+                    f"@prefetch_related expects a list of model instances, got {type(new_records)}"
+                )
+
+            if not new_records:
+                return func(*args, **kwargs)
+
+            model_cls = new_records[0].__class__
+            ids_to_fetch = [obj.pk for obj in new_records if getattr(obj, "pk", None)]
+
+            if ids_to_fetch:
+                # Validate fields (no dotted notation)
+                for field in related_fields:
+                    if "." in field:
+                        raise ValueError(
+                            f"@prefetch_related does not support nested fields like '{field}'"
+                        )
+
+                fetched_map = {
+                    obj.pk: obj
+                    for obj in (
+                        model_cls._base_manager.filter(pk__in=ids_to_fetch)
+                        .prefetch_related(*related_fields)
+                    )
+                }
+
+                for obj in new_records:
+                    preloaded = fetched_map.get(obj.pk)
+                    if preloaded is None:
+                        continue
+                    # Copy prefetch cache entries from the preloaded instance
+                    src_cache = getattr(preloaded, "_prefetched_objects_cache", {})
+                    if not src_cache:
+                        continue
+                    dst_cache = getattr(obj, "_prefetched_objects_cache", None)
+                    if dst_cache is None:
+                        obj._prefetched_objects_cache = {}
+                        dst_cache = obj._prefetched_objects_cache
+                    for field in related_fields:
+                        if field in src_cache and field not in dst_cache:
+                            dst_cache[field] = src_cache[field]
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
+
+    return decorator

django_bulk_hooks/engine.py

@@ -1,8 +1,10 @@
 import logging
 
 from django.core.exceptions import ValidationError
+from django.db import transaction
 
 from django_bulk_hooks.registry import get_hooks
+from django_bulk_hooks.handler import hook_vars
 
 logger = logging.getLogger(__name__)
 
@@ -10,7 +12,14 @@ logger = logging.getLogger(__name__)
 def run(model_cls, event, new_records, old_records=None, ctx=None):
     """
     Run hooks for a given model, event, and records.
-    
+
+    Production-grade executor:
+    - Honors bypass_hooks via ctx
+    - Runs model.clean() before BEFORE_* events for validation
+    - Executes hooks in registry priority order with condition filtering
+    - Exposes thread-local context via hook_vars during execution
+    - AFTER_* timing is configurable via settings.BULK_HOOKS_AFTER_ON_COMMIT (default: False)
+
     Args:
         model_cls: The Django model class
         event: The hook event (e.g., 'before_create', 'after_update')
@@ -21,16 +30,16 @@ def run(model_cls, event, new_records, old_records=None, ctx=None):
     if not new_records:
         return
 
-    # Get hooks for this model and event
     hooks = get_hooks(model_cls, event)
-
     if not hooks:
         return
 
-    logger.debug(f"Running {len(hooks)} hooks for {model_cls.__name__}.{event} ({len(new_records)} records)")
-    
+    logger.debug(
+        f"Running {len(hooks)} hooks for {model_cls.__name__}.{event} ({len(new_records)} records)"
+    )
+
     # Check if we're in a bypass context
-    if ctx and hasattr(ctx, 'bypass_hooks') and ctx.bypass_hooks:
+    if ctx and hasattr(ctx, "bypass_hooks") and ctx.bypass_hooks:
         logger.debug("Hook execution bypassed")
         return
 
@@ -43,47 +52,76 @@ def run(model_cls, event, new_records, old_records=None, ctx=None):
                 logger.error("Validation failed for %s: %s", instance, e)
                 raise
 
-    # Process hooks in priority order (highest priority first)
-    # Registry now sorts by priority (highest first)
-    for handler_cls, method_name, condition, priority in hooks:
-        logger.debug(f"Processing {handler_cls.__name__}.{method_name} (priority: {priority})")
-        
+    def _execute():
+        hook_vars.depth += 1
+        hook_vars.new = new_records
+        hook_vars.old = old_records
+        hook_vars.event = event
+        hook_vars.model = model_cls
+
         try:
-            handler_instance = handler_cls()
-            func = getattr(handler_instance, method_name)
-        except Exception as e:
-            logger.error(f"Failed to instantiate {handler_cls.__name__}: {e}")
-            continue
-
-        to_process_new = []
-        to_process_old = []
-
-        for new, original in zip(
-            new_records,
-            old_records or [None] * len(new_records),
-            strict=True,
-        ):
-            if not condition:
-                to_process_new.append(new)
-                to_process_old.append(original)
-            else:
+            # Align old_records length with new_records for safe zipping
+            local_old = old_records or []
+            if len(local_old) < len(new_records):
+                local_old = local_old + [None] * (len(new_records) - len(local_old))
+
+            for handler_cls, method_name, condition, priority in hooks:
                 try:
-                    condition_result = condition.check(new, original)
-                    if condition_result:
-                        to_process_new.append(new)
-                        to_process_old.append(original)
+                    handler_instance = handler_cls()
+                    func = getattr(handler_instance, method_name)
                 except Exception as e:
-                    logger.error(f"Condition check failed for {handler_cls.__name__}.{method_name}: {e}")
+                    logger.error(
+                        "Failed to instantiate %s.%s: %s",
+                        handler_cls.__name__,
+                        method_name,
+                        e,
+                    )
                     continue
 
-        if to_process_new:
-            logger.debug(f"Executing {handler_cls.__name__}.{method_name} for {len(to_process_new)} records")
-            try:
-                func(
-                    new_records=to_process_new,
-                    old_records=to_process_old if any(x is not None for x in to_process_old) else None,
-                )
-            except Exception as e:
-                logger.error(f"Hook execution failed in {handler_cls.__name__}.{method_name}: {e}")
-                # Re-raise the exception to ensure proper error handling
-                raise
+                # Condition filtering per record
+                to_process_new = []
+                to_process_old = []
+                for new_obj, old_obj in zip(new_records, local_old, strict=True):
+                    if not condition:
+                        to_process_new.append(new_obj)
+                        to_process_old.append(old_obj)
+                    else:
+                        try:
+                            if condition.check(new_obj, old_obj):
+                                to_process_new.append(new_obj)
+                                to_process_old.append(old_obj)
+                        except Exception as e:
+                            logger.error(
+                                "Condition failed for %s.%s: %s",
+                                handler_cls.__name__,
+                                method_name,
+                                e,
+                            )
+                            continue
+
+                if not to_process_new:
+                    continue
+
+                try:
+                    func(
+                        new_records=to_process_new,
+                        old_records=to_process_old
+                        if any(x is not None for x in to_process_old)
+                        else None,
+                    )
+                except Exception:
+                    logger.exception(
+                        "Error in hook %s.%s", handler_cls.__name__, method_name
+                    )
+                    # Re-raise to ensure proper transactional behavior
+                    raise
+        finally:
+            hook_vars.new = None
+            hook_vars.old = None
+            hook_vars.event = None
+            hook_vars.model = None
+            hook_vars.depth -= 1
+
+    # Execute immediately so AFTER_* runs within the transaction.
+    # If a hook raises, the transaction is rolled back (Salesforce-style).
+    _execute()

django_bulk_hooks/enums.py

@@ -1,3 +1,14 @@
+"""
+Compatibility layer for priority-related exports.
+
+This module re-exports the canonical Priority enum and a DEFAULT_PRIORITY
+constant so existing imports like `from django_bulk_hooks.enums import ...`
+continue to work without churn. Prefer importing from `priority` in new code.
+"""
+
 from django_bulk_hooks.priority import Priority
 
+# Default priority used when none is specified by the hook decorator
 DEFAULT_PRIORITY = Priority.NORMAL
+
+__all__ = ["Priority", "DEFAULT_PRIORITY"]

django_bulk_hooks/handler.py

@@ -2,8 +2,6 @@ import logging
 import threading
 from collections import deque
 
-from django.db import transaction
-
 from django_bulk_hooks.registry import get_hooks, register_hook
 
 logger = logging.getLogger(__name__)
@@ -77,9 +75,6 @@ class HookMeta(type):
                 attr = getattr(cls, attr_name)
                 if callable(attr) and hasattr(attr, "hooks_hooks"):
                     for model_cls, event, condition, priority in attr.hooks_hooks:
-                        # Create a unique key for this hook registration
-                        key = (model_cls, event, cls, attr_name)
-                        
                         # Register the hook
                         register_hook(
                             model=model_cls,
@@ -171,12 +166,8 @@ class Hook(metaclass=HookMeta):
                     # Re-raise the exception to ensure proper error handling
                     raise
 
-        conn = transaction.get_connection()
         try:
-            if conn.in_atomic_block and event.startswith("after_"):
-                transaction.on_commit(_execute)
-            else:
-                _execute()
+            _execute()
         finally:
             hook_vars.new = None
             hook_vars.old = None