django-bulk-hooks 0.1.98__py3-none-any.whl → 0.1.101__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 preloads related fields in-place on `new_records`, before the hook logic runs.
+    Decorator that marks a hook method to preload related fields.
     
-    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.
+    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.
 
     - Works with instance methods (resolves `self`)
     - Avoids replacing model instances
@@ -37,114 +37,9 @@ def select_related(*related_fields):
     """
 
     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(
-                    "@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
+        # Store the related fields on the function for later access
+        func._select_related_fields = related_fields
+        return func
 
     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 in hooks:
+    for handler_cls, method_name, condition, priority, select_related_fields in hooks:
         # Get or create handler instance from cache
         handler_key = (handler_cls, method_name)
         if handler_key not in _handler_cache:
@@ -52,13 +52,19 @@ 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, original_instances, strict=True):
+            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)
@@ -79,4 +85,54 @@ def run(model_cls, event, new_instances, original_instances=None, ctx=None):
         else:
             # No condition, process all instances
             logger.debug("No condition, processing all instances")
-            func(new_records=new_instances, old_records=original_instances if any(original_instances) else None)
+            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]
+
+    # 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
+
+    # 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
+
+    return instances

django_bulk_hooks/handler.py

@@ -75,6 +75,11 @@ 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,
@@ -82,6 +87,7 @@ class HookMeta(type):
                             method_name=method_name,
                             condition=condition,
                             priority=priority,
+                            select_related_fields=select_related_fields,
                         )
                         HookMeta._registered.add(key)
         return cls
@@ -132,10 +138,17 @@ 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 in hooks:
+            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
+
                 if condition is not None:
                     checks = [
-                        condition.check(n, o) for n, o in zip(new_local, old_local)
+                        condition.check(n, o) for n, o in zip(new_local_with_related, old_local)
                     ]
                     if not any(checks):
                         continue
@@ -157,7 +170,7 @@ class HookHandler(metaclass=HookMeta):
                 try:
                     method(
                         old_records=old_local,
-                        new_records=new_local,
+                        new_records=new_local_with_related,
                         **kwargs,
                     )
                 except Exception:

django_bulk_hooks/models.py

@@ -1,4 +1,8 @@
+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,
@@ -14,9 +18,6 @@ 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
@@ -26,7 +27,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:
@@ -35,7 +36,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:
@@ -63,7 +64,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
@@ -80,7 +81,9 @@ 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__)
@@ -91,27 +94,40 @@ class HookModelMixin(models.Model):
         is_create = self.pk is None
         ctx = HookContext(self.__class__)
 
-        # Let Django save first to handle form validation
-        super().save(*args, **kwargs)
-
-        # Then run our hooks with the validated data
+        # Run BEFORE hooks before saving to allow field modifications
         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)
-                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__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx)
+                    run(
+                        self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx
+                    )
                     run(self.__class__, BEFORE_UPDATE, [self], [old_instance], ctx=ctx)
-                    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__, 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
+                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__, AFTER_UPDATE, [self], [old_instance], ctx=ctx)
+                except self.__class__.DoesNotExist:
+                    # If the old instance doesn't exist, treat as create
                     run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
 
         return self
@@ -125,5 +141,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]]] = {}
+_hooks: dict[tuple[type, str], list[tuple[type, str, Callable, int, tuple]]] = {}
 
 
 def register_hook(
-    model, event, handler_cls, method_name, condition, priority: Union[int, Priority]
+    model, event, handler_cls, method_name, condition, priority: Union[int, Priority], select_related_fields=None
 ):
     key = (model, event)
     hooks = _hooks.setdefault(key, [])
-    hooks.append((handler_cls, method_name, condition, priority))
+    hooks.append((handler_cls, method_name, condition, priority, select_related_fields))
     # keep sorted by priority
     hooks.sort(key=lambda x: x[3])
 

django_bulk_hooks-0.1.101.dist-info/METADATA

@@ -0,0 +1,295 @@
+Metadata-Version: 2.1
+Name: django-bulk-hooks
+Version: 0.1.101
+Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
+Home-page: https://github.com/AugendLimited/django-bulk-hooks
+License: MIT
+Keywords: django,bulk,hooks
+Author: Konrad Beck
+Author-email: konrad.beck@merchantcapital.co.za
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: Django (>=4.0)
+Project-URL: Repository, https://github.com/AugendLimited/django-bulk-hooks
+Description-Content-Type: text/markdown
+
+
+# django-bulk-hooks
+
+⚡ Bulk hooks for Django bulk operations and individual model lifecycle events.
+
+`django-bulk-hooks` brings a declarative, hook-like experience to Django's `bulk_create`, `bulk_update`, and `bulk_delete` — including support for `BEFORE_` and `AFTER_` hooks, conditions, batching, and transactional safety. It also provides comprehensive lifecycle hooks for individual model operations.
+
+## ✨ Features
+
+- Declarative hook system: `@hook(AFTER_UPDATE, condition=...)`
+- BEFORE/AFTER hooks for create, update, delete
+- Hook-aware manager that wraps Django's `bulk_` operations
+- **NEW**: `HookModelMixin` for individual model lifecycle events
+- Hook chaining, hook deduplication, and atomicity
+- Class-based hook handlers with DI support
+- Support for both bulk and individual model operations
+- **NEW**: Safe handling of related objects to prevent `RelatedObjectDoesNotExist` errors
+- **NEW**: `@select_related` decorator to prevent queries in loops
+
+## 🚀 Quickstart
+
+```bash
+pip install django-bulk-hooks
+```
+
+### Define Your Model
+
+```python
+from django.db import models
+from django_bulk_hooks.models import HookModelMixin
+
+class Account(HookModelMixin):
+    balance = models.DecimalField(max_digits=10, decimal_places=2)
+    # The HookModelMixin automatically provides BulkHookManager
+```
+
+### Create a Hook Handler
+
+```python
+from django_bulk_hooks import hook, AFTER_UPDATE, select_related
+from django_bulk_hooks.conditions import WhenFieldHasChanged
+from .models import Account
+
+class AccountHandler:
+    @hook(AFTER_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    @select_related("user")  # Preload user to prevent queries in loops
+    def notify_balance_change(self, new_records, old_records):
+        for account in new_records:
+            # This won't cause a query since user is preloaded
+            user_email = account.user.email
+            self.send_notification(user_email, account.balance)
+```
+
+## 🔧 Using `@select_related` to Prevent Queries in Loops
+
+The `@select_related` decorator is essential when your hook logic needs to access related objects. Without it, you might end up with N+1 query problems.
+
+### ❌ Without `@select_related` (causes queries in loops)
+
+```python
+@hook(AFTER_CREATE, model=LoanAccount)
+def process_accounts(self, new_records, old_records):
+    for account in new_records:
+        # ❌ This causes a query for each account!
+        status_name = account.status.name
+        if status_name == "ACTIVE":
+            self.activate_account(account)
+```
+
+### ✅ With `@select_related` (bulk loads related objects)
+
+```python
+@hook(AFTER_CREATE, model=LoanAccount)
+@select_related("status")  # Bulk load status objects
+def process_accounts(self, new_records, old_records):
+    for account in new_records:
+        # ✅ No query here - status is preloaded
+        status_name = account.status.name
+        if status_name == "ACTIVE":
+            self.activate_account(account)
+```
+
+### Multiple Related Fields
+
+```python
+@hook(AFTER_UPDATE, model=Transaction)
+@select_related("account", "category", "status")
+def process_transactions(self, new_records, old_records):
+    for transaction in new_records:
+        # All related objects are preloaded - no queries in loops
+        account_name = transaction.account.name
+        category_type = transaction.category.type
+        status_name = transaction.status.name
+        
+        if status_name == "COMPLETE":
+            self.process_complete_transaction(transaction)
+```
+
+### Your Original Example (Fixed)
+
+```python
+@hook(BEFORE_CREATE, model=LoanAccount, condition=IsEqual("status.name", value=Status.ACTIVE.value))
+@hook(
+    BEFORE_UPDATE,
+    model=LoanAccount,
+    condition=HasChanged("status", has_changed=True) & IsEqual("status.name", value=Status.ACTIVE.value),
+    priority=Priority.HIGH,
+)
+@select_related("status")  # This ensures status is preloaded
+def _set_activated_date(self, old_records: list[LoanAccount], new_records: list[LoanAccount], **kwargs) -> None:
+    logger.info(f"Setting activated date for {new_records}")
+    # No queries in loops - status objects are preloaded
+    self._loan_account_service.set_activated_date(new_records)
+```
+
+## 🛡️ Safe Handling of Related Objects
+
+Use the `safe_get_related_attr` utility function to safely access related object attributes:
+
+```python
+from django_bulk_hooks.conditions import safe_get_related_attr
+
+# ✅ SAFE: Use safe_get_related_attr to handle None values
+@hook(AFTER_CREATE, model=Transaction)
+def process_transaction(self, new_records, old_records):
+    for transaction in new_records:
+        # Safely get the status name, returns None if status doesn't exist
+        status_name = safe_get_related_attr(transaction, 'status', 'name')
+        
+        if status_name == "COMPLETE":
+            # Process the transaction
+            pass
+        elif status_name is None:
+            # Handle case where status is not set
+            print(f"Transaction {transaction.id} has no status")
+```
+
+### Complete Example
+
+```python
+from django.db import models
+from django_bulk_hooks import hook, select_related
+from django_bulk_hooks.conditions import safe_get_related_attr
+
+class Status(models.Model):
+    name = models.CharField(max_length=50)
+
+class Transaction(HookModelMixin, models.Model):
+    amount = models.DecimalField(max_digits=10, decimal_places=2)
+    status = models.ForeignKey(Status, on_delete=models.CASCADE, null=True, blank=True)
+    category = models.ForeignKey('Category', on_delete=models.CASCADE, null=True, blank=True)
+
+class TransactionHandler:
+    @hook(Transaction, "before_create")
+    def set_default_status(self, new_records, old_records=None):
+        """Set default status for new transactions."""
+        default_status = Status.objects.filter(name="PENDING").first()
+        for transaction in new_records:
+            if transaction.status is None:
+                transaction.status = default_status
+    
+    @hook(Transaction, "after_create")
+    @select_related("status", "category")  # Preload related objects
+    def process_transactions(self, new_records, old_records=None):
+        """Process transactions based on their status."""
+        for transaction in new_records:
+            # ✅ SAFE: Get status name safely (no queries in loops)
+            status_name = safe_get_related_attr(transaction, 'status', 'name')
+            
+            if status_name == "COMPLETE":
+                self._process_complete_transaction(transaction)
+            elif status_name == "FAILED":
+                self._process_failed_transaction(transaction)
+            elif status_name is None:
+                print(f"Transaction {transaction.id} has no status")
+            
+            # ✅ SAFE: Check for related object existence (no queries in loops)
+            category = safe_get_related_attr(transaction, 'category')
+            if category:
+                print(f"Transaction {transaction.id} belongs to category: {category.name}")
+    
+    def _process_complete_transaction(self, transaction):
+        # Process complete transaction logic
+        pass
+    
+    def _process_failed_transaction(self, transaction):
+        # Process failed transaction logic
+        pass
+```
+
+### Best Practices for Related Objects
+
+1. **Always use `@select_related`** when accessing related object attributes in hooks
+2. **Use `safe_get_related_attr`** for safe access to related object attributes
+3. **Set default values in `BEFORE_CREATE` hooks** to ensure related objects exist
+4. **Handle None cases explicitly** to avoid unexpected behavior
+5. **Use bulk operations efficiently** by fetching related objects once and reusing them
+
+## 🔍 Performance Tips
+
+### Monitor Query Count
+
+```python
+from django.db import connection, reset_queries
+
+# Before your bulk operation
+reset_queries()
+
+# Your bulk operation
+accounts = Account.objects.bulk_create(account_list)
+
+# After your bulk operation
+print(f"Total queries: {len(connection.queries)}")
+```
+
+### Use `@select_related` Strategically
+
+```python
+# Only select_related fields you actually use
+@select_related("status")  # Good - only what you need
+@select_related("status", "category", "user", "account")  # Only if you use all of them
+```
+
+### Avoid Nested Loops with Related Objects
+
+```python
+# ❌ Bad - nested loops with related objects
+@hook(AFTER_CREATE, model=Order)
+def process_orders(self, new_records, old_records):
+    for order in new_records:
+        for item in order.items.all():  # This causes queries!
+            process_item(item)
+
+# ✅ Good - use prefetch_related for many-to-many/one-to-many
+@hook(AFTER_CREATE, model=Order)
+@select_related("customer")
+def process_orders(self, new_records, old_records):
+    # Prefetch items for all orders at once
+    from django.db.models import Prefetch
+    orders_with_items = Order.objects.prefetch_related(
+        Prefetch('items', queryset=Item.objects.select_related('product'))
+    ).filter(id__in=[order.id for order in new_records])
+    
+    for order in orders_with_items:
+        for item in order.items.all():  # No queries here
+            process_item(item)
+```
+
+## 📚 API Reference
+
+### Decorators
+
+- `@hook(event, model, condition=None, priority=DEFAULT_PRIORITY)` - Register a hook
+- `@select_related(*fields)` - Preload related fields to prevent queries in loops
+
+### Conditions
+
+- `IsEqual(field, value)` - Check if field equals value
+- `HasChanged(field, has_changed=True)` - Check if field has changed
+- `safe_get_related_attr(instance, field, attr=None)` - Safely get related object attributes
+
+### Events
+
+- `BEFORE_CREATE`, `AFTER_CREATE`
+- `BEFORE_UPDATE`, `AFTER_UPDATE`
+- `BEFORE_DELETE`, `AFTER_DELETE`
+- `VALIDATE_CREATE`, `VALIDATE_UPDATE`, `VALIDATE_DELETE`
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

django_bulk_hooks-0.1.101.dist-info/RECORD

@@ -0,0 +1,16 @@
+django_bulk_hooks/__init__.py,sha256=EAWve4HjrrIuPbl8uc1s1ISDM3RPDtwCvTOPRwFpX8w,1392
+django_bulk_hooks/conditions.py,sha256=wDtY90Kv3xjWx8HEA4aAjva8fDDaYegJhn0Eu6G0F60,12150
+django_bulk_hooks/constants.py,sha256=3x1H1fSUUNo0DZONN7GUVDuySZctTR-jtByBHmAIX5w,303
+django_bulk_hooks/context.py,sha256=HVDT73uSzvgrOR6mdXTvsBm3hLOgBU8ant_mB7VlFuM,380
+django_bulk_hooks/decorators.py,sha256=_bTcC4zJiRjpJIMBhjZbuTsqeR0y4GAQ70EJvp8Q0wU,2517
+django_bulk_hooks/engine.py,sha256=T3vIrYDRfGLr6GQfDwwlQQKpEGzsCfCca012DfPl7Z4,6137
+django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
+django_bulk_hooks/handler.py,sha256=1viPTjT9U-5rUPETOtyGHp_UaSPNxVoSYhbBwIHigy8,6076
+django_bulk_hooks/manager.py,sha256=DcVosEA4RS79KSYgw3Z14_a9Sd8CfxNNc5F3eSb8xc0,11459
+django_bulk_hooks/models.py,sha256=U5nCxingZS2sznDjgW8fWo93SisA03WKcGpxxApqhuM,5519
+django_bulk_hooks/queryset.py,sha256=7lLqhZ-XOYsZ1I3Loxi4Nhz79M8HlTYE413AW8nyeDI,1330
+django_bulk_hooks/registry.py,sha256=MY-JOuDphsxay9GHqpZGY_NHGGkvqaH_8RW5kiStDuI,741
+django_bulk_hooks-0.1.101.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
+django_bulk_hooks-0.1.101.dist-info/METADATA,sha256=UgcHNzW2TURJUzwXHW4bcnDeaPUMh9ySdEl8FnIK8fY,10700
+django_bulk_hooks-0.1.101.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+django_bulk_hooks-0.1.101.dist-info/RECORD,,

django_bulk_hooks-0.1.98.dist-info/METADATA

@@ -1,391 +0,0 @@
-Metadata-Version: 2.1
-Name: django-bulk-hooks
-Version: 0.1.98
-Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
-Home-page: https://github.com/AugendLimited/django-bulk-hooks
-License: MIT
-Keywords: django,bulk,hooks
-Author: Konrad Beck
-Author-email: konrad.beck@merchantcapital.co.za
-Requires-Python: >=3.11,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: Django (>=4.0)
-Project-URL: Repository, https://github.com/AugendLimited/django-bulk-hooks
-Description-Content-Type: text/markdown
-
-
-# django-bulk-hooks
-
-⚡ Bulk hooks for Django bulk operations and individual model lifecycle events.
-
-`django-bulk-hooks` brings a declarative, hook-like experience to Django's `bulk_create`, `bulk_update`, and `bulk_delete` — including support for `BEFORE_` and `AFTER_` hooks, conditions, batching, and transactional safety. It also provides comprehensive lifecycle hooks for individual model operations.
-
-## ✨ Features
-
-- Declarative hook system: `@hook(AFTER_UPDATE, condition=...)`
-- BEFORE/AFTER hooks for create, update, delete
-- Hook-aware manager that wraps Django's `bulk_` operations
-- **NEW**: `HookModelMixin` for individual model lifecycle events
-- Hook chaining, hook deduplication, and atomicity
-- Class-based hook handlers with DI support
-- Support for both bulk and individual model operations
-- **NEW**: Safe handling of related objects to prevent `RelatedObjectDoesNotExist` errors
-
-## 🚀 Quickstart
-
-```bash
-pip install django-bulk-hooks
-```
-
-### Define Your Model
-
-```python
-from django.db import models
-from django_bulk_hooks.models import HookModelMixin
-
-class Account(HookModelMixin):
-    balance = models.DecimalField(max_digits=10, decimal_places=2)
-    # The HookModelMixin automatically provides BulkHookManager
-```
-
-### Create a Hook Handler
-
-```python
-from django_bulk_hooks import hook, AFTER_UPDATE, Hook
-from django_bulk_hooks.conditions import WhenFieldHasChanged
-from .models import Account
-
-class AccountHooks(HookHandler):
-    @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])
-```
-
-### Advanced Hook Usage
-
-```python
-class AdvancedAccountHooks(HookHandler):
-    @hook(BEFORE_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
-    def validate_balance_change(self, new_records, old_records):
-        for new_account, old_account in zip(new_records, old_records):
-            if new_account.balance < 0 and old_account.balance >= 0:
-                raise ValueError("Cannot set negative balance")
-    
-    @hook(AFTER_CREATE, model=Account)
-    def send_welcome_email(self, new_records, old_records):
-        for account in new_records:
-            # Send welcome email logic here
-            pass
-```
-
-## 🔒 Safely Handling Related Objects
-
-One of the most common issues when working with hooks is the `RelatedObjectDoesNotExist` exception. This occurs when you try to access a related object that doesn't exist or hasn't been saved yet.
-
-### The Problem
-
-```python
-# ❌ DANGEROUS: This can raise RelatedObjectDoesNotExist
-@hook(AFTER_CREATE, model=Transaction)
-def process_transaction(self, new_records, old_records):
-    for transaction in new_records:
-        # This will fail if transaction.status is None or doesn't exist
-        if transaction.status.name == "COMPLETE":
-            # Process the transaction
-            pass
-```
-
-### The Solution
-
-Use the `safe_get_related_attr` utility function to safely access related object attributes:
-
-```python
-from django_bulk_hooks.conditions import safe_get_related_attr
-
-# ✅ SAFE: Use safe_get_related_attr to handle None values
-@hook(AFTER_CREATE, model=Transaction)
-def process_transaction(self, new_records, old_records):
-    for transaction in new_records:
-        # Safely get the status name, returns None if status doesn't exist
-        status_name = safe_get_related_attr(transaction, 'status', 'name')
-        
-        if status_name == "COMPLETE":
-            # Process the transaction
-            pass
-        elif status_name is None:
-            # Handle case where status is not set
-            print(f"Transaction {transaction.id} has no status")
-```
-
-### Complete Example
-
-```python
-from django.db import models
-from django_bulk_hooks import hook
-from django_bulk_hooks.conditions import safe_get_related_attr
-
-class Status(models.Model):
-    name = models.CharField(max_length=50)
-
-class Transaction(HookModelMixin, models.Model):
-    amount = models.DecimalField(max_digits=10, decimal_places=2)
-    status = models.ForeignKey(Status, on_delete=models.CASCADE, null=True, blank=True)
-    category = models.ForeignKey('Category', on_delete=models.CASCADE, null=True, blank=True)
-
-class TransactionHandler:
-    @hook(Transaction, "before_create")
-    def set_default_status(self, new_records, old_records=None):
-        """Set default status for new transactions."""
-        default_status = Status.objects.filter(name="PENDING").first()
-        for transaction in new_records:
-            if transaction.status is None:
-                transaction.status = default_status
-    
-    @hook(Transaction, "after_create")
-    def process_transactions(self, new_records, old_records=None):
-        """Process transactions based on their status."""
-        for transaction in new_records:
-            # ✅ SAFE: Get status name safely
-            status_name = safe_get_related_attr(transaction, 'status', 'name')
-            
-            if status_name == "COMPLETE":
-                self._process_complete_transaction(transaction)
-            elif status_name == "FAILED":
-                self._process_failed_transaction(transaction)
-            elif status_name is None:
-                print(f"Transaction {transaction.id} has no status")
-            
-            # ✅ SAFE: Check for related object existence
-            category = safe_get_related_attr(transaction, 'category')
-            if category:
-                print(f"Transaction {transaction.id} belongs to category: {category.name}")
-    
-    def _process_complete_transaction(self, transaction):
-        # Process complete transaction logic
-        pass
-    
-    def _process_failed_transaction(self, transaction):
-        # Process failed transaction logic
-        pass
-```
-
-### Best Practices for Related Objects
-
-1. **Always use `safe_get_related_attr`** when accessing related object attributes in hooks
-2. **Set default values in `BEFORE_CREATE` hooks** to ensure related objects exist
-3. **Handle None cases explicitly** to avoid unexpected behavior
-4. **Use bulk operations efficiently** by fetching related objects once and reusing them
-
-```python
-class EfficientTransactionHandler:
-    @hook(Transaction, "before_create")
-    def prepare_transactions(self, new_records, old_records=None):
-        """Efficiently prepare transactions for bulk creation."""
-        # Get default objects once to avoid multiple queries
-        default_status = Status.objects.filter(name="PENDING").first()
-        default_category = Category.objects.filter(name="GENERAL").first()
-        
-        for transaction in new_records:
-            if transaction.status is None:
-                transaction.status = default_status
-            if transaction.category is None:
-                transaction.category = default_category
-    
-    @hook(Transaction, "after_create")
-    def post_creation_processing(self, new_records, old_records=None):
-        """Process transactions after creation."""
-        # Group by status for efficient processing
-        transactions_by_status = {}
-        
-        for transaction in new_records:
-            status_name = safe_get_related_attr(transaction, 'status', 'name')
-            if status_name not in transactions_by_status:
-                transactions_by_status[status_name] = []
-            transactions_by_status[status_name].append(transaction)
-        
-        # Process each group
-        for status_name, transactions in transactions_by_status.items():
-            if status_name == "COMPLETE":
-                self._batch_process_complete(transactions)
-            elif status_name == "FAILED":
-                self._batch_process_failed(transactions)
-```
-
-This approach ensures your hooks are robust and won't fail due to missing related objects, while also being efficient with database queries.
-
-## 🎯 Lambda Conditions and Anonymous Functions
-
-`django-bulk-hooks` supports using anonymous functions (lambda functions) and custom callables as conditions, giving you maximum flexibility for complex filtering logic.
-
-### Using LambdaCondition
-
-The `LambdaCondition` class allows you to use lambda functions or any callable as a condition:
-
-```python
-from django_bulk_hooks import LambdaCondition
-
-class ProductHandler:
-    # Simple lambda condition
-    @hook(Product, "after_create", condition=LambdaCondition(
-        lambda instance: instance.price > 100
-    ))
-    def handle_expensive_products(self, new_records, old_records):
-        """Handle products with price > 100"""
-        for product in new_records:
-            print(f"Expensive product: {product.name}")
-    
-    # Lambda with multiple conditions
-    @hook(Product, "after_update", condition=LambdaCondition(
-        lambda instance: instance.price > 50 and instance.is_active and instance.stock_quantity > 0
-    ))
-    def handle_available_expensive_products(self, new_records, old_records):
-        """Handle active products with price > 50 and stock > 0"""
-        for product in new_records:
-            print(f"Available expensive product: {product.name}")
-    
-    # Lambda comparing with original instance
-    @hook(Product, "after_update", condition=LambdaCondition(
-        lambda instance, original: original and instance.price > original.price * 1.5
-    ))
-    def handle_significant_price_increases(self, new_records, old_records):
-        """Handle products with >50% price increase"""
-        for new_product, old_product in zip(new_records, old_records):
-            if old_product:
-                increase = ((new_product.price - old_product.price) / old_product.price) * 100
-                print(f"Significant price increase: {new_product.name} +{increase:.1f}%")
-```
-
-### Combining Lambda Conditions with Built-in Conditions
-
-You can combine lambda conditions with built-in conditions using the `&` (AND) and `|` (OR) operators:
-
-```python
-from django_bulk_hooks.conditions import HasChanged, IsEqual
-
-class AdvancedProductHandler:
-    # Combine lambda with built-in conditions
-    @hook(Product, "after_update", condition=(
-        HasChanged("price") & 
-        LambdaCondition(lambda instance: instance.price > 100)
-    ))
-    def handle_expensive_price_changes(self, new_records, old_records):
-        """Handle when expensive products have price changes"""
-        for new_product, old_product in zip(new_records, old_records):
-            print(f"Expensive product price changed: {new_product.name}")
-    
-    # Complex combined conditions
-    @hook(Order, "after_update", condition=(
-        LambdaCondition(lambda instance: instance.status == 'completed') &
-        LambdaCondition(lambda instance, original: original and instance.total_amount > original.total_amount)
-    ))
-    def handle_completed_orders_with_increased_amount(self, new_records, old_records):
-        """Handle completed orders that had amount increases"""
-        for new_order, old_order in zip(new_records, old_records):
-            if old_order:
-                increase = new_order.total_amount - old_order.total_amount
-                print(f"Completed order with amount increase: {new_order.customer_name} +${increase}")
-```
-
-### Custom Condition Classes
-
-For reusable logic, you can create custom condition classes:
-
-```python
-from django_bulk_hooks.conditions import HookCondition
-
-class IsPremiumProduct(HookCondition):
-    def check(self, instance, original_instance=None):
-        return (
-            instance.price > 200 and 
-            instance.rating >= 4.0 and 
-            instance.is_active
-        )
-    
-    def get_required_fields(self):
-        return {'price', 'rating', 'is_active'}
-
-class ProductHandler:
-    @hook(Product, "after_create", condition=IsPremiumProduct())
-    def handle_premium_products(self, new_records, old_records):
-        """Handle premium products"""
-        for product in new_records:
-            print(f"Premium product: {product.name}")
-```
-
-### Lambda Conditions with Required Fields
-
-For optimization, you can specify which fields your lambda condition depends on:
-
-```python
-class OptimizedProductHandler:
-    @hook(Product, "after_update", condition=LambdaCondition(
-        lambda instance: instance.price > 100 and instance.category == 'electronics',
-        required_fields={'price', 'category'}
-    ))
-    def handle_expensive_electronics(self, new_records, old_records):
-        """Handle expensive electronics products"""
-        for product in new_records:
-            print(f"Expensive electronics: {product.name}")
-```
-
-### Best Practices for Lambda Conditions
-
-1. **Keep lambdas simple** - Complex logic should be moved to custom condition classes
-2. **Handle None values** - Always check for None before performing operations
-3. **Specify required fields** - This helps with query optimization
-4. **Use descriptive names** - Make your lambda conditions self-documenting
-5. **Test thoroughly** - Lambda conditions can be harder to debug than named functions
-
-```python
-# ✅ GOOD: Simple, clear lambda
-condition = LambdaCondition(lambda instance: instance.price > 100)
-
-# ✅ GOOD: Handles None values
-condition = LambdaCondition(
-    lambda instance: instance.price is not None and instance.price > 100
-)
-
-# ❌ AVOID: Complex logic in lambda
-condition = LambdaCondition(
-    lambda instance: (
-        instance.price > 100 and 
-        instance.category in ['electronics', 'computers'] and
-        instance.stock_quantity > 0 and
-        instance.rating >= 4.0 and
-        instance.is_active and
-        instance.created_at > datetime.now() - timedelta(days=30)
-    )
-)
-
-# ✅ BETTER: Use custom condition class for complex logic
-class IsRecentExpensiveElectronics(HookCondition):
-    def check(self, instance, original_instance=None):
-        return (
-            instance.price > 100 and 
-            instance.category in ['electronics', 'computers'] and
-            instance.stock_quantity > 0 and
-            instance.rating >= 4.0 and
-            instance.is_active and
-            instance.created_at > datetime.now() - timedelta(days=30)
-        )
-    
-    def get_required_fields(self):
-        return {'price', 'category', 'stock_quantity', 'rating', 'is_active', 'created_at'}
-```
-
-## 🔧 Best Practices for Related Objects
-

django_bulk_hooks-0.1.98.dist-info/RECORD

@@ -1,16 +0,0 @@
-django_bulk_hooks/__init__.py,sha256=EAWve4HjrrIuPbl8uc1s1ISDM3RPDtwCvTOPRwFpX8w,1392
-django_bulk_hooks/conditions.py,sha256=wDtY90Kv3xjWx8HEA4aAjva8fDDaYegJhn0Eu6G0F60,12150
-django_bulk_hooks/constants.py,sha256=3x1H1fSUUNo0DZONN7GUVDuySZctTR-jtByBHmAIX5w,303
-django_bulk_hooks/context.py,sha256=HVDT73uSzvgrOR6mdXTvsBm3hLOgBU8ant_mB7VlFuM,380
-django_bulk_hooks/decorators.py,sha256=zstmb27dKcOHu3Atg7cauewCTzPvUmq03mzVKJRi56o,7230
-django_bulk_hooks/engine.py,sha256=qSBvBel3pBWVE92ZzgKjMn2ceQpA7FMws2uMXes1MkA,3626
-django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
-django_bulk_hooks/handler.py,sha256=tdDolHAJ_Nd7-RT4s9HRyLtM1UWGjRjP1Y_U6Af32Gg,5325
-django_bulk_hooks/manager.py,sha256=DcVosEA4RS79KSYgw3Z14_a9Sd8CfxNNc5F3eSb8xc0,11459
-django_bulk_hooks/models.py,sha256=a9XoGgIG4Sfi_kvGnPBbG2DlvgZDz6Qck4VG-DGqFT0,4981
-django_bulk_hooks/queryset.py,sha256=7lLqhZ-XOYsZ1I3Loxi4Nhz79M8HlTYE413AW8nyeDI,1330
-django_bulk_hooks/registry.py,sha256=Vh78exKYcdZhM27120kQm-iXGOjd_kf9ZUYBZ8eQ2V0,683
-django_bulk_hooks-0.1.98.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
-django_bulk_hooks-0.1.98.dist-info/METADATA,sha256=KLEuzqcEjYRTaH3rhRfoyQIGkbNQwhA0KL1HniVfHzM,15414
-django_bulk_hooks-0.1.98.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-django_bulk_hooks-0.1.98.dist-info/RECORD,,