django-bulk-hooks 0.1.101__py3-none-any.whl → 0.1.102__py3-none-any.whl

django_bulk_hooks/decorators.py

@@ -24,11 +24,11 @@ def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
 
 def select_related(*related_fields):
     """
-    Decorator that marks a hook method to preload related fields.
+    Decorator that preloads related fields in-place on `new_records`, before the hook logic runs.
     
-    This decorator works in conjunction with the hook system to ensure that
-    related fields are bulk-loaded before the hook logic runs, preventing
-    queries in loops.
+    This decorator provides bulk loading for performance when you explicitly need it.
+    If you don't use this decorator, the framework will automatically detect and load
+    foreign keys only when conditions need them, preserving standard Django behavior.
 
     - Works with instance methods (resolves `self`)
     - Avoids replacing model instances
@@ -37,9 +37,114 @@ def select_related(*related_fields):
     """
 
     def decorator(func):
-        # Store the related fields on the function for later access
-        func._select_related_fields = related_fields
-        return 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(
+                    "@select_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"@select_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 = []
+            instances_without_pk = []
+            
+            for obj in new_records:
+                if obj.pk is None:
+                    # For objects without PKs (BEFORE_CREATE), check if foreign key fields are already set
+                    instances_without_pk.append(obj)
+                    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)
+
+            # Load foreign keys for objects with PKs
+            fetched = {}
+            if ids_to_fetch:
+                fetched = model_cls.objects.select_related(*related_fields).in_bulk(ids_to_fetch)
+
+            # Apply loaded foreign keys to objects with PKs
+            for obj in new_records:
+                if obj.pk is None:
+                    continue
+                    
+                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"@select_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
+            
+            # For objects without PKs, ensure foreign key fields are properly set in the cache
+            # This prevents RelatedObjectDoesNotExist when accessing foreign keys
+            for obj in instances_without_pk:
+                for field in related_fields:
+                    if "." in field:
+                        raise ValueError(
+                            f"@select_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
+                    
+                    # Check if the foreign key field is set
+                    fk_field_name = f"{field}_id"
+                    if hasattr(obj, fk_field_name) and getattr(obj, fk_field_name) is not None:
+                        # The foreign key ID is set, so we can try to get the related object safely
+                        rel_obj = safe_get_related_object(obj, field)
+                        if rel_obj is not None:
+                            # Ensure it's cached to prevent future queries
+                            if not hasattr(obj._state, 'fields_cache'):
+                                obj._state.fields_cache = {}
+                            obj._state.fields_cache[field] = rel_obj
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
 
     return decorator
 

django_bulk_hooks/engine.py

@@ -42,7 +42,7 @@ def run(model_cls, event, new_instances, original_instances=None, ctx=None):
         original_instances = [None] * len(new_instances)
 
     # Process all hooks
-    for handler_cls, method_name, condition, priority, select_related_fields in hooks:
+    for handler_cls, method_name, condition, priority in hooks:
         # Get or create handler instance from cache
         handler_key = (handler_cls, method_name)
         if handler_key not in _handler_cache:
@@ -52,87 +52,20 @@ def run(model_cls, event, new_instances, original_instances=None, ctx=None):
         else:
             handler_instance, func = _handler_cache[handler_key]
 
-        # Apply select_related if specified
-        if select_related_fields:
-            new_instances_with_related = _apply_select_related(new_instances, select_related_fields)
-        else:
-            new_instances_with_related = new_instances
-
-        # Filter instances based on condition
-        if condition:
-            to_process_new = []
-            to_process_old = []
-
-            logger.debug(f"Checking condition {condition.__class__.__name__} for {len(new_instances)} instances")
-            for new, original in zip(new_instances_with_related, original_instances, strict=True):
-                logger.debug(f"Checking instance {new.__class__.__name__}(pk={new.pk})")
-                try:
-                    matches = condition.check(new, original)
-                    logger.debug(f"Condition check result: {matches}")
-                    if matches:
-                        to_process_new.append(new)
-                        to_process_old.append(original)
-                except Exception as e:
-                    logger.error(f"Error checking condition: {e}")
-                    raise
-
-            # Only call if we have matching instances
-            if to_process_new:
-                logger.debug(f"Running hook for {len(to_process_new)} matching instances")
-                func(new_records=to_process_new, old_records=to_process_old if any(to_process_old) else None)
-            else:
-                logger.debug("No instances matched condition")
-        else:
-            # No condition, process all instances
-            logger.debug("No condition, processing all instances")
-            func(new_records=new_instances_with_related, old_records=original_instances if any(original_instances) else None)
-
-
-def _apply_select_related(instances, related_fields):
-    """
-    Apply select_related to instances to prevent queries in loops.
-    This function bulk loads related objects and caches them on the instances.
-    """
-    if not instances:
-        return instances
-
-    # Separate instances with and without PKs
-    instances_with_pk = [obj for obj in instances if obj.pk is not None]
-    instances_without_pk = [obj for obj in instances if obj.pk is None]
+        # If no condition, process all instances at once
+        if not condition:
+            func(new_records=new_instances, old_records=original_instances if any(original_instances) else None)
+            continue
 
-    # Bulk load related objects for instances with PKs
-    if instances_with_pk:
-        model_cls = instances_with_pk[0].__class__
-        pks = [obj.pk for obj in instances_with_pk]
-        
-        # Bulk fetch with select_related
-        fetched_instances = model_cls.objects.select_related(*related_fields).in_bulk(pks)
-        
-        # Apply cached related objects to original instances
-        for obj in instances_with_pk:
-            fetched_obj = fetched_instances.get(obj.pk)
-            if fetched_obj:
-                for field in related_fields:
-                    if field not in obj._state.fields_cache:
-                        try:
-                            rel_obj = getattr(fetched_obj, field)
-                            setattr(obj, field, rel_obj)
-                            obj._state.fields_cache[field] = rel_obj
-                        except AttributeError:
-                            pass
+        # For conditional hooks, filter instances first
+        to_process_new = []
+        to_process_old = []
 
-    # Handle instances without PKs (e.g., BEFORE_CREATE)
-    for obj in instances_without_pk:
-        for field in related_fields:
-            # Check if the foreign key field is set
-            fk_field_name = f"{field}_id"
-            if hasattr(obj, fk_field_name) and getattr(obj, fk_field_name) is not None:
-                # The foreign key ID is set, so we can try to get the related object safely
-                rel_obj = safe_get_related_object(obj, field)
-                if rel_obj is not None:
-                    # Ensure it's cached to prevent future queries
-                    if not hasattr(obj._state, 'fields_cache'):
-                        obj._state.fields_cache = {}
-                    obj._state.fields_cache[field] = rel_obj
+        for new, original in zip(new_instances, original_instances, strict=True):
+            if condition.check(new, original):
+                to_process_new.append(new)
+                to_process_old.append(original)
 
-    return instances
+        if to_process_new:
+            # Call the function with keyword arguments
+            func(new_records=to_process_new, old_records=to_process_old if any(to_process_old) else None)

django_bulk_hooks/handler.py

@@ -1,4 +1,3 @@
-import inspect
 import logging
 import threading
 from collections import deque
@@ -75,11 +74,6 @@ class HookMeta(type):
                 for model_cls, event, condition, priority in method.hooks_hooks:
                     key = (model_cls, event, cls, method_name)
                     if key not in HookMeta._registered:
-                        # Check if the method has been decorated with select_related
-                        select_related_fields = getattr(
-                            method, "_select_related_fields", None
-                        )
-
                         register_hook(
                             model=model_cls,
                             event=event,
@@ -87,7 +81,6 @@ class HookMeta(type):
                             method_name=method_name,
                             condition=condition,
                             priority=priority,
-                            select_related_fields=select_related_fields,
                         )
                         HookMeta._registered.add(key)
         return cls
@@ -138,17 +131,10 @@ class HookHandler(metaclass=HookMeta):
             if len(old_local) < len(new_local):
                 old_local += [None] * (len(new_local) - len(old_local))
 
-            for handler_cls, method_name, condition, priority, select_related_fields in hooks:
-                # Apply select_related if specified to prevent queries in loops
-                if select_related_fields:
-                    from django_bulk_hooks.engine import _apply_select_related
-                    new_local_with_related = _apply_select_related(new_local, select_related_fields)
-                else:
-                    new_local_with_related = new_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_with_related, old_local)
+                        condition.check(n, o) for n, o in zip(new_local, old_local)
                     ]
                     if not any(checks):
                         continue
