django-bulk-hooks 0.1.83__py3-none-any.whl → 0.2.100__py3-none-any.whl

django_bulk_hooks-0.1.83.dist-info/METADATA

@@ -1,228 +0,0 @@
-Metadata-Version: 2.3
-Name: django-bulk-hooks
-Version: 0.1.83
-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.83.dist-info/RECORD

@@ -1,16 +0,0 @@
-django_bulk_hooks/__init__.py,sha256=2PcJ6xz7t7Du0nmLO_5732G6u_oZTygogG0fKESRHHk,1082
-django_bulk_hooks/conditions.py,sha256=cif5R4C_N2HosuYiB03STc2rHb800EJV0Nby-ZPac1s,12460
-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=b1AO8qyl2VMt1CHyefn1Gt1_ARaV80yBZ3mGXsJ9_eA,2021
-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=-V128ACxPAz82ua4jQRFUkjAKtKW4MN5ppz0bHcv5s4,7138
-django_bulk_hooks/models.py,sha256=m_dsCcKX8euGU-aDvlkY-vi5QTsRaXhyT-6EZotYuXM,3813
-django_bulk_hooks/queryset.py,sha256=7lLqhZ-XOYsZ1I3Loxi4Nhz79M8HlTYE413AW8nyeDI,1330
-django_bulk_hooks/registry.py,sha256=Vh78exKYcdZhM27120kQm-iXGOjd_kf9ZUYBZ8eQ2V0,683
-django_bulk_hooks-0.1.83.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
-django_bulk_hooks-0.1.83.dist-info/METADATA,sha256=G6_6NsM-MqUem0Y5fmZz0pktXtmsaIVpglFeBDIv7JM,9051
-django_bulk_hooks-0.1.83.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-django_bulk_hooks-0.1.83.dist-info/RECORD,,