django-bulk-hooks 0.1.230__tar.gz → 0.1.231__tar.gz

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.1.230
+Version: 0.1.231
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks

django_bulk_hooks-0.1.231/django_bulk_hooks/__init__.py

@@ -0,0 +1,15 @@
+from django_bulk_hooks.handler import Hook
+from django_bulk_hooks.manager import BulkHookManager
+from django_bulk_hooks.decorators import hook
+from django_bulk_hooks.priority import Priority
+from django_bulk_hooks.context import HookContext
+from django_bulk_hooks.models import HookModelMixin
+
+__all__ = [
+    "Hook",
+    "hook",
+    "Priority",
+    "HookContext",
+    "HookModelMixin",
+    "BulkHookManager",
+]

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/django_bulk_hooks/decorators.py

@@ -129,6 +129,17 @@ def bulk_hook(model_cls: type, event: str, when: Optional[Callable] = None, prio
         priority: Optional priority for hook execution order
     """
     def decorator(func: Callable):
+        # Deprecation: prefer @hook(event, model=...) on a Hook subclass
+        try:
+            import warnings
+            warnings.warn(
+                "bulk_hook is deprecated; use @hook(event, model=..., condition=..., priority=...) on a Hook subclass",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        except Exception:
+            pass
+
         # Create a simple handler class for the function
         class FunctionHandler:
             def __init__(self):

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/django_bulk_hooks/engine.py

@@ -2,6 +2,7 @@ import logging
 
 from django.core.exceptions import ValidationError
 from django.db import transaction
+from django.conf import settings
 
 from django_bulk_hooks.registry import get_hooks
 from django_bulk_hooks.handler import hook_vars
@@ -9,6 +10,18 @@ from django_bulk_hooks.handler import hook_vars
 logger = logging.getLogger(__name__)
 
 
+class AggregatedHookError(Exception):
+    """Raised when multiple hook handlers fail under best-effort policy."""
+
+    def __init__(self, errors):
+        self.errors = errors
+        message_lines = [
+            "Multiple hook errors occurred:",
+            *(f"- {ctx}: {exc}" for ctx, exc in errors),
+        ]
+        super().__init__("\n".join(message_lines))
+
+
 def run(model_cls, event, new_records, old_records=None, ctx=None):
     """
     Run hooks for a given model, event, and records.
@@ -54,16 +67,35 @@ def run(model_cls, event, new_records, old_records=None, ctx=None):
 
     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))
+            # Build deterministic pairing of new and old by primary key when possible
+            def pair_records(new_list, old_list):
+                if not old_list:
+                    # No old records; pair each new with None
+                    return [(n, None) for n in new_list]
+
+                # If all new have PKs, align by PK preserving new order
+                if all(getattr(n, "pk", None) is not None for n in new_list):
+                    old_by_pk = {getattr(o, "pk", None): o for o in old_list if o is not None}
+                    pairs = []
+                    for n in new_list:
+                        pk = getattr(n, "pk", None)
+                        pairs.append((n, old_by_pk.get(pk)))
+                    return pairs
+
+                # Fallback: best-effort positional pairing (create flows etc.)
+                pairs = []
+                for idx, n in enumerate(new_list):
+                    o = old_list[idx] if idx < len(old_list) else None
+                    pairs.append((n, o))
+                return pairs
+
+            pairs = pair_records(new_records, old_records or [])
+
+            failure_policy = getattr(settings, "BULK_HOOKS_FAILURE_POLICY", "fail_fast")
+            collected_errors = []
 
             for handler_cls, method_name, condition, priority in hooks:
                 try:
@@ -78,10 +110,10 @@ def run(model_cls, event, new_records, old_records=None, ctx=None):
                     )
                     continue
 
-                # Condition filtering per record
+                # Condition filtering per record using the deterministic pairs
                 to_process_new = []
                 to_process_old = []
-                for new_obj, old_obj in zip(new_records, local_old, strict=True):
+                for new_obj, old_obj in pairs:
                     if not condition:
                         to_process_new.append(new_obj)
                         to_process_old.append(old_obj)
@@ -105,21 +137,22 @@ def run(model_cls, event, new_records, old_records=None, ctx=None):
                 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,
+                        old_records=to_process_old if any(x is not None for x in to_process_old) else None,
                     )
