django-bulk-hooks 0.1.101__py3-none-any.whl → 0.1.103__py3-none-any.whl

django_bulk_hooks/__init__.py

@@ -1,62 +1,4 @@
-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
+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",
-    "IsBlank",
-    "IsGreaterThan",
-    "IsLessThan",
-    "IsGreaterThanOrEqual",
-    "IsLessThanOrEqual",
-    "LambdaCondition",
-]
+__all__ = ["BulkHookManager", "Hook"]

django_bulk_hooks/conditions.py

@@ -1,93 +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 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):
+def resolve_dotted_attr(instance, dotted_path):
     """
-    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.
+    Recursively resolve a dotted attribute path, e.g., "type.category".
     """
-    return hasattr(instance, field_name)
+    for attr in dotted_path.split("."):
+        if instance is None:
+            return None
+        instance = getattr(instance, attr, None)
+    return instance
 
 
 class HookCondition:
@@ -106,253 +25,157 @@ 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 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
+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):
-        return not self.condition.check(instance, original_instance)
-
-    def get_required_fields(self):
-        return self.condition.get_required_fields()
+        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_name, value):
-        self.field_name = field_name
+    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):
-        return getattr(instance, self.field_name, None) == self.value
+        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
 
-    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
+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 original_instance is None:
+        if not original_instance:
             return False
-        return getattr(original_instance, self.field_name, None) == self.value
-
-    def get_required_fields(self):
-        return {self.field_name}
+        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_name, 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_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
+        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_name = field_name
-        self.has_changed = has_changed
+        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:
-            # 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}
+            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_name, value):
-        self.field_name = field_name
+    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 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}
+            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_name, value):
-        self.field_name = field_name
+    def __init__(self, field, value):
+        self.field = field
         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}
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current > self.value
 
 
-class IsLessThan(HookCondition):
-    def __init__(self, field_name, value):
-        self.field_name = field_name
+class IsGreaterThanOrEqual(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
         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
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current >= 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
+class IsLessThan(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
         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}
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current < self.value
 
 
 class IsLessThanOrEqual(HookCondition):
-    def __init__(self, field_name, value):
-        self.field_name = field_name
+    def __init__(self, field, value):
+        self.field = field
         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
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current <= self.value
 
-    def get_required_fields(self):
-        return {self.field_name}
 
+class AndCondition(HookCondition):
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
 
-class LambdaCondition(HookCondition):
-    """
-    A condition that uses a lambda function or any callable.
+    def check(self, instance, original_instance=None):
+        return self.cond1.check(instance, original_instance) and self.cond2.check(
+            instance, original_instance
+        )
 
-    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)
+class OrCondition(HookCondition):
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
 
-        # Lambda with original instance
-        condition = LambdaCondition(
-            lambda instance, original: instance.price > original.price
+    def check(self, instance, original_instance=None):
+        return self.cond1.check(instance, original_instance) or self.cond2.check(
+            instance, original_instance
         )
 
-        # 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()
+class NotCondition(HookCondition):
+    def __init__(self, cond):
+        self.cond = cond
 
     def check(self, instance, original_instance=None):
-        return self.func(instance, original_instance)
-
-    def get_required_fields(self):
-        return self._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):
@@ -24,22 +23,83 @@ def hook(event, *, model, condition=None, priority=DEFAULT_PRIORITY):
 
 def select_related(*related_fields):
     """
-    Decorator that marks a hook method to preload related fields.
-    
-    This decorator works in conjunction with the hook system to ensure that
-    related fields are bulk-loaded before the hook logic runs, preventing
-    queries in loops.
+    Decorator that preloads related fields in-place on `new_records`, before the hook logic runs.
 
     - 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):
-        # Store the related fields on the function for later access
-        func._select_related_fields = related_fields
-        return func
+        sig = inspect.signature(func)
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            bound = sig.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+
+            if "new_records" not in bound.arguments:
+                raise TypeError(
+                    "@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"@preload_related expects a list of model instances, got {type(new_records)}"
+                )
+
+            if not new_records:
+                return func(*args, **kwargs)
+
+            # Determine which instances actually need preloading
+            model_cls = new_records[0].__class__
+            ids_to_fetch = []
+            for obj in new_records:
+                if obj.pk is None:
+                    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)
+
+            fetched = {}
+            if ids_to_fetch:
+                fetched = model_cls.objects.select_related(*related_fields).in_bulk(ids_to_fetch)
+
+            for obj in new_records:
+                preloaded = fetched.get(obj.pk)
+                if not preloaded:
+                    continue
+                for field in related_fields:
+                    if field in obj._state.fields_cache:
+                        # don't override values that were explicitly set or already loaded
+                        continue
+                    if "." in field:
+                        raise ValueError(
+                            f"@preload_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
+
+                    try:
+                        rel_obj = getattr(preloaded, field)
+                        setattr(obj, field, rel_obj)
+                        obj._state.fields_cache[field] = rel_obj
+                    except AttributeError:
+                        pass
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
 
     return decorator