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

django_bulk_hooks-0.1.102.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.1
+Name: django-bulk-hooks
+Version: 0.1.102
+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.

django_bulk_hooks-0.1.102.dist-info/RECORD

@@ -0,0 +1,16 @@
+django_bulk_hooks/__init__.py,sha256=b5LIO5oWX9ZVITZddma_E_Hosx8Zy9B3_v3z8HmSykg,1132
+django_bulk_hooks/conditions.py,sha256=iCdIrpVciGsmyKgIEjcC0nl_2-mAxay4Tss-ZaenSuY,13735
+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=kWxAggInO8GhmQfSzJrGATAPgnuG7580llpO9NoxHA8,2897
+django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
+django_bulk_hooks/handler.py,sha256=Qpg_zT6SsQiTlhduvzXxPdG6uynjyR2fBjj-R6HZiXI,4861
+django_bulk_hooks/manager.py,sha256=vyIc7ktNbjXCJrqP7SO7lsamBYFrZSCIQBmXSnpK874,12481
+django_bulk_hooks/models.py,sha256=9KvWkmrR0wbTHN6r7-FrSSO9ViS83NvG7iXLBw_iDZs,4793
+django_bulk_hooks/queryset.py,sha256=7lLqhZ-XOYsZ1I3Loxi4Nhz79M8HlTYE413AW8nyeDI,1330
+django_bulk_hooks/registry.py,sha256=Vh78exKYcdZhM27120kQm-iXGOjd_kf9ZUYBZ8eQ2V0,683
+django_bulk_hooks-0.1.102.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
+django_bulk_hooks-0.1.102.dist-info/METADATA,sha256=xpdCGrDTHoLswDQAXL67JvvvUkyEyTkyQfdbRGDiuz8,9040
+django_bulk_hooks-0.1.102.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+django_bulk_hooks-0.1.102.dist-info/RECORD,,

django_bulk_hooks-0.1.101.dist-info/METADATA

@@ -1,295 +0,0 @@
-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

@@ -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=_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,,