-                except Exception:
+                except Exception as e:
                     logger.exception(
                         "Error in hook %s.%s", handler_cls.__name__, method_name
                     )
-                    # Re-raise to ensure proper transactional behavior
+                    if failure_policy == "best_effort":
+                        collected_errors.append((f"{handler_cls.__name__}.{method_name}", e))
+                        continue
+                    # fail_fast
                     raise
+
+            if collected_errors:
+                raise AggregatedHookError(collected_errors)
         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.

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/django_bulk_hooks/handler.py

@@ -2,7 +2,7 @@ import logging
 import threading
 from collections import deque
 
-from django_bulk_hooks.registry import get_hooks, register_hook
+from django_bulk_hooks.registry import register_hook
 
 logger = logging.getLogger(__name__)
 
@@ -108,16 +108,11 @@ class Hook(metaclass=HookMeta):
         old_records: list = None,
         **kwargs,
     ) -> None:
-        queue = get_hook_queue()
-        queue.append((cls, event, model, new_records, old_records, kwargs))
-
-        if len(queue) > 1:
-            return  # nested call, will be processed by outermost
-
-        # only outermost handle will process the queue
-        while queue:
-            cls_, event_, model_, new_, old_, kw_ = queue.popleft()
-            cls_._process(event_, model_, new_, old_, **kw_)
+        """
+        Legacy entrypoint; delegate to the unified executor in engine.run.
+        """
+        from django_bulk_hooks.engine import run as run_engine
+        run_engine(model, event, new_records or [], old_records or None, ctx=kwargs.get("ctx"))
 
     @classmethod
     def _process(
@@ -128,52 +123,11 @@ class Hook(metaclass=HookMeta):
         old_records,
         **kwargs,
     ):
-        hook_vars.depth += 1
-        hook_vars.new = new_records
-        hook_vars.old = old_records
-        hook_vars.event = event
-        hook_vars.model = model
-
-        hooks = get_hooks(model, event)
-
-        def _execute():
-            new_local = new_records or []
-            old_local = old_records or []
-            if len(old_local) < len(new_local):
-                old_local += [None] * (len(new_local) - len(old_local))
-
-            for handler_cls, method_name, condition, priority in hooks:
-                if condition is not None:
-                    checks = [
-                        condition.check(n, o) for n, o in zip(new_local, old_local)
-                    ]
-                    if not any(checks):
-                        continue
-
-                handler = handler_cls()
-                method = getattr(handler, method_name)
-
-                try:
-                    method(
-                        new_records=new_local,
-                        old_records=old_local,
-                        **kwargs,
-                    )
-                except Exception:
-                    logger.exception(
-                        "Error in hook %s.%s", handler_cls.__name__, method_name
-                    )
-                    # Re-raise the exception to ensure proper error handling
-                    raise
-
-        try:
-            _execute()
-        finally:
-            hook_vars.new = None
-            hook_vars.old = None
-            hook_vars.event = None
-            hook_vars.model = None
-            hook_vars.depth -= 1
+        """
+        Legacy internal; delegate to engine.run to avoid divergence.
+        """
+        from django_bulk_hooks.engine import run as run_engine
+        run_engine(model, event, new_records or [], old_records or None, ctx=kwargs.get("ctx"))
 
 
 # Create a global Hook instance for context access

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/django_bulk_hooks/models.py

@@ -56,10 +56,11 @@ class HookModelMixin(models.Model):
                 run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
 
     def save(self, *args, bypass_hooks=False, **kwargs):
-        # If bypass_hooks is True, use base manager to avoid triggering hooks
+        # If bypass_hooks is True, call the parent save directly within a bypass context
         if bypass_hooks:
             logger.debug(f"save() called with bypass_hooks=True for {self.__class__.__name__} pk={self.pk}")
-            return self._base_manager.save(self, *args, **kwargs)
+            with HookContext(self.__class__, bypass_hooks=True):
+                return super().save(*args, **kwargs)
 
         # Only create a new transaction if we're not already in one
         # This allows for proper nested transaction handling
@@ -118,9 +119,10 @@ class HookModelMixin(models.Model):
         return self
 
     def delete(self, *args, bypass_hooks=False, **kwargs):
-        # If bypass_hooks is True, use base manager to avoid triggering hooks
+        # If bypass_hooks is True, call the parent delete directly within a bypass context
         if bypass_hooks:
