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

{django_bulk_hooks-0.1.96 → django_bulk_hooks-0.1.98}/PKG-INFO

@@ -1,7 +1,8 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: django-bulk-hooks
-Version: 0.1.96
+Version: 0.1.98
 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
@@ -13,7 +14,6 @@ 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
 
@@ -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.96 → django_bulk_hooks-0.1.98}/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.96 → django_bulk_hooks-0.1.98}/django_bulk_hooks/__init__.py

@@ -1,52 +1,62 @@
-from django_bulk_hooks.constants import (
-    AFTER_CREATE,
-    AFTER_DELETE,
-    AFTER_UPDATE,
-    BEFORE_CREATE,
-    BEFORE_DELETE,
-    BEFORE_UPDATE,
-    VALIDATE_CREATE,
-    VALIDATE_DELETE,
-    VALIDATE_UPDATE,
-)
-from django_bulk_hooks.conditions import (
-    ChangesTo,
-    HasChanged,
-    IsEqual,
-    IsNotEqual,
-    WasEqual,
-    IsBlank,
-    safe_get_related_object,
-    safe_get_related_attr,
-    is_field_set,
-)
-from django_bulk_hooks.decorators import hook, select_related
-from django_bulk_hooks.handler import HookHandler
-from django_bulk_hooks.models import HookModelMixin
-from django_bulk_hooks.enums import Priority
-
-__all__ = [
-    "HookHandler",
-    "HookModelMixin",
-    "BEFORE_CREATE",
-    "AFTER_CREATE",
-    "BEFORE_UPDATE",
-    "AFTER_UPDATE",
-    "BEFORE_DELETE",
-    "AFTER_DELETE",
-    "VALIDATE_CREATE",
-    "VALIDATE_UPDATE",
-    "VALIDATE_DELETE",
-    "safe_get_related_object",
-    "safe_get_related_attr",
-    "is_field_set",
-    "Priority",
-    "hook",
-    "select_related",
-    "ChangesTo",
-    "HasChanged",
-    "IsEqual",
-    "IsNotEqual",
-    "WasEqual",
-    "IsBlank",
-]
+from django_bulk_hooks.conditions import (
+    ChangesTo,
+    HasChanged,
+    IsBlank,
+    IsEqual,
+    IsGreaterThan,
+    IsGreaterThanOrEqual,
+    IsLessThan,
+    IsLessThanOrEqual,
+    IsNotEqual,
+    LambdaCondition,
+    WasEqual,
+    is_field_set,
+    safe_get_related_attr,
+    safe_get_related_object,
+)
+from django_bulk_hooks.constants import (
+    AFTER_CREATE,
+    AFTER_DELETE,
+    AFTER_UPDATE,
+    BEFORE_CREATE,
+    BEFORE_DELETE,
+    BEFORE_UPDATE,
+    VALIDATE_CREATE,
+    VALIDATE_DELETE,
+    VALIDATE_UPDATE,
+)
+from django_bulk_hooks.decorators import hook, select_related
+from django_bulk_hooks.enums import Priority
+from django_bulk_hooks.handler import HookHandler
+from django_bulk_hooks.models import HookModelMixin
+
+__all__ = [
+    "HookHandler",
+    "HookModelMixin",
+    "BEFORE_CREATE",
+    "AFTER_CREATE",
+    "BEFORE_UPDATE",
+    "AFTER_UPDATE",
+    "BEFORE_DELETE",
+    "AFTER_DELETE",
+    "VALIDATE_CREATE",
+    "VALIDATE_UPDATE",
+    "VALIDATE_DELETE",
+    "safe_get_related_object",
+    "safe_get_related_attr",
+    "is_field_set",
+    "Priority",
+    "hook",
+    "select_related",
+    "ChangesTo",
+    "HasChanged",
+    "IsEqual",
+    "IsNotEqual",
+    "WasEqual",
+    "IsBlank",
+    "IsGreaterThan",
+    "IsLessThan",
+    "IsGreaterThanOrEqual",
+    "IsLessThanOrEqual",
+    "LambdaCondition",
+]

{django_bulk_hooks-0.1.96 → django_bulk_hooks-0.1.98}/django_bulk_hooks/conditions.py

