django-bulk-hooks 0.1.280__py3-none-any.whl → 0.2.1__py3-none-any.whl

django_bulk_hooks/handler.py

@@ -1,75 +1,68 @@
 import logging
-import threading
-from collections import deque
 
-from django.db import transaction
-
-from django_bulk_hooks.registry import get_hooks, register_hook
+from django_bulk_hooks.registry import register_hook
 
 logger = logging.getLogger(__name__)
 
 
-# Thread-local hook context and hook state
-class HookVars(threading.local):
-    def __init__(self):
-        self.new = None
-        self.old = None
-        self.event = None
-        self.model = None
-        self.depth = 0
-
-
-hook_vars = HookVars()
-
-# Hook queue per thread
-_hook_context = threading.local()
-
-
-def get_hook_queue():
-    if not hasattr(_hook_context, "queue"):
-        _hook_context.queue = deque()
-    return _hook_context.queue
-
-
-class HookContextState:
-    @property
-    def is_before(self):
-        return hook_vars.event.startswith("before_") if hook_vars.event else False
-
-    @property
-    def is_after(self):
-        return hook_vars.event.startswith("after_") if hook_vars.event else False
-
-    @property
-    def is_create(self):
-        return "create" in hook_vars.event if hook_vars.event else False
-
-    @property
-    def is_update(self):
-        return "update" in hook_vars.event if hook_vars.event else False
-
-    @property
-    def new(self):
-        return hook_vars.new
-
-    @property
-    def old(self):
-        return hook_vars.old
+class HookMeta(type):
+    _registered = set()
+    _class_hook_map: dict[
+        type, set[tuple]
+    ] = {}  # Track which hooks belong to which class
 
-    @property
-    def model(self):
-        return hook_vars.model
+    def __new__(mcs, name, bases, namespace):
+        cls = super().__new__(mcs, name, bases, namespace)
+        mcs._register_hooks_for_class(cls)
+        return cls
 
+    @classmethod
+    def _register_hooks_for_class(mcs, cls):
+        """
+        Register hooks for a given class following OOP inheritance semantics.
+
+        - Child classes inherit all parent hook methods
+        - Child overrides replace parent implementations (not add to them)
+        - Child can add new hook methods
+        """
+        from django_bulk_hooks.registry import register_hook, unregister_hook
+
+        # Step 1: Unregister ALL hooks from parent classes in the MRO
+        # This ensures only the most-derived class owns the active hooks,
+        # providing true OOP semantics (overrides replace, others are inherited once).
+        for base in cls.__mro__[1:]:  # Skip cls itself, start from first parent
+            if not isinstance(base, HookMeta):
+                continue
 
-HookContext = HookContextState()
+            if base in mcs._class_hook_map:
+                for model_cls, event, base_cls, method_name in list(
+                    mcs._class_hook_map[base]
+                ):
+                    key = (model_cls, event, base_cls, method_name)
+                    if key in HookMeta._registered:
+                        unregister_hook(model_cls, event, base_cls, method_name)
+                        HookMeta._registered.discard(key)
+                        logger.debug(
+                            f"Unregistered base hook: {base_cls.__name__}.{method_name} "
+                            f"(superseded by {cls.__name__})"
+                        )
 
+        # Step 2: Register all hook methods on this class (including inherited ones)
+        # Walk the MRO to find ALL methods with hook decorators
+        all_hook_methods = {}
+        for klass in reversed(cls.__mro__):  # Start from most base class
+            if not isinstance(klass, HookMeta):
+                continue
+            for method_name, method in klass.__dict__.items():
+                if hasattr(method, "hooks_hooks"):
+                    # Store with method name as key - child methods will override parent
+                    all_hook_methods[method_name] = method
 
-class HookMeta(type):
-    _registered = set()
+        # Step 3: Register all hook methods with THIS class as the handler
+        if cls not in mcs._class_hook_map:
+            mcs._class_hook_map[cls] = set()
 