@@ -156,21 +142,10 @@ class HookHandler(metaclass=HookMeta):
                 handler = handler_cls()
                 method = getattr(handler, method_name)
 
-                # Inspect the method signature to determine parameter order
-                import inspect
-
-                sig = inspect.signature(method)
-                params = list(sig.parameters.keys())
-
-                # Remove 'self' from params if it exists
-                if params and params[0] == "self":
-                    params = params[1:]
-
-                # Always call with keyword arguments to make order irrelevant
                 try:
                     method(
+                        new_records=new_local,
                         old_records=old_local,
-                        new_records=new_local_with_related,
                         **kwargs,
                     )
                 except Exception:

django_bulk_hooks/manager.py

@@ -20,7 +20,7 @@ class BulkHookManager(models.Manager):
     # Default chunk sizes - can be overridden per model
     DEFAULT_CHUNK_SIZE = 200
     DEFAULT_RELATED_CHUNK_SIZE = 500  # Higher for related object fetching
-    
+
     def __init__(self):
         super().__init__()
         self._chunk_size = self.DEFAULT_CHUNK_SIZE
@@ -28,11 +28,16 @@ class BulkHookManager(models.Manager):
         self._prefetch_related_fields = set()
         self._select_related_fields = set()
 
-    def configure(self, chunk_size=None, related_chunk_size=None, 
-                 select_related=None, prefetch_related=None):
+    def configure(
+        self,
+        chunk_size=None,
+        related_chunk_size=None,
+        select_related=None,
+        prefetch_related=None,
+    ):
         """
         Configure bulk operation parameters for this manager.
-        
+
         Args:
             chunk_size: Number of objects to process in each bulk operation chunk
             related_chunk_size: Number of objects to fetch in each related object query
@@ -53,24 +58,24 @@ class BulkHookManager(models.Manager):
         Optimized loading of original instances with smart batching and field selection.
         """
         queryset = self.model.objects.filter(pk__in=pks)
