django-bulk-hooks 0.2.69__tar.gz → 0.2.71__tar.gz

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.2.69
+Version: 0.2.71
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks
@@ -244,17 +244,68 @@ LoanAccount.objects.bulk_update(reordered)  # fields are auto-detected
 
 ## 🧩 Integration with Other Managers
 
-You can extend from `BulkHookManager` to work with other manager classes. The manager uses a cooperative approach that dynamically injects bulk hook functionality into any queryset, ensuring compatibility with other managers.
+### Recommended: QuerySet-based Composition (New Approach)
+
+For the best compatibility and to avoid inheritance conflicts, use the queryset-based composition approach:
+
+```python
+from django_bulk_hooks.queryset import HookQuerySet
+from queryable_properties.managers import QueryablePropertiesManager
+
+class MyManager(QueryablePropertiesManager):
+    """Manager that combines queryable properties with hooks"""
+
+    def get_queryset(self):
+        # Get the QueryableProperties QuerySet
+        qs = super().get_queryset()
+        # Apply hooks on top of it
+        return HookQuerySet.with_hooks(qs)
+
+class Article(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.BooleanField(default=False)
+
+    objects = MyManager()
+
+# This gives you both queryable properties AND hooks
+# No inheritance conflicts, no MRO issues!
+```
+
+### Alternative: Explicit Hook Application
+
+For more control, you can apply hooks explicitly:
+
+```python
+class MyManager(QueryablePropertiesManager):
+    def get_queryset(self):
+        return super().get_queryset()
+
+    def with_hooks(self):
+        """Apply hooks to this queryset"""
+        return HookQuerySet.with_hooks(self.get_queryset())
+
+# Usage:
+Article.objects.with_hooks().filter(published=True).update(title="Updated")
+```
+
+### Legacy: Manager Inheritance (Not Recommended)
+
+The old inheritance approach still works but is not recommended due to potential MRO conflicts:
 
 ```python
 from django_bulk_hooks.manager import BulkHookManager
 from queryable_properties.managers import QueryablePropertiesManager
 
 class MyManager(BulkHookManager, QueryablePropertiesManager):
-    pass
+    pass  # ⚠️ Can cause inheritance conflicts
 ```
 
-This approach uses the industry-standard injection pattern, similar to how `QueryablePropertiesManager` works, ensuring both functionalities work seamlessly together without any framework-specific knowledge.
+**Why the new approach is better:**
+- ✅ No inheritance conflicts
+- ✅ No MRO (Method Resolution Order) issues
+- ✅ Works with any manager combination
+- ✅ Cleaner and more maintainable
+- ✅ Follows Django's queryset enhancement patterns
 
 Framework needs to:
 Register these methods

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/README.md

@@ -225,17 +225,68 @@ LoanAccount.objects.bulk_update(reordered)  # fields are auto-detected
 
 ## 🧩 Integration with Other Managers
 
-You can extend from `BulkHookManager` to work with other manager classes. The manager uses a cooperative approach that dynamically injects bulk hook functionality into any queryset, ensuring compatibility with other managers.
+### Recommended: QuerySet-based Composition (New Approach)
+
+For the best compatibility and to avoid inheritance conflicts, use the queryset-based composition approach:
+
+```python
+from django_bulk_hooks.queryset import HookQuerySet
+from queryable_properties.managers import QueryablePropertiesManager
+
+class MyManager(QueryablePropertiesManager):
+    """Manager that combines queryable properties with hooks"""
+
+    def get_queryset(self):
+        # Get the QueryableProperties QuerySet
+        qs = super().get_queryset()
+        # Apply hooks on top of it
+        return HookQuerySet.with_hooks(qs)
+
+class Article(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.BooleanField(default=False)
+
+    objects = MyManager()
+
+# This gives you both queryable properties AND hooks
+# No inheritance conflicts, no MRO issues!
+```
+
+### Alternative: Explicit Hook Application
+
+For more control, you can apply hooks explicitly:
+
+```python
+class MyManager(QueryablePropertiesManager):
+    def get_queryset(self):
+        return super().get_queryset()
+
+    def with_hooks(self):
+        """Apply hooks to this queryset"""
+        return HookQuerySet.with_hooks(self.get_queryset())
+
+# Usage:
+Article.objects.with_hooks().filter(published=True).update(title="Updated")
+```
+
+### Legacy: Manager Inheritance (Not Recommended)
+
+The old inheritance approach still works but is not recommended due to potential MRO conflicts:
 
 ```python
 from django_bulk_hooks.manager import BulkHookManager
 from queryable_properties.managers import QueryablePropertiesManager
 
 class MyManager(BulkHookManager, QueryablePropertiesManager):
-    pass
+    pass  # ⚠️ Can cause inheritance conflicts
 ```
 