-    def __new__(mcs, name, bases, namespace):
-        cls = super().__new__(mcs, name, bases, namespace)
-        for method_name, method in namespace.items():
+        for method_name, method in all_hook_methods.items():
             if hasattr(method, "hooks_hooks"):
                 for model_cls, event, condition, priority in method.hooks_hooks:
                     key = (model_cls, event, cls, method_name)
@@ -83,106 +76,40 @@ class HookMeta(type):
                             priority=priority,
                         )
                         HookMeta._registered.add(key)
-        return cls
+                        mcs._class_hook_map[cls].add(key)
+                        logger.debug(
+                            f"Registered hook: {cls.__name__}.{method_name} "
+                            f"for {model_cls.__name__}.{event}"
+                        )
+
+    @classmethod
+    def re_register_all_hooks(mcs):
+        """Re-register all hooks for all existing Hook classes."""
+        # Clear the registered set and class hook map so we can re-register
+        HookMeta._registered.clear()
+        mcs._class_hook_map.clear()
+
+        # Find all Hook classes and re-register their hooks
+        import gc
+
+        registered_classes = set()
+        for obj in gc.get_objects():
+            if isinstance(obj, type) and isinstance(obj, HookMeta):
+                if obj not in registered_classes:
+                    registered_classes.add(obj)
+                    mcs._register_hooks_for_class(obj)
 
 
 class Hook(metaclass=HookMeta):
-    @classmethod
-    def handle(
-        cls,
-        event: str,
-        model: type,
-        *,
-        new_records: list = None,
-        old_records: list = None,
-        **kwargs,
-    ) -> None:
-        queue = get_hook_queue()
-        queue.append((cls, event, model, new_records, old_records, kwargs))
-        logger.debug(f"Added item to queue: {event}, depth: {hook_vars.depth}")
-
-        # If we're already processing hooks (depth > 0), don't process the queue
-        # The outermost call will process the entire queue
-        if hook_vars.depth > 0:
-            logger.debug(f"Depth > 0, returning without processing queue")
-            return
-
-        # Process the entire queue
-        logger.debug(f"Processing queue with {len(queue)} items")
-        while queue:
-            item = queue.popleft()
-            if len(item) == 6:
-                cls_, event_, model_, new_, old_, kw_ = item
-                logger.debug(f"Processing queue item: {event_}")
-                # Call _process on the Hook class, not the calling class
-                Hook._process(event_, model_, new_, old_, **kw_)
-            else:
-                logger.warning(f"Invalid queue item format: {item}")
-                continue
+    """
+    Base class for hook handlers.
 
-    @classmethod
-    def _process(
-        cls,
-        event,
-        model,
-        new_records,
-        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 = sorted(get_hooks(model, event), key=lambda x: x[3])
-        logger.debug(f"Found {len(hooks)} hooks for {event}")
-
-        def _execute():
-            logger.debug(f"Executing {len(hooks)} hooks for {event}")
-            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:
-                logger.debug(f"Processing hook {handler_cls.__name__}.{method_name}")
-                if condition is not None:
-                    checks = [
-                        condition.check(n, o) for n, o in zip(new_local, old_local)
-                    ]
-                    if not any(checks):
-                        logger.debug(f"Condition failed for {handler_cls.__name__}.{method_name}")
-                        continue
-
-                handler = handler_cls()
-                method = getattr(handler, method_name)
-                logger.debug(f"Executing {handler_cls.__name__}.{method_name}")
-
-                try:
-                    method(
-                        new_records=new_local,
-                        old_records=old_local,
-                        **kwargs,
-                    )
-                    logger.debug(f"Successfully executed {handler_cls.__name__}.{method_name}")
-                except Exception:
-                    logger.exception(
-                        "Error in hook %s.%s", handler_cls.__name__, method_name
-                    )
-
-        conn = transaction.get_connection()
-        logger.debug(f"Transaction in_atomic_block: {conn.in_atomic_block}, event: {event}")
-        try:
-            if conn.in_atomic_block and event.startswith("after_"):
-                logger.debug(f"Deferring {event} to on_commit")
-                transaction.on_commit(_execute)
-            else:
-                logger.debug(f"Executing {event} immediately")
-                _execute()
-        finally:
-            hook_vars.new = None
-            hook_vars.old = None
-            hook_vars.event = None
-            hook_vars.model = None
-            hook_vars.depth -= 1
+    Hooks are registered via the @hook decorator and executed by
+    the HookDispatcher. This class serves as a base for all hook
+    handlers and uses HookMeta for automatic registration.
+
+    All hook execution logic has been moved to HookDispatcher for
+    a single, consistent execution path.
+    """
+
+    pass

