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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.1.230
+Version: 0.1.232
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks
@@ -59,37 +59,21 @@ from django_bulk_hooks.conditions import WhenFieldHasChanged
 from .models import Account
 
 class AccountHooks(Hook):
-    @hook(AFTER_UPDATE, condition=WhenFieldHasChanged('balance'))
-    def _notify_balance_change(self, new_records, old_records, **kwargs):
-        for new_record, old_record in zip(new_records, old_records):
-            if old_record and new_record.balance != old_record.balance:
-                print(f"Balance changed from {old_record.balance} to {new_record.balance}")
-```
-
-### Bulk Operations with Hooks
-
-```python
-# For complete hook execution, use the update() method
-accounts = Account.objects.filter(active=True)
-accounts.update(balance=1000)  # Runs all hooks automatically
-
-# For bulk operations with hooks
-accounts = Account.objects.filter(active=True)
-instances = list(accounts)
-
-# bulk_update now runs complete hook cycle by default
-accounts.bulk_update(instances, ['balance'])  # Runs VALIDATE → BEFORE → DB update → AFTER
-
-# To skip hooks (for performance or when called from update())
-accounts.bulk_update(instances, ['balance'], bypass_hooks=True)
+    @hook(AFTER_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    def log_balance_change(self, new_records, old_records):
+        print("Accounts updated:", [a.pk for a in new_records])
+    
+    @hook(BEFORE_CREATE, model=Account)
+    def before_create(self, new_records, old_records):
+        for account in new_records:
+            if account.balance < 0:
+                raise ValueError("Account cannot have negative balance")
+    
+    @hook(AFTER_DELETE, model=Account)
+    def after_delete(self, new_records, old_records):
+        print("Accounts deleted:", [a.pk for a in old_records])
 ```
 
-### Understanding Hook Execution
-
-- **`update()` method**: Runs complete hook cycle (VALIDATE → BEFORE → DB update → AFTER)
-- **`bulk_update()` method**: Runs complete hook cycle (VALIDATE → BEFORE → DB update → AFTER)
-- **`bypass_hooks=True`**: Skips all hooks for performance or to prevent double execution
-
 ## 🛠 Supported Hook Events
 
 - `BEFORE_CREATE`, `AFTER_CREATE`

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.232}/README.md

@@ -40,37 +40,21 @@ from django_bulk_hooks.conditions import WhenFieldHasChanged
 from .models import Account
 
 class AccountHooks(Hook):
-    @hook(AFTER_UPDATE, condition=WhenFieldHasChanged('balance'))
-    def _notify_balance_change(self, new_records, old_records, **kwargs):
-        for new_record, old_record in zip(new_records, old_records):
-            if old_record and new_record.balance != old_record.balance:
-                print(f"Balance changed from {old_record.balance} to {new_record.balance}")
-```
-
-### Bulk Operations with Hooks
-
-```python
-# For complete hook execution, use the update() method
-accounts = Account.objects.filter(active=True)
-accounts.update(balance=1000)  # Runs all hooks automatically
-
-# For bulk operations with hooks
-accounts = Account.objects.filter(active=True)
-instances = list(accounts)
-
-# bulk_update now runs complete hook cycle by default
-accounts.bulk_update(instances, ['balance'])  # Runs VALIDATE → BEFORE → DB update → AFTER
-
-# To skip hooks (for performance or when called from update())
-accounts.bulk_update(instances, ['balance'], bypass_hooks=True)
+    @hook(AFTER_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    def log_balance_change(self, new_records, old_records):
+        print("Accounts updated:", [a.pk for a in new_records])
+    
+    @hook(BEFORE_CREATE, model=Account)
+    def before_create(self, new_records, old_records):
+        for account in new_records:
+            if account.balance < 0:
+                raise ValueError("Account cannot have negative balance")
+    
+    @hook(AFTER_DELETE, model=Account)
+    def after_delete(self, new_records, old_records):
+        print("Accounts deleted:", [a.pk for a in old_records])
 ```
 
-### Understanding Hook Execution
-
-- **`update()` method**: Runs complete hook cycle (VALIDATE → BEFORE → DB update → AFTER)
-- **`bulk_update()` method**: Runs complete hook cycle (VALIDATE → BEFORE → DB update → AFTER)
-- **`bypass_hooks=True`**: Skips all hooks for performance or to prevent double execution
-
 ## 🛠 Supported Hook Events
 
 - `BEFORE_CREATE`, `AFTER_CREATE`

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.232}/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-0.1.232/django_bulk_hooks/context.py

@@ -0,0 +1,53 @@
+import threading
+from collections import deque
+from django_bulk_hooks.handler import hook_vars
+
+
+_hook_context = threading.local()
+
+
+def get_hook_queue():
+    if not hasattr(_hook_context, "queue"):
+        _hook_context.queue = deque()
+    return _hook_context.queue
+
+
+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():
+    """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
+        set_bypass_hooks(bypass_hooks)
+
+    @property
+    def is_executing(self):
+        """
+        Check if we're currently in a hook execution context.
+        Similar to Salesforce's Trigger.isExecuting.
+        Use this to prevent infinite recursion in hooks.
+        """
+        return hasattr(hook_vars, 'event') and hook_vars.event is not None
+
+    @property
+    def current_event(self):
+        """
+        Get the current hook event being executed.
+        """
+        return getattr(hook_vars, 'event', None)
+
+    @property
+    def execution_depth(self):
+        """
+        Get the current execution depth to detect deep recursion.
+        """
+        return getattr(hook_vars, 'depth', 0)

{django_bulk_hooks-0.1.230 → django_bulk_hooks-0.1.232}/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-0.1.232/django_bulk_hooks/engine.py

@@ -0,0 +1,74 @@
+import logging
+
+from django.core.exceptions import ValidationError
+
+from django_bulk_hooks.registry import get_hooks
+
+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.
+    """
+    if not new_records:
+        return
+
+    # Get hooks for this model and event
+    hooks = get_hooks(model_cls, event)
+
+    if not hooks:
+        return
+
+    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("engine.run bypassed")
+        return
+
+    # For BEFORE_* events, run model.clean() first for validation
+    if event.startswith("before_"):
+        for instance in new_records:
+            try:
+                instance.clean()
+            except ValidationError as e:
+                logger.error("Validation failed for %s: %s", instance, e)
+                raise
+
+    # 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-0.1.232/django_bulk_hooks/enums.py

@@ -0,0 +1,17 @@
+from enum import IntEnum
+
+
+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 = Priority.NORMAL