django-bulk-hooks 0.2.59__py3-none-any.whl → 0.2.61__py3-none-any.whl

django_bulk_hooks/changeset.py

@@ -96,30 +96,11 @@ class RecordChange:
         if self.old_record is None:
             return set()
 
-        changed = set()
-        model_cls = self.new_record.__class__
+        # Import here to avoid circular dependency
+        from .operations.field_utils import get_changed_fields
 
-        for field in model_cls._meta.fields:
-            # Skip primary key - it shouldn't change
-            if field.primary_key:
-                continue
-
-            old_val = getattr(self.old_record, field.name, None)
-            new_val = getattr(self.new_record, field.name, None)
-
-            # Use field's get_prep_value for proper comparison
-            # This handles database-level transformations (e.g., timezone conversions)
-            try:
-                old_prep = field.get_prep_value(old_val)
-                new_prep = field.get_prep_value(new_val)
-                if old_prep != new_prep:
-                    changed.add(field.name)
-            except Exception:
-                # Fallback to direct comparison if get_prep_value fails
-                if old_val != new_val:
-                    changed.add(field.name)
-
-        return changed
+        model_cls = self.new_record.__class__
+        return get_changed_fields(self.old_record, self.new_record, model_cls)
 
 
 class ChangeSet:

django_bulk_hooks/helpers.py

@@ -8,9 +8,26 @@ NOTE: These helpers are pure changeset builders - they don't fetch data.
 Data fetching is the responsibility of ModelAnalyzer.
 """
 
+import logging
+
 from django_bulk_hooks.changeset import ChangeSet
 from django_bulk_hooks.changeset import RecordChange
 
+logger = logging.getLogger(__name__)
+
+
+def extract_pks(objects):
+    """
+    Extract non-None primary keys from objects.
+
+    Args:
+        objects: Iterable of model instances or objects with pk attribute
+
+    Returns:
+        List of non-None primary key values
+    """
+    return [obj.pk for obj in objects if obj.pk is not None]
+
 
 def build_changeset_for_update(
     model_cls, instances, update_kwargs, old_records_map=None, **meta,
@@ -83,6 +100,79 @@ def build_changeset_for_delete(model_cls, instances, **meta):
     return ChangeSet(model_cls, changes, "delete", meta)
 
 
+def get_fields_for_model(model_cls, field_names, include_relations=False):
+    """
+    Get field objects for the given model from a list of field names.
+
+    Handles field name normalization (e.g., 'field_id' -> 'field').
+    Only returns fields that actually exist on the model.
+
+    Args:
+        model_cls: Django model class
+        field_names: List of field names (strings)
+        include_relations: Whether to include relation fields (default False)
+
+    Returns:
+        List of field objects that exist on the model, in the same order as field_names
+    """
+    if not field_names:
+        return []
+
+    # Build lookup dict of available fields
+    fields_by_name = {}
+    # Use local_fields for child tables, get_fields() for parent tables that need inherited fields
+    fields_to_check = model_cls._meta.local_fields if not include_relations else model_cls._meta.get_fields()
+    for field in fields_to_check:
+        if not include_relations and (field.many_to_many or field.one_to_many):
+            continue
+        fields_by_name[field.name] = field
+
+    # Handle field name normalization and preserve order
+    result = []
+    seen = set()
+
+    for name in field_names:
+        # Try original name first
+        if name in fields_by_name and name not in seen:
+            result.append(fields_by_name[name])
+            seen.add(name)
+        # Try normalized name (field_id -> field)
+        elif name.endswith('_id') and name[:-3] in fields_by_name and name[:-3] not in seen:
+            result.append(fields_by_name[name[:-3]])
+            seen.add(name[:-3])
+
+    return result
+
+
+def filter_field_names_for_model(model_cls, field_names):
+    """
+    Filter a list of field names to only those that exist on the model.
+
+    Handles field name normalization (e.g., 'field_id' -> 'field').
+
+    Args:
+        model_cls: Django model class
+        field_names: List of field names (strings)
+
+    Returns:
+        List of field names that exist on the model
+    """
+    if not field_names:
+        return []
+
+    # Get all available field names
+    available_names = {field.name for field in model_cls._meta.local_fields}
+
+    result = []
+    for name in field_names:
+        if name in available_names:
+            result.append(name)
+        elif name.endswith('_id') and name[:-3] in available_names:
+            result.append(name[:-3])
+
+    return result
+
+
 def dispatch_hooks_for_operation(changeset, event, bypass_hooks=False):
     """
     Dispatch hooks for an operation using the dispatcher.
@@ -98,3 +188,58 @@ def dispatch_hooks_for_operation(changeset, event, bypass_hooks=False):
 
     dispatcher = get_dispatcher()
     dispatcher.dispatch(changeset, event, bypass_hooks=bypass_hooks)