-        
-        # Only select specific fields if provided
-        if fields_to_fetch:
-            queryset = queryset.only('pk', *fields_to_fetch)
-            
+
+        # Only select specific fields if provided and not empty
+        if fields_to_fetch and len(fields_to_fetch) > 0:
+            queryset = queryset.only("pk", *fields_to_fetch)
+
         # Apply configured related field optimizations
         if self._select_related_fields:
             queryset = queryset.select_related(*self._select_related_fields)
         if self._prefetch_related_fields:
             queryset = queryset.prefetch_related(*self._prefetch_related_fields)
-            
+
         # Batch load in chunks to avoid memory issues
         all_originals = []
         for i in range(0, len(pks), self._related_chunk_size):
-            chunk_pks = pks[i:i + self._related_chunk_size]
+            chunk_pks = pks[i : i + self._related_chunk_size]
             chunk_originals = list(queryset.filter(pk__in=chunk_pks))
             all_originals.extend(chunk_originals)
-            
+
         return all_originals
 
     def _get_fields_to_fetch(self, objs, fields):
@@ -79,20 +84,51 @@ class BulkHookManager(models.Manager):
         and what's needed for hooks.
         """
         fields_to_fetch = set(fields)
-        
+
         # Add fields needed by registered hooks
         from django_bulk_hooks.registry import get_hooks
-        hooks = get_hooks(self.model, "before_update") + get_hooks(self.model, "after_update")
-        
+
+        hooks = get_hooks(self.model, "before_update") + get_hooks(
+            self.model, "after_update"
+        )
+
         for handler_cls, method_name, condition, _ in hooks:
             if condition:
                 # If there's a condition, we need all fields it might access
                 fields_to_fetch.update(condition.get_required_fields())
-                
-        return fields_to_fetch
+
+        # Filter out fields that don't exist on the model
+        valid_fields = set()
+        invalid_fields = set()
+        for field_name in fields_to_fetch:
+            try:
+                self.model._meta.get_field(field_name)
+                valid_fields.add(field_name)
+            except Exception as e:
+                # Field doesn't exist, skip it
+                invalid_fields.add(field_name)
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.debug(
+                    f"Field '{field_name}' requested by hook condition but doesn't exist on {self.model.__name__}: {e}"
+                )
+                continue
+
+        if invalid_fields:
+            import logging
+            logger = logging.getLogger(__name__)
+            logger.warning(
+                f"Invalid fields requested for {self.model.__name__}: {invalid_fields}. "
+                f"These fields were ignored to prevent errors."
+            )
+
+        return valid_fields
 
     @transaction.atomic
-    def bulk_update(self, objs, fields, bypass_hooks=False, bypass_validation=False, **kwargs):
+    def bulk_update(
+        self, objs, fields, bypass_hooks=False, bypass_validation=False, **kwargs
+    ):
         if not objs:
             return []
 
@@ -106,14 +142,14 @@ class BulkHookManager(models.Manager):
         if not bypass_hooks:
             # Determine which fields we need to fetch
             fields_to_fetch = self._get_fields_to_fetch(objs, fields)
-            
+
             # Load originals efficiently
             pks = [obj.pk for obj in objs if obj.pk is not None]
             originals = self._load_originals_optimized(pks, fields_to_fetch)
-            
+
             # Create a mapping for quick lookup
             original_map = {obj.pk: obj for obj in originals}
-            
+
             # Align originals with new instances
             aligned_originals = [original_map.get(obj.pk) for obj in objs]
 
@@ -135,7 +171,7 @@ class BulkHookManager(models.Manager):
 
         # Process in chunks
         for i in range(0, len(objs), self._chunk_size):
-            chunk = objs[i:i + self._chunk_size]
+            chunk = objs[i : i + self._chunk_size]
             super(models.Manager, self).bulk_update(chunk, fields, **kwargs)
 
         if not bypass_hooks:
@@ -205,30 +241,32 @@ class BulkHookManager(models.Manager):
             # Process validation in chunks to avoid memory issues
             if not bypass_validation:
                 for i in range(0, len(objs), self._chunk_size):
-                    chunk = objs[i:i + self._chunk_size]
+                    chunk = objs[i : i + self._chunk_size]
                     engine.run(model_cls, VALIDATE_CREATE, chunk, ctx=ctx)
 
             # Process before_create hooks in chunks
             for i in range(0, len(objs), self._chunk_size):
-                chunk = objs[i:i + self._chunk_size]
+                chunk = objs[i : i + self._chunk_size]
                 engine.run(model_cls, BEFORE_CREATE, chunk, ctx=ctx)
 
         # Perform bulk create in chunks
         for i in range(0, len(objs), self._chunk_size):
-            chunk = objs[i:i + self._chunk_size]
+            chunk = objs[i : i + self._chunk_size]
             created_chunk = super(models.Manager, self).bulk_create(chunk, **kwargs)
             result.extend(created_chunk)
 
         if not bypass_hooks:
             # Process after_create hooks in chunks
             for i in range(0, len(result), self._chunk_size):
-                chunk = result[i:i + self._chunk_size]
+                chunk = result[i : i + self._chunk_size]
                 engine.run(model_cls, AFTER_CREATE, chunk, ctx=ctx)
 
         return result
 
     @transaction.atomic
-    def bulk_delete(self, objs, batch_size=None, bypass_hooks=False, bypass_validation=False):
+    def bulk_delete(
+        self, objs, batch_size=None, bypass_hooks=False, bypass_validation=False
+    ):
         if not objs:
             return []
 
@@ -245,8 +283,8 @@ class BulkHookManager(models.Manager):
         if not bypass_hooks:
             # Process hooks in chunks
             for i in range(0, len(objs), chunk_size):
-                chunk = objs[i:i + chunk_size]
-                
+                chunk = objs[i : i + chunk_size]
+
                 if not bypass_validation:
                     engine.run(model_cls, VALIDATE_DELETE, chunk, ctx=ctx)
                 engine.run(model_cls, BEFORE_DELETE, chunk, ctx=ctx)
@@ -254,13 +292,13 @@ class BulkHookManager(models.Manager):
         # Collect PKs and delete in chunks
         pks = [obj.pk for obj in objs if obj.pk is not None]
         for i in range(0, len(pks), chunk_size):
-            chunk_pks = pks[i:i + chunk_size]
+            chunk_pks = pks[i : i + chunk_size]
             model_cls._base_manager.filter(pk__in=chunk_pks).delete()
 
         if not bypass_hooks:
             # Process after_delete hooks in chunks
             for i in range(0, len(objs), chunk_size):
-                chunk = objs[i:i + chunk_size]
+                chunk = objs[i : i + chunk_size]
                 engine.run(model_cls, AFTER_DELETE, chunk, ctx=ctx)
 
         return objs

django_bulk_hooks/models.py

@@ -1,8 +1,4 @@
-import contextlib
-from functools import wraps
-
 from django.db import models, transaction
-from django.db.models.fields.related_descriptors import ForwardManyToOneDescriptor
 
 from django_bulk_hooks.constants import (
     AFTER_CREATE,
@@ -18,6 +14,9 @@ from django_bulk_hooks.constants import (
 from django_bulk_hooks.context import HookContext
 from django_bulk_hooks.engine import run
 from django_bulk_hooks.manager import BulkHookManager
+from django.db.models.fields.related_descriptors import ForwardManyToOneDescriptor
+from functools import wraps
+import contextlib
 
 
 @contextlib.contextmanager
@@ -27,7 +26,7 @@ def patch_foreign_key_behavior():
     RelatedObjectDoesNotExist when accessing an unset foreign key field.
     """
     original_get = ForwardManyToOneDescriptor.__get__
