django-bulk-hooks 0.1.280__py3-none-any.whl → 0.2.1__py3-none-any.whl

django_bulk_hooks/operations/coordinator.py

@@ -0,0 +1,369 @@
+"""
+Bulk operation coordinator - Single entry point for all bulk operations.
+
+This facade hides the complexity of wiring up multiple services and provides
+a clean, simple API for the QuerySet to use.
+"""
+
+import logging
+from django.db import transaction
+from django.db.models import QuerySet as BaseQuerySet
+
+from django_bulk_hooks.helpers import (
+    build_changeset_for_create,
+    build_changeset_for_update,
+    build_changeset_for_delete,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BulkOperationCoordinator:
+    """
+    Single entry point for coordinating bulk operations.
+
+    This coordinator manages all services and provides a clean facade
+    for the QuerySet. It wires up services and coordinates the hook
+    lifecycle for each operation type.
+
+    Services are created lazily and cached.
+    """
+
+    def __init__(self, queryset):
+        """
+        Initialize coordinator for a queryset.
+
+        Args:
+            queryset: Django QuerySet instance
+        """
+        self.queryset = queryset
+        self.model_cls = queryset.model
+
+        # Lazy initialization
+        self._analyzer = None
+        self._mti_handler = None
+        self._executor = None
+        self._dispatcher = None
+
+    @property
+    def analyzer(self):
+        """Get or create ModelAnalyzer"""
+        if self._analyzer is None:
+            from django_bulk_hooks.operations.analyzer import ModelAnalyzer
+
+            self._analyzer = ModelAnalyzer(self.model_cls)
+        return self._analyzer
+
+    @property
+    def mti_handler(self):
+        """Get or create MTIHandler"""
+        if self._mti_handler is None:
+            from django_bulk_hooks.operations.mti_handler import MTIHandler
+
+            self._mti_handler = MTIHandler(self.model_cls)
+        return self._mti_handler
+
+    @property
+    def executor(self):
+        """Get or create BulkExecutor"""
+        if self._executor is None:
+            from django_bulk_hooks.operations.bulk_executor import BulkExecutor
+
+            self._executor = BulkExecutor(
+                queryset=self.queryset,
+                analyzer=self.analyzer,
+                mti_handler=self.mti_handler,
+            )
+        return self._executor
+
+    @property
+    def dispatcher(self):
+        """Get or create Dispatcher"""
+        if self._dispatcher is None:
+            from django_bulk_hooks.dispatcher import get_dispatcher
+
+            self._dispatcher = get_dispatcher()
+        return self._dispatcher
+
+    # ==================== PUBLIC API ====================
+
+    @transaction.atomic
+    def create(
+        self,
+        objs,
+        batch_size=None,
+        ignore_conflicts=False,
+        update_conflicts=False,
+        update_fields=None,
+        unique_fields=None,
+        bypass_hooks=False,
+        bypass_validation=False,
+    ):
+        """
+        Execute bulk create with hooks.
+
+        Args:
+            objs: List of model instances to create
+            batch_size: Number of objects per batch
+            ignore_conflicts: Ignore conflicts if True
+            update_conflicts: Update on conflict if True
+            update_fields: Fields to update on conflict
+            unique_fields: Fields to check for conflicts
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            List of created objects
+        """
+        if not objs:
+            return objs
+
+        # Validate
+        self.analyzer.validate_for_create(objs)
+
+        # Build initial changeset
+        changeset = build_changeset_for_create(
+            self.model_cls,
+            objs,
+            batch_size=batch_size,
+            ignore_conflicts=ignore_conflicts,
+            update_conflicts=update_conflicts,
+            update_fields=update_fields,
+            unique_fields=unique_fields,
+        )
+
+        # Execute with hook lifecycle
+        def operation():
+            return self.executor.bulk_create(
+                objs,
+                batch_size=batch_size,
+                ignore_conflicts=ignore_conflicts,
+                update_conflicts=update_conflicts,
+                update_fields=update_fields,
+                unique_fields=unique_fields,
+            )
+
+        return self.dispatcher.execute_operation_with_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="create",
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
+        )
+
+    @transaction.atomic
+    def update(
+        self,
+        objs,
+        fields,
+        batch_size=None,
+        bypass_hooks=False,
+        bypass_validation=False,
+    ):
+        """
+        Execute bulk update with hooks.
+
+        Args:
+            objs: List of model instances to update
+            fields: List of field names to update
+            batch_size: Number of objects per batch
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Number of objects updated
+        """
+        if not objs:
+            return 0
+
+        # Validate
+        self.analyzer.validate_for_update(objs)
+
+        # Fetch old records using analyzer (single source of truth)
+        old_records_map = self.analyzer.fetch_old_records_map(objs)
+
+        # Build changeset
+        from django_bulk_hooks.changeset import ChangeSet, RecordChange
+
+        changes = [
+            RecordChange(
+                new_record=obj,
+                old_record=old_records_map.get(obj.pk),
+                changed_fields=fields,
+            )
+            for obj in objs
+        ]
+        changeset = ChangeSet(self.model_cls, changes, "update", {"fields": fields})
+
+        # Execute with hook lifecycle
+        def operation():
+            return self.executor.bulk_update(objs, fields, batch_size=batch_size)
+
+        return self.dispatcher.execute_operation_with_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="update",
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
+        )
+
+    @transaction.atomic
+    def update_queryset(
+        self, update_kwargs, bypass_hooks=False, bypass_validation=False
+    ):
+        """
+        Execute queryset update with hooks.
+        
+        ARCHITECTURE: Database-Layer vs Application-Layer Updates
+        ==========================================================
+        
+        Unlike bulk_update(objs), queryset.update() is a pure SQL UPDATE operation.
+        The database evaluates ALL expressions (F(), Subquery, Case, functions, etc.)
+        without Python ever seeing the new values.
+        
+        To maintain Salesforce's hook contract (AFTER hooks see accurate new_records),
+        we ALWAYS refetch instances after the update for AFTER hooks.
+        
+        This is NOT a hack - it respects the fundamental architectural difference:
+        
+        1. queryset.update():  Database evaluates → Must refetch for AFTER hooks
+        2. bulk_update(objs):  Python has values → No refetch needed
+        
+        The refetch handles ALL database-level changes:
+        - F() expressions: F('count') + 1
+        - Subquery: Subquery(related.aggregate(...))
+        - Case/When: Case(When(status='A', then=Value('Active')))
+        - Database functions: Upper('name'), Concat(...)
+        - Database hooks/defaults
+        - Any other DB-evaluated expression
+        
+        Trade-off:
+        - Cost: 1 extra SELECT query per queryset.update() call
+        - Benefit: 100% correctness for ALL database expressions
+
+        Args:
+            update_kwargs: Dict of fields to update
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Number of objects updated
+        """
+        # Fetch instances BEFORE update
+        instances = list(self.queryset)
+        if not instances:
+            return 0
+
+        # Fetch old records for comparison (single bulk query)
+        old_records_map = self.analyzer.fetch_old_records_map(instances)
+
+        # Build changeset for VALIDATE and BEFORE hooks
+        # These see pre-update state, which is correct
+        changeset_before = build_changeset_for_update(
+            self.model_cls,
+            instances,
+            update_kwargs,
+            old_records_map=old_records_map,
+        )
+
+        if bypass_hooks:
+            # No hooks - just execute the update
+            return BaseQuerySet.update(self.queryset, **update_kwargs)
+
+        # Execute VALIDATE and BEFORE hooks
+        if not bypass_validation:
+            self.dispatcher.dispatch(changeset_before, "validate_update", bypass_hooks=False)
+        self.dispatcher.dispatch(changeset_before, "before_update", bypass_hooks=False)
+
+        # Execute the actual database UPDATE
+        # Database evaluates all expressions here (Subquery, F(), etc.)
+        result = BaseQuerySet.update(self.queryset, **update_kwargs)
+
+        # Refetch instances to get actual post-update values from database
+        # This ensures AFTER hooks see the real final state
+        pks = [obj.pk for obj in instances]
+        refetched_instances = list(
+            self.model_cls.objects.filter(pk__in=pks)
+        )
+
+        # Build changeset for AFTER hooks with accurate new values
+        changeset_after = build_changeset_for_update(
+            self.model_cls,
+            refetched_instances,  # Fresh from database
+            update_kwargs,
+            old_records_map=old_records_map,  # Still have old values for comparison
+        )
+
+        # Execute AFTER hooks with accurate new_records
+        self.dispatcher.dispatch(changeset_after, "after_update", bypass_hooks=False)
+
+        return result
+
+    @transaction.atomic
+    def delete(self, bypass_hooks=False, bypass_validation=False):
+        """
+        Execute delete with hooks.
+
+        Args:
+            bypass_hooks: Skip all hooks if True
+            bypass_validation: Skip validation hooks if True
+
+        Returns:
+            Tuple of (count, details dict)
+        """
+        # Get objects
+        objs = list(self.queryset)
+        if not objs:
+            return 0, {}
+
+        # Validate
+        self.analyzer.validate_for_delete(objs)
+
+        # Build changeset
+        changeset = build_changeset_for_delete(self.model_cls, objs)
+
+        # Execute with hook lifecycle
+        def operation():
+            # Call base Django QuerySet.delete() to avoid recursion
+            return BaseQuerySet.delete(self.queryset)
+
+        return self.dispatcher.execute_operation_with_hooks(
+            changeset=changeset,
+            operation=operation,
+            event_prefix="delete",
+            bypass_hooks=bypass_hooks,
+            bypass_validation=bypass_validation,
+        )
+
+    def clean(self, objs, is_create=None):
+        """
+        Execute validation hooks only (no database operations).
+
+        This is used by Django's clean() method to hook VALIDATE_* events
+        without performing the actual operation.
+
+        Args:
+            objs: List of model instances to validate
+            is_create: True for create, False for update, None to auto-detect
+
+        Returns:
+            None
+        """
+        if not objs:
+            return
+
+        # Auto-detect if is_create not specified
+        if is_create is None:
+            is_create = objs[0].pk is None
+
+        # Build changeset based on operation type
+        if is_create:
+            changeset = build_changeset_for_create(self.model_cls, objs)
+            event = "validate_create"
+        else:
+            # For update validation, no old records needed - hooks handle their own queries
+            changeset = build_changeset_for_update(self.model_cls, objs, {})
+            event = "validate_update"
+
+        # Dispatch validation event only
+        self.dispatcher.dispatch(changeset, event, bypass_hooks=False)