-This approach uses the industry-standard injection pattern, similar to how `QueryablePropertiesManager` works, ensuring both functionalities work seamlessly together without any framework-specific knowledge.
+**Why the new approach is better:**
+- ✅ No inheritance conflicts
+- ✅ No MRO (Method Resolution Order) issues
+- ✅ Works with any manager combination
+- ✅ Cleaner and more maintainable
+- ✅ Follows Django's queryset enhancement patterns
 
 Framework needs to:
 Register these methods

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/django_bulk_hooks/dispatcher.py

@@ -106,12 +106,68 @@ class HookDispatcher:
         if not hooks:
             return
 
-        # Execute hooks in priority order
-        logger.info(f"🔥 HOOKS: Executing {len(hooks)} hooks for {changeset.model_cls.__name__}.{event}")
+        # Create an operation key that includes the changeset model to avoid
+        # deduplicating hooks across different operations on the same records
+        # This prevents the same hook from executing multiple times for MTI inheritance chains
+        # but allows different operations on the same records to execute their hooks
+        record_ids = set()
+        for change in changeset.changes:
+            if change.new_record and change.new_record.pk:
+                record_ids.add(change.new_record.pk)
+            if change.old_record and change.old_record.pk:
+                record_ids.add(change.old_record.pk)
+
+        # Sort record IDs safely (handle Mock objects and other non-comparable types)
+        try:
+            sorted_record_ids = tuple(sorted(record_ids, key=lambda x: str(x)))
+        except (TypeError, AttributeError):
+            # Fallback for non-comparable objects (like Mock objects in tests)
+            sorted_record_ids = tuple(record_ids)
+
+        # Include changeset model and operation details to make the key more specific
+        operation_meta = getattr(changeset, 'operation_meta', {}) or {}
+        operation_type = getattr(changeset, 'operation_type', 'unknown')
+
+        # Include update_kwargs if present to distinguish different queryset operations
+        update_kwargs = operation_meta.get('update_kwargs', {})
+        if update_kwargs:
+            try:
+                # Convert to a hashable representation
+                update_kwargs_key = tuple(sorted((k, str(v)) for k, v in update_kwargs.items()))
+            except (TypeError, AttributeError):
+                # Fallback if values are not convertible to string
+                update_kwargs_key = tuple(sorted(update_kwargs.keys()))
+        else:
+            update_kwargs_key = ()
+
+        operation_key = (event, changeset.model_cls.__name__, operation_type, sorted_record_ids, update_kwargs_key)
+
+        # Track executed hooks to prevent duplicates in MTI inheritance chains
+        if not hasattr(self, '_executed_hooks'):
+            self._executed_hooks = set()
+
+        # Filter out hooks that have already been executed for this operation
+        unique_hooks = []
         for handler_cls, method_name, condition, priority in hooks:
+            hook_key = (handler_cls, method_name, operation_key)
+            if hook_key not in self._executed_hooks:
+                unique_hooks.append((handler_cls, method_name, condition, priority))
+                self._executed_hooks.add(hook_key)
+
+
+        if not unique_hooks:
+            return
+
+        # Execute hooks in priority order
+        logger.info(f"🔥 HOOKS: Executing {len(unique_hooks)} hooks for {changeset.model_cls.__name__}.{event}")
+        for handler_cls, method_name, condition, priority in unique_hooks:
             logger.info(f"  → {handler_cls.__name__}.{method_name} (priority={priority})")
             self._execute_hook(handler_cls, method_name, condition, changeset, event)
 