-
+    
     @wraps(original_get)
     def safe_get(self, instance, cls=None):
         if instance is None:
@@ -36,7 +35,7 @@ def patch_foreign_key_behavior():
             return original_get(self, instance, cls)
         except self.RelatedObjectDoesNotExist:
             return None
-
+    
     # Patch the descriptor
     ForwardManyToOneDescriptor.__get__ = safe_get
     try:
@@ -64,7 +63,7 @@ class HookModelMixin(models.Model):
         # Skip hook validation during admin form validation
         # This prevents RelatedObjectDoesNotExist errors when Django hasn't
         # fully set up the object's relationships yet
-        if hasattr(self, "_state") and getattr(self._state, "validating", False):
+        if hasattr(self, '_state') and getattr(self._state, 'validating', False):
             return
 
         # Determine if this is a create or update operation
@@ -81,9 +80,7 @@ class HookModelMixin(models.Model):
                 old_instance = self.__class__.objects.get(pk=self.pk)
                 ctx = HookContext(self.__class__)
                 with patch_foreign_key_behavior():
-                    run(
-                        self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx
-                    )
+                    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__)
@@ -94,40 +91,24 @@ class HookModelMixin(models.Model):
         is_create = self.pk is None
         ctx = HookContext(self.__class__)
 
-        # Run BEFORE hooks before saving to allow field modifications
+        # Use a single context manager for all hooks
         with patch_foreign_key_behavior():
             if is_create:
                 # For create operations