@@ -1,256 +1,358 @@
-from django.db import models
-
-
-def safe_get_related_object(instance, field_name):
-    """
-    Safely get a related object without raising RelatedObjectDoesNotExist.
-    Returns None if the foreign key field is None or the related object doesn't exist.
-    """
-    if not hasattr(instance, field_name):
-        return None
-    
-    # Get the foreign key field
-    try:
-        field = instance._meta.get_field(field_name)
-        if not field.is_relation or field.many_to_many or field.one_to_many:
-            return getattr(instance, field_name, None)
-    except models.FieldDoesNotExist:
-        return getattr(instance, field_name, None)
-    
-    # Check if the foreign key field is None
-    fk_field_name = f"{field_name}_id"
-    if hasattr(instance, fk_field_name) and getattr(instance, fk_field_name) is None:
-        return None
-    
-    # Try to get the related object, but catch RelatedObjectDoesNotExist
-    try:
-        return getattr(instance, field_name)
-    except field.related_model.RelatedObjectDoesNotExist:
-        return None
-
-
-def safe_get_related_attr(instance, field_name, attr_name=None):
-    """
-    Safely get a related object or its attribute without raising RelatedObjectDoesNotExist.
-    
-    This is particularly useful in hooks where objects might not have their related
-    fields populated yet (e.g., during bulk_create operations or on unsaved objects).
-    
-    Args:
-        instance: The model instance
-        field_name: The foreign key field name
-        attr_name: Optional attribute name to access on the related object
-    
-    Returns:
-        The related object, the attribute value, or None if not available
-        
-    Example:
-        # Instead of: loan_transaction.status.name (which might fail)
-        # Use: safe_get_related_attr(loan_transaction, 'status', 'name')
-        
-        status_name = safe_get_related_attr(loan_transaction, 'status', 'name')
-        if status_name in {Status.COMPLETE.value, Status.FAILED.value}:
-            # Process the transaction
-            pass
-    """
-    # For unsaved objects, check the foreign key ID field first
-    if instance.pk is None:
-        fk_field_name = f"{field_name}_id"
-        if hasattr(instance, fk_field_name):
-            fk_value = getattr(instance, fk_field_name, None)
-            if fk_value is None:
-                return None
-            # If we have an ID but the object isn't loaded, try to load it
-            try:
-                field = instance._meta.get_field(field_name)
-                if hasattr(field, 'related_model'):
-                    related_obj = field.related_model.objects.get(id=fk_value)
-                    if attr_name is None:
-                        return related_obj
-                    return getattr(related_obj, attr_name, None)
-            except (field.related_model.DoesNotExist, AttributeError):
-                return None
-    
-    # For saved objects or when the above doesn't work, use the original method
-    related_obj = safe_get_related_object(instance, field_name)
-    if related_obj is None:
-        return None
-    if attr_name is None:
-        return related_obj
-    return getattr(related_obj, attr_name, None)
-
-
-def is_field_set(instance, field_name):
-    """
-    Check if a field has been set on a model instance.
-    
-    This is useful for checking if a field has been explicitly set,
-    even if it's been set to None.
-    """
-    return hasattr(instance, field_name)
-
-
-class HookCondition:
-    def check(self, instance, original_instance=None):
-        raise NotImplementedError
-
-    def __call__(self, instance, original_instance=None):
-        return self.check(instance, original_instance)
-
-    def __and__(self, other):
-        return AndCondition(self, other)
-
-    def __or__(self, other):
-        return OrCondition(self, other)
-
-    def __invert__(self):
-        return NotCondition(self)
-
-    def get_required_fields(self):
-        """
-        Returns a set of field names that this condition needs to evaluate.
-        Override in subclasses to specify required fields.
-        """
-        return set()
-
-
-class IsBlank(HookCondition):
-    """
-    Condition that checks if a field is blank (None or empty string).
-    """
-    def __init__(self, field_name):
-        self.field_name = field_name
-
-    def check(self, instance, original_instance=None):
-        value = getattr(instance, self.field_name, None)
-        return value is None or value == ""
-
-    def get_required_fields(self):
-        return {self.field_name}
-
-
-class AndCondition(HookCondition):
-    def __init__(self, *conditions):
-        self.conditions = conditions
-
-    def check(self, instance, original_instance=None):
-        return all(c.check(instance, original_instance) for c in self.conditions)
-
-    def get_required_fields(self):
-        fields = set()
-        for condition in self.conditions:
-            fields.update(condition.get_required_fields())
-        return fields
-
-
-class OrCondition(HookCondition):
-    def __init__(self, *conditions):
-        self.conditions = conditions
-
-    def check(self, instance, original_instance=None):
-        return any(c.check(instance, original_instance) for c in self.conditions)
-
-    def get_required_fields(self):
-        fields = set()
-        for condition in self.conditions:
-            fields.update(condition.get_required_fields())
-        return fields
-
-
-class NotCondition(HookCondition):
-    def __init__(self, condition):
-        self.condition = condition
-
-    def check(self, instance, original_instance=None):
-        return not self.condition.check(instance, original_instance)
-
-    def get_required_fields(self):
-        return self.condition.get_required_fields()
-
-
-class IsEqual(HookCondition):
-    def __init__(self, field_name, value):
-        self.field_name = field_name
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        return getattr(instance, self.field_name, None) == self.value
-
-    def get_required_fields(self):
-        return {self.field_name}
-
-
-class WasEqual(HookCondition):
-    def __init__(self, field_name, value):
-        self.field_name = field_name
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        if original_instance is None:
-            return False
-        return getattr(original_instance, self.field_name, None) == self.value
-
-    def get_required_fields(self):
-        return {self.field_name}
-
-
-class HasChanged(HookCondition):
-    def __init__(self, field_name, has_changed=True):
-        """
-        Check if a field's value has changed or remained the same.
-        
-        Args:
-            field_name: The field name to check
-            has_changed: If True (default), condition passes when field has changed.
-                        If False, condition passes when field has remained the same.
-                        This is useful for:
-                        - Detecting stable/unchanged fields
-                        - Validating field immutability
-                        - Ensuring critical fields remain constant
-                        - State machine validations
-        """
-        self.field_name = field_name
-        self.has_changed = has_changed
-
-    def check(self, instance, original_instance=None):
-        if original_instance is None:
-            # For new instances:
-            # - If we're checking for changes (has_changed=True), return True since it's a new record
-            # - If we're checking for stability (has_changed=False), return False since it's technically changed from nothing
-            return self.has_changed
-            
-        current_value = getattr(instance, self.field_name, None)
-        original_value = getattr(original_instance, self.field_name, None)
-        return (current_value != original_value) == self.has_changed
-
-    def get_required_fields(self):
-        return {self.field_name}
-
-
-class ChangesTo(HookCondition):
-    def __init__(self, field_name, value):
-        self.field_name = field_name
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        if original_instance is None:
-            return getattr(instance, self.field_name, None) == self.value
-        return (
-            getattr(instance, self.field_name, None) == self.value
-            and getattr(instance, self.field_name, None) != getattr(original_instance, self.field_name, None)
-        )
-
-    def get_required_fields(self):
-        return {self.field_name}
-
-
-class IsNotEqual(HookCondition):
-    def __init__(self, field_name, value):
-        self.field_name = field_name
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        return getattr(instance, self.field_name, None) != self.value
-
-    def get_required_fields(self):
-        return {self.field_name}
+from django.db import models
+
+
+def safe_get_related_object(instance, field_name):
+    """
+    Safely get a related object without raising RelatedObjectDoesNotExist.
+    Returns None if the foreign key field is None or the related object doesn't exist.
+    """
+    if not hasattr(instance, field_name):
+        return None
+
+    # Get the foreign key field
+    try:
+        field = instance._meta.get_field(field_name)
+        if not field.is_relation or field.many_to_many or field.one_to_many:
+            return getattr(instance, field_name, None)
+    except models.FieldDoesNotExist:
+        return getattr(instance, field_name, None)
+
+    # Check if the foreign key field is None
+    fk_field_name = f"{field_name}_id"
+    if hasattr(instance, fk_field_name) and getattr(instance, fk_field_name) is None:
+        return None
+
+    # Try to get the related object, but catch RelatedObjectDoesNotExist
+    try:
+        return getattr(instance, field_name)
+    except field.related_model.RelatedObjectDoesNotExist:
+        return None
+
+
+def safe_get_related_attr(instance, field_name, attr_name=None):
+    """
+    Safely get a related object or its attribute without raising RelatedObjectDoesNotExist.
+
+    This is particularly useful in hooks where objects might not have their related
+    fields populated yet (e.g., during bulk_create operations or on unsaved objects).
+
+    Args:
+        instance: The model instance
+        field_name: The foreign key field name
+        attr_name: Optional attribute name to access on the related object
+
+    Returns:
+        The related object, the attribute value, or None if not available
+
+    Example:
+        # Instead of: loan_transaction.status.name (which might fail)
+        # Use: safe_get_related_attr(loan_transaction, 'status', 'name')
+
+        status_name = safe_get_related_attr(loan_transaction, 'status', 'name')
+        if status_name in {Status.COMPLETE.value, Status.FAILED.value}:
+            # Process the transaction
+            pass
+    """
+    # For unsaved objects, check the foreign key ID field first
+    if instance.pk is None:
+        fk_field_name = f"{field_name}_id"
+        if hasattr(instance, fk_field_name):
+            fk_value = getattr(instance, fk_field_name, None)
+            if fk_value is None:
+                return None
+            # If we have an ID but the object isn't loaded, try to load it
+            try:
+                field = instance._meta.get_field(field_name)
+                if hasattr(field, "related_model"):
+                    related_obj = field.related_model.objects.get(id=fk_value)
+                    if attr_name is None:
+                        return related_obj
+                    return getattr(related_obj, attr_name, None)
+            except (field.related_model.DoesNotExist, AttributeError):
+                return None
+
+    # For saved objects or when the above doesn't work, use the original method
+    related_obj = safe_get_related_object(instance, field_name)
+    if related_obj is None:
+        return None
+    if attr_name is None:
+        return related_obj
+    return getattr(related_obj, attr_name, None)
+
+
+def is_field_set(instance, field_name):
+    """
+    Check if a field has been set on a model instance.
+
+    This is useful for checking if a field has been explicitly set,
+    even if it's been set to None.
+    """
+    return hasattr(instance, field_name)
+
+
+class HookCondition:
+    def check(self, instance, original_instance=None):
+        raise NotImplementedError
+
+    def __call__(self, instance, original_instance=None):
+        return self.check(instance, original_instance)
+
+    def __and__(self, other):
+        return AndCondition(self, other)
+
+    def __or__(self, other):
+        return OrCondition(self, other)
+
+    def __invert__(self):
+        return NotCondition(self)
+
+    def get_required_fields(self):
+        """
+        Returns a set of field names that this condition needs to evaluate.
+        Override in subclasses to specify required fields.
+        """
+        return set()
+
+
+class IsBlank(HookCondition):
+    """
+    Condition that checks if a field is blank (None or empty string).
+    """
+
+    def __init__(self, field_name):
+        self.field_name = field_name
+
+    def check(self, instance, original_instance=None):
+        value = getattr(instance, self.field_name, None)
+        return value is None or value == ""
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class AndCondition(HookCondition):
+    def __init__(self, *conditions):
+        self.conditions = conditions
+
+    def check(self, instance, original_instance=None):
+        return all(c.check(instance, original_instance) for c in self.conditions)
+
+    def get_required_fields(self):
+        fields = set()
+        for condition in self.conditions:
+            fields.update(condition.get_required_fields())
+        return fields
+
+
+class OrCondition(HookCondition):
+    def __init__(self, *conditions):
+        self.conditions = conditions
+
+    def check(self, instance, original_instance=None):
+        return any(c.check(instance, original_instance) for c in self.conditions)
+
+    def get_required_fields(self):
+        fields = set()
+        for condition in self.conditions:
+            fields.update(condition.get_required_fields())
+        return fields
+
+
+class NotCondition(HookCondition):
+    def __init__(self, condition):
+        self.condition = condition
+
+    def check(self, instance, original_instance=None):
+        return not self.condition.check(instance, original_instance)
+
+    def get_required_fields(self):
+        return self.condition.get_required_fields()
+
+
+class IsEqual(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        return getattr(instance, self.field_name, None) == self.value
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class WasEqual(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            return False
+        return getattr(original_instance, self.field_name, None) == self.value
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class HasChanged(HookCondition):
+    def __init__(self, field_name, has_changed=True):
+        """
+        Check if a field's value has changed or remained the same.
+
+        Args:
+            field_name: The field name to check
+            has_changed: If True (default), condition passes when field has changed.
+                        If False, condition passes when field has remained the same.
+                        This is useful for:
+                        - Detecting stable/unchanged fields
+                        - Validating field immutability
+                        - Ensuring critical fields remain constant
+                        - State machine validations
+        """
+        self.field_name = field_name
+        self.has_changed = has_changed
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            # For new instances:
+            # - If we're checking for changes (has_changed=True), return True since it's a new record
+            # - If we're checking for stability (has_changed=False), return False since it's technically changed from nothing
+            return self.has_changed
+
+        current_value = getattr(instance, self.field_name, None)
+        original_value = getattr(original_instance, self.field_name, None)
+        return (current_value != original_value) == self.has_changed
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class ChangesTo(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            return getattr(instance, self.field_name, None) == self.value
+        return getattr(instance, self.field_name, None) == self.value and getattr(
+            instance, self.field_name, None
+        ) != getattr(original_instance, self.field_name, None)
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class IsNotEqual(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        return getattr(instance, self.field_name, None) != self.value
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class IsGreaterThan(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        field_value = getattr(instance, self.field_name, None)
+        if field_value is None:
+            return False
+        return field_value > self.value
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class IsLessThan(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        field_value = getattr(instance, self.field_name, None)
+        if field_value is None:
+            return False
+        return field_value < self.value
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class IsGreaterThanOrEqual(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        field_value = getattr(instance, self.field_name, None)
+        if field_value is None:
+            return False
+        return field_value >= self.value
+
+    def get_required_fields(self):
+        return {self.field_name}
+
+
+class IsLessThanOrEqual(HookCondition):
+    def __init__(self, field_name, value):
+        self.field_name = field_name
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        field_value = getattr(instance, self.field_name, None)
+        if field_value is None:
+            return False
+        return field_value <= self.value
+
+    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.96 → django_bulk_hooks-0.1.98}/django_bulk_hooks/engine.py

@@ -1,82 +1,82 @@
-import logging
-
-from django.core.exceptions import ValidationError
-from django.db import models
-from django_bulk_hooks.registry import get_hooks
-from django_bulk_hooks.conditions import safe_get_related_object, safe_get_related_attr
-
-logger = logging.getLogger(__name__)
-
-
-# Cache for hook handlers to avoid creating them repeatedly
-_handler_cache = {}
-
-def run(model_cls, event, new_instances, original_instances=None, ctx=None):
-    # Get hooks from cache or fetch them
-    cache_key = (model_cls, event)
-    hooks = get_hooks(model_cls, event)
-
-    if not hooks:
-        return
-
-    # For BEFORE_* events, run model.clean() first for validation
-    if event.startswith("before_"):
-        for instance in new_instances:
-            try:
-                instance.clean()
-            except ValidationError as e:
-                logger.error("Validation failed for %s: %s", instance, e)
-                raise
-            except Exception as e:
-                # Handle RelatedObjectDoesNotExist and other exceptions that might occur
-                # when accessing foreign key fields on unsaved objects
-                if "RelatedObjectDoesNotExist" in str(type(e).__name__):
-                    logger.debug("Skipping validation for unsaved object with unset foreign keys: %s", e)
-                    continue
-                else:
-                    logger.error("Unexpected error during validation for %s: %s", instance, e)
-                    raise
-
-    # Pre-create None list for originals if needed
-    if original_instances is None:
-        original_instances = [None] * len(new_instances)
-
-    # Process all hooks
-    for handler_cls, method_name, condition, priority in hooks:
-        # Get or create handler instance from cache
-        handler_key = (handler_cls, method_name)
-        if handler_key not in _handler_cache:
-            handler_instance = handler_cls()
-            func = getattr(handler_instance, method_name)
-            _handler_cache[handler_key] = (handler_instance, func)
-        else:
-            handler_instance, func = _handler_cache[handler_key]
-
-        # Filter instances based on condition
-        if condition:
-            to_process_new = []
-            to_process_old = []
-
-            logger.debug(f"Checking condition {condition.__class__.__name__} for {len(new_instances)} instances")
-            for new, original in zip(new_instances, original_instances, strict=True):
-                logger.debug(f"Checking instance {new.__class__.__name__}(pk={new.pk})")
-                try:
-                    matches = condition.check(new, original)
-                    logger.debug(f"Condition check result: {matches}")
-                    if matches:
-                        to_process_new.append(new)
-                        to_process_old.append(original)
-                except Exception as e:
-                    logger.error(f"Error checking condition: {e}")
-                    raise
-
-            # Only call if we have matching instances
-            if to_process_new:
-                logger.debug(f"Running hook for {len(to_process_new)} matching instances")
-                func(new_records=to_process_new, old_records=to_process_old if any(to_process_old) else None)
-            else:
-                logger.debug("No instances matched condition")
-        else:
-            # No condition, process all instances
-            logger.debug("No condition, processing all instances")
-            func(new_records=new_instances, old_records=original_instances if any(original_instances) else None)
+import logging
+
+from django.core.exceptions import ValidationError
+from django.db import models
+from django_bulk_hooks.registry import get_hooks
+from django_bulk_hooks.conditions import safe_get_related_object, safe_get_related_attr
+
+logger = logging.getLogger(__name__)
+
+
+# Cache for hook handlers to avoid creating them repeatedly
+_handler_cache = {}
+
+def run(model_cls, event, new_instances, original_instances=None, ctx=None):
+    # Get hooks from cache or fetch them
+    cache_key = (model_cls, event)
+    hooks = get_hooks(model_cls, event)
+
+    if not hooks:
+        return
+
+    # For BEFORE_* events, run model.clean() first for validation
+    if event.startswith("before_"):
+        for instance in new_instances:
+            try:
+                instance.clean()
+            except ValidationError as e:
+                logger.error("Validation failed for %s: %s", instance, e)
+                raise
+            except Exception as e:
+                # Handle RelatedObjectDoesNotExist and other exceptions that might occur
+                # when accessing foreign key fields on unsaved objects
+                if "RelatedObjectDoesNotExist" in str(type(e).__name__):
+                    logger.debug("Skipping validation for unsaved object with unset foreign keys: %s", e)
+                    continue
+                else:
+                    logger.error("Unexpected error during validation for %s: %s", instance, e)
+                    raise
+
+    # Pre-create None list for originals if needed
+    if original_instances is None:
+        original_instances = [None] * len(new_instances)
+
+    # Process all hooks
+    for handler_cls, method_name, condition, priority in hooks:
+        # Get or create handler instance from cache
+        handler_key = (handler_cls, method_name)
+        if handler_key not in _handler_cache:
+            handler_instance = handler_cls()
+            func = getattr(handler_instance, method_name)
+            _handler_cache[handler_key] = (handler_instance, func)
+        else:
+            handler_instance, func = _handler_cache[handler_key]
+
+        # Filter instances based on condition
+        if condition:
+            to_process_new = []
+            to_process_old = []
+
+            logger.debug(f"Checking condition {condition.__class__.__name__} for {len(new_instances)} instances")
+            for new, original in zip(new_instances, original_instances, strict=True):
+                logger.debug(f"Checking instance {new.__class__.__name__}(pk={new.pk})")
+                try:
+                    matches = condition.check(new, original)
+                    logger.debug(f"Condition check result: {matches}")
+                    if matches:
+                        to_process_new.append(new)
+                        to_process_old.append(original)
+                except Exception as e:
+                    logger.error(f"Error checking condition: {e}")
+                    raise
+
+            # Only call if we have matching instances
+            if to_process_new:
+                logger.debug(f"Running hook for {len(to_process_new)} matching instances")
+                func(new_records=to_process_new, old_records=to_process_old if any(to_process_old) else None)
+            else:
+                logger.debug("No instances matched condition")
+        else:
+            # No condition, process all instances
+            logger.debug("No condition, processing all instances")
+            func(new_records=new_instances, old_records=original_instances if any(original_instances) else None)

{django_bulk_hooks-0.1.96 → django_bulk_hooks-0.1.98}/django_bulk_hooks/handler.py

@@ -1,3 +1,4 @@
+import inspect
 import logging
 import threading
 from collections import deque
@@ -144,11 +145,12 @@ class HookHandler(metaclass=HookMeta):
 
                 # Inspect the method signature to determine parameter order
                 import inspect
+
                 sig = inspect.signature(method)
                 params = list(sig.parameters.keys())
-                
+
                 # Remove 'self' from params if it exists
-                if params and params[0] == 'self':
+                if params and params[0] == "self":
                     params = params[1:]
 
                 # Always call with keyword arguments to make order irrelevant

{django_bulk_hooks-0.1.96 → django_bulk_hooks-0.1.98}/pyproject.toml

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