django-bulk-hooks 0.1.97__tar.gz → 0.1.100__tar.gz

{django_bulk_hooks-0.1.97 → django_bulk_hooks-0.1.100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-bulk-hooks
-Version: 0.1.97
+Version: 0.1.100
 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
@@ -226,3 +226,166 @@ class EfficientTransactionHandler:
 ```
 
 This approach ensures your hooks are robust and won't fail due to missing related objects, while also being efficient with database queries.
+
+## 🎯 Lambda Conditions and Anonymous Functions
+
+`django-bulk-hooks` supports using anonymous functions (lambda functions) and custom callables as conditions, giving you maximum flexibility for complex filtering logic.
+
+### Using LambdaCondition
+
+The `LambdaCondition` class allows you to use lambda functions or any callable as a condition:
+
+```python
+from django_bulk_hooks import LambdaCondition
+
+class ProductHandler:
+    # Simple lambda condition
+    @hook(Product, "after_create", condition=LambdaCondition(
+        lambda instance: instance.price > 100
+    ))
+    def handle_expensive_products(self, new_records, old_records):
+        """Handle products with price > 100"""
+        for product in new_records:
+            print(f"Expensive product: {product.name}")
+    
+    # Lambda with multiple conditions
+    @hook(Product, "after_update", condition=LambdaCondition(
+        lambda instance: instance.price > 50 and instance.is_active and instance.stock_quantity > 0
+    ))
+    def handle_available_expensive_products(self, new_records, old_records):
+        """Handle active products with price > 50 and stock > 0"""
+        for product in new_records:
+            print(f"Available expensive product: {product.name}")
+    
+    # Lambda comparing with original instance
+    @hook(Product, "after_update", condition=LambdaCondition(
+        lambda instance, original: original and instance.price > original.price * 1.5
+    ))
+    def handle_significant_price_increases(self, new_records, old_records):
+        """Handle products with >50% price increase"""
+        for new_product, old_product in zip(new_records, old_records):
+            if old_product:
+                increase = ((new_product.price - old_product.price) / old_product.price) * 100
+                print(f"Significant price increase: {new_product.name} +{increase:.1f}%")
+```
+
+### Combining Lambda Conditions with Built-in Conditions
+
+You can combine lambda conditions with built-in conditions using the `&` (AND) and `|` (OR) operators:
+
+```python
+from django_bulk_hooks.conditions import HasChanged, IsEqual
+
+class AdvancedProductHandler:
+    # Combine lambda with built-in conditions
+    @hook(Product, "after_update", condition=(
+        HasChanged("price") & 
+        LambdaCondition(lambda instance: instance.price > 100)
+    ))
+    def handle_expensive_price_changes(self, new_records, old_records):
+        """Handle when expensive products have price changes"""
+        for new_product, old_product in zip(new_records, old_records):
+            print(f"Expensive product price changed: {new_product.name}")
+    
+    # Complex combined conditions
+    @hook(Order, "after_update", condition=(
+        LambdaCondition(lambda instance: instance.status == 'completed') &
+        LambdaCondition(lambda instance, original: original and instance.total_amount > original.total_amount)
+    ))
+    def handle_completed_orders_with_increased_amount(self, new_records, old_records):
+        """Handle completed orders that had amount increases"""
+        for new_order, old_order in zip(new_records, old_records):
+            if old_order:
+                increase = new_order.total_amount - old_order.total_amount
+                print(f"Completed order with amount increase: {new_order.customer_name} +${increase}")
+```
+
+### Custom Condition Classes
+
+For reusable logic, you can create custom condition classes:
+
+```python
+from django_bulk_hooks.conditions import HookCondition
+
+class IsPremiumProduct(HookCondition):
+    def check(self, instance, original_instance=None):
+        return (
+            instance.price > 200 and 
+            instance.rating >= 4.0 and 
+            instance.is_active
+        )
+    
+    def get_required_fields(self):
+        return {'price', 'rating', 'is_active'}
+
+class ProductHandler:
+    @hook(Product, "after_create", condition=IsPremiumProduct())
+    def handle_premium_products(self, new_records, old_records):
+        """Handle premium products"""
+        for product in new_records:
+            print(f"Premium product: {product.name}")
+```
+
+### Lambda Conditions with Required Fields
+
+For optimization, you can specify which fields your lambda condition depends on:
+
+```python
+class OptimizedProductHandler:
+    @hook(Product, "after_update", condition=LambdaCondition(
+        lambda instance: instance.price > 100 and instance.category == 'electronics',
+        required_fields={'price', 'category'}
+    ))
+    def handle_expensive_electronics(self, new_records, old_records):
+        """Handle expensive electronics products"""
+        for product in new_records:
+            print(f"Expensive electronics: {product.name}")
+```
+
+### Best Practices for Lambda Conditions
+
+1. **Keep lambdas simple** - Complex logic should be moved to custom condition classes
+2. **Handle None values** - Always check for None before performing operations
+3. **Specify required fields** - This helps with query optimization
+4. **Use descriptive names** - Make your lambda conditions self-documenting
+5. **Test thoroughly** - Lambda conditions can be harder to debug than named functions
+
+```python
+# ✅ GOOD: Simple, clear lambda
+condition = LambdaCondition(lambda instance: instance.price > 100)
+
+# ✅ GOOD: Handles None values
+condition = LambdaCondition(
+    lambda instance: instance.price is not None and instance.price > 100
+)
+
+# ❌ AVOID: Complex logic in lambda
+condition = LambdaCondition(
+    lambda instance: (
+        instance.price > 100 and 
+        instance.category in ['electronics', 'computers'] and
+        instance.stock_quantity > 0 and
+        instance.rating >= 4.0 and
+        instance.is_active and
+        instance.created_at > datetime.now() - timedelta(days=30)
+    )
+)
+
+# ✅ BETTER: Use custom condition class for complex logic
+class IsRecentExpensiveElectronics(HookCondition):
+    def check(self, instance, original_instance=None):
+        return (
+            instance.price > 100 and 
+            instance.category in ['electronics', 'computers'] and
+            instance.stock_quantity > 0 and
+            instance.rating >= 4.0 and
+            instance.is_active and
+            instance.created_at > datetime.now() - timedelta(days=30)
+        )
+    
+    def get_required_fields(self):
+        return {'price', 'category', 'stock_quantity', 'rating', 'is_active', 'created_at'}
+```
+
+## 🔧 Best Practices for Related Objects
+

{django_bulk_hooks-0.1.97 → django_bulk_hooks-0.1.100}/README.md

@@ -206,4 +206,166 @@ class EfficientTransactionHandler:
                 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.
+This approach ensures your hooks are robust and won't fail due to missing related objects, while also being efficient with database queries.
+
+## 🎯 Lambda Conditions and Anonymous Functions
+
+`django-bulk-hooks` supports using anonymous functions (lambda functions) and custom callables as conditions, giving you maximum flexibility for complex filtering logic.
+
+### Using LambdaCondition
+
+The `LambdaCondition` class allows you to use lambda functions or any callable as a condition:
+
+```python
+from django_bulk_hooks import LambdaCondition
+
+class ProductHandler:
+    # Simple lambda condition
+    @hook(Product, "after_create", condition=LambdaCondition(
+        lambda instance: instance.price > 100
+    ))
+    def handle_expensive_products(self, new_records, old_records):
+        """Handle products with price > 100"""
+        for product in new_records:
+            print(f"Expensive product: {product.name}")
+    
+    # Lambda with multiple conditions
+    @hook(Product, "after_update", condition=LambdaCondition(
+        lambda instance: instance.price > 50 and instance.is_active and instance.stock_quantity > 0
+    ))
+    def handle_available_expensive_products(self, new_records, old_records):
+        """Handle active products with price > 50 and stock > 0"""
+        for product in new_records:
+            print(f"Available expensive product: {product.name}")
+    
+    # Lambda comparing with original instance
+    @hook(Product, "after_update", condition=LambdaCondition(
+        lambda instance, original: original and instance.price > original.price * 1.5
+    ))
+    def handle_significant_price_increases(self, new_records, old_records):
+        """Handle products with >50% price increase"""
+        for new_product, old_product in zip(new_records, old_records):
+            if old_product:
+                increase = ((new_product.price - old_product.price) / old_product.price) * 100
+                print(f"Significant price increase: {new_product.name} +{increase:.1f}%")
+```
+
+### Combining Lambda Conditions with Built-in Conditions
+
+You can combine lambda conditions with built-in conditions using the `&` (AND) and `|` (OR) operators:
+
+```python
+from django_bulk_hooks.conditions import HasChanged, IsEqual
+
+class AdvancedProductHandler:
+    # Combine lambda with built-in conditions
+    @hook(Product, "after_update", condition=(
+        HasChanged("price") & 
+        LambdaCondition(lambda instance: instance.price > 100)
+    ))
+    def handle_expensive_price_changes(self, new_records, old_records):
+        """Handle when expensive products have price changes"""
+        for new_product, old_product in zip(new_records, old_records):
+            print(f"Expensive product price changed: {new_product.name}")
+    
+    # Complex combined conditions
+    @hook(Order, "after_update", condition=(
+        LambdaCondition(lambda instance: instance.status == 'completed') &
+        LambdaCondition(lambda instance, original: original and instance.total_amount > original.total_amount)
+    ))
+    def handle_completed_orders_with_increased_amount(self, new_records, old_records):
+        """Handle completed orders that had amount increases"""
+        for new_order, old_order in zip(new_records, old_records):
+            if old_order:
+                increase = new_order.total_amount - old_order.total_amount
+                print(f"Completed order with amount increase: {new_order.customer_name} +${increase}")
+```
+
+### Custom Condition Classes
+
+For reusable logic, you can create custom condition classes:
+
+```python
+from django_bulk_hooks.conditions import HookCondition
+
+class IsPremiumProduct(HookCondition):
+    def check(self, instance, original_instance=None):
+        return (
+            instance.price > 200 and 
+            instance.rating >= 4.0 and 
+            instance.is_active
+        )
+    
+    def get_required_fields(self):
+        return {'price', 'rating', 'is_active'}
+
+class ProductHandler:
+    @hook(Product, "after_create", condition=IsPremiumProduct())
+    def handle_premium_products(self, new_records, old_records):
+        """Handle premium products"""
+        for product in new_records:
+            print(f"Premium product: {product.name}")
+```
+
+### Lambda Conditions with Required Fields
+
+For optimization, you can specify which fields your lambda condition depends on:
+
+```python
+class OptimizedProductHandler:
+    @hook(Product, "after_update", condition=LambdaCondition(
+        lambda instance: instance.price > 100 and instance.category == 'electronics',
+        required_fields={'price', 'category'}
+    ))
+    def handle_expensive_electronics(self, new_records, old_records):
+        """Handle expensive electronics products"""
+        for product in new_records:
+            print(f"Expensive electronics: {product.name}")
+```
+
+### Best Practices for Lambda Conditions
+
+1. **Keep lambdas simple** - Complex logic should be moved to custom condition classes
+2. **Handle None values** - Always check for None before performing operations
+3. **Specify required fields** - This helps with query optimization
+4. **Use descriptive names** - Make your lambda conditions self-documenting
+5. **Test thoroughly** - Lambda conditions can be harder to debug than named functions
+
+```python
+# ✅ GOOD: Simple, clear lambda
+condition = LambdaCondition(lambda instance: instance.price > 100)
+
+# ✅ GOOD: Handles None values
+condition = LambdaCondition(
+    lambda instance: instance.price is not None and instance.price > 100
+)
+
+# ❌ AVOID: Complex logic in lambda
+condition = LambdaCondition(
+    lambda instance: (
+        instance.price > 100 and 
+        instance.category in ['electronics', 'computers'] and
+        instance.stock_quantity > 0 and
+        instance.rating >= 4.0 and
+        instance.is_active and
+        instance.created_at > datetime.now() - timedelta(days=30)
+    )
+)
+
+# ✅ BETTER: Use custom condition class for complex logic
+class IsRecentExpensiveElectronics(HookCondition):
+    def check(self, instance, original_instance=None):
+        return (
+            instance.price > 100 and 
+            instance.category in ['electronics', 'computers'] and
+            instance.stock_quantity > 0 and
+            instance.rating >= 4.0 and
+            instance.is_active and
+            instance.created_at > datetime.now() - timedelta(days=30)
+        )
+    
+    def get_required_fields(self):
+        return {'price', 'category', 'stock_quantity', 'rating', 'is_active', 'created_at'}
+```
+
+## 🔧 Best Practices for Related Objects

{django_bulk_hooks-0.1.97 → django_bulk_hooks-0.1.100}/django_bulk_hooks/__init__.py

@@ -8,6 +8,7 @@ from django_bulk_hooks.conditions import (
     IsLessThan,
     IsLessThanOrEqual,
     IsNotEqual,
+    LambdaCondition,
     WasEqual,
     is_field_set,
     safe_get_related_attr,
@@ -57,4 +58,5 @@ __all__ = [
     "IsLessThan",
     "IsGreaterThanOrEqual",
     "IsLessThanOrEqual",
+    "LambdaCondition",
 ]

{django_bulk_hooks-0.1.97 → django_bulk_hooks-0.1.100}/django_bulk_hooks/conditions.py

@@ -314,3 +314,45 @@ class IsLessThanOrEqual(HookCondition):
 
     def get_required_fields(self):
         return {self.field_name}
+
+
+class LambdaCondition(HookCondition):
+    """
+    A condition that uses a lambda function or any callable.
+
+    This makes it easy to create custom conditions inline without defining
+    a full class.
+
+    Example:
+        # Simple lambda condition
+        condition = LambdaCondition(lambda instance: instance.price > 100)
+
+        # Lambda with original instance
+        condition = LambdaCondition(
+            lambda instance, original: instance.price > original.price
+        )
+
+        # Using in a hook
+        @hook(Product, "after_update", condition=LambdaCondition(
+            lambda instance: instance.price > 100 and instance.is_active
+        ))
+        def handle_expensive_active_products(self, new_records, old_records):
+            pass
+    """
+
+    def __init__(self, func, required_fields=None):
+        """
+        Initialize with a callable function.
+
+        Args:
+            func: A callable that takes (instance, original_instance=None) and returns bool
+            required_fields: Optional set of field names this condition depends on
+        """
+        self.func = func
+        self._required_fields = required_fields or set()
+
+    def check(self, instance, original_instance=None):
+        return self.func(instance, original_instance)
+
+    def get_required_fields(self):
+        return self._required_fields

{django_bulk_hooks-0.1.97 → django_bulk_hooks-0.1.100}/django_bulk_hooks/models.py

@@ -1,4 +1,8 @@
+import contextlib
+from functools import wraps
+
 from django.db import models, transaction
+from django.db.models.fields.related_descriptors import ForwardManyToOneDescriptor
 
 from django_bulk_hooks.constants import (
     AFTER_CREATE,
@@ -14,9 +18,6 @@ from django_bulk_hooks.constants import (
 from django_bulk_hooks.context import HookContext
 from django_bulk_hooks.engine import run
 from django_bulk_hooks.manager import BulkHookManager
-from django.db.models.fields.related_descriptors import ForwardManyToOneDescriptor
-from functools import wraps
-import contextlib
 
 
 @contextlib.contextmanager
@@ -26,7 +27,7 @@ def patch_foreign_key_behavior():
     RelatedObjectDoesNotExist when accessing an unset foreign key field.
     """
     original_get = ForwardManyToOneDescriptor.__get__
-    
+
     @wraps(original_get)
     def safe_get(self, instance, cls=None):
         if instance is None:
@@ -35,7 +36,7 @@ def patch_foreign_key_behavior():
             return original_get(self, instance, cls)
         except self.RelatedObjectDoesNotExist:
             return None
-    
+
     # Patch the descriptor
     ForwardManyToOneDescriptor.__get__ = safe_get
     try:
@@ -63,7 +64,7 @@ class HookModelMixin(models.Model):
         # Skip hook validation during admin form validation
         # This prevents RelatedObjectDoesNotExist errors when Django hasn't
         # fully set up the object's relationships yet
-        if hasattr(self, '_state') and getattr(self._state, 'validating', False):
+        if hasattr(self, "_state") and getattr(self._state, "validating", False):
             return
 
         # Determine if this is a create or update operation
@@ -80,7 +81,9 @@ class HookModelMixin(models.Model):
                 old_instance = self.__class__.objects.get(pk=self.pk)
                 ctx = HookContext(self.__class__)
                 with patch_foreign_key_behavior():
-                    run(self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx)
+                    run(
+                        self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx
+                    )
             except self.__class__.DoesNotExist:
                 # If the old instance doesn't exist, treat as create
                 ctx = HookContext(self.__class__)
@@ -91,27 +94,40 @@ class HookModelMixin(models.Model):
         is_create = self.pk is None
         ctx = HookContext(self.__class__)
 
-        # Let Django save first to handle form validation
-        super().save(*args, **kwargs)
-
-        # Then run our hooks with the validated data
+        # Run BEFORE hooks before saving to allow field modifications
         with patch_foreign_key_behavior():
             if is_create:
                 # For create operations
                 run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
                 run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
-                run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
             else:
                 # For update operations
                 try:
                     old_instance = self.__class__.objects.get(pk=self.pk)
-                    run(self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx)
+                    run(
+                        self.__class__, VALIDATE_UPDATE, [self], [old_instance], ctx=ctx
+                    )
                     run(self.__class__, BEFORE_UPDATE, [self], [old_instance], ctx=ctx)
-                    run(self.__class__, AFTER_UPDATE, [self], [old_instance], ctx=ctx)
                 except self.__class__.DoesNotExist:
                     # If the old instance doesn't exist, treat as create
                     run(self.__class__, VALIDATE_CREATE, [self], ctx=ctx)
                     run(self.__class__, BEFORE_CREATE, [self], ctx=ctx)
+
+        # Now let Django save with any modifications from BEFORE hooks
+        super().save(*args, **kwargs)
+
+        # Then run AFTER hooks
+        with patch_foreign_key_behavior():
+            if is_create:
+                # For create operations
+                run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
+            else:
+                # For update operations
+                try:
+                    old_instance = self.__class__.objects.get(pk=self.pk)
+                    run(self.__class__, AFTER_UPDATE, [self], [old_instance], ctx=ctx)
+                except self.__class__.DoesNotExist:
+                    # If the old instance doesn't exist, treat as create
                     run(self.__class__, AFTER_CREATE, [self], ctx=ctx)
 
         return self
@@ -125,5 +141,5 @@ class HookModelMixin(models.Model):
             run(self.__class__, BEFORE_DELETE, [self], ctx=ctx)
             result = super().delete(*args, **kwargs)
             run(self.__class__, AFTER_DELETE, [self], ctx=ctx)
-            
+
         return result

{django_bulk_hooks-0.1.97 → django_bulk_hooks-0.1.100}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.1.97"
+version = "0.1.100"
 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"