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

django_bulk_hooks/__init__.py

@@ -1,4 +1,60 @@
+import logging
+
 from django_bulk_hooks.handler import Hook as HookClass
 from django_bulk_hooks.manager import BulkHookManager
+from django_bulk_hooks.factory import (
+    set_hook_factory,
+    set_default_hook_factory,
+    configure_hook_container,
+    configure_nested_container,
+    clear_hook_factories,
+    create_hook_instance,
+    is_container_configured,
+)
+from django_bulk_hooks.constants import DEFAULT_BULK_UPDATE_BATCH_SIZE
+from django_bulk_hooks.changeset import ChangeSet, RecordChange
+from django_bulk_hooks.dispatcher import get_dispatcher, HookDispatcher
+from django_bulk_hooks.helpers import (
+    build_changeset_for_create,
+    build_changeset_for_update,
+    build_changeset_for_delete,
+    dispatch_hooks_for_operation,
+)
+
+# Service layer (NEW architecture)
+from django_bulk_hooks.operations import (
+    BulkOperationCoordinator,
+    ModelAnalyzer,
+    BulkExecutor,
+    MTIHandler,
+)
+
+# Add NullHandler to prevent logging messages if the application doesn't configure logging
+logging.getLogger(__name__).addHandler(logging.NullHandler())
 
-__all__ = ["BulkHookManager", "HookClass"]
+__all__ = [
+    "BulkHookManager",
+    "HookClass",
+    "set_hook_factory",
+    "set_default_hook_factory",
+    "configure_hook_container",
+    "configure_nested_container",
+    "clear_hook_factories",
+    "create_hook_instance",
+    "is_container_configured",
+    "DEFAULT_BULK_UPDATE_BATCH_SIZE",
+    # Dispatcher-centric architecture
+    "ChangeSet",
+    "RecordChange",
+    "get_dispatcher",
+    "HookDispatcher",
+    "build_changeset_for_create",
+    "build_changeset_for_update",
+    "build_changeset_for_delete",
+    "dispatch_hooks_for_operation",
+    # Service layer (composition-based architecture)
+    "BulkOperationCoordinator",
+    "ModelAnalyzer",
+    "BulkExecutor",
+    "MTIHandler",
+]

django_bulk_hooks/changeset.py