+
+
+def tag_upsert_metadata(result_objects, existing_record_ids, existing_pks_map):
+    """
+    Tag objects with metadata indicating whether they were created or updated.
+
+    Args:
+        result_objects: List of objects returned from bulk operation
+        existing_record_ids: Set of id() for objects that existed before
+        existing_pks_map: Dict mapping id(obj) -> pk for existing records
+    """
+    existing_pks = set(existing_pks_map.values())
+
+    created_count = 0
+    updated_count = 0
+
+    for obj in result_objects:
+        # Use PK to determine if this record was created or updated
+        was_created = obj.pk not in existing_pks
+        obj._bulk_hooks_was_created = was_created
+        obj._bulk_hooks_upsert_metadata = True
+
+        if was_created:
+            created_count += 1
+        else:
+            updated_count += 1
+
+    logger.info(
+        f"Tagged upsert metadata: {created_count} created, {updated_count} updated "
+        f"(total={len(result_objects)}, existing_pks={len(existing_pks)})"
+    )
+
+
+def was_created(obj):
+    """Check if an object was created in an upsert operation."""
+    return getattr(obj, '_bulk_hooks_was_created', False)
+
+
+def is_upsert_result(obj):
+    """Check if an object has upsert metadata."""
+    return getattr(obj, '_bulk_hooks_upsert_metadata', False)
+
+
+def cleanup_upsert_metadata(objects):
+    """
+    Clean up upsert metadata after hook execution.
+
+    Args:
+        objects: Objects to clean up
+    """
+    for obj in objects:
+        if hasattr(obj, '_bulk_hooks_was_created'):
+            delattr(obj, '_bulk_hooks_was_created')
+        if hasattr(obj, '_bulk_hooks_upsert_metadata'):
+            delattr(obj, '_bulk_hooks_upsert_metadata')

django_bulk_hooks/manager.py

@@ -3,6 +3,20 @@ from django.db import models
 from django_bulk_hooks.queryset import HookQuerySet
 
 
+def _delegate_to_queryset(self, method_name, *args, **kwargs):
+    """
+    Generic delegation to queryset method.
+
+    Args:
+        method_name: Name of the method to call on the queryset
+        *args, **kwargs: Arguments to pass to the method
+
+    Returns:
+        Result of the queryset method call
+    """
+    return getattr(self.get_queryset(), method_name)(*args, **kwargs)
+
+
 class BulkHookManager(models.Manager):
     """
     Manager that provides hook-aware bulk operations.
@@ -47,15 +61,17 @@ class BulkHookManager(models.Manager):
         Delegate to QuerySet's bulk_create implementation.
         This follows Django's pattern where Manager methods call QuerySet methods.
         """
