django-bulk-hooks 0.1.80__tar.gz → 0.1.81__tar.gz

django_bulk_hooks-0.1.81/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.3
+Name: django-bulk-hooks
+Version: 0.1.81
+Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
+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: Homepage, https://github.com/AugendLimited/django-bulk-hooks
+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.

django_bulk_hooks-0.1.81/README.md

@@ -0,0 +1,209 @@
+
+# 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.

{django_bulk_hooks-0.1.80 → django_bulk_hooks-0.1.81}/django_bulk_hooks/conditions.py

@@ -29,6 +29,81 @@ def safe_get_related_object(instance, field_name):
         return None
 
 
+def safe_get_related_attr(instance, field_name, attr_name=None):
+    """
+    Safely get a related object or its attribute without raising RelatedObjectDoesNotExist.
+    
+    This is particularly useful in hooks where objects might not have their related
+    fields populated yet (e.g., during bulk_create operations).
+    
+    Args:
+        instance: The model instance
+        field_name: The foreign key field name
+        attr_name: Optional attribute name to access on the related object
+    
+    Returns:
+        The related object, the attribute value, or None if not available
+        
+    Example:
+        # Instead of: loan_transaction.status.name (which might fail)
+        # Use: safe_get_related_attr(loan_transaction, 'status', 'name')
+        
+        status_name = safe_get_related_attr(loan_transaction, 'status', 'name')
+        if status_name in {Status.COMPLETE.value, Status.FAILED.value}:
+            # Process the transaction
+            pass
+    """
+    related_obj = safe_get_related_object(instance, field_name)
+    if related_obj is None:
+        return None
+    
+    if attr_name is None:
+        return related_obj
+    
+    return getattr(related_obj, attr_name, None)
+
+
+def safe_get_related_attr_with_fallback(instance, field_name, attr_name=None, fallback_value=None):
+    """
+    Enhanced version of safe_get_related_attr that provides fallback handling.
+    
+    This function is especially useful for bulk operations where related objects
+    might not be fully loaded or might not exist yet.
+    
+    Args:
+        instance: The model instance
+        field_name: The foreign key field name
+        attr_name: Optional attribute name to access on the related object
+        fallback_value: Value to return if the related object or attribute doesn't exist
+    
+    Returns:
+        The related object, the attribute value, or fallback_value if not available
+    """
+    # First try the standard safe access
+    result = safe_get_related_attr(instance, field_name, attr_name)
+    if result is not None:
+        return result
+    
+    # If that fails, try to get the foreign key ID and fetch the object directly
+    fk_field_name = f"{field_name}_id"
+    if hasattr(instance, fk_field_name):
+        fk_id = getattr(instance, fk_field_name)
+        if fk_id is not None:
+            try:
+                # Get the field to determine the related model
+                field = instance._meta.get_field(field_name)
+                if field.is_relation and not field.many_to_many and not field.one_to_many:
+                    # Try to fetch the related object directly
+                    related_obj = field.related_model.objects.get(pk=fk_id)
+                    if attr_name is None:
+                        return related_obj
+                    return getattr(related_obj, attr_name, fallback_value)
+            except (field.related_model.DoesNotExist, AttributeError):
+                pass
+    
+    return fallback_value
+
+
 def resolve_dotted_attr(instance, dotted_path):
     """
     Recursively resolve a dotted attribute path, e.g., "type.category".

{django_bulk_hooks-0.1.80 → django_bulk_hooks-0.1.81}/django_bulk_hooks/engine.py

@@ -3,33 +3,11 @@ import logging
 from django.core.exceptions import ValidationError
 from django.db import models
 from django_bulk_hooks.registry import get_hooks
-from django_bulk_hooks.conditions import safe_get_related_object
+from django_bulk_hooks.conditions import safe_get_related_object, safe_get_related_attr
 
 logger = logging.getLogger(__name__)
 
 
-def safe_get_related_attr(instance, field_name, attr_name=None):
-    """
-    Safely get a related object or its attribute without raising RelatedObjectDoesNotExist.
-    
-    Args:
-        instance: The model instance
-        field_name: The foreign key field name
-        attr_name: Optional attribute name to access on the related object
-    
-    Returns:
-        The related object, the attribute value, or None if not available
-    """
-    related_obj = safe_get_related_object(instance, field_name)
-    if related_obj is None:
-        return None
-    
-    if attr_name is None:
-        return related_obj
-    
-    return getattr(related_obj, attr_name, None)
-
-
 def run(model_cls, event, new_instances, original_instances=None, ctx=None):
     hooks = get_hooks(model_cls, event)
 

{django_bulk_hooks-0.1.80 → django_bulk_hooks-0.1.81}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.1.80"
+version = "0.1.81"
 description = "Hook-style hooks for Django bulk operations like bulk_create and bulk_update."
 authors = ["Konrad Beck <konrad.beck@merchantcapital.co.za>"]
 readme = "README.md"

django_bulk_hooks-0.1.80/PKG-INFO

@@ -1,92 +0,0 @@
-Metadata-Version: 2.3
-Name: django-bulk-hooks
-Version: 0.1.80
-Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
-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: Homepage, https://github.com/AugendLimited/django-bulk-hooks
-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
-
-## 🚀 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
-```

django_bulk_hooks-0.1.80/README.md

@@ -1,73 +0,0 @@
-
-# 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
-
-## 🚀 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
-```