@@ -0,0 +1,230 @@
+"""
+ChangeSet and RecordChange classes for Salesforce-style hook context.
+
+Provides a first-class abstraction for tracking changes in bulk operations,
+similar to Salesforce's Hook.new, Hook.old, and Hook.newMap.
+"""
+
+
+class RecordChange:
+    """
+    Represents a single record change with old/new state.
+
+    Similar to accessing Hook.newMap.get(id) in Salesforce, but with
+    additional conveniences like O(1) field change detection.
+    """
+
+    def __init__(self, new_record, old_record=None, changed_fields=None):
+        """
+        Initialize a RecordChange.
+
+        Args:
+            new_record: The new/current state of the record
+            old_record: The old/previous state of the record (None for creates)
+            changed_fields: Optional pre-computed set of changed field names.
+                          If None, will be computed lazily on first access.
+        """
+        self.new_record = new_record
+        self.old_record = old_record
+        self._changed_fields = changed_fields
+        self._pk = getattr(new_record, "pk", None) if new_record else None
+
+    @property
+    def pk(self):
+        """Primary key of the record."""
+        return self._pk
+
+    @property
+    def changed_fields(self):
+        """
+        Set of field names that have changed.
+
+        Computed lazily on first access and cached for O(1) subsequent checks.
+        """
+        if self._changed_fields is None:
+            self._changed_fields = self._compute_changed_fields()
+        return self._changed_fields
+
+    def has_changed(self, field_name):
+        """
+        O(1) check if a specific field has changed.
+
+        Args:
+            field_name: Name of the field to check
+
+        Returns:
+            True if the field value changed, False otherwise
+        """
+        return field_name in self.changed_fields
+
+    def get_old_value(self, field_name):
+        """
+        Get the old value for a field.
+
+        Args:
+            field_name: Name of the field
+
+        Returns:
+            The old value, or None if no old record exists
+        """
+        if self.old_record is None:
+            return None
+        return getattr(self.old_record, field_name, None)
+
+    def get_new_value(self, field_name):
+        """
+        Get the new value for a field.
+
+        Args:
+            field_name: Name of the field
+
+        Returns:
+            The new value
+        """
+        return getattr(self.new_record, field_name, None)
+
+    def _compute_changed_fields(self):
+        """
+        Compute which fields have changed between old and new records.
+
+        Uses Django's field.get_prep_value() for proper comparison that
+        handles database-level transformations.
+
+        Returns:
+            Set of field names that have changed
+        """
+        if self.old_record is None:
+            return set()
+
+        changed = set()
+        model_cls = self.new_record.__class__
+
+        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
+
+
+class ChangeSet:
+    """
+    Collection of RecordChanges for a bulk operation.
+
+    Similar to Salesforce's Hook context (Hook.new, Hook.old, Hook.newMap),
+    but enhanced for Python's bulk operations paradigm with O(1) lookups and
+    additional metadata.
+    """
+
+    def __init__(self, model_cls, changes, operation_type, operation_meta=None):
+        """
+        Initialize a ChangeSet.
+
+        Args:
+            model_cls: The Django model class
+            changes: List of RecordChange instances
+            operation_type: Type of operation ('create', 'update', 'delete')
+            operation_meta: Optional dict of additional metadata (e.g., update_kwargs)
+        """
+        self.model_cls = model_cls
+        self.changes = changes  # List[RecordChange]
+        self.operation_type = operation_type
+        self.operation_meta = operation_meta or {}
+
+        # Build PK -> RecordChange map for O(1) lookups (like Hook.newMap)
+        self._pk_to_change = {c.pk: c for c in changes if c.pk is not None}
+
+    @property
+    def new_records(self):
+        """
+        List of new/current record states.
+
+        Similar to Hook.new in Salesforce.
+        """
+        return [c.new_record for c in self.changes if c.new_record is not None]
+
+    @property
+    def old_records(self):
+        """
+        List of old/previous record states.
+
+        Similar to Hook.old in Salesforce.
+        Only includes records that have old states (excludes creates).
+        """
+        return [c.old_record for c in self.changes if c.old_record is not None]
+
+    def has_field_changed(self, pk, field_name):
+        """
+        O(1) check if a field changed for a specific record.
+
+        Args:
+            pk: Primary key of the record
+            field_name: Name of the field to check
+
+        Returns:
+            True if the field changed, False otherwise
+        """
+        change = self._pk_to_change.get(pk)
+        return change.has_changed(field_name) if change else False
+
+    def get_old_value(self, pk, field_name):
+        """
+        Get the old value for a specific record and field.
+
+        Args:
+            pk: Primary key of the record
+            field_name: Name of the field
+
+        Returns:
+            The old value, or None if not found
+        """
+        change = self._pk_to_change.get(pk)
+        return change.get_old_value(field_name) if change else None
+
+    def get_new_value(self, pk, field_name):
+        """
+        Get the new value for a specific record and field.
+
+        Args:
+            pk: Primary key of the record
+            field_name: Name of the field
+
+        Returns:
+            The new value, or None if not found
+        """
+        change = self._pk_to_change.get(pk)
+        return change.get_new_value(field_name) if change else None
+
+    def chunk(self, chunk_size):
+        """
+        Split ChangeSet into smaller chunks for memory-efficient processing.
+
+        Useful for processing very large bulk operations without loading
+        all data into memory at once.
+
+        Args:
+            chunk_size: Number of changes per chunk
+
+        Yields:
+            ChangeSet instances, each with up to chunk_size changes
+        """
+        for i in range(0, len(self.changes), chunk_size):
+            chunk_changes = self.changes[i : i + chunk_size]
+            yield ChangeSet(
+                self.model_cls, chunk_changes, self.operation_type, self.operation_meta
+            )

django_bulk_hooks/conditions.py

@@ -6,12 +6,53 @@ logger = logging.getLogger(__name__)
 def resolve_dotted_attr(instance, dotted_path):
     """
     Recursively resolve a dotted attribute path, e.g., "type.category".
+
+    CRITICAL: For foreign key fields, uses attname to access the ID directly
+    to avoid hooking Django's descriptor protocol which causes N+1 queries.
     """
-    for attr in dotted_path.split("."):
-        if instance is None:
+    # For simple field access (no dots), use optimized field access
+    if "." not in dotted_path:
+        try:
+            # Get the field from the model's meta to check if it's a foreign key
+            field = instance._meta.get_field(dotted_path)
+            if field.is_relation and not field.many_to_many:
+                # For foreign key fields, use attname to get the ID directly
+                # This avoids hooking Django's descriptor protocol
+                return getattr(instance, field.attname, None)
+            else:
+                # For regular fields, use normal getattr
+                return getattr(instance, dotted_path, None)
+        except Exception:
+            # If field lookup fails, fall back to normal getattr
+            return getattr(instance, dotted_path, None)
+
+    # For dotted paths, traverse the relationship chain with FK optimization
+    current_instance = instance
+    for i, attr in enumerate(dotted_path.split(".")):
+        if current_instance is None:
             return None