-            return self._base_manager.delete(self, *args, **kwargs)
+            with HookContext(self.__class__, bypass_hooks=True):
+                return super().delete(*args, **kwargs)
 
         # Only create a new transaction if we're not already in one
         # This allows for proper nested transaction handling

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/django_bulk_hooks/registry.py

@@ -1,7 +1,8 @@
 import logging
 import threading
 from collections.abc import Callable
-from typing import Dict, List, Optional, Tuple, Union
+from contextlib import contextmanager
+from typing import Dict, Iterable, Iterator, List, Optional, Tuple, Union
 
 from django_bulk_hooks.priority import Priority
 
@@ -10,6 +11,7 @@ logger = logging.getLogger(__name__)
 # Key: (ModelClass, event)
 # Value: list of tuples (handler_cls, method_name, condition_callable, priority)
 _hooks: Dict[Tuple[type, str], List[Tuple[type, str, Callable, int]]] = {}
+_registration_counter = 0  # secondary stable ordering for tie-breaks
 
 # Registry lock for thread-safety during registration and clearing
 _lock = threading.RLock()
@@ -42,6 +44,8 @@ def register_hook(
     event = str(event)
 
     with _lock:
+        global _registration_counter
+        _registration_counter += 1
         key = (model, event)
         hooks = _hooks.setdefault(key, [])
 
@@ -57,10 +61,11 @@ def register_hook(
             )
             return
 
-        # Add the hook
+        # Add the hook (append preserves registration order)
         hooks.append((handler_cls, method_name, condition, priority))
 
         # Sort by priority (highest numbers execute first)
+        # Stable sort by priority (desc) and then by original registration order (stable append)
         def sort_key(hook_info: Tuple[type, str, Callable, int]) -> int:
             p = hook_info[3]
             return p.value if hasattr(p, "value") else int(p)
@@ -134,3 +139,63 @@ def unregister_hook(model: type, event: str, handler_cls: type, method_name: str
         ]
         if not _hooks[key]:
             del _hooks[key]
+
+
+@contextmanager
+def isolated_registry() -> Iterator[None]:
+    """
+    Context manager that snapshots the hook registry and restores it on exit.
+
+    Useful for tests to avoid global cross-test interference without relying on
+    private state mutation from the outside.
+    """
+    with _lock:
+        snapshot = {k: list(v) for k, v in _hooks.items()}
+    try:
+        yield
+    finally:
+        with _lock:
+            _hooks.clear()
+            _hooks.update({k: list(v) for k, v in snapshot.items()})
+
+
+@contextmanager
+def temporary_hook(
+    model: type,
+    event: str,
+    handler_cls: type,
+    method_name: str,
+    condition: Optional[Callable] = None,
+    priority: Union[int, Priority] = Priority.NORMAL,
+) -> Iterator[None]:
+    """
+    Temporarily register a single hook for the duration of the context.
+
+    Ensures the hook is unregistered even if an exception occurs.
+    """
+    register_hook(model, event, handler_cls, method_name, condition, priority)
+    try:
+        yield
+    finally:
+        unregister_hook(model, event, handler_cls, method_name)
+
+
+@contextmanager
+def temporary_hooks(
+    registrations: Iterable[Tuple[type, str, type, str, Optional[Callable], Union[int, Priority]]]
+) -> Iterator[None]:
+    """
+    Temporarily register multiple hooks for the duration of the context.
+
+    Args:
+        registrations: Iterable of (model, event, handler_cls, method_name, condition, priority)
+    """
+    # Register all
+    for model, event, handler_cls, method_name, condition, priority in registrations:
+        register_hook(model, event, handler_cls, method_name, condition, priority)
+    try:
+        yield
+    finally:
+        # Best-effort unregister all in reverse order
+        for model, event, handler_cls, method_name, _, _ in reversed(list(registrations)):
+            unregister_hook(model, event, handler_cls, method_name)

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.231}/pyproject.toml

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

django_bulk_hooks-0.1.230/django_bulk_hooks/__init__.py

@@ -1,4 +0,0 @@
-from django_bulk_hooks.handler import Hook
-from django_bulk_hooks.manager import BulkHookManager
-
-__all__ = ["BulkHookManager", "Hook"]