django-bulk-hooks 0.1.232__tar.gz → 0.2.93__tar.gz

{django_bulk_hooks-0.1.232 → django_bulk_hooks-0.2.93}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.1.232
+Version: 0.2.93
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: Django (>=4.0)
+Requires-Dist: django (>=5.2.0,<6.0.0)
 Project-URL: Homepage, https://github.com/AugendLimited/django-bulk-hooks
 Project-URL: Repository, https://github.com/AugendLimited/django-bulk-hooks
 Description-Content-Type: text/markdown
@@ -84,39 +84,39 @@ class AccountHooks(Hook):
 
 ### Individual Model Operations
 
-The `HookModelMixin` automatically triggers hooks for individual model operations:
+The `HookModelMixin` automatically hooks hooks for individual model operations:
 
 ```python
-# These will trigger BEFORE_CREATE and AFTER_CREATE hooks
+# These will hook BEFORE_CREATE and AFTER_CREATE hooks
 account = Account.objects.create(balance=100.00)
 account.save()  # for new instances
 
-# These will trigger BEFORE_UPDATE and AFTER_UPDATE hooks
+# These will hook BEFORE_UPDATE and AFTER_UPDATE hooks
 account.balance = 200.00
 account.save()  # for existing instances
 
-# This will trigger BEFORE_DELETE and AFTER_DELETE hooks
+# This will hook BEFORE_DELETE and AFTER_DELETE hooks
 account.delete()
 ```
 
 ### Bulk Operations
 
-Bulk operations also trigger the same hooks:
+Bulk operations also hook the same hooks:
 
 ```python
-# Bulk create - triggers BEFORE_CREATE and AFTER_CREATE hooks
+# Bulk create - hooks BEFORE_CREATE and AFTER_CREATE hooks
 accounts = [
     Account(balance=100.00),
     Account(balance=200.00),
 ]
 Account.objects.bulk_create(accounts)
 
-# Bulk update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+# Bulk update - hooks BEFORE_UPDATE and AFTER_UPDATE hooks
 for account in accounts:
     account.balance *= 1.1
-Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_update(accounts)  # fields are auto-detected
 
-# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+# Bulk delete - hooks BEFORE_DELETE and AFTER_DELETE hooks
 Account.objects.bulk_delete(accounts)
 ```
 
@@ -125,10 +125,10 @@ Account.objects.bulk_delete(accounts)
 Queryset operations are also supported:
 
 ```python
-# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+# Queryset update - hooks BEFORE_UPDATE and AFTER_UPDATE hooks
 Account.objects.update(balance=0.00)
 
-# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+# Queryset delete - hooks BEFORE_DELETE and AFTER_DELETE hooks
 Account.objects.delete()
 ```
 
@@ -180,7 +180,7 @@ Django's `bulk_` methods bypass signals and `save()`. This package fills that ga
 - **NEW**: Individual model lifecycle hooks that work with `save()` and `delete()`
 - Scalable performance via chunking (default 200)
 - Support for `@hook` decorators and centralized hook classes
-- **NEW**: Automatic hook triggering for admin operations and other Django features
+- **NEW**: Automatic hook hooking for admin operations and other Django features
 - **NEW**: Proper ordering guarantees for old/new record pairing in hooks (Salesforce-like behavior)
 
 ## 📦 Usage Examples
@@ -188,7 +188,7 @@ Django's `bulk_` methods bypass signals and `save()`. This package fills that ga
 ### Individual Model Operations
 
 ```python
-# These automatically trigger hooks
+# These automatically hook hooks
 account = Account.objects.create(balance=100.00)
 account.balance = 200.00
 account.save()
@@ -198,9 +198,9 @@ account.delete()
 ### Bulk Operations
 
 ```python
-# These also trigger hooks
+# These also hook hooks
 Account.objects.bulk_create(accounts)
-Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_update(accounts)  # fields are auto-detected
 Account.objects.bulk_delete(accounts)
 ```
 
@@ -239,22 +239,80 @@ accounts = [account1, account2, account3]  # IDs: 1, 2, 3
 reordered = [account3, account1, account2]  # IDs: 3, 1, 2
 
 # The hook will still receive properly paired old/new records
-LoanAccount.objects.bulk_update(reordered, ['balance'])
+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
+Know when to execute them (BEFORE_UPDATE, AFTER_UPDATE)
+Execute them in priority order
+Pass ChangeSet to them
+Handle errors (rollback on failure)
 
 ## 📝 License
 

{django_bulk_hooks-0.1.232 → django_bulk_hooks-0.2.93}/README.md

@@ -65,39 +65,39 @@ class AccountHooks(Hook):
 
 ### Individual Model Operations
 
-The `HookModelMixin` automatically triggers hooks for individual model operations:
+The `HookModelMixin` automatically hooks hooks for individual model operations:
 
 ```python
-# These will trigger BEFORE_CREATE and AFTER_CREATE hooks
+# These will hook BEFORE_CREATE and AFTER_CREATE hooks
 account = Account.objects.create(balance=100.00)
 account.save()  # for new instances
 
-# These will trigger BEFORE_UPDATE and AFTER_UPDATE hooks
+# These will hook BEFORE_UPDATE and AFTER_UPDATE hooks
 account.balance = 200.00
 account.save()  # for existing instances
 
