django-bulk-hooks 0.2.1__tar.gz → 0.2.2__tar.gz

{django_bulk_hooks-0.2.1 → django_bulk_hooks-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.2.1
+Version: 0.2.2
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks

django_bulk_hooks-0.2.2/django_bulk_hooks/operations/bulk_executor.py

@@ -0,0 +1,430 @@
+"""
+Bulk executor service for database operations.
+
+This service coordinates bulk database operations with validation and MTI handling.
+"""
+
+import logging
+from django.db import transaction
+from django.db.models import AutoField
+
+logger = logging.getLogger(__name__)
+
+
+class BulkExecutor:
+    """
+    Executes bulk database operations.
+
+    This service coordinates validation, MTI handling, and actual database
+    operations. It's the only service that directly calls Django ORM methods.
+
+    Dependencies are explicitly injected via constructor.
+    """
+
+    def __init__(self, queryset, analyzer, mti_handler):
+        """
+        Initialize bulk executor with explicit dependencies.
+
+        Args:
+            queryset: Django QuerySet instance
+            analyzer: ModelAnalyzer instance (replaces validator + field_tracker)
+            mti_handler: MTIHandler instance
+        """
+        self.queryset = queryset
+        self.analyzer = analyzer
+        self.mti_handler = mti_handler
+        self.model_cls = queryset.model
+
+    def bulk_create(
+        self,
+        objs,
+        batch_size=None,
+        ignore_conflicts=False,
+        update_conflicts=False,
+        update_fields=None,
+        unique_fields=None,
+        **kwargs,
+    ):
+        """
+        Execute bulk create operation.
+
+        NOTE: Coordinator is responsible for validation before calling this method.
+        This executor trusts that inputs have already been validated.
+
+        Args:
+            objs: List of model instances to create (pre-validated)
+            batch_size: Number of objects to create per batch
+            ignore_conflicts: Whether to ignore conflicts
+            update_conflicts: Whether to update on conflict
+            update_fields: Fields to update on conflict
+            unique_fields: Fields to use for conflict detection
+            **kwargs: Additional arguments
+
+        Returns:
+            List of created objects
+        """
+        if not objs:
+            return objs
+
+        # Check if this is an MTI model and route accordingly
+        if self.mti_handler.is_mti_model():
+            logger.info(f"Detected MTI model {self.model_cls.__name__}, using MTI bulk create")
+            # Build execution plan
+            plan = self.mti_handler.build_create_plan(
+                objs,
+                batch_size=batch_size,
+                update_conflicts=update_conflicts,
+                update_fields=update_fields,
+                unique_fields=unique_fields,
+            )
+            # Execute the plan
+            return self._execute_mti_create_plan(plan)
+
+        # Non-MTI model - use Django's native bulk_create
+        return self._execute_bulk_create(
+            objs,
+            batch_size,
+            ignore_conflicts,
+            update_conflicts,
+            update_fields,
+            unique_fields,
+            **kwargs,
+        )
+
+    def _execute_bulk_create(
+        self,
+        objs,
+        batch_size=None,
+        ignore_conflicts=False,
+        update_conflicts=False,
+        update_fields=None,
+        unique_fields=None,
+        **kwargs,
+    ):
+        """
+        Execute the actual Django bulk_create.
+
+        This is the only method that directly calls Django ORM.
+        We must call the base Django QuerySet to avoid recursion.
+        """
+        from django.db.models import QuerySet
+
+        # Create a base Django queryset (not our HookQuerySet)
+        base_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
+
+        return base_qs.bulk_create(
+            objs,
+            batch_size=batch_size,
+            ignore_conflicts=ignore_conflicts,
+            update_conflicts=update_conflicts,
+            update_fields=update_fields,
+            unique_fields=unique_fields,
+        )
+
+    def bulk_update(self, objs, fields, batch_size=None):
+        """
+        Execute bulk update operation.
+
+        NOTE: Coordinator is responsible for validation before calling this method.
+        This executor trusts that inputs have already been validated.
+
+        Args:
+            objs: List of model instances to update (pre-validated)
+            fields: List of field names to update
+            batch_size: Number of objects to update per batch
+
+        Returns:
+            Number of objects updated
+        """
+        if not objs:
+            return 0
+
+        # Check if this is an MTI model and route accordingly
+        if self.mti_handler.is_mti_model():
+            logger.info(f"Detected MTI model {self.model_cls.__name__}, using MTI bulk update")
+            # Build execution plan
+            plan = self.mti_handler.build_update_plan(objs, fields, batch_size=batch_size)
+            # Execute the plan
+            return self._execute_mti_update_plan(plan)
+
+        # Non-MTI model - use Django's native bulk_update
+        # Validation already done by coordinator
+        from django.db.models import QuerySet
+
+        base_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
+        return base_qs.bulk_update(objs, fields, batch_size=batch_size)
+
+    # ==================== MTI PLAN EXECUTION ====================
+
+    def _execute_mti_create_plan(self, plan):
+        """
+        Execute an MTI create plan.
+        
+        This is where ALL database operations happen for MTI bulk_create.
+        
+        Args:
+            plan: MTICreatePlan object from MTIHandler
+            
+        Returns:
+            List of created objects with PKs assigned
+        """
+        from django.db import transaction
+        from django.db.models import QuerySet as BaseQuerySet
+        
+        if not plan:
+            return []
+        
+        with transaction.atomic(using=self.queryset.db, savepoint=False):
+            # Step 1: Create all parent objects level by level
+            parent_instances_map = {}  # Maps original obj id() -> {model: parent_instance}
+            
+            for parent_level in plan.parent_levels:
+                # Bulk create parents for this level
+                bulk_kwargs = {"batch_size": len(parent_level.objects)}
+                
+                if parent_level.update_conflicts:
+                    bulk_kwargs["update_conflicts"] = True
+                    bulk_kwargs["unique_fields"] = parent_level.unique_fields
+                    bulk_kwargs["update_fields"] = parent_level.update_fields
+                
+                # Use base QuerySet to avoid recursion
+                base_qs = BaseQuerySet(model=parent_level.model_class, using=self.queryset.db)
+                created_parents = base_qs.bulk_create(parent_level.objects, **bulk_kwargs)
+                
+                # Copy generated fields back to parent objects
+                for created_parent, parent_obj in zip(created_parents, parent_level.objects):
+                    for field in parent_level.model_class._meta.local_fields:
+                        created_value = getattr(created_parent, field.name, None)
+                        if created_value is not None:
+                            setattr(parent_obj, field.name, created_value)
+                    
+                    parent_obj._state.adding = False
+                    parent_obj._state.db = self.queryset.db
+                
+                # Map parents back to original objects
+                for parent_obj in parent_level.objects:
+                    orig_obj_id = parent_level.original_object_map[id(parent_obj)]
+                    if orig_obj_id not in parent_instances_map:
+                        parent_instances_map[orig_obj_id] = {}
+                    parent_instances_map[orig_obj_id][parent_level.model_class] = parent_obj
+            
+            # Step 2: Add parent links to child objects
+            for child_obj, orig_obj in zip(plan.child_objects, plan.original_objects):
+                parent_instances = parent_instances_map.get(id(orig_obj), {})
+                
+                for parent_model, parent_instance in parent_instances.items():
+                    parent_link = plan.child_model._meta.get_ancestor_link(parent_model)
+                    if parent_link:
+                        setattr(child_obj, parent_link.attname, parent_instance.pk)
+                        setattr(child_obj, parent_link.name, parent_instance)
+            
+            # Step 3: Bulk create child objects using _batched_insert (to bypass MTI check)
+            base_qs = BaseQuerySet(model=plan.child_model, using=self.queryset.db)
+            base_qs._prepare_for_bulk_create(plan.child_objects)
+            
+            # Partition objects by PK status
+            objs_without_pk, objs_with_pk = [], []
+            for obj in plan.child_objects:
+                if obj._is_pk_set():
+                    objs_with_pk.append(obj)
+                else:
+                    objs_without_pk.append(obj)
+            
+            # Get fields for insert
+            opts = plan.child_model._meta
+            fields = [f for f in opts.local_fields if not f.generated]
+            
+            # Execute bulk insert
+            if objs_with_pk:
+                returned_columns = base_qs._batched_insert(
+                    objs_with_pk,
+                    fields,
+                    batch_size=len(objs_with_pk),
+                )
+                if returned_columns:
+                    for obj, results in zip(objs_with_pk, returned_columns):
+                        if hasattr(opts, "db_returning_fields") and hasattr(opts, "pk"):
+                            for result, field in zip(results, opts.db_returning_fields):
+                                if field != opts.pk:
+                                    setattr(obj, field.attname, result)
+                        obj._state.adding = False
+                        obj._state.db = self.queryset.db
+                else:
+                    for obj in objs_with_pk:
+                        obj._state.adding = False
+                        obj._state.db = self.queryset.db
+            
+            if objs_without_pk:
+                filtered_fields = [
+                    f for f in fields
+                    if not isinstance(f, AutoField) and not f.primary_key
+                ]
+                returned_columns = base_qs._batched_insert(
+                    objs_without_pk,
+                    filtered_fields,
+                    batch_size=len(objs_without_pk),
+                )
+                if returned_columns:
+                    for obj, results in zip(objs_without_pk, returned_columns):
+                        if hasattr(opts, "db_returning_fields"):
+                            for result, field in zip(results, opts.db_returning_fields):
+                                setattr(obj, field.attname, result)
+                        obj._state.adding = False
+                        obj._state.db = self.queryset.db
+                else:
+                    for obj in objs_without_pk:
+                        obj._state.adding = False
+                        obj._state.db = self.queryset.db
+            
+            created_children = plan.child_objects
+            
+            # Step 4: Copy PKs and auto-generated fields back to original objects
+            pk_field_name = plan.child_model._meta.pk.name
+            
+            for orig_obj, child_obj in zip(plan.original_objects, created_children):
+                # Copy PK
+                child_pk = getattr(child_obj, pk_field_name)
+                setattr(orig_obj, pk_field_name, child_pk)
+                
+                # Copy auto-generated fields from all levels
+                parent_instances = parent_instances_map.get(id(orig_obj), {})
+                
+                for model_class in plan.inheritance_chain:
+                    # Get source object for this level
+                    if model_class in parent_instances:
+                        source_obj = parent_instances[model_class]
+                    elif model_class == plan.child_model:
+                        source_obj = child_obj
+                    else:
+                        continue
+                    
+                    # Copy auto-generated field values
+                    for field in model_class._meta.local_fields:
+                        if field.name == pk_field_name:
+                            continue
+                        
+                        # Skip parent link fields
+                        if hasattr(field, 'remote_field') and field.remote_field:
+                            parent_link = plan.child_model._meta.get_ancestor_link(model_class)
+                            if parent_link and field.name == parent_link.name:
+                                continue
+                        
+                        # Copy auto_now_add, auto_now, and db_returning fields
+                        if (getattr(field, 'auto_now_add', False) or 
+                            getattr(field, 'auto_now', False) or
+                            getattr(field, 'db_returning', False)):
+                            source_value = getattr(source_obj, field.name, None)
+                            if source_value is not None:
+                                setattr(orig_obj, field.name, source_value)
+                
+                # Update object state
+                orig_obj._state.adding = False
+                orig_obj._state.db = self.queryset.db
+        
+        return plan.original_objects
+
+    def _execute_mti_update_plan(self, plan):
+        """
+        Execute an MTI update plan.
+        
+        Updates each table in the inheritance chain using CASE/WHEN for bulk updates.
+        
+        Args:
+            plan: MTIUpdatePlan object from MTIHandler
+            
+        Returns:
+            Number of objects updated
+        """
+        from django.db import transaction
+        from django.db.models import Case, Value, When, QuerySet as BaseQuerySet
+        
+        if not plan:
+            return 0
+        
+        total_updated = 0
+        
+        # Get PKs for filtering
+        root_pks = [
+            getattr(obj, "pk", None) or getattr(obj, "id", None) 
+            for obj in plan.objects 
+            if getattr(obj, "pk", None) or getattr(obj, "id", None)
+        ]
+        
+        if not root_pks:
+            return 0
+        
+        with transaction.atomic(using=self.queryset.db, savepoint=False):
+            # Update each table in the chain
+            for field_group in plan.field_groups:
+                if not field_group.fields:
+                    continue
+                
+                base_qs = BaseQuerySet(model=field_group.model_class, using=self.queryset.db)
+                
+                # Check if records exist
+                existing_count = base_qs.filter(**{f"{field_group.filter_field}__in": root_pks}).count()
+                if existing_count == 0:
+                    continue
+                
+                # Build CASE statements for bulk update
+                case_statements = {}
+                for field_name in field_group.fields:
+                    field = field_group.model_class._meta.get_field(field_name)
+                    
+                    # Use column name for FK fields
+                    if getattr(field, 'is_relation', False) and hasattr(field, 'attname'):
+                        db_field_name = field.attname
+                        target_field = field.target_field
+                    else:
+                        db_field_name = field_name
+                        target_field = field
+                    
+                    when_statements = []
+                    for pk, obj in zip(root_pks, plan.objects):
+                        obj_pk = getattr(obj, "pk", None) or getattr(obj, "id", None)
+                        if obj_pk is None:
+                            continue
+                        
+                        value = getattr(obj, db_field_name)
+                        when_statements.append(
+                            When(
+                                **{field_group.filter_field: pk},
+                                then=Value(value, output_field=target_field),
+                            )
+                        )
+                    
+                    if when_statements:
+                        case_statements[db_field_name] = Case(
+                            *when_statements, output_field=target_field
+                        )
+                
+                # Execute bulk update
+                if case_statements:
+                    try:
+                        updated_count = base_qs.filter(
+                            **{f"{field_group.filter_field}__in": root_pks}
+                        ).update(**case_statements)
+                        total_updated += updated_count
+                    except Exception as e:
+                        logger.error(f"MTI bulk update failed for {field_group.model_class.__name__}: {e}")
+        
+        return total_updated
+
+    def delete_queryset(self):
+        """
+        Execute delete on the queryset.
+
+        NOTE: Coordinator is responsible for validation before calling this method.
+        This executor trusts that inputs have already been validated.
+
+        Returns:
+            Tuple of (count, details dict)
+        """
+        if not self.queryset:
+            return 0, {}
+
+        # Execute delete via QuerySet
+        # Validation already done by coordinator
+        from django.db.models import QuerySet
+
+        return QuerySet.delete(self.queryset)

django_bulk_hooks-0.2.2/django_bulk_hooks/operations/mti_handler.py

@@ -0,0 +1,473 @@
+"""
+Multi-table inheritance (MTI) handler service.
+
+Handles detection and planning for multi-table inheritance operations.
+
+This handler is PURE LOGIC - it does not execute database operations.
+It returns plans (data structures) that the BulkExecutor executes.
+"""
+
+import logging
+from django.db.models import AutoField
+
+logger = logging.getLogger(__name__)
+
+
+class MTIHandler:
+    """
+    Handles multi-table inheritance (MTI) operation planning.
+
+    This service detects MTI models and builds execution plans.
+    It does NOT execute database operations - that's the BulkExecutor's job.
+    
+    Responsibilities:
+    - Detect MTI models
+    - Build inheritance chains
+    - Create parent/child instances (in-memory only)
+    - Return execution plans
+    """
+
+    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)
+
+    # ==================== MTI BULK CREATE PLANNING ====================
+
+    def build_create_plan(
+        self,
+        objs,
+        batch_size=None,
+        update_conflicts=False,
+        unique_fields=None,
+        update_fields=None,
+    ):
+        """
+        Build an execution plan for bulk creating MTI model instances.
+        
+        This method does NOT execute any database operations.
+        It returns a plan that the BulkExecutor will execute.
+        
+        Args:
+            objs: List of model instances to create
+            batch_size: Number of objects per batch
+            update_conflicts: Enable UPSERT on conflict
+            unique_fields: Fields for conflict detection
+            update_fields: Fields to update on conflict
+            
+        Returns:
+            MTICreatePlan object
+        """
+        from django_bulk_hooks.operations.mti_plans import MTICreatePlan, ParentLevel
+        
+        if not objs:
+            return None
+        
+        inheritance_chain = self.get_inheritance_chain()
+        if len(inheritance_chain) <= 1:
+            raise ValueError("build_create_plan called on non-MTI model")
+        
+        batch_size = batch_size or len(objs)
+        
+        # Build parent levels
+        parent_levels = self._build_parent_levels(
+            objs,
+            inheritance_chain,
+            update_conflicts=update_conflicts,
+            unique_fields=unique_fields,
+            update_fields=update_fields,
+        )
+        
+        # Build child object templates (without parent links - executor adds them)
+        child_objects = []
+        for obj in objs:
+            child_obj = self._create_child_instance_template(obj, inheritance_chain[-1])
+            child_objects.append(child_obj)
+        
+        return MTICreatePlan(
+            inheritance_chain=inheritance_chain,
+            parent_levels=parent_levels,
+            child_objects=child_objects,
+            child_model=inheritance_chain[-1],
+            original_objects=objs,
+            batch_size=batch_size,
+        )
+
+    def _build_parent_levels(
+        self,
+        objs,
+        inheritance_chain,
+        update_conflicts=False,
+        unique_fields=None,
+        update_fields=None,
+    ):
+        """
+        Build parent level objects for each level in the inheritance chain.
+        
+        This is pure in-memory object creation - no DB operations.
+        
+        Returns:
+            List of ParentLevel objects
+        """
+        from django_bulk_hooks.operations.mti_plans import ParentLevel
+        
+        parent_levels = []
+        parent_instances_map = {}  # Maps obj id() -> {model_class: parent_instance}
+        
+        for level_idx, model_class in enumerate(inheritance_chain[:-1]):
+            parent_objs_for_level = []
+            
+            for obj in objs:
+                # Get current parent from previous level
+                current_parent = None
+                if level_idx > 0:
+                    prev_parents = parent_instances_map.get(id(obj), {})
+                    current_parent = prev_parents.get(inheritance_chain[level_idx - 1])
+                
+                # Create parent instance
+                parent_obj = self._create_parent_instance(obj, model_class, current_parent)
+                parent_objs_for_level.append(parent_obj)
+                
+                # Store in map
+                if id(obj) not in parent_instances_map:
+                    parent_instances_map[id(obj)] = {}
+                parent_instances_map[id(obj)][model_class] = parent_obj
+            
+            # Determine upsert parameters for this level
+            level_update_conflicts = False
+            level_unique_fields = []
+            level_update_fields = []
+            
+            if update_conflicts and unique_fields:
+                # Filter unique_fields and update_fields to only those in this model
+                model_fields_by_name = {f.name: f for f in model_class._meta.local_fields}
+                
+                # Normalize unique fields
+                normalized_unique = []
+                for uf in unique_fields or []:
+                    if uf in model_fields_by_name:
+                        normalized_unique.append(uf)
+                    elif uf.endswith("_id") and uf[:-3] in model_fields_by_name:
+                        normalized_unique.append(uf[:-3])
+                
+                # Check if this model has a matching constraint
+                if normalized_unique and self._has_matching_constraint(model_class, normalized_unique):
+                    # Filter update fields
+                    filtered_updates = [
+                        uf for uf in (update_fields or []) if uf in model_fields_by_name
+                    ]
+                    
+                    if filtered_updates:
+                        level_update_conflicts = True
+                        level_unique_fields = normalized_unique
+                        level_update_fields = filtered_updates
+            
+            # Create parent level
+            parent_level = ParentLevel(
+                model_class=model_class,
+                objects=parent_objs_for_level,
+                original_object_map={id(p): id(o) for p, o in zip(parent_objs_for_level, objs)},
+                update_conflicts=level_update_conflicts,
+                unique_fields=level_unique_fields,
+                update_fields=level_update_fields,
+            )
+            parent_levels.append(parent_level)
+        
+        return parent_levels
+
+    def _has_matching_constraint(self, model_class, normalized_unique):
+        """Check if model has a unique constraint matching the given fields."""
+        try:
+            from django.db.models import UniqueConstraint
+            constraint_field_sets = [
+                tuple(c.fields) for c in model_class._meta.constraints 
+                if isinstance(c, UniqueConstraint)
+            ]
+        except Exception:
+            constraint_field_sets = []
+        
+        # Check unique_together
+        ut = getattr(model_class._meta, "unique_together", ()) or ()
+        if isinstance(ut, tuple) and ut and not isinstance(ut[0], (list, tuple)):
+            ut = (ut,)
+        ut_field_sets = [tuple(group) for group in ut]
+        
+        # Compare as sets
+        provided_set = set(normalized_unique)
+        for group in constraint_field_sets + ut_field_sets:
+            if provided_set == set(group):
+                return True
+        return False
+
+    def _create_parent_instance(self, source_obj, parent_model, current_parent):
+        """
+        Create a parent instance from source object (in-memory only).
+        
+        Args:
+            source_obj: Original object with data
+            parent_model: Parent model class to create instance of
+            current_parent: Parent instance from previous level (if any)
+            
+        Returns:
+            Parent model instance (not saved)
+        """
+        parent_obj = parent_model()
+        
+        # Copy field values from source
+        for field in parent_model._meta.local_fields:
+            if hasattr(source_obj, field.name):
+                value = getattr(source_obj, field.name, None)
+                if value is not None:
+                    if (field.is_relation and not field.many_to_many and 
+                        not field.one_to_many):
+                        # Handle FK fields
+                        if hasattr(value, "pk") and value.pk is not None:
+                            setattr(parent_obj, field.attname, value.pk)
+                        else:
+                            setattr(parent_obj, field.attname, value)
+                    else:
+                        setattr(parent_obj, field.name, value)
+        
+        # Link to parent if exists
+        if current_parent is not None:
+            for field in parent_model._meta.local_fields:
+                if (hasattr(field, "remote_field") and field.remote_field and
+                    field.remote_field.model == current_parent.__class__):
+                    setattr(parent_obj, field.name, current_parent)
+                    break
+        
+        # Copy object state
+        if hasattr(source_obj, '_state') and hasattr(parent_obj, '_state'):
+            parent_obj._state.adding = source_obj._state.adding
+            if hasattr(source_obj._state, 'db'):
+                parent_obj._state.db = source_obj._state.db
+        
+        # Handle auto_now_add and auto_now fields
+        for field in parent_model._meta.local_fields:
+            if getattr(field, 'auto_now_add', False):
+                if getattr(parent_obj, field.name) is None:
+                    field.pre_save(parent_obj, add=True)
+                    setattr(parent_obj, field.attname, field.value_from_object(parent_obj))
+            elif getattr(field, 'auto_now', False):
+                field.pre_save(parent_obj, add=True)
+        
+        return parent_obj
+
+    def _create_child_instance_template(self, source_obj, child_model):
+        """
+        Create a child instance template (in-memory only, without parent links).
+        
+        The executor will add parent links after creating parent objects.
+        
+        Args:
+            source_obj: Original object with data
+            child_model: Child model class
+            
+        Returns:
+            Child model instance (not saved, no parent links)
+        """
+        child_obj = child_model()
+        
+        # Copy field values (excluding AutoField and parent links)
+        for field in child_model._meta.local_fields:
+            if isinstance(field, AutoField):
+                continue
+            
+            # Skip parent link fields - executor will set these
+            if field.is_relation and hasattr(field, 'related_model'):
+                # Check if this field is a parent link
+                if child_model._meta.get_ancestor_link(field.related_model) == field:
+                    continue
+            
+            if hasattr(source_obj, field.name):
+                value = getattr(source_obj, field.name, None)
+                if value is not None:
+                    if (field.is_relation and not field.many_to_many and 
+                        not field.one_to_many):
+                        if hasattr(value, "pk") and value.pk is not None:
+                            setattr(child_obj, field.attname, value.pk)
+                        else:
+                            setattr(child_obj, field.attname, value)
+                    else:
+                        setattr(child_obj, field.name, value)
+        
+        # Copy object state
+        if hasattr(source_obj, '_state') and hasattr(child_obj, '_state'):
+            child_obj._state.adding = source_obj._state.adding
+            if hasattr(source_obj._state, 'db'):
+                child_obj._state.db = source_obj._state.db
+        
+        # Handle auto_now_add and auto_now fields
+        for field in child_model._meta.local_fields:
+            if getattr(field, 'auto_now_add', False):
+                if getattr(child_obj, field.name) is None:
+                    field.pre_save(child_obj, add=True)
+                    setattr(child_obj, field.attname, field.value_from_object(child_obj))
+            elif getattr(field, 'auto_now', False):
+                field.pre_save(child_obj, add=True)
+        
+        return child_obj
+
+    # ==================== MTI BULK UPDATE PLANNING ====================
+
+    def build_update_plan(self, objs, fields, batch_size=None):
+        """
+        Build an execution plan for bulk updating MTI model instances.
+        
+        This method does NOT execute any database operations.
+        
+        Args:
+            objs: List of model instances to update
+            fields: List of field names to update
+            batch_size: Number of objects per batch
+            
+        Returns:
+            MTIUpdatePlan object
+        """
+        from django_bulk_hooks.operations.mti_plans import MTIUpdatePlan, ModelFieldGroup
+        
+        if not objs:
+            return None
+        
+        inheritance_chain = self.get_inheritance_chain()
+        if len(inheritance_chain) <= 1:
+            raise ValueError("build_update_plan called on non-MTI model")
+        
+        batch_size = batch_size or len(objs)
+        
+        # Handle auto_now fields
+        for obj in objs:
+            for model in inheritance_chain:
+                for field in model._meta.local_fields:
+                    if getattr(field, 'auto_now', False):
+                        field.pre_save(obj, add=False)
+        
+        # Add auto_now fields to update list
+        auto_now_fields = set()
+        for model in inheritance_chain:
+            for field in model._meta.local_fields:
+                if getattr(field, 'auto_now', False):
+                    auto_now_fields.add(field.name)
+        
+        all_fields = list(fields) + list(auto_now_fields)
+        
+        # Group fields by model
+        field_groups = []
+        for model_idx, model in enumerate(inheritance_chain):
+            model_fields = []
+            
+            for field_name in all_fields:
+                try:
+                    field = self.model_cls._meta.get_field(field_name)
+                    if field in model._meta.local_fields:
+                        # Skip auto_now_add fields for updates
+                        if not getattr(field, 'auto_now_add', False):
+                            model_fields.append(field_name)
+                except Exception:
+                    continue
+            
+            if model_fields:
+                # Determine filter field
+                if model_idx == 0:
+                    filter_field = "pk"
+                else:
+                    # Find parent link
+                    parent_link = None
+                    for parent_model in inheritance_chain:
+                        if parent_model in model._meta.parents:
+                            parent_link = model._meta.parents[parent_model]
+                            break
+                    filter_field = parent_link.attname if parent_link else "pk"
+                
+                field_groups.append(ModelFieldGroup(
+                    model_class=model,
+                    fields=model_fields,
+                    filter_field=filter_field,
+                ))
+        
+        return MTIUpdatePlan(
+            inheritance_chain=inheritance_chain,
+            field_groups=field_groups,
+            objects=objs,
+            batch_size=batch_size,
+        )