+    def _reset_executed_hooks(self):
+        """Reset the executed hooks tracking for a new operation."""
+        self._executed_hooks = set()
+
     def _execute_hook(self, handler_cls, method_name, condition, changeset, event):
         """
         Execute a single hook with condition checking.

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/django_bulk_hooks/manager.py

@@ -21,29 +21,19 @@ class BulkHookManager(models.Manager):
     """
     Manager that provides hook-aware bulk operations.
 
-    This is a simple facade that returns HookQuerySet,
-    delegating all bulk operations to it.
+    This manager automatically applies hook functionality to its querysets.
+    It can be used as a base class or composed with other managers using
+    the queryset-based approach.
     """
 
     def get_queryset(self):
         """
         Return a HookQuerySet for this manager.
 
-        This ensures all bulk operations go through the coordinator.
+        Uses the new with_hooks() method for better composition with other managers.
         """
         base_queryset = super().get_queryset()
-
-        # If the base queryset is already a HookQuerySet, return it as-is
-        if isinstance(base_queryset, HookQuerySet):
-            return base_queryset
-
-        # Otherwise, create a new HookQuerySet with the same parameters
-        return HookQuerySet(
-            model=base_queryset.model,
-            query=base_queryset.query,
-            using=base_queryset._db,
-            hints=base_queryset._hints,
-        )
+        return HookQuerySet.with_hooks(base_queryset)
 
     def bulk_create(
         self,

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/django_bulk_hooks/operations/coordinator.py

@@ -700,6 +700,9 @@ class BulkOperationCoordinator:
         if bypass_hooks:
             return operation()
 
+        # Reset hook execution tracking for this new operation
+        self.dispatcher._reset_executed_hooks()
+
         # Get all models in inheritance chain
         models_in_chain = self._get_models_in_chain(changeset.model_cls)
 

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/django_bulk_hooks/queryset.py

@@ -35,6 +35,57 @@ class HookQuerySet(models.QuerySet):
         super().__init__(*args, **kwargs)
         self._coordinator = None
 
+    @classmethod
+    def with_hooks(cls, queryset):
+        """
+        Apply hook functionality to any queryset.
+
+        This enables hooks to work with any manager by applying hook
+        capabilities at the queryset level rather than through inheritance.
+
+        Args:
+            queryset: Any Django QuerySet instance
+
+        Returns:
+            HookQuerySet instance with the same query parameters
+        """
+        if isinstance(queryset, cls):
+            return queryset  # Already has hooks
+
+        # Create a new HookQuerySet with the same parameters as the original queryset
+        hook_qs = cls(
+            model=queryset.model,
+            query=queryset.query,
+            using=queryset._db,
+            hints=getattr(queryset, '_hints', {}),
+        )
+
+        # Preserve any additional attributes from the original queryset
+        # This allows composition with other queryset enhancements
+        cls._preserve_queryset_attributes(hook_qs, queryset)
+
+        return hook_qs
+
+    @classmethod
+    def _preserve_queryset_attributes(cls, hook_qs, original_qs):
+        """
+        Preserve attributes from the original queryset.
+
+        This enables composition with other queryset enhancements like
+        queryable properties, annotations, etc.
+        """
+        # Copy non-method attributes that might be set by other managers
+        for attr_name in dir(original_qs):
+            if (not attr_name.startswith('_') and
+                not hasattr(cls, attr_name) and
+                not callable(getattr(original_qs, attr_name, None))):
+                try:
+                    value = getattr(original_qs, attr_name)
+                    setattr(hook_qs, attr_name, value)
+                except (AttributeError, TypeError):
+                    # Skip attributes that can't be copied
+                    continue
+
     @property
     def coordinator(self):
         """Lazy initialization of coordinator"""

{django_bulk_hooks-0.2.69 → django_bulk_hooks-0.2.71}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.2.69"
+version = "0.2.71"
 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"