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

django_bulk_hooks/__init__.py

@@ -1,50 +1,4 @@
-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
+from django_bulk_hooks.handler import Hook
+from django_bulk_hooks.manager import BulkHookManager
 
-__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",
-]
+__all__ = ["BulkHookManager", "Hook"]

django_bulk_hooks/conditions.py

@@ -1,182 +1,12 @@
-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:
+        if instance 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
+        instance = getattr(instance, attr, None)
+    return instance
 
 
 class HookCondition:
@@ -195,104 +25,90 @@ class HookCondition:
     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 IsEqual(HookCondition):
-    def __init__(self, field, value):
+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_value = resolve_dotted_attr(instance, self.field)
-        return current_value == self.value
-
-    def get_required_fields(self):
-        return {self.field.split('.')[0]}
+        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 IsNotEqual(HookCondition):
-    def __init__(self, field, 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_value = resolve_dotted_attr(instance, self.field)
-        return current_value != self.value
-
-    def get_required_fields(self):
-        return {self.field.split('.')[0]}
+        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 WasEqual(HookCondition):
-    def __init__(self, field, value):
+class HasChanged(HookCondition):
+    def __init__(self, field, has_changed=True):
         self.field = field
-        self.value = value
+        self.has_changed = has_changed
 
     def check(self, instance, original_instance=None):
-        if original_instance is None:
+        if not original_instance:
             return False
-        original_value = resolve_dotted_attr(original_instance, self.field)
-        return original_value == self.value
-
-    def get_required_fields(self):
-        return {self.field.split('.')[0]}
+        current = resolve_dotted_attr(instance, self.field)
+        previous = resolve_dotted_attr(original_instance, self.field)
+        return (current != previous) == self.has_changed
 
 
-class HasChanged(HookCondition):
-    def __init__(self, field, has_changed=True):
+class WasEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
         """
-        Check if a field's value has changed or remained the same.
-        
-        Args:
-            field: 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
+        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.has_changed = has_changed
+        self.value = value
+        self.only_on_change = only_on_change
 
     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 False since there's no change yet
-            # - If we're checking for stability (has_changed=False), return True since it's technically unchanged
-            return not self.has_changed
-            
-        current_value = resolve_dotted_attr(instance, self.field)
-        original_value = resolve_dotted_attr(original_instance, self.field)
-        return (current_value != original_value) == self.has_changed
-
-    def get_required_fields(self):
-        return {self.field.split('.')[0]}
+            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:
-            current_value = resolve_dotted_attr(instance, self.field)
-            return current_value == self.value
-
-        current_value = resolve_dotted_attr(instance, self.field)
-        original_value = resolve_dotted_attr(original_instance, self.field)
-        return current_value == self.value and current_value != original_value
-
-    def get_required_fields(self):
-        return {self.field.split('.')[0]}
+            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):
@@ -336,41 +152,30 @@ class IsLessThanOrEqual(HookCondition):
 
 
 class AndCondition(HookCondition):
-    def __init__(self, condition1, condition2):
-        self.condition1 = condition1
-        self.condition2 = condition2
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
 
     def check(self, instance, original_instance=None):
-        return (
-            self.condition1.check(instance, original_instance)
-            and self.condition2.check(instance, original_instance)
+        return self.cond1.check(instance, original_instance) and self.cond2.check(
+            instance, original_instance
         )
 
-    def get_required_fields(self):
-        return self.condition1.get_required_fields() | self.condition2.get_required_fields()
-
 
 class OrCondition(HookCondition):
-    def __init__(self, condition1, condition2):
-        self.condition1 = condition1
-        self.condition2 = condition2
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
 
     def check(self, instance, original_instance=None):
-        return (
-            self.condition1.check(instance, original_instance)
-            or self.condition2.check(instance, original_instance)
+        return self.cond1.check(instance, original_instance) or self.cond2.check(
+            instance, original_instance
         )
 
-    def get_required_fields(self):
-        return self.condition1.get_required_fields() | self.condition2.get_required_fields()
-
 
 class NotCondition(HookCondition):
-    def __init__(self, condition):
-        self.condition = condition
+    def __init__(self, cond):
+        self.cond = cond
 
     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()
+        return not self.cond.check(instance, original_instance)

django_bulk_hooks/decorators.py

@@ -4,7 +4,6 @@ from functools import wraps
 from django.core.exceptions import FieldDoesNotExist
 from django_bulk_hooks.enums import DEFAULT_PRIORITY
 from django_bulk_hooks.registry import register_hook
-from django_bulk_hooks.engine import safe_get_related_object
 
 
 def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
@@ -25,15 +24,10 @@ def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
 def select_related(*related_fields):
     """
     Decorator that preloads related fields in-place on `new_records`, before the hook logic runs.
-    
-    This decorator provides bulk loading for performance when you explicitly need it.
-    If you don't use this decorator, the framework will automatically detect and load
-    foreign keys only when conditions need them, preserving standard Django behavior.
 
     - Works with instance methods (resolves `self`)
     - Avoids replacing model instances
     - Populates Django's relation cache to avoid extra queries
-    - Provides bulk loading for performance optimization
     """
 
     def decorator(func):
@@ -46,14 +40,14 @@ def select_related(*related_fields):
 
             if "new_records" not in bound.arguments:
                 raise TypeError(
-                    "@select_related requires a 'new_records' argument in the decorated function"
+                    "@preload_related requires a 'new_records' argument in the decorated function"
                 )
 
             new_records = bound.arguments["new_records"]
 
             if not isinstance(new_records, list):
                 raise TypeError(
-                    f"@select_related expects a list of model instances, got {type(new_records)}"
+                    f"@preload_related expects a list of model instances, got {type(new_records)}"
                 )
 
             if not new_records:
@@ -62,29 +56,19 @@ def select_related(*related_fields):
             # Determine which instances actually need preloading
             model_cls = new_records[0].__class__
             ids_to_fetch = []
-            instances_without_pk = []
-            
             for obj in new_records:
                 if obj.pk is None:
-                    # For objects without PKs (BEFORE_CREATE), check if foreign key fields are already set
-                    instances_without_pk.append(obj)
                     continue
-                
                 # if any related field is not already cached on the instance,
                 # mark it for fetching
                 if any(field not in obj._state.fields_cache for field in related_fields):
                     ids_to_fetch.append(obj.pk)
 
-            # Load foreign keys for objects with PKs
             fetched = {}
             if ids_to_fetch:
                 fetched = model_cls.objects.select_related(*related_fields).in_bulk(ids_to_fetch)
 
-            # Apply loaded foreign keys to objects with PKs
             for obj in new_records:
-                if obj.pk is None:
-                    continue
-                    
                 preloaded = fetched.get(obj.pk)
                 if not preloaded:
                     continue
@@ -94,7 +78,7 @@ def select_related(*related_fields):
                         continue
                     if "." in field:
                         raise ValueError(
-                            f"@select_related does not support nested fields like '{field}'"
+                            f"@preload_related does not support nested fields like '{field}'"
                         )
 
                     try:
@@ -112,35 +96,6 @@ def select_related(*related_fields):
                         obj._state.fields_cache[field] = rel_obj
                     except AttributeError:
                         pass
-            
-            # For objects without PKs, ensure foreign key fields are properly set in the cache
-            # This prevents RelatedObjectDoesNotExist when accessing foreign keys
-            for obj in instances_without_pk:
-                for field in related_fields:
-                    if "." in field:
-                        raise ValueError(
-                            f"@select_related does not support nested fields like '{field}'"
-                        )
-
-                    try:
-                        f = model_cls._meta.get_field(field)
-                        if not (
-                            f.is_relation and not f.many_to_many and not f.one_to_many
-                        ):
-                            continue
-                    except FieldDoesNotExist:
-                        continue
-                    
-                    # Check if the foreign key field is set
-                    fk_field_name = f"{field}_id"
-                    if hasattr(obj, fk_field_name) and getattr(obj, fk_field_name) is not None:
-                        # The foreign key ID is set, so we can try to get the related object safely
-                        rel_obj = safe_get_related_object(obj, field)
-                        if rel_obj is not None:
-                            # Ensure it's cached to prevent future queries
-                            if not hasattr(obj._state, 'fields_cache'):
-                                obj._state.fields_cache = {}
-                            obj._state.fields_cache[field] = rel_obj
 
             return func(*bound.args, **bound.kwargs)
 

django_bulk_hooks/engine.py

@@ -1,19 +1,13 @@
 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:
@@ -27,42 +21,20 @@ def run(model_cls, event, new_instances, original_instances=None, ctx=None):
             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]
-
-        # If no condition, process all instances at once
-        if not condition:
-            func(new_records=new_instances, old_records=original_instances if any(original_instances) else None)
-            continue
+        handler_instance = handler_cls()
+        func = getattr(handler_instance, method_name)
 
-        # For conditional hooks, filter instances first
         to_process_new = []
         to_process_old = []
 
-        for new, original in zip(new_instances, original_instances, strict=True):
-            if condition.check(new, original):
+        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)
 

django_bulk_hooks/handler.py

@@ -86,7 +86,7 @@ class HookMeta(type):
         return cls
 
 
-class HookHandler(metaclass=HookMeta):
+class Hook(metaclass=HookMeta):
     @classmethod
     def handle(
         cls,