django-bulk-hooks 0.1.80__py3-none-any.whl → 0.1.82__py3-none-any.whl

django_bulk_hooks/__init__.py

@@ -1,47 +1,50 @@
-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,
-)
-from django_bulk_hooks.decorators import hook, select_related
-from django_bulk_hooks.engine import safe_get_related_object, safe_get_related_attr
-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",
-    "Priority",
-    "hook",
-    "select_related",
-    "ChangesTo",
-    "HasChanged",
-    "IsEqual",
-    "IsNotEqual",
-    "WasEqual",
-]
+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,
+    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",
+]

django_bulk_hooks/conditions.py

@@ -1,233 +1,351 @@
-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 resolve_dotted_attr(instance, dotted_path):
-    """
-    Recursively resolve a dotted attribute path, e.g., "type.category".
-    This function is designed to work with pre-loaded foreign keys to avoid queries.
-    """
-    if instance is None:
-        return None
-    
-    current = instance
-    for attr in dotted_path.split("."):
-        if current is None:
-            return None
-        
-        # Check if this is a foreign key that might trigger a query
-        if hasattr(current, '_meta') and hasattr(current._meta, 'get_field'):
-            try:
-                field = current._meta.get_field(attr)
-                if field.is_relation and not field.many_to_many and not field.one_to_many:
-                    # For foreign keys, use safe access to prevent RelatedObjectDoesNotExist
-                    current = safe_get_related_object(current, attr)
-                else:
-                    current = getattr(current, attr, None)
-            except Exception:
-                # If field lookup fails, fall back to regular attribute access
-                current = getattr(current, attr, None)
-        else:
-            # Not a model instance, use regular attribute access
-            current = getattr(current, attr, None)
-    
-    return current
-
-
-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)
-
-
-class IsNotEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
-        self.field = field
-        self.value = value
-        self.only_on_change = only_on_change
-
-    def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        if self.only_on_change:
-            if original_instance is None:
-                return False
-            previous = resolve_dotted_attr(original_instance, self.field)
-            return previous == self.value and current != self.value
-        else:
-            return current != self.value
-
-
-class IsEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
-        self.field = field
-        self.value = value
-        self.only_on_change = only_on_change
-
-    def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        if self.only_on_change:
-            if original_instance is None:
-                return False
-            previous = resolve_dotted_attr(original_instance, self.field)
-            return previous != self.value and current == self.value
-        else:
-            return current == self.value
-
-
-class HasChanged(HookCondition):
-    def __init__(self, field, has_changed=True):
-        self.field = field
-        self.has_changed = has_changed
-
-    def check(self, instance, original_instance=None):
-        if not original_instance:
-            return False
-        current = resolve_dotted_attr(instance, self.field)
-        previous = resolve_dotted_attr(original_instance, self.field)
-        return (current != previous) == self.has_changed
-
-
-class WasEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
-        """
-        Check if a field's original value was `value`.
-        If only_on_change is True, only return True when the field has changed away from that value.
-        """
-        self.field = field
-        self.value = value
-        self.only_on_change = only_on_change
-
-    def check(self, instance, original_instance=None):
-        if original_instance is None:
-            return False
-        previous = resolve_dotted_attr(original_instance, self.field)
-        if self.only_on_change:
-            current = resolve_dotted_attr(instance, self.field)
-            return previous == self.value and current != self.value
-        else:
-            return previous == self.value
-
-
-class ChangesTo(HookCondition):
-    def __init__(self, field, value):
-        """
-        Check if a field's value has changed to `value`.
-        Only returns True when original value != value and current value == value.
-        """
-        self.field = field
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        if original_instance is None:
-            return False
-        previous = resolve_dotted_attr(original_instance, self.field)
-        current = resolve_dotted_attr(instance, self.field)
-        return previous != self.value and current == self.value
-
-
-class IsGreaterThan(HookCondition):
-    def __init__(self, field, value):
-        self.field = field
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        return current is not None and current > self.value
-
-
-class IsGreaterThanOrEqual(HookCondition):
-    def __init__(self, field, value):
-        self.field = field
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        return current is not None and current >= self.value
-
-
-class IsLessThan(HookCondition):
-    def __init__(self, field, value):
-        self.field = field
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        return current is not None and current < self.value
-
-
-class IsLessThanOrEqual(HookCondition):
-    def __init__(self, field, value):
-        self.field = field
-        self.value = value
-
-    def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        return current is not None and current <= self.value
-
-
-class AndCondition(HookCondition):
-    def __init__(self, cond1, cond2):
-        self.cond1 = cond1
-        self.cond2 = cond2
-
-    def check(self, instance, original_instance=None):
-        return self.cond1.check(instance, original_instance) and self.cond2.check(
-            instance, original_instance
-        )
-
-
-class OrCondition(HookCondition):
-    def __init__(self, cond1, cond2):
-        self.cond1 = cond1
-        self.cond2 = cond2
-
-    def check(self, instance, original_instance=None):
-        return self.cond1.check(instance, original_instance) or self.cond2.check(
-            instance, original_instance
-        )
-
-
-class NotCondition(HookCondition):
-    def __init__(self, cond):
-        self.cond = cond
-
-    def check(self, instance, original_instance=None):
-        return not self.cond.check(instance, original_instance)
+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 is_field_set(instance, field_name):
+    """
+    Check if a foreign key field is set without raising RelatedObjectDoesNotExist.
+    
+    Args:
+        instance: The model instance
+        field_name: The foreign key field name
+    
+    Returns:
+        True if the field is set, False otherwise
+    """
+    # Check the foreign key ID field first
+    fk_field_name = f"{field_name}_id"
+    if hasattr(instance, fk_field_name):
+        fk_value = getattr(instance, fk_field_name, None)
+        return fk_value is not None
+    
+    # Fallback to checking the field directly
+    try:
+        return getattr(instance, field_name) is not None
+    except Exception:
+        return False
+
+
+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 safe_get_related_attr_with_fallback(instance, field_name, attr_name=None, fallback_value=None):
+    """
+    Enhanced version of safe_get_related_attr that provides fallback handling.
+    
+    This function is especially useful for bulk operations where related objects
+    might not be fully loaded or might not exist yet.
+    
+    Args:
+        instance: The model instance
+        field_name: The foreign key field name
+        attr_name: Optional attribute name to access on the related object
+        fallback_value: Value to return if the related object or attribute doesn't exist
+    
+    Returns:
+        The related object, the attribute value, or fallback_value if not available
+    """
+    # First try the standard safe access
+    result = safe_get_related_attr(instance, field_name, attr_name)
+    if result is not None:
+        return result
+    
+    # If that fails, try to get the foreign key ID and fetch the object directly
+    fk_field_name = f"{field_name}_id"
+    if hasattr(instance, fk_field_name):
+        fk_id = getattr(instance, fk_field_name)
+        if fk_id is not None:
+            try:
+                # Get the field to determine the related model
+                field = instance._meta.get_field(field_name)
+                if field.is_relation and not field.many_to_many and not field.one_to_many:
+                    # Try to fetch the related object directly
+                    related_obj = field.related_model.objects.get(pk=fk_id)
+                    if attr_name is None:
+                        return related_obj
+                    return getattr(related_obj, attr_name, fallback_value)
+            except (field.related_model.DoesNotExist, AttributeError):
+                pass
+    
+    return fallback_value
+
+
+def resolve_dotted_attr(instance, dotted_path):
+    """
+    Recursively resolve a dotted attribute path, e.g., "type.category".
+    This function is designed to work with pre-loaded foreign keys to avoid queries.
+    """
+    if instance is None:
+        return None
+    
+    current = instance
+    for attr in dotted_path.split("."):
+        if current is None:
+            return None
+        
+        # Check if this is a foreign key that might trigger a query
+        if hasattr(current, '_meta') and hasattr(current._meta, 'get_field'):
+            try:
+                field = current._meta.get_field(attr)
+                if field.is_relation and not field.many_to_many and not field.one_to_many:
+                    # For foreign keys, use safe access to prevent RelatedObjectDoesNotExist
+                    current = safe_get_related_object(current, attr)
+                else:
+                    current = getattr(current, attr, None)
+            except Exception:
+                # If field lookup fails, fall back to regular attribute access
+                current = getattr(current, attr, None)
+        else:
+            # Not a model instance, use regular attribute access
+            current = getattr(current, attr, None)
+    
+    return current
+
+
+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)
+
+
+class IsNotEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
+        self.field = field
+        self.value = value
+        self.only_on_change = only_on_change
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        if self.only_on_change:
+            if original_instance is None:
+                return False
+            previous = resolve_dotted_attr(original_instance, self.field)
+            return previous == self.value and current != self.value
+        else:
+            return current != self.value
+
+
+class IsEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
+        self.field = field
+        self.value = value
+        self.only_on_change = only_on_change
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        if self.only_on_change:
+            if original_instance is None:
+                return False
+            previous = resolve_dotted_attr(original_instance, self.field)
+            return previous != self.value and current == self.value
+        else:
+            return current == self.value
+
+
+class HasChanged(HookCondition):
+    def __init__(self, field, has_changed=True):
+        self.field = field
+        self.has_changed = has_changed
+
+    def check(self, instance, original_instance=None):
+        if not original_instance:
+            return False
+        current = resolve_dotted_attr(instance, self.field)
+        previous = resolve_dotted_attr(original_instance, self.field)
+        return (current != previous) == self.has_changed
+
+
+class WasEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
+        """
+        Check if a field's original value was `value`.
+        If only_on_change is True, only return True when the field has changed away from that value.
+        """
+        self.field = field
+        self.value = value
+        self.only_on_change = only_on_change
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            return False
+        previous = resolve_dotted_attr(original_instance, self.field)
+        if self.only_on_change:
+            current = resolve_dotted_attr(instance, self.field)
+            return previous == self.value and current != self.value
+        else:
+            return previous == self.value
+
+
+class ChangesTo(HookCondition):
+    def __init__(self, field, value):
+        """
+        Check if a field's value has changed to `value`.
+        Only returns True when original value != value and current value == value.
+        """
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            return False
+        previous = resolve_dotted_attr(original_instance, self.field)
+        current = resolve_dotted_attr(instance, self.field)
+        return previous != self.value and current == self.value
+
+
+class IsGreaterThan(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current > self.value
+
+
+class IsGreaterThanOrEqual(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current >= self.value
+
+
+class IsLessThan(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current < self.value
+
+
+class IsLessThanOrEqual(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current <= self.value
+
+
+class AndCondition(HookCondition):
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
+
+    def check(self, instance, original_instance=None):
+        return self.cond1.check(instance, original_instance) and self.cond2.check(
+            instance, original_instance
+        )
+
+
+class OrCondition(HookCondition):
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
+
+    def check(self, instance, original_instance=None):
+        return self.cond1.check(instance, original_instance) or self.cond2.check(
+            instance, original_instance
+        )
+
+
+class NotCondition(HookCondition):
+    def __init__(self, cond):
+        self.cond = cond
+
+    def check(self, instance, original_instance=None):
+        return not self.cond.check(instance, original_instance)

django_bulk_hooks/engine.py

@@ -1,66 +1,53 @@
-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
-
-logger = logging.getLogger(__name__)
-
-
-def safe_get_related_attr(instance, field_name, attr_name=None):
-    """
-    Safely get a related object or its attribute without raising RelatedObjectDoesNotExist.
-    
-    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
-    """
-    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 run(model_cls, event, new_instances, original_instances=None, ctx=None):
-    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
-
-    for handler_cls, method_name, condition, priority in hooks:
-        handler_instance = handler_cls()
-        func = getattr(handler_instance, method_name)
-
-        to_process_new = []
-        to_process_old = []
-
-        for new, original in zip(
-            new_instances,
-            original_instances or [None] * len(new_instances),
-            strict=True,
-        ):
-            if not condition or condition.check(new, original):
-                to_process_new.append(new)
-                to_process_old.append(original)
-
-        if to_process_new:
-            # Call the function with keyword arguments
-            func(new_records=to_process_new, old_records=to_process_old if any(to_process_old) 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__)
+
+
+def run(model_cls, event, new_instances, original_instances=None, ctx=None):
+    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
+
+    for handler_cls, method_name, condition, priority in hooks:
+        handler_instance = handler_cls()
+        func = getattr(handler_instance, method_name)
+
+        to_process_new = []
+        to_process_old = []
+
+        for new, original in zip(
+            new_instances,
+            original_instances or [None] * len(new_instances),
+            strict=True,
+        ):
+            if not condition or condition.check(new, original):
+                to_process_new.append(new)
+                to_process_old.append(original)
+
+        if to_process_new:
+            # Call the function with keyword arguments
+            func(new_records=to_process_new, old_records=to_process_old if any(to_process_old) else None)

django_bulk_hooks/models.py

@@ -28,8 +28,15 @@ class HookModelMixin(models.Model):
         This ensures that when Django calls clean() (like in admin forms),
         it triggers the VALIDATE_* hooks for validation only.
         """
+        # Call Django's clean first
         super().clean()
 
+        # 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):
+            return
+
         # Determine if this is a create or update operation
         is_create = self.pk is None
 

django_bulk_hooks-0.1.82.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.3
+Name: django-bulk-hooks
+Version: 0.1.82
+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.80.dist-info → django_bulk_hooks-0.1.82.dist-info}/RECORD

@@ -1,16 +1,16 @@
-django_bulk_hooks/__init__.py,sha256=iY8RkL2-qPV2y15FaEVgO7ZYrbYceZjsCtYCU073S2U,1119
-django_bulk_hooks/conditions.py,sha256=o31qTnSfEkAKMVnFPF0JdkuvMFWb92Lc-o-WQ2CoWAk,8107
+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=ru6oxoXEj4eC8JM30hzLj-jcD-_Mcg-SaPqexxR87c0,2183
+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=7RG7GrOdHXFjGVPV4FPRZVNMIHHW-hMCi6hn9LH_hVI,3331
+django_bulk_hooks/models.py,sha256=S4CLMcZeOv0XWCmmC7ieOExL73WmfWUKXPYD3N9wrVc,3666
 django_bulk_hooks/queryset.py,sha256=7lLqhZ-XOYsZ1I3Loxi4Nhz79M8HlTYE413AW8nyeDI,1330
 django_bulk_hooks/registry.py,sha256=Vh78exKYcdZhM27120kQm-iXGOjd_kf9ZUYBZ8eQ2V0,683
-django_bulk_hooks-0.1.80.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
-django_bulk_hooks-0.1.80.dist-info/METADATA,sha256=A1dYixWjfYcpuaUIrf_a_tLzbvtGLkbeuAOweiJqFN8,3388
-django_bulk_hooks-0.1.80.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-django_bulk_hooks-0.1.80.dist-info/RECORD,,
+django_bulk_hooks-0.1.82.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
+django_bulk_hooks-0.1.82.dist-info/METADATA,sha256=gYgpti0VC1zlAh2NlINn-lyAPPCXkB0K1XzIq4WgsxM,9051
+django_bulk_hooks-0.1.82.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+django_bulk_hooks-0.1.82.dist-info/RECORD,,

django_bulk_hooks-0.1.80.dist-info/METADATA

@@ -1,92 +0,0 @@
-Metadata-Version: 2.3
-Name: django-bulk-hooks
-Version: 0.1.80
-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
-
-## 🚀 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
-```