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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.1.231
+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.231 → 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.232/django_bulk_hooks/__init__.py

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

{django_bulk_hooks-0.1.231 → 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.232/django_bulk_hooks/decorators.py

@@ -0,0 +1,137 @@
+import inspect
+from functools import wraps
+
+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):
+    """
+    Decorator to annotate a method with multiple hooks hook registrations.
+    If no priority is provided, uses Priority.NORMAL (50).
+    """
+
+    def decorator(fn):
+        if not hasattr(fn, "hooks_hooks"):
+            fn.hooks_hooks = []
+        fn.hooks_hooks.append((model, event, condition, priority))
+        return fn
+
+    return decorator
+
+
+def select_related(*related_fields):
+    """
+    Decorator that preloads related fields in-place on `new_records`, before the hook logic runs.
+
+    - Works with instance methods (resolves `self`)
+    - Avoids replacing model instances
+    - Populates Django's relation cache to avoid extra queries
+    """
+
+    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:
+                raise TypeError(
+                    "@preload_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"@preload_related expects a list of model instances, got {type(new_records)}"
+                )
+
+            if not new_records:
+                return func(*args, **kwargs)
+
+            # Determine which instances actually need preloading
+            model_cls = new_records[0].__class__
+            ids_to_fetch = []
+            for obj in new_records:
+                if obj.pk is None:
+                    continue
+                # if any related field is not already cached on the instance,
+                # mark it for fetching
+                if any(field not in obj._state.fields_cache for field in related_fields):
+                    ids_to_fetch.append(obj.pk)
+
+            fetched = {}
+            if ids_to_fetch:
+                # Use the base manager to avoid recursion
+                fetched = model_cls._base_manager.select_related(*related_fields).in_bulk(ids_to_fetch)
+
+            for obj in new_records:
+                preloaded = fetched.get(obj.pk)
+                if not preloaded:
+                    continue
+                for field in related_fields:
+                    if field in obj._state.fields_cache:
+                        # don't override values that were explicitly set or already loaded
+                        continue
+                    if "." in field:
+                        raise ValueError(
+                            f"@preload_related does not support nested fields like '{field}'"
+                        )
+
+                    try:
+                        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
+                    except FieldDoesNotExist:
+                        continue
+
+                    try:
+                        rel_obj = getattr(preloaded, field)
+                        setattr(obj, field, rel_obj)
+                        obj._state.fields_cache[field] = rel_obj
+                    except AttributeError:
+                        pass
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def bulk_hook(model_cls, event, when=None, priority=None):
+    """
+    Decorator to register a bulk hook for a model.
+    
+    Args:
+        model_cls: The model class to hook into
+        event: The event to hook into (e.g., BEFORE_UPDATE, AFTER_UPDATE)
+        when: Optional condition for when the hook should run
+        priority: Optional priority for hook execution order
+    """
+    def decorator(func):
+        # Create a simple handler class for the function
+        class FunctionHandler:
+            def __init__(self):
+                self.func = func
+            
+            def handle(self, new_instances, original_instances):
+                return self.func(new_instances, original_instances)
+        
+        # Register the hook using the registry
+        register_hook(
+            model=model_cls,
+            event=event,
+            handler_cls=FunctionHandler,
+            method_name='handle',
+            condition=when,
+            priority=priority or DEFAULT_PRIORITY,
+        )
+        return func
+    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