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

django_bulk_hooks-0.1.103.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.1
+Name: django-bulk-hooks
+Version: 0.1.103
+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
+
+## 🚀 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(Hook):
+    @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])
+```
+
+## 🛠 Supported Hook Events
+
+- `BEFORE_CREATE`, `AFTER_CREATE`
+- `BEFORE_UPDATE`, `AFTER_UPDATE`
+- `BEFORE_DELETE`, `AFTER_DELETE`
+
+## 🔄 Lifecycle Events
+
+### Individual Model Operations
+
+The `HookModelMixin` automatically triggers hooks for individual model operations:
+
+```python
+# These will trigger BEFORE_CREATE and AFTER_CREATE hooks
+account = Account.objects.create(balance=100.00)
+account.save()  # for new instances
+
+# These will trigger BEFORE_UPDATE and AFTER_UPDATE hooks
+account.balance = 200.00
+account.save()  # for existing instances
+
+# This will trigger BEFORE_DELETE and AFTER_DELETE hooks
+account.delete()
+```
+
+### Bulk Operations
+
+Bulk operations also trigger the same hooks:
+
+```python
+# Bulk create - triggers BEFORE_CREATE and AFTER_CREATE hooks
+accounts = [
+    Account(balance=100.00),
+    Account(balance=200.00),
+]
+Account.objects.bulk_create(accounts)
+
+# Bulk update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+for account in accounts:
+    account.balance *= 1.1
+Account.objects.bulk_update(accounts, ['balance'])
+
+# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+Account.objects.bulk_delete(accounts)
+```
+
+### Queryset Operations
+
+Queryset operations are also supported:
+
+```python
+# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+Account.objects.update(balance=0.00)
+
+# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+Account.objects.delete()
+```
+
+## 🧠 Why?
+
+Django's `bulk_` methods bypass signals and `save()`. This package fills that gap with:
+
+- Hooks that behave consistently across creates/updates/deletes
+- **NEW**: Individual model lifecycle hooks that work with `save()` and `delete()`
+- Scalable performance via chunking (default 200)
+- Support for `@hook` decorators and centralized hook classes
+- **NEW**: Automatic hook triggering for admin operations and other Django features
+- **NEW**: Proper ordering guarantees for old/new record pairing in hooks (Salesforce-like behavior)
+
+## 📦 Usage Examples
+
+### Individual Model Operations
+
+```python
+# These automatically trigger hooks
+account = Account.objects.create(balance=100.00)
+account.balance = 200.00
+account.save()
+account.delete()
+```
+
+### Bulk Operations
+
+```python
+# These also trigger hooks
+Account.objects.bulk_create(accounts)
+Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_delete(accounts)
+```
+
+### Advanced Hook Usage
+
+```python
+class AdvancedAccountHooks(Hook):
+    @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
+```
+
+### Salesforce-like Ordering Guarantees
+
+The system ensures that `old_records` and `new_records` are always properly paired, regardless of the order in which you pass objects to bulk operations:
+
+```python
+class LoanAccountHooks(Hook):
+    @hook(BEFORE_UPDATE, model=LoanAccount)
+    def validate_account_number(self, new_records, old_records):
+        # old_records[i] always corresponds to new_records[i]
+        for new_account, old_account in zip(new_records, old_records):
+            if old_account.account_number != new_account.account_number:
+                raise ValidationError("Account number cannot be changed")
+
+# This works correctly even with reordered objects:
+accounts = [account1, account2, account3]  # IDs: 1, 2, 3
+reordered = [account3, account1, account2]  # IDs: 3, 1, 2
+
+# The hook will still receive properly paired old/new records
+LoanAccount.objects.bulk_update(reordered, ['balance'])
+```
+
+## 🧩 Integration with Queryable Properties
+
+You can extend from `BulkHookManager` to support formula fields or property querying.
+
+```python
+class MyManager(BulkHookManager, QueryablePropertiesManager):
+    pass
+```
+
+## 📝 License
+
+MIT © 2024 Augend / Konrad Beck
+

django_bulk_hooks-0.1.103.dist-info/RECORD

@@ -0,0 +1,17 @@
+django_bulk_hooks/__init__.py,sha256=uUgpnb9AWjIAcWNpCMqBcOewSnpJjJYH6cjPbQkzoNU,140
+django_bulk_hooks/conditions.py,sha256=mTvlLcttixbXRkTSNZU5VewkPUavbXRuD2BkJbVWMkw,6041
+django_bulk_hooks/constants.py,sha256=3x1H1fSUUNo0DZONN7GUVDuySZctTR-jtByBHmAIX5w,303
+django_bulk_hooks/context.py,sha256=HVDT73uSzvgrOR6mdXTvsBm3hLOgBU8ant_mB7VlFuM,380
+django_bulk_hooks/decorators.py,sha256=tckDcxtOzKCbgvS9QydgeIAWTFDEl-ch3_Q--ruEGdQ,4831
+django_bulk_hooks/engine.py,sha256=3HbgV12JRYIy9IlygHPxZiHnFXj7EwzLyTuJNQeVIoI,1402
+django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
+django_bulk_hooks/handler.py,sha256=xZt8iNdYF-ACz-MnKMY0co6scWINU5V5wC1lyDn844k,4854
+django_bulk_hooks/manager.py,sha256=JkhOw9XbEUt8VpunhUSP0z-NlazIFUWmAesj7H4ge8w,7148
+django_bulk_hooks/models.py,sha256=7RG7GrOdHXFjGVPV4FPRZVNMIHHW-hMCi6hn9LH_hVI,3331
+django_bulk_hooks/priority.py,sha256=HG_2D35nga68lBCZmSXTcplXrjFoRgZFRDOy4ROKonY,376
+django_bulk_hooks/queryset.py,sha256=iet4z-9SKhnresA4FBQbxx9rdYnoaOWbw9LUlGftlP0,1466
+django_bulk_hooks/registry.py,sha256=-mQBizJ06nz_tajZBinViKx_uP2Tbc1tIpTEMv7lwKA,705
+django_bulk_hooks-0.1.103.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
+django_bulk_hooks-0.1.103.dist-info/METADATA,sha256=Y_okaTk73sz_FCHWBOczBT8tzRz-wQJmNzmofLWy3MI,6939
+django_bulk_hooks-0.1.103.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+django_bulk_hooks-0.1.103.dist-info/RECORD,,

django_bulk_hooks-0.1.102.dist-info/METADATA

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

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