-# This will trigger BEFORE_DELETE and AFTER_DELETE hooks
+# This will hook BEFORE_DELETE and AFTER_DELETE hooks
 account.delete()
 ```
 
 ### Bulk Operations
 
-Bulk operations also trigger the same hooks:
+Bulk operations also hook the same hooks:
 
 ```python
-# Bulk create - triggers BEFORE_CREATE and AFTER_CREATE hooks
+# Bulk create - hooks BEFORE_CREATE and AFTER_CREATE hooks
 accounts = [
     Account(balance=100.00),
     Account(balance=200.00),
 ]
 Account.objects.bulk_create(accounts)
 
-# Bulk update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+# Bulk update - hooks BEFORE_UPDATE and AFTER_UPDATE hooks
 for account in accounts:
     account.balance *= 1.1
-Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_update(accounts)  # fields are auto-detected
 
-# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+# Bulk delete - hooks BEFORE_DELETE and AFTER_DELETE hooks
 Account.objects.bulk_delete(accounts)
 ```
 
@@ -106,10 +106,10 @@ Account.objects.bulk_delete(accounts)
 Queryset operations are also supported:
 
 ```python
-# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+# Queryset update - hooks BEFORE_UPDATE and AFTER_UPDATE hooks
 Account.objects.update(balance=0.00)
 
-# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+# Queryset delete - hooks BEFORE_DELETE and AFTER_DELETE hooks
 Account.objects.delete()
 ```
 
@@ -161,7 +161,7 @@ Django's `bulk_` methods bypass signals and `save()`. This package fills that ga
 - **NEW**: Individual model lifecycle hooks that work with `save()` and `delete()`
 - Scalable performance via chunking (default 200)
 - Support for `@hook` decorators and centralized hook classes
-- **NEW**: Automatic hook triggering for admin operations and other Django features
+- **NEW**: Automatic hook hooking for admin operations and other Django features
 - **NEW**: Proper ordering guarantees for old/new record pairing in hooks (Salesforce-like behavior)
 
 ## 📦 Usage Examples
@@ -169,7 +169,7 @@ Django's `bulk_` methods bypass signals and `save()`. This package fills that ga
 ### Individual Model Operations
 
 ```python
-# These automatically trigger hooks
+# These automatically hook hooks
 account = Account.objects.create(balance=100.00)
 account.balance = 200.00
 account.save()
@@ -179,9 +179,9 @@ account.delete()
 ### Bulk Operations
 
 ```python
-# These also trigger hooks
+# These also hook hooks
 Account.objects.bulk_create(accounts)
-Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_update(accounts)  # fields are auto-detected
 Account.objects.bulk_delete(accounts)
 ```
 
@@ -220,22 +220,80 @@ accounts = [account1, account2, account3]  # IDs: 1, 2, 3
 reordered = [account3, account1, account2]  # IDs: 3, 1, 2
 
 # The hook will still receive properly paired old/new records
-LoanAccount.objects.bulk_update(reordered, ['balance'])
+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
+Know when to execute them (BEFORE_UPDATE, AFTER_UPDATE)
+Execute them in priority order
+Pass ChangeSet to them
+Handle errors (rollback on failure)
 
 ## 📝 License
 

django_bulk_hooks-0.2.93/django_bulk_hooks/__init__.py

@@ -0,0 +1,53 @@
+import logging
+
+from django_bulk_hooks.changeset import ChangeSet
+from django_bulk_hooks.changeset import RecordChange
+from django_bulk_hooks.constants import DEFAULT_BULK_UPDATE_BATCH_SIZE
+from django_bulk_hooks.dispatcher import HookDispatcher
+from django_bulk_hooks.dispatcher import get_dispatcher
+from django_bulk_hooks.factory import clear_hook_factories
+from django_bulk_hooks.factory import configure_hook_container
+from django_bulk_hooks.factory import configure_nested_container
+from django_bulk_hooks.factory import create_hook_instance
+from django_bulk_hooks.factory import is_container_configured
+from django_bulk_hooks.factory import set_default_hook_factory
+from django_bulk_hooks.factory import set_hook_factory
+from django_bulk_hooks.handler import Hook as HookClass
+from django_bulk_hooks.helpers import build_changeset_for_create
+from django_bulk_hooks.helpers import build_changeset_for_delete
+from django_bulk_hooks.helpers import build_changeset_for_update
+from django_bulk_hooks.helpers import dispatch_hooks_for_operation
+from django_bulk_hooks.manager import BulkHookManager
+from django_bulk_hooks.operations import BulkExecutor
+
+# Service layer (NEW architecture)
+from django_bulk_hooks.operations import BulkOperationCoordinator
+from django_bulk_hooks.operations import ModelAnalyzer
+from django_bulk_hooks.operations import MTIHandler
+
+__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-0.2.93/django_bulk_hooks/changeset.py

@@ -0,0 +1,214 @@
+"""
+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()
+
+        # Import here to avoid circular dependency
+        from .operations.field_utils import get_changed_fields
+
+        model_cls = self.new_record.__class__
+        return get_changed_fields(self.old_record, self.new_record, model_cls)
+
+
+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,
+            )