-        instance = getattr(instance, attr, None)
-    return instance
+
+        try:
+            # Check if this is the last attribute and if it's a FK field
+            is_last_attr = i == len(dotted_path.split(".")) - 1
+            if is_last_attr and hasattr(current_instance, "_meta"):
+                try:
+                    field = current_instance._meta.get_field(attr)
+                    if field.is_relation and not field.many_to_many:
+                        # Use attname for the final FK field access
+                        current_instance = getattr(
+                            current_instance, field.attname, None
+                        )
+                        continue
+                except:
+                    pass  # Fall through to normal getattr
+
+            # Normal getattr for non-FK fields or when FK optimization fails
+            current_instance = getattr(current_instance, attr, None)
+        except Exception:
+            current_instance = None
+
+    return current_instance
 
 
 class HookCondition:
@@ -56,6 +97,7 @@ class IsEqual(HookCondition):
 
     def check(self, instance, original_instance=None):
         current = resolve_dotted_attr(instance, self.field)
+
         if self.only_on_change:
             if original_instance is None:
                 return False
@@ -73,15 +115,11 @@ class HasChanged(HookCondition):
     def check(self, instance, original_instance=None):
         if not original_instance:
             return False
-        
+
         current = resolve_dotted_attr(instance, self.field)
         previous = resolve_dotted_attr(original_instance, self.field)
-        
-        result = (current != previous) == self.has_changed
-        # Only log when there's an actual change to reduce noise
-        if result:
-            logger.debug(f"HasChanged {self.field} detected change on instance {getattr(instance, 'pk', 'No PK')}")
-        return result
+
+        return (current != previous) == self.has_changed
 
 
 class WasEqual(HookCondition):

django_bulk_hooks/constants.py

@@ -7,3 +7,7 @@ AFTER_DELETE = "after_delete"
 VALIDATE_CREATE = "validate_create"
 VALIDATE_UPDATE = "validate_update"
 VALIDATE_DELETE = "validate_delete"
+
+# Default batch size for bulk_update operations to prevent massive SQL statements
+# This prevents PostgreSQL from crashing when updating large datasets with hooks
+DEFAULT_BULK_UPDATE_BATCH_SIZE = 1000

django_bulk_hooks/context.py

@@ -1,15 +1,13 @@
-import threading
-from collections import deque
-from django_bulk_hooks.handler import hook_vars
-
+"""
+Thread-local context management for bulk operations.
 
-_hook_context = threading.local()
+This module provides thread-safe storage for operation state like
+bypass_hooks flags and bulk update metadata.
+"""
 
+import threading
 
-def get_hook_queue():
-    if not hasattr(_hook_context, "queue"):
-        _hook_context.queue = deque()
-    return _hook_context.queue
+_hook_context = threading.local()
 
 
 def set_bypass_hooks(bypass_hooks):
@@ -19,14 +17,14 @@ def set_bypass_hooks(bypass_hooks):
 
 def get_bypass_hooks():
     """Get the current bypass_hooks state for the current thread."""
-    return getattr(_hook_context, 'bypass_hooks', False)
+    return getattr(_hook_context, "bypass_hooks", False)
 
 
 # Thread-local storage for passing per-object field values from bulk_update -> update
 def set_bulk_update_value_map(value_map):
     """Store a mapping of {pk: {field_name: value}} for the current thread.
 
-    This allows the internal update() call (triggered by Django's bulk_update)
+    This allows the internal update() call (hooked by Django's bulk_update)
     to populate in-memory instances with the concrete values that will be
     written to the database, instead of Django expression objects like Case/Cast.
     """
@@ -35,35 +33,24 @@ def set_bulk_update_value_map(value_map):
 
 def get_bulk_update_value_map():
     """Retrieve the mapping {pk: {field_name: value}} for the current thread, if any."""
-    return getattr(_hook_context, 'bulk_update_value_map', None)
-
-
-class HookContext:
-    def __init__(self, model, bypass_hooks=False):
-        self.model = model
-        self.bypass_hooks = bypass_hooks
-        # Set the thread-local bypass state when creating a context
-        set_bypass_hooks(bypass_hooks)
-
-    @property
-    def is_executing(self):
-        """
-        Check if we're currently in a hook execution context.
-        Similar to Salesforce's Trigger.isExecuting.
-        Use this to prevent infinite recursion in hooks.
-        """
-        return hasattr(hook_vars, 'event') and hook_vars.event is not None
-
-    @property
-    def current_event(self):
-        """
-        Get the current hook event being executed.
-        """
-        return getattr(hook_vars, 'event', None)
-
-    @property
-    def execution_depth(self):
-        """
-        Get the current execution depth to detect deep recursion.
-        """
-        return getattr(hook_vars, 'depth', 0)
+    return getattr(_hook_context, "bulk_update_value_map", None)
+
+
+def set_bulk_update_active(active):
+    """Set whether we're currently in a bulk_update operation."""
+    _hook_context.bulk_update_active = active
+
+
+def get_bulk_update_active():
+    """Get whether we're currently in a bulk_update operation."""
+    return getattr(_hook_context, "bulk_update_active", False)
+
+
+def set_bulk_update_batch_size(batch_size):
+    """Store the batch_size for the current bulk_update operation."""
+    _hook_context.bulk_update_batch_size = batch_size
+
+
+def get_bulk_update_batch_size():
+    """Get the batch_size for the current bulk_update operation."""
+    return getattr(_hook_context, "bulk_update_batch_size", None)