django_bulk_hooks/helpers.py

@@ -0,0 +1,99 @@
+"""
+Helper functions for building ChangeSets from operation contexts.
+
+These functions eliminate duplication across queryset.py, bulk_operations.py,
+and models.py by providing reusable ChangeSet builders.
+
+NOTE: These helpers are pure changeset builders - they don't fetch data.
+Data fetching is the responsibility of ModelAnalyzer.
+"""
+
+from django_bulk_hooks.changeset import ChangeSet, RecordChange
+
+
+def build_changeset_for_update(
+    model_cls, instances, update_kwargs, old_records_map=None, **meta
+):
+    """
+    Build ChangeSet for update operations.
+
+    Args:
+        model_cls: Django model class
+        instances: List of instances being updated
+        update_kwargs: Dict of fields being updated
+        old_records_map: Optional dict of {pk: old_instance}. If None, no old records.
+        **meta: Additional metadata (e.g., has_subquery=True, lock_records=False)
+
+    Returns:
+        ChangeSet instance ready for dispatcher
+    """
+    if old_records_map is None:
+        old_records_map = {}
+
+    changes = [
+        RecordChange(
+            new, old_records_map.get(new.pk), changed_fields=list(update_kwargs.keys())
+        )
+        for new in instances
+    ]
+
+    operation_meta = {"update_kwargs": update_kwargs}
+    operation_meta.update(meta)
+
+    return ChangeSet(model_cls, changes, "update", operation_meta)
+
+
+def build_changeset_for_create(model_cls, instances, **meta):
+    """
+    Build ChangeSet for create operations.
+
+    Args:
+        model_cls: Django model class
+        instances: List of instances being created
+        **meta: Additional metadata (e.g., batch_size=1000)
+
+    Returns:
+        ChangeSet instance ready for dispatcher
+    """
+    changes = [RecordChange(new, None) for new in instances]
+    return ChangeSet(model_cls, changes, "create", meta)
+
+
+def build_changeset_for_delete(model_cls, instances, **meta):
+    """
+    Build ChangeSet for delete operations.
+
+    For delete, the "new_record" is the object being deleted (current state),
+    and old_record is also the same (or None). This matches Salesforce behavior
+    where Hook.new contains the records being deleted.
+
+    Args:
+        model_cls: Django model class
+        instances: List of instances being deleted
+        **meta: Additional metadata
+
+    Returns:
+        ChangeSet instance ready for dispatcher
+    """
+    changes = [
+        RecordChange(obj, obj)  # new_record and old_record are the same for delete
+        for obj in instances
+    ]
+    return ChangeSet(model_cls, changes, "delete", meta)
+
+
+def dispatch_hooks_for_operation(changeset, event, bypass_hooks=False):
+    """
+    Dispatch hooks for an operation using the dispatcher.
+
+    This is a convenience function that wraps the dispatcher call.
+
+    Args:
+        changeset: ChangeSet instance
+        event: Event name (e.g., 'before_update', 'after_create')
+        bypass_hooks: If True, skip hook execution
+    """
+    from django_bulk_hooks.dispatcher import get_dispatcher
+
+    dispatcher = get_dispatcher()
+    dispatcher.dispatch(changeset, event, bypass_hooks=bypass_hooks)

django_bulk_hooks/manager.py

@@ -1,20 +1,29 @@
 from django.db import models
 