django_bulk_hooks-0.2.2/django_bulk_hooks/operations/mti_plans.py

@@ -0,0 +1,87 @@
+"""
+MTI operation plans - Data structures for multi-table inheritance operations.
+
+These are pure data structures returned by MTIHandler to be executed by BulkExecutor.
+This separates planning (logic) from execution (database operations).
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Any
+
+
+@dataclass
+class ParentLevel:
+    """
+    Represents one level in the parent hierarchy for MTI bulk create.
+    
+    Attributes:
+        model_class: The parent model class for this level
+        objects: List of parent instances to create
+        original_object_map: Maps parent instance id() -> original object id()
+        update_conflicts: Whether to enable UPSERT for this level
+        unique_fields: Fields for conflict detection (if update_conflicts=True)
+        update_fields: Fields to update on conflict (if update_conflicts=True)
+    """
+    model_class: Any
+    objects: List[Any]
+    original_object_map: Dict[int, int] = field(default_factory=dict)
+    update_conflicts: bool = False
+    unique_fields: List[str] = field(default_factory=list)
+    update_fields: List[str] = field(default_factory=list)
+
+
+@dataclass
+class MTICreatePlan:
+    """
+    Plan for executing bulk_create on an MTI model.
+    
+    This plan describes WHAT to create, not HOW to create it.
+    The executor is responsible for executing this plan.
+    
+    Attributes:
+        inheritance_chain: List of model classes from root to child
+        parent_levels: List of ParentLevel objects, one per parent model
+        child_objects: List of child instances to create (not yet with parent links)
+        child_model: The child model class
+        original_objects: Original objects provided by user
+        batch_size: Batch size for operations
+    """
+    inheritance_chain: List[Any]
+    parent_levels: List[ParentLevel]
+    child_objects: List[Any]
+    child_model: Any
+    original_objects: List[Any]
+    batch_size: int = None
+
+
+@dataclass
+class ModelFieldGroup:
+    """
+    Represents fields to update for one model in the inheritance chain.
+    
+    Attributes:
+        model_class: The model class
+        fields: List of field names to update on this model
+        filter_field: Field to use for filtering (e.g., 'pk' or parent link attname)
+    """
+    model_class: Any
+    fields: List[str]
+    filter_field: str = "pk"
+
+
+@dataclass
+class MTIUpdatePlan:
+    """
+    Plan for executing bulk_update on an MTI model.
+    
+    Attributes:
+        inheritance_chain: List of model classes from root to child
+        field_groups: List of ModelFieldGroup objects
+        objects: Objects to update
+        batch_size: Batch size for operations
+    """
+    inheritance_chain: List[Any]
+    field_groups: List[ModelFieldGroup]
+    objects: List[Any]
+    batch_size: int = None
+

{django_bulk_hooks-0.2.1 → django_bulk_hooks-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.2.1"
+version = "0.2.2"
 description = "Hook-style hooks for Django bulk operations like bulk_create and bulk_update."
 authors = ["Konrad Beck <konrad.beck@merchantcapital.co.za>"]
 readme = "README.md"

django_bulk_hooks-0.2.1/django_bulk_hooks/operations/bulk_executor.py

@@ -1,151 +0,0 @@
-"""
-Bulk executor service for database operations.
-
-This service coordinates bulk database operations with validation and MTI handling.
-"""
-
-import logging
-from django.db import transaction
-
-logger = logging.getLogger(__name__)
-
-
-class BulkExecutor:
-    """
-    Executes bulk database operations.
-
-    This service coordinates validation, MTI handling, and actual database
-    operations. It's the only service that directly calls Django ORM methods.
-
-    Dependencies are explicitly injected via constructor.
-    """
-
-    def __init__(self, queryset, analyzer, mti_handler):
-        """
-        Initialize bulk executor with explicit dependencies.
-
-        Args:
-            queryset: Django QuerySet instance
-            analyzer: ModelAnalyzer instance (replaces validator + field_tracker)
-            mti_handler: MTIHandler instance
-        """
-        self.queryset = queryset
-        self.analyzer = analyzer
-        self.mti_handler = mti_handler
-        self.model_cls = queryset.model
-
-    def bulk_create(
-        self,
-        objs,
-        batch_size=None,
-        ignore_conflicts=False,
-        update_conflicts=False,
-        update_fields=None,
-        unique_fields=None,
-        **kwargs,
-    ):
-        """
-        Execute bulk create operation.
-
-        NOTE: Coordinator is responsible for validation before calling this method.
-        This executor trusts that inputs have already been validated.
-
-        Args:
-            objs: List of model instances to create (pre-validated)
-            batch_size: Number of objects to create per batch
-            ignore_conflicts: Whether to ignore conflicts
-            update_conflicts: Whether to update on conflict
-            update_fields: Fields to update on conflict
-            unique_fields: Fields to use for conflict detection
-            **kwargs: Additional arguments
-
-        Returns:
-            List of created objects
-        """
-        if not objs:
-            return objs
-
-        # Execute bulk create - validation already done by coordinator
-        return self._execute_bulk_create(
-            objs,
-            batch_size,
-            ignore_conflicts,
-            update_conflicts,
-            update_fields,
-            unique_fields,
-            **kwargs,
-        )
-
-    def _execute_bulk_create(
-        self,
-        objs,
-        batch_size=None,
-        ignore_conflicts=False,
-        update_conflicts=False,
-        update_fields=None,
-        unique_fields=None,
-        **kwargs,
-    ):
-        """
-        Execute the actual Django bulk_create.
-
-        This is the only method that directly calls Django ORM.
-        We must call the base Django QuerySet to avoid recursion.
-        """
-        from django.db.models import QuerySet
-
-        # Create a base Django queryset (not our HookQuerySet)
-        base_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
-
-        return base_qs.bulk_create(
-            objs,
-            batch_size=batch_size,
-            ignore_conflicts=ignore_conflicts,
-            update_conflicts=update_conflicts,
-            update_fields=update_fields,
-            unique_fields=unique_fields,
-        )
-
-    def bulk_update(self, objs, fields, batch_size=None):
-        """
-        Execute bulk update operation.
-
-        NOTE: Coordinator is responsible for validation before calling this method.
-        This executor trusts that inputs have already been validated.
-
-        Args:
-            objs: List of model instances to update (pre-validated)
-            fields: List of field names to update
-            batch_size: Number of objects to update per batch
-
-        Returns:
-            Number of objects updated
-        """
-        if not objs:
-            return 0
-
-        # Execute bulk update - use base Django QuerySet to avoid recursion
-        # Validation already done by coordinator
-        from django.db.models import QuerySet
-
-        base_qs = QuerySet(model=self.model_cls, using=self.queryset.db)
-        return base_qs.bulk_update(objs, fields, batch_size=batch_size)
-
-    def delete_queryset(self):
-        """
-        Execute delete on the queryset.
-
-        NOTE: Coordinator is responsible for validation before calling this method.
-        This executor trusts that inputs have already been validated.
-
-        Returns:
-            Tuple of (count, details dict)
-        """
-        if not self.queryset:
-            return 0, {}
-
-        # Execute delete via QuerySet
-        # Validation already done by coordinator
-        from django.db.models import QuerySet
-
-        return QuerySet.delete(self.queryset)

django_bulk_hooks-0.2.1/django_bulk_hooks/operations/mti_handler.py

@@ -1,103 +0,0 @@
-"""
-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)