django_bulk_hooks/debug_utils.py

@@ -0,0 +1,145 @@
+"""
+Debug utilities for tracking N+1 queries and database performance.
+"""
+
+import logging
+import time
+from functools import wraps
+from django.db import connection
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+
+def track_queries(func):
+    """
+    Decorator to track database queries during function execution.
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        # Reset query count
+        initial_queries = len(connection.queries)
+        initial_time = time.time()
+
+        logger.debug(
+            f"QUERY DEBUG: Starting {func.__name__} - initial query count: {initial_queries}"
+        )
+
+        try:
+            result = func(*args, **kwargs)
+
+            final_queries = len(connection.queries)
+            final_time = time.time()
+            query_count = final_queries - initial_queries
+            duration = final_time - initial_time
+
+            logger.debug(
+                f"QUERY DEBUG: Completed {func.__name__} - queries executed: {query_count}, duration: {duration:.4f}s"
+            )
+
+            # Log all queries executed during this function
+            if query_count > 0:
+                logger.debug(f"QUERY DEBUG: Queries executed in {func.__name__}:")
+                for i, query in enumerate(connection.queries[initial_queries:], 1):
+                    logger.debug(
+                        f"QUERY DEBUG:   {i}. {query['sql'][:100]}... (time: {query['time']})"
+                    )
+
+            return result
+
+        except Exception as e:
+            final_queries = len(connection.queries)
+            query_count = final_queries - initial_queries
+            logger.debug(
+                f"QUERY DEBUG: Exception in {func.__name__} - queries executed: {query_count}"
+            )
+            raise
+
+    return wrapper
+
+
+def log_query_count(context=""):
+    """
+    Log the current query count with optional context.
+    """
+    query_count = len(connection.queries)
+    logger.debug(f"QUERY DEBUG: Query count at {context}: {query_count}")
+
+
+def log_recent_queries(count=5, context=""):
+    """
+    Log the most recent database queries.
+    """
+    recent_queries = connection.queries[-count:] if connection.queries else []
+    logger.debug(f"QUERY DEBUG: Recent {len(recent_queries)} queries at {context}:")
+    for i, query in enumerate(recent_queries, 1):
+        logger.debug(
+            f"QUERY DEBUG:   {i}. {query['sql'][:100]}... (time: {query['time']})"
+        )
+
+
+class QueryTracker:
+    """
+    Context manager for tracking database queries.
+    """
+
+    def __init__(self, context_name="QueryTracker"):
+        self.context_name = context_name
+        self.initial_queries = 0
+        self.start_time = 0
+
+    def __enter__(self):
+        self.initial_queries = len(connection.queries)
+        self.start_time = time.time()
+        logger.debug(
+            f"QUERY DEBUG: Starting {self.context_name} - initial query count: {self.initial_queries}"
+        )
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        final_queries = len(connection.queries)
+        final_time = time.time()
+        query_count = final_queries - self.initial_queries
+        duration = final_time - self.start_time
+
+        logger.debug(
+            f"QUERY DEBUG: Completed {self.context_name} - queries executed: {query_count}, duration: {duration:.4f}s"
+        )
+
+        if query_count > 0:
+            logger.debug(f"QUERY DEBUG: Queries executed in {self.context_name}:")
+            for i, query in enumerate(connection.queries[self.initial_queries :], 1):
+                logger.debug(
+                    f"QUERY DEBUG:   {i}. {query['sql'][:100]}... (time: {query['time']})"
+                )
+
+        return False  # Don't suppress exceptions
+
+
+def enable_django_query_logging():
+    """
+    Enable Django's built-in query logging.
+    """
+    if not settings.DEBUG:
+        logger.warning("Django query logging can only be enabled in DEBUG mode")
+        return
+
+    # Enable query logging
+    settings.LOGGING = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+            },
+        },
+        "loggers": {
+            "django.db.backends": {
+                "level": "DEBUG",
+                "handlers": ["console"],
+            },
+        },
+    }
+
+    logger.info("Django query logging enabled")