-                run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
                 run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
-            else:
-                # For update operations
-                try:
-                    old_instance = self.__class__.objects.get(pk=self.pk)
-                    run(
-                        self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx
-                    )
-                    run(self.__class__, BEFORE_UPDATE, [self], [old_instance], ctx=ctx)
-                except self.__class__.DoesNotExist:
-                    # If the old instance doesn't exist, treat as create
-                    run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
-                    run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
-
-        # Now let Django save with any modifications from BEFORE hooks
-        super().save(*args, **kwargs)
-
-        # Then run AFTER hooks
-        with patch_foreign_key_behavior():
-            if is_create:
-                # For create operations
+                super().save(*args, **kwargs)
                 run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
             else:
                 # For update operations
                 try:
                     old_instance = self.__class__.objects.get(pk=self.pk)
+                    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
+                    run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
+                    super().save(*args, **kwargs)
                     run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
 
         return self
@@ -141,5 +122,5 @@ class HookModelMixin(models.Model):
             run(self.__class__, BEFORE_DELETE, [self], ctx=ctx)
             result = super().delete(*args, **kwargs)
             run(self.__class__, AFTER_DELETE, [self], ctx=ctx)
-
+            
         return result

django_bulk_hooks/registry.py

@@ -3,15 +3,15 @@ from typing import Union
 
 from django_bulk_hooks.enums import Priority
 
-_hooks: dict[tuple[type, str], list[tuple[type, str, Callable, int, tuple]]] = {}
+_hooks: dict[tuple[type, str], list[tuple[type, str, Callable, int]]] = {}
 
 
 def register_hook(
-    model, event, handler_cls, method_name, condition, priority: Union[int, Priority], select_related_fields=None
+    model, event, handler_cls, method_name, condition, priority: Union[int, Priority]
 ):
     key = (model, event)
     hooks = _hooks.setdefault(key, [])
-    hooks.append((handler_cls, method_name, condition, priority, select_related_fields))
+    hooks.append((handler_cls, method_name, condition, priority))
     # keep sorted by priority
     hooks.sort(key=lambda x: x[3])