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

django_bulk_hooks/conditions.py

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

django_bulk_hooks/context.py

@@ -1,61 +1,36 @@
 import threading
-from typing import Deque, Optional
-from django_bulk_hooks.handler import hook_vars, get_hook_queue as _handler_get_hook_queue
+from collections import deque
+from django_bulk_hooks.handler import hook_vars
 
 
 _hook_context = threading.local()
 
 
-def get_hook_queue() -> Deque:
-    """
-    Return the per-thread hook execution queue used by the handler.
+def get_hook_queue():
+    if not hasattr(_hook_context, "queue"):
+        _hook_context.queue = deque()
+    return _hook_context.queue
 
-    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: bool) -> None:
+def set_bypass_hooks(bypass_hooks):
     """Set the current bypass_hooks state for the current thread."""
     _hook_context.bypass_hooks = bypass_hooks
 
 
-def get_bypass_hooks() -> bool:
+def get_bypass_hooks():
     """Get the current bypass_hooks state for the current thread."""
     return getattr(_hook_context, 'bypass_hooks', False)
 
 
 class HookContext:
-    """
-    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
+    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
         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) -> bool:
+    def is_executing(self):
         """
         Check if we're currently in a hook execution context.
         Similar to Salesforce's Trigger.isExecuting.
@@ -64,18 +39,15 @@ class HookContext:
         return hasattr(hook_vars, 'event') and hook_vars.event is not None
 
     @property
-    def current_event(self) -> Optional[str]:
+    def current_event(self):
         """
         Get the current hook event being executed.
         """
         return getattr(hook_vars, 'event', None)
 
     @property
-    def execution_depth(self) -> int:
+    def execution_depth(self):
         """
         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,28 +1,18 @@
-"""
-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: str, *, model: type, condition: Optional[Callable] = None, priority: int = DEFAULT_PRIORITY):
+def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
     """
     Decorator to annotate a method with multiple hooks hook registrations.
     If no priority is provided, uses Priority.NORMAL (50).
     """
 
-    def decorator(fn: Callable):
+    def decorator(fn):
         if not hasattr(fn, "hooks_hooks"):
             fn.hooks_hooks = []
         fn.hooks_hooks.append((model, event, condition, priority))
@@ -31,7 +21,7 @@ def hook(event: str, *, model: type, condition: Optional[Callable] = None, prior
     return decorator
 
 
-def select_related(*related_fields: str):
+def select_related(*related_fields):
     """
     Decorator that preloads related fields in-place on `new_records`, before the hook logic runs.
 
@@ -40,14 +30,11 @@ def select_related(*related_fields: str):
     - Populates Django's relation cache to avoid extra queries
     """
 
-    def decorator(func: Callable):
-        # No-op if no fields specified
-        if not related_fields:
-            return func
+    def decorator(func):
         sig = inspect.signature(func)
 
         @wraps(func)
-        def wrapper(*args: Any, **kwargs: Any):
+        def wrapper(*args, **kwargs):
             bound = sig.bind_partial(*args, **kwargs)
             bound.apply_defaults()
 
@@ -118,7 +105,7 @@ def select_related(*related_fields: str):
     return decorator
 
 
-def bulk_hook(model_cls: type, event: str, when: Optional[Callable] = None, priority: Optional[int] = None):
+def bulk_hook(model_cls, event, when=None, priority=None):
     """
     Decorator to register a bulk hook for a model.
     
@@ -128,13 +115,13 @@ def bulk_hook(model_cls: type, event: str, when: Optional[Callable] = None, prio
         when: Optional condition for when the hook should run
         priority: Optional priority for hook execution order
     """
-    def decorator(func: Callable):
+    def decorator(func):
         # Create a simple handler class for the function
         class FunctionHandler:
             def __init__(self):
                 self.func = func
             
-            def handle(self, new_instances: list, original_instances: Optional[list]):
+            def handle(self, new_instances, original_instances):
                 return self.func(new_instances, original_instances)
         
         # Register the hook using the registry
@@ -148,82 +135,3 @@ def bulk_hook(model_cls: type, event: str, when: Optional[Callable] = None, prio
         )
         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,10 +1,8 @@
 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__)
 
@@ -12,35 +10,24 @@ 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')
-        new_records: List of new/updated records
-        old_records: List of original records (for comparison)
-        ctx: Optional hook context
     """
     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)"
-    )
+    import traceback
 
+    stack = traceback.format_stack()
+    logger.debug(f"engine.run {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:
-        logger.debug("Hook execution bypassed")
+    if ctx and hasattr(ctx, 'bypass_hooks') and ctx.bypass_hooks:
+        logger.debug("engine.run bypassed")
         return
 
     # For BEFORE_* events, run model.clean() first for validation
@@ -52,76 +39,36 @@ def run(model_cls, event, new_records, old_records=None, ctx=None):
                 logger.error("Validation failed for %s: %s", instance, e)
                 raise
 
-    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:
-            # 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:
-                    handler_instance = handler_cls()
-                    func = getattr(handler_instance, method_name)
-                except Exception as e:
-                    logger.error(
-                        "Failed to instantiate %s.%s: %s",
-                        handler_cls.__name__,
-                        method_name,
-                        e,
-                    )
-                    continue
-
-                # 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()
+    # Process hooks
+    for handler_cls, method_name, condition, priority in hooks:
+        logger.debug(f"Processing {handler_cls.__name__}.{method_name}")
+        handler_instance = handler_cls()
+        func = getattr(handler_instance, method_name)
+
+        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:
+                condition_result = condition.check(new, original)
+                if condition_result:
+                    to_process_new.append(new)
+                    to_process_old.append(original)
+
+        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(to_process_old) else None,
+                )
+            except Exception as e:
+                logger.debug(f"Hook execution failed: {e}")
+                raise

django_bulk_hooks/enums.py

@@ -1,14 +1,17 @@
-"""
-Compatibility layer for priority-related exports.
+from enum import IntEnum
 
-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
+class Priority(IntEnum):
+    """
+    Named priorities for django-bulk-hooks hooks.
+    Replaces module-level constants with a clean IntEnum.
+    """
+
+    HIGHEST = 0  # runs first
+    HIGH = 25  # runs early
+    NORMAL = 50  # default ordering
+    LOW = 75  # runs late
+    LOWEST = 100  # runs last
 
-# Default priority used when none is specified by the hook decorator
-DEFAULT_PRIORITY = Priority.NORMAL
 
-__all__ = ["Priority", "DEFAULT_PRIORITY"]
+DEFAULT_PRIORITY = Priority.NORMAL