-        return self.get_queryset().bulk_create(
+        return _delegate_to_queryset(
+            self,
+            "bulk_create",
             objs,
-            bypass_hooks=bypass_hooks,
-            bypass_validation=bypass_validation,
             batch_size=batch_size,
             ignore_conflicts=ignore_conflicts,
             update_conflicts=update_conflicts,
             update_fields=update_fields,
             unique_fields=unique_fields,
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
             **kwargs,
         )
 
@@ -77,7 +93,9 @@ class BulkHookManager(models.Manager):
         """
         if fields is not None:
             kwargs["fields"] = fields
-        return self.get_queryset().bulk_update(
+        return _delegate_to_queryset(
+            self,
+            "bulk_update",
             objs,
             bypass_hooks=bypass_hooks,
             bypass_validation=bypass_validation,
@@ -96,11 +114,13 @@ class BulkHookManager(models.Manager):
         Delegate to QuerySet's bulk_delete implementation.
         This follows Django's pattern where Manager methods call QuerySet methods.
         """
-        return self.get_queryset().bulk_delete(
+        return _delegate_to_queryset(
+            self,
+            "bulk_delete",
             objs,
+            batch_size=batch_size,
             bypass_hooks=bypass_hooks,
             bypass_validation=bypass_validation,
-            batch_size=batch_size,
             **kwargs,
         )
 
@@ -109,14 +129,14 @@ class BulkHookManager(models.Manager):
         Delegate to QuerySet's delete implementation.
         This follows Django's pattern where Manager methods call QuerySet methods.
         """
-        return self.get_queryset().delete()
+        return _delegate_to_queryset(self, "delete")
 
     def update(self, **kwargs):
         """
         Delegate to QuerySet's update implementation.
         This follows Django's pattern where Manager methods call QuerySet methods.
         """
-        return self.get_queryset().update(**kwargs)
+        return _delegate_to_queryset(self, "update", **kwargs)
 
     def save(self, obj):
         """

django_bulk_hooks/models.py

@@ -7,7 +7,19 @@ from django_bulk_hooks.manager import BulkHookManager
 logger = logging.getLogger(__name__)
 
 
-class HookModelMixin(models.Model):
+class TimestampMixin(models.Model):
+    """Mixin providing standard created_at and updated_at timestamp fields."""
+
+    created_at = models.DateTimeField(auto_now_add=True, help_text="When this record was created")
+    updated_at = models.DateTimeField(auto_now=True, help_text="When this record was last updated")
+
+    class Meta:
+        abstract = True
+
+
+class HookModelMixin(TimestampMixin, models.Model):
+    """Combined mixin providing timestamps and hook functionality."""
+
     objects = BulkHookManager()
 
     class Meta:

django_bulk_hooks/operations/analyzer.py

@@ -9,6 +9,9 @@ This service handles all model analysis needs:
 
 import logging
 
+from django_bulk_hooks.helpers import extract_pks
+from .field_utils import get_changed_fields, get_auto_fields, get_fk_fields
+
 logger = logging.getLogger(__name__)
 
 
@@ -29,8 +32,40 @@ class ModelAnalyzer:
         """
         self.model_cls = model_cls
 
+    # Define validation requirements per operation
+    VALIDATION_REQUIREMENTS = {
+        "bulk_create": ["types"],
+        "bulk_update": ["types", "has_pks"],
+        "delete": ["types"],
+    }
+
     # ========== Validation Methods ==========
 
+    def validate_for_operation(self, objs, operation):
+        """
+        Centralized validation method that applies operation-specific checks.
+
+        Args:
+            objs: List of model instances
+            operation: String identifier for the operation
+
+        Returns:
+            True if validation passes
+
+        Raises:
+            TypeError: If type validation fails
+            ValueError: If PK validation fails
+        """
+        requirements = self.VALIDATION_REQUIREMENTS.get(operation, [])
+
+        # Apply each required validation check
+        if "types" in requirements:
+            self._check_types(objs, operation)
+        if "has_pks" in requirements:
+            self._check_has_pks(objs, operation)
+
+        return True
+
     def validate_for_create(self, objs):
         """
         Validate objects for bulk_create operation.
@@ -41,8 +76,7 @@ class ModelAnalyzer:
         Raises:
             TypeError: If objects are not instances of model_cls
         """
-        self._check_types(objs, operation="bulk_create")
-        return True
+        return self.validate_for_operation(objs, "bulk_create")
 
     def validate_for_update(self, objs):
         """
@@ -55,9 +89,7 @@ class ModelAnalyzer:
             TypeError: If objects are not instances of model_cls
             ValueError: If objects don't have primary keys
         """
-        self._check_types(objs, operation="bulk_update")
-        self._check_has_pks(objs, operation="bulk_update")
-        return True
+        return self.validate_for_operation(objs, "bulk_update")
 
     def validate_for_delete(self, objs):
         """
@@ -69,8 +101,7 @@ class ModelAnalyzer:
         Raises:
             TypeError: If objects are not instances of model_cls
         """
-        self._check_types(objs, operation="delete")
-        return True
+        return self.validate_for_operation(objs, "delete")
 
     def _check_types(self, objs, operation="operation"):
         """Check that all objects are instances of the model class"""
@@ -109,7 +140,7 @@ class ModelAnalyzer:
         Returns:
             Dict[pk, instance] for O(1) lookups
         """
-        pks = [obj.pk for obj in instances if obj.pk is not None]
+        pks = extract_pks(instances)
         if not pks:
             return {}
 
@@ -124,15 +155,7 @@ class ModelAnalyzer:
         Returns:
             list: Field names with auto_now behavior
         """
-        auto_now_fields = []
-        for field in self.model_cls._meta.fields:
-            if getattr(field, "auto_now", False) or getattr(
-                field,
-                "auto_now_add",
-                False,
-            ):
-                auto_now_fields.append(field.name)
-        return auto_now_fields
+        return get_auto_fields(self.model_cls, include_auto_now_add=True)
 
     def get_fk_fields(self):
         """
@@ -141,7 +164,7 @@ class ModelAnalyzer:
         Returns:
             list: FK field names
         """
-        return [field.name for field in self.model_cls._meta.concrete_fields if field.is_relation and not field.many_to_many]
+        return get_fk_fields(self.model_cls)
 
     def detect_changed_fields(self, objs):
         """
@@ -179,25 +202,9 @@ class ModelAnalyzer:
                 # Object doesn't exist in DB, skip
                 continue
 
-            # Check each field for changes
-            for field in self.model_cls._meta.fields:
-                # Skip primary key and auto fields
-                if field.primary_key or field.auto_created:
-                    continue
-
-                old_val = getattr(old_obj, field.name, None)
-                new_val = getattr(obj, field.name, None)
-
-                # Use field's get_prep_value for proper comparison
-                try:
-                    old_prep = field.get_prep_value(old_val)
-                    new_prep = field.get_prep_value(new_val)
-                    if old_prep != new_prep:
-                        changed_fields_set.add(field.name)
-                except (TypeError, ValueError):
-                    # Fallback to direct comparison
-                    if old_val != new_val:
-                        changed_fields_set.add(field.name)
+            # Use canonical field comparison (skips auto_created fields)
+            changed_fields = get_changed_fields(old_obj, obj, self.model_cls, skip_auto_fields=True)
+            changed_fields_set.update(changed_fields)
 
         # Return as sorted list for deterministic behavior
         return sorted(changed_fields_set)