django_bulk_hooks/operations/mti_handler.py

@@ -0,0 +1,103 @@
+"""
+Multi-table inheritance (MTI) handler service.
+
+Handles detection and coordination of multi-table inheritance operations.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class MTIHandler:
+    """
+    Handles multi-table inheritance (MTI) operations.
+
+    This service detects MTI models and provides the inheritance chain
+    for coordinating parent/child table operations.
+    """
+
+    def __init__(self, model_cls):
+        """
+        Initialize MTI handler for a specific model.
+
+        Args:
+            model_cls: The Django model class
+        """
+        self.model_cls = model_cls
+        self._inheritance_chain = None
+
+    def is_mti_model(self):
+        """
+        Determine if the model uses multi-table inheritance.
+
+        Returns:
+            bool: True if model has concrete parent models
+        """
+        for parent in self.model_cls._meta.all_parents:
+            if parent._meta.concrete_model != self.model_cls._meta.concrete_model:
+                return True
+        return False
+
+    def get_inheritance_chain(self):
+        """
+        Get the complete inheritance chain from root to child.
+
+        Returns:
+            list: Model classes ordered from root parent to current model
+                 Returns empty list if not MTI model
+        """
+        if self._inheritance_chain is None:
+            self._inheritance_chain = self._compute_chain()
+        return self._inheritance_chain
+
+    def _compute_chain(self):
+        """
+        Compute the inheritance chain by walking up the parent hierarchy.
+
+        Returns:
+            list: Model classes in order [RootParent, Parent, Child]
+        """
+        chain = []
+        current_model = self.model_cls
+
+        while current_model:
+            if not current_model._meta.proxy:
+                chain.append(current_model)
+
+            # Get concrete parent models
+            parents = [
+                parent
+                for parent in current_model._meta.parents.keys()
+                if not parent._meta.proxy
+            ]
+
+            current_model = parents[0] if parents else None
+
+        # Reverse to get root-to-child order
+        chain.reverse()
+        return chain
+
+    def get_parent_models(self):
+        """
+        Get all parent models in the inheritance chain.
+
+        Returns:
+            list: Parent model classes (excludes current model)
+        """
+        chain = self.get_inheritance_chain()
+        if len(chain) <= 1:
+            return []
+        return chain[:-1]  # All except current model
+
+    def get_local_fields_for_model(self, model_cls):
+        """
+        Get fields defined directly on a specific model in the chain.
+
+        Args:
+            model_cls: Model class to get fields for
+
+        Returns:
+            list: Field objects defined on this model
+        """
+        return list(model_cls._meta.local_fields)