django-bulk-hooks 0.1.83__py3-none-any.whl → 0.2.100__py3-none-any.whl

django_bulk_hooks/handler.py

@@ -1,167 +1,106 @@
-import logging
-import threading
-from collections import deque
-
-from django.db import transaction
-
-from django_bulk_hooks.registry import get_hooks, 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
-
-    @property
-    def model(self):
-        return hook_vars.model
-
-
-Hook = HookContextState()
-
-
-class HookMeta(type):
-    _registered = set()
-
-    def __new__(mcs, name, bases, namespace):
-        cls = super().__new__(mcs, name, bases, namespace)
-        for method_name, method in namespace.items():
-            if hasattr(method, "hooks_hooks"):
-                for model_cls, event, condition, priority in method.hooks_hooks:
-                    key = (model_cls, event, cls, method_name)
-                    if key not in HookMeta._registered:
-                        register_hook(
-                            model=model_cls,
-                            event=event,
-                            handler_cls=cls,
-                            method_name=method_name,
-                            condition=condition,
-                            priority=priority,
-                        )
-                        HookMeta._registered.add(key)
-        return cls
-
-
-class HookHandler(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))
-
-        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_)
-
-    @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])
-
-        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
-                    )
-
-        conn = transaction.get_connection()
-        try:
-            if conn.in_atomic_block and event.startswith("after_"):
-                transaction.on_commit(_execute)
-            else:
-                _execute()
-        finally:
-            hook_vars.new = None
-            hook_vars.old = None
-            hook_vars.event = None
-            hook_vars.model = None
-            hook_vars.depth -= 1
+import logging
+
+from django_bulk_hooks.registry import register_hook
+
+logger = logging.getLogger(__name__)
+
+
+class HookMeta(type):
+    _registered = set()
+    _class_hook_map: dict[
+        type,
+        set[tuple],
+    ] = {}  # Track which hooks belong to which class
+
+    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 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
+
+            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)
+
+        # 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
+
+        # 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()
+
+        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)
+                    if key not in HookMeta._registered:
+                        register_hook(
+                            model=model_cls,
+                            event=event,
+                            handler_cls=cls,
+                            method_name=method_name,
+                            condition=condition,
+                            priority=priority,
+                        )
+                        HookMeta._registered.add(key)
+                        mcs._class_hook_map[cls].add(key)
+
+    @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):
+    """
+    Base class for hook handlers.
+
+    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.
+    """

django_bulk_hooks/helpers.py

@@ -0,0 +1,258 @@
+"""
+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.
+"""
+
+import logging
+
+from django_bulk_hooks.changeset import ChangeSet
+from django_bulk_hooks.changeset import RecordChange
+
+logger = logging.getLogger(__name__)
+
+
+def extract_pks(objects):
+    """
+    Extract non-None primary keys from objects.
+
+    Args:
+        objects: Iterable of model instances or objects with pk attribute
+
+    Returns:
+        List of non-None primary key values
+    """
+    return [obj.pk for obj in objects if obj.pk is not None]
+
+
+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 = {}
+
+    # Smart pre-computation logic:
+    # - If update_kwargs non-empty and old_records exist: Don't precompute (QuerySet.update case)
+    # - If update_kwargs empty and old_records exist: Don't precompute (upsert case)
+    # - If update_kwargs empty and no old_records: Precompute as empty (validation case)
+    should_precompute = not bool(update_kwargs) and old_records_map is None
+    changed_fields = list(update_kwargs.keys()) if should_precompute else None
+
+    changes = [
+        RecordChange(
+            new,
+            old_records_map.get(new.pk),
+            changed_fields=changed_fields,
+        )
+        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 get_fields_for_model(model_cls, field_names, include_relations=False):
+    """
+    Get field objects for the given model from a list of field names.
+
+    Handles field name normalization (e.g., 'field_id' -> 'field').
+    Only returns fields that actually exist on the model.
+
+    Args:
+        model_cls: Django model class
+        field_names: List of field names (strings)
+        include_relations: Whether to include relation fields (default False)
+
+    Returns:
+        List of field objects that exist on the model, in the same order as field_names
+    """
+    if not field_names:
+        return []
+
+    # Build lookup dict of available fields
+    fields_by_name = {}
+    # Use local_fields for child tables, get_fields() for parent tables that need inherited fields
+    fields_to_check = model_cls._meta.local_fields if not include_relations else model_cls._meta.get_fields()
+    for field in fields_to_check:
+        if not include_relations and (field.many_to_many or field.one_to_many):
+            continue
+        fields_by_name[field.name] = field
+
+    # Handle field name normalization and preserve order
+    result = []
+    seen = set()
+
+    for name in field_names:
+        # Try original name first
+        if name in fields_by_name and name not in seen:
+            result.append(fields_by_name[name])
+            seen.add(name)
+        # Try normalized name (field_id -> field)
+        elif name.endswith("_id") and name[:-3] in fields_by_name and name[:-3] not in seen:
+            result.append(fields_by_name[name[:-3]])
+            seen.add(name[:-3])
+
+    return result
+
+
+def filter_field_names_for_model(model_cls, field_names):
+    """
+    Filter a list of field names to only those that exist on the model.
+
+    Handles field name normalization (e.g., 'field_id' -> 'field').
+
+    Args:
+        model_cls: Django model class
+        field_names: List of field names (strings)
+
+    Returns:
+        List of field names that exist on the model
+    """
+    if not field_names:
+        return []
+
+    # Get all available field names
+    available_names = {field.name for field in model_cls._meta.local_fields}
+
+    result = []
+    for name in field_names:
+        if name in available_names:
+            result.append(name)
+        elif name.endswith("_id") and name[:-3] in available_names:
+            result.append(name[:-3])
+
+    return result
+
+
+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)
+
+
+def tag_upsert_metadata(result_objects, existing_record_ids, existing_pks_map):
+    """
+    Tag objects with metadata indicating whether they were created or updated.
+
+    Args:
+        result_objects: List of objects returned from bulk operation
+        existing_record_ids: Set of id() for objects that existed before
+        existing_pks_map: Dict mapping id(obj) -> pk for existing records
+    """
+    existing_pks = set(existing_pks_map.values())
+
+    created_count = 0
+    updated_count = 0
+
+    for obj in result_objects:
+        # Use PK to determine if this record was created or updated
+        was_created = obj.pk not in existing_pks
+        obj._bulk_hooks_was_created = was_created
+        obj._bulk_hooks_upsert_metadata = True
+
+        if was_created:
+            created_count += 1
+        else:
+            updated_count += 1
+
+    logger.info(
+        f"Tagged upsert metadata: {created_count} created, {updated_count} updated "
+        f"(total={len(result_objects)}, existing_pks={len(existing_pks)})"
+    )
+
+
+def was_created(obj):
+    """Check if an object was created in an upsert operation."""
+    return getattr(obj, "_bulk_hooks_was_created", False)
+
+
+def is_upsert_result(obj):
+    """Check if an object has upsert metadata."""
+    return getattr(obj, "_bulk_hooks_upsert_metadata", False)
+
+
+def cleanup_upsert_metadata(objects):
+    """
+    Clean up upsert metadata after hook execution.
+
+    Args:
+        objects: Objects to clean up
+    """
+    for obj in objects:
+        if hasattr(obj, "_bulk_hooks_was_created"):
+            delattr(obj, "_bulk_hooks_was_created")
+        if hasattr(obj, "_bulk_hooks_upsert_metadata"):
+            delattr(obj, "_bulk_hooks_upsert_metadata")