-from django_bulk_hooks.queryset import HookQuerySet, HookQuerySetMixin
+from django_bulk_hooks.queryset import HookQuerySet
 
 
 class BulkHookManager(models.Manager):
+    """
+    Manager that provides hook-aware bulk operations.
+
+    This is a simple facade that returns HookQuerySet,
+    delegating all bulk operations to it.
+    """
+
     def get_queryset(self):
-        # Use super().get_queryset() to let Django and MRO build the queryset
-        # This ensures cooperation with other managers
+        """
+        Return a HookQuerySet for this manager.
+
+        This ensures all bulk operations go through the coordinator.
+        """
         base_queryset = super().get_queryset()
 
-        # If the base queryset already has hook functionality, return it as-is
-        if isinstance(base_queryset, HookQuerySetMixin):
+        # If the base queryset is already a HookQuerySet, return it as-is
+        if isinstance(base_queryset, HookQuerySet):
             return base_queryset
 
         # Otherwise, create a new HookQuerySet with the same parameters
-        # This is much simpler and avoids dynamic class creation issues
         return HookQuerySet(
             model=base_queryset.model,
             query=base_queryset.query,
@@ -50,7 +59,14 @@ class BulkHookManager(models.Manager):
             **kwargs,
         )
 
-    def bulk_update(self, objs, bypass_hooks=False, bypass_validation=False, **kwargs):
+    def bulk_update(
+        self,
+        objs,
+        fields=None,
+        bypass_hooks=False,
+        bypass_validation=False,
+        **kwargs,
+    ):
         """
         Delegate to QuerySet's bulk_update implementation.
         This follows Django's pattern where Manager methods call QuerySet methods.
@@ -59,6 +75,8 @@ class BulkHookManager(models.Manager):
         are not supported by bulk_update and will be ignored with a warning.
         These parameters are only available in bulk_create for UPSERT operations.
         """
+        if fields is not None:
+            kwargs["fields"] = fields
         return self.get_queryset().bulk_update(
             objs,
             bypass_hooks=bypass_hooks,

django_bulk_hooks/models.py

@@ -1,19 +1,7 @@
 import logging
+
 from django.db import models
 
-from django_bulk_hooks.constants import (
-    AFTER_CREATE,
-    AFTER_DELETE,
-    AFTER_UPDATE,
-    BEFORE_CREATE,
-    BEFORE_DELETE,
-    BEFORE_UPDATE,
-    VALIDATE_CREATE,
-    VALIDATE_DELETE,
-    VALIDATE_UPDATE,
-)
-from django_bulk_hooks.context import HookContext
-from django_bulk_hooks.engine import run
 from django_bulk_hooks.manager import BulkHookManager
 
 logger = logging.getLogger(__name__)
@@ -27,9 +15,9 @@ class HookModelMixin(models.Model):
 
     def clean(self, bypass_hooks=False):
         """
-        Override clean() to trigger validation hooks.
+        Override clean() to hook validation hooks.
         This ensures that when Django calls clean() (like in admin forms),
-        it triggers the VALIDATE_* hooks for validation only.
+        it hooks the VALIDATE_* hooks for validation only.
         """
         super().clean()
 
@@ -37,79 +25,52 @@ class HookModelMixin(models.Model):
         if bypass_hooks:
             return
 
-        # Determine if this is a create or update operation
+        # Delegate to coordinator (consistent with save/delete)
         is_create = self.pk is None
-
-        if is_create:
-            # For create operations, run VALIDATE_CREATE hooks for validation
-            ctx = HookContext(self.__class__)
-            run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
-        else:
-            # For update operations, run VALIDATE_UPDATE hooks for validation
-            try:
-                # Use _base_manager to avoid triggering hooks recursively
-                old_instance = self.__class__._base_manager.get(pk=self.pk)
-                ctx = HookContext(self.__class__)
-                run(self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx)
-            except self.__class__.DoesNotExist:
-                # If the old instance doesn't exist, treat as create
-                ctx = HookContext(self.__class__)
-                run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
+        self.__class__.objects.get_queryset().coordinator.clean(
+            [self], is_create=is_create
+        )
 
     def save(self, *args, bypass_hooks=False, **kwargs):
-        # If bypass_hooks is True, use base manager to avoid triggering hooks
+        """
+        Save the model instance.
+
+        Delegates to bulk_create/bulk_update which handle all hook logic
+        including MTI parent hooks.
+        """
         if bypass_hooks:
-            logger.debug(f"save() called with bypass_hooks=True for {self.__class__.__name__} pk={self.pk}")
-            return self.__class__._base_manager.save(self, *args, **kwargs)
+            # Use super().save() to call Django's default save without our hook logic
+            return super().save(*args, **kwargs)
 
         is_create = self.pk is None
 
         if is_create:
-            logger.debug(f"save() creating new {self.__class__.__name__} instance")
-            # For create operations, we don't have old records
-            ctx = HookContext(self.__class__)
-            run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
-
-            super().save(*args, **kwargs)
-
-            run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
+            # Delegate to bulk_create which handles all hook logic
+            result = self.__class__.objects.bulk_create([self])
+            return result[0] if result else self
         else:
-            logger.debug(f"save() updating existing {self.__class__.__name__} instance pk={self.pk}")
-            # For update operations, we need to get the old record
-            try:
-                # Use _base_manager to avoid triggering hooks recursively
-                old_instance = self.__class__._base_manager.get(pk=self.pk)
-                ctx = HookContext(self.__class__)
-                run(self.__class__, BEFORE_UPDATE, [self], [old_instance], ctx=ctx)
-
-                super().save(*args, **kwargs)
-
-                run(self.__class__, AFTER_UPDATE, [self], [old_instance], ctx=ctx)
-            except self.__class__.DoesNotExist:
-                # If the old instance doesn't exist, treat as create
-                ctx = HookContext(self.__class__)
-                run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
-
-                super().save(*args, **kwargs)
-
-                run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
-
-        return self
+            # Delegate to bulk_update which handles all hook logic
+            update_fields = kwargs.get("update_fields")
+            if update_fields is None:
+                # Update all non-auto fields
+                update_fields = [
+                    f.name
+                    for f in self.__class__._meta.fields
+                    if not f.auto_created and f.name != "id"
+                ]
+            self.__class__.objects.bulk_update([self], update_fields)
+            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:
-            return self.__class__._base_manager.delete(self, *args, **kwargs)
-
-        ctx = HookContext(self.__class__)
-
-        # Run validation hooks first
-        run(self.__class__, VALIDATE_DELETE, [self], ctx=ctx)
-
-        # Then run business logic hooks
-        run(self.__class__, BEFORE_DELETE, [self], ctx=ctx)
+        """
+        Delete the model instance.
 
-        result = super().delete(*args, **kwargs)
+        Delegates to bulk_delete which handles all hook logic
+        including MTI parent hooks.
+        """
+        if bypass_hooks:
+            # Use super().delete() to call Django's default delete without our hook logic
+            return super().delete(*args, **kwargs)
 
-        run(self.__class__, AFTER_DELETE, [self], ctx=ctx)
-        return result
+        # Delegate to bulk_delete (handles both MTI and non-MTI)
+        return self.__class__.objects.filter(pk=self.pk).delete()

django_bulk_hooks/operations/__init__.py

@@ -0,0 +1,18 @@
+"""
+Operations module for django-bulk-hooks.
+
+This module contains all services for bulk operations following
+a clean, service-based architecture.
+"""
+
+from django_bulk_hooks.operations.coordinator import BulkOperationCoordinator
+from django_bulk_hooks.operations.analyzer import ModelAnalyzer
+from django_bulk_hooks.operations.bulk_executor import BulkExecutor
+from django_bulk_hooks.operations.mti_handler import MTIHandler
+
+__all__ = [
+    'BulkOperationCoordinator',
+    'ModelAnalyzer',
+    'BulkExecutor',
+    'MTIHandler',
+]