django-bulk-hooks 0.1.98__tar.gz → 0.1.101__tar.gz

django_bulk_hooks-0.1.101/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,275 @@
+
+# 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/django_bulk_hooks/decorators.py

@@ -0,0 +1,76 @@
+import inspect
+from functools import wraps
+
+from django.core.exceptions import FieldDoesNotExist
+from django_bulk_hooks.enums import DEFAULT_PRIORITY
+from django_bulk_hooks.registry import register_hook
+from django_bulk_hooks.engine import safe_get_related_object
+
+
+def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
+    """
+    Decorator to annotate a method with multiple hooks hook registrations.
+    If no priority is provided, uses Priority.NORMAL (50).
+    """
+
+    def decorator(fn):
+        if not hasattr(fn, "hooks_hooks"):
+            fn.hooks_hooks = []
+        fn.hooks_hooks.append((model, event, condition, priority))
+        return fn
+
+    return decorator
+
+
+def select_related(*related_fields):
+    """
+    Decorator that marks a hook method to preload related fields.
+    
+    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
+    - Populates Django's relation cache to avoid extra queries
+    - Provides bulk loading for performance optimization
+    """
+
+    def decorator(func):
+        # Store the related fields on the function for later access
+        func._select_related_fields = related_fields
+        return func
+
+    return decorator
+
+
+def bulk_hook(model_cls, event, when=None, priority=None):
+    """
+    Decorator to register a bulk hook for a model.
+    
+    Args:
+        model_cls: The model class to hook into
+        event: The event to hook into (e.g., BEFORE_UPDATE, AFTER_UPDATE)
+        when: Optional condition for when the hook should run
+        priority: Optional priority for hook execution order
+    """
+    def decorator(func):
+        # Create a simple handler class for the function
+        class FunctionHandler:
+            def __init__(self):
+                self.func = func
+            
+            def handle(self, new_instances, original_instances):
+                return self.func(new_instances, original_instances)
+        
+        # Register the hook using the registry
+        register_hook(
+            model=model_cls,
+            event=event,
+            handler_cls=FunctionHandler,
+            method_name='handle',
+            condition=when,
+            priority=priority or DEFAULT_PRIORITY,
+        )
+        return func
+    return decorator