django-bulk-hooks 0.1.102__tar.gz → 0.1.103__tar.gz

django_bulk_hooks-0.1.103/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.1
+Name: django-bulk-hooks
+Version: 0.1.103
+Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
+Home-page: https://github.com/AugendLimited/django-bulk-hooks
+License: MIT
+Keywords: django,bulk,hooks
+Author: Konrad Beck
+Author-email: konrad.beck@merchantcapital.co.za
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+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)
+Project-URL: Repository, https://github.com/AugendLimited/django-bulk-hooks
+Description-Content-Type: text/markdown
+
+
+# django-bulk-hooks
+
+⚡ Bulk hooks for Django bulk operations and individual model lifecycle events.
+
+`django-bulk-hooks` brings a declarative, hook-like experience to Django's `bulk_create`, `bulk_update`, and `bulk_delete` — including support for `BEFORE_` and `AFTER_` hooks, conditions, batching, and transactional safety. It also provides comprehensive lifecycle hooks for individual model operations.
+
+## ✨ Features
+
+- Declarative hook system: `@hook(AFTER_UPDATE, condition=...)`
+- BEFORE/AFTER hooks for create, update, delete
+- Hook-aware manager that wraps Django's `bulk_` operations
+- **NEW**: `HookModelMixin` for individual model lifecycle events
+- Hook chaining, hook deduplication, and atomicity
+- Class-based hook handlers with DI support
+- Support for both bulk and individual model operations
+
+## 🚀 Quickstart
+
+```bash
+pip install django-bulk-hooks
+```
+
+### Define Your Model
+
+```python
+from django.db import models
+from django_bulk_hooks.models import HookModelMixin
+
+class Account(HookModelMixin):
+    balance = models.DecimalField(max_digits=10, decimal_places=2)
+    # The HookModelMixin automatically provides BulkHookManager
+```
+
+### Create a Hook Handler
+
+```python
+from django_bulk_hooks import hook, AFTER_UPDATE, Hook
+from django_bulk_hooks.conditions import WhenFieldHasChanged
+from .models import Account
+
+class AccountHooks(Hook):
+    @hook(AFTER_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    def log_balance_change(self, new_records, old_records):
+        print("Accounts updated:", [a.pk for a in new_records])
+    
+    @hook(BEFORE_CREATE, model=Account)
+    def before_create(self, new_records, old_records):
+        for account in new_records:
+            if account.balance < 0:
+                raise ValueError("Account cannot have negative balance")
+    
+    @hook(AFTER_DELETE, model=Account)
+    def after_delete(self, new_records, old_records):
+        print("Accounts deleted:", [a.pk for a in old_records])
+```
+
+## 🛠 Supported Hook Events
+
+- `BEFORE_CREATE`, `AFTER_CREATE`
+- `BEFORE_UPDATE`, `AFTER_UPDATE`
+- `BEFORE_DELETE`, `AFTER_DELETE`
+
+## 🔄 Lifecycle Events
+
+### Individual Model Operations
+
+The `HookModelMixin` automatically triggers hooks for individual model operations:
+
+```python
+# These will trigger 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
+account.balance = 200.00
+account.save()  # for existing instances
+
+# This will trigger BEFORE_DELETE and AFTER_DELETE hooks
+account.delete()
+```
+
+### Bulk Operations
+
+Bulk operations also trigger the same hooks:
+
+```python
+# Bulk create - triggers 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
+for account in accounts:
+    account.balance *= 1.1
+Account.objects.bulk_update(accounts, ['balance'])
+
+# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+Account.objects.bulk_delete(accounts)
+```
+
+### Queryset Operations
+
+Queryset operations are also supported:
+
+```python
+# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+Account.objects.update(balance=0.00)
+
+# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+Account.objects.delete()
+```
+
+## 🧠 Why?
+
+Django's `bulk_` methods bypass signals and `save()`. This package fills that gap with:
+
+- Hooks that behave consistently across creates/updates/deletes
+- **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**: Proper ordering guarantees for old/new record pairing in hooks (Salesforce-like behavior)
+
+## 📦 Usage Examples
+
+### Individual Model Operations
+
+```python
+# These automatically trigger hooks
+account = Account.objects.create(balance=100.00)
+account.balance = 200.00
+account.save()
+account.delete()
+```
+
+### Bulk Operations
+
+```python
+# These also trigger hooks
+Account.objects.bulk_create(accounts)
+Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_delete(accounts)
+```
+
+### Advanced Hook Usage
+
+```python
+class AdvancedAccountHooks(Hook):
+    @hook(BEFORE_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    def validate_balance_change(self, new_records, old_records):
+        for new_account, old_account in zip(new_records, old_records):
+            if new_account.balance < 0 and old_account.balance >= 0:
+                raise ValueError("Cannot set negative balance")
+    
+    @hook(AFTER_CREATE, model=Account)
+    def send_welcome_email(self, new_records, old_records):
+        for account in new_records:
+            # Send welcome email logic here
+            pass
+```
+
+### Salesforce-like Ordering Guarantees
+
+The system ensures that `old_records` and `new_records` are always properly paired, regardless of the order in which you pass objects to bulk operations:
+
+```python
+class LoanAccountHooks(Hook):
+    @hook(BEFORE_UPDATE, model=LoanAccount)
+    def validate_account_number(self, new_records, old_records):
+        # old_records[i] always corresponds to new_records[i]
+        for new_account, old_account in zip(new_records, old_records):
+            if old_account.account_number != new_account.account_number:
+                raise ValidationError("Account number cannot be changed")
+
+# This works correctly even with reordered objects:
+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'])
+```
+
+## 🧩 Integration with Queryable Properties
+
+You can extend from `BulkHookManager` to support formula fields or property querying.
+
+```python
+class MyManager(BulkHookManager, QueryablePropertiesManager):
+    pass
+```
+
+## 📝 License
+
+MIT © 2024 Augend / Konrad Beck
+

django_bulk_hooks-0.1.103/README.md

@@ -0,0 +1,197 @@
+
+# django-bulk-hooks
+
+⚡ Bulk hooks for Django bulk operations and individual model lifecycle events.
+
+`django-bulk-hooks` brings a declarative, hook-like experience to Django's `bulk_create`, `bulk_update`, and `bulk_delete` — including support for `BEFORE_` and `AFTER_` hooks, conditions, batching, and transactional safety. It also provides comprehensive lifecycle hooks for individual model operations.
+
+## ✨ Features
+
+- Declarative hook system: `@hook(AFTER_UPDATE, condition=...)`
+- BEFORE/AFTER hooks for create, update, delete
+- Hook-aware manager that wraps Django's `bulk_` operations
+- **NEW**: `HookModelMixin` for individual model lifecycle events
+- Hook chaining, hook deduplication, and atomicity
+- Class-based hook handlers with DI support
+- Support for both bulk and individual model operations
+
+## 🚀 Quickstart
+
+```bash
+pip install django-bulk-hooks
+```
+
+### Define Your Model
+
+```python
+from django.db import models
+from django_bulk_hooks.models import HookModelMixin
+
+class Account(HookModelMixin):
+    balance = models.DecimalField(max_digits=10, decimal_places=2)
+    # The HookModelMixin automatically provides BulkHookManager
+```
+
+### Create a Hook Handler
+
+```python
+from django_bulk_hooks import hook, AFTER_UPDATE, Hook
+from django_bulk_hooks.conditions import WhenFieldHasChanged
+from .models import Account
+
+class AccountHooks(Hook):
+    @hook(AFTER_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    def log_balance_change(self, new_records, old_records):
+        print("Accounts updated:", [a.pk for a in new_records])
+    
+    @hook(BEFORE_CREATE, model=Account)
+    def before_create(self, new_records, old_records):
+        for account in new_records:
+            if account.balance < 0:
+                raise ValueError("Account cannot have negative balance")
+    
+    @hook(AFTER_DELETE, model=Account)
+    def after_delete(self, new_records, old_records):
+        print("Accounts deleted:", [a.pk for a in old_records])
+```
+
+## 🛠 Supported Hook Events
+
+- `BEFORE_CREATE`, `AFTER_CREATE`
+- `BEFORE_UPDATE`, `AFTER_UPDATE`
+- `BEFORE_DELETE`, `AFTER_DELETE`
+
+## 🔄 Lifecycle Events
+
+### Individual Model Operations
+
+The `HookModelMixin` automatically triggers hooks for individual model operations:
+
+```python
+# These will trigger 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
+account.balance = 200.00
+account.save()  # for existing instances
+
+# This will trigger BEFORE_DELETE and AFTER_DELETE hooks
+account.delete()
+```
+
+### Bulk Operations
+
+Bulk operations also trigger the same hooks:
+
+```python
+# Bulk create - triggers 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
+for account in accounts:
+    account.balance *= 1.1
+Account.objects.bulk_update(accounts, ['balance'])
+
+# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+Account.objects.bulk_delete(accounts)
+```
+
+### Queryset Operations
+
+Queryset operations are also supported:
+
+```python
+# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+Account.objects.update(balance=0.00)
+
+# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+Account.objects.delete()
+```
+
+## 🧠 Why?
+
+Django's `bulk_` methods bypass signals and `save()`. This package fills that gap with:
+
+- Hooks that behave consistently across creates/updates/deletes
+- **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**: Proper ordering guarantees for old/new record pairing in hooks (Salesforce-like behavior)
+
+## 📦 Usage Examples
+
+### Individual Model Operations
+
+```python
+# These automatically trigger hooks
+account = Account.objects.create(balance=100.00)
+account.balance = 200.00
+account.save()
+account.delete()
+```
+
+### Bulk Operations
+
+```python
+# These also trigger hooks
+Account.objects.bulk_create(accounts)
+Account.objects.bulk_update(accounts, ['balance'])
+Account.objects.bulk_delete(accounts)
+```
+
+### Advanced Hook Usage
+
+```python
+class AdvancedAccountHooks(Hook):
+    @hook(BEFORE_UPDATE, model=Account, condition=WhenFieldHasChanged("balance"))
+    def validate_balance_change(self, new_records, old_records):
+        for new_account, old_account in zip(new_records, old_records):
+            if new_account.balance < 0 and old_account.balance >= 0:
+                raise ValueError("Cannot set negative balance")
+    
+    @hook(AFTER_CREATE, model=Account)
+    def send_welcome_email(self, new_records, old_records):
+        for account in new_records:
+            # Send welcome email logic here
+            pass
+```
+
+### Salesforce-like Ordering Guarantees
+
+The system ensures that `old_records` and `new_records` are always properly paired, regardless of the order in which you pass objects to bulk operations:
+
+```python
+class LoanAccountHooks(Hook):
+    @hook(BEFORE_UPDATE, model=LoanAccount)
+    def validate_account_number(self, new_records, old_records):
+        # old_records[i] always corresponds to new_records[i]
+        for new_account, old_account in zip(new_records, old_records):
+            if old_account.account_number != new_account.account_number:
+                raise ValidationError("Account number cannot be changed")
+
+# This works correctly even with reordered objects:
+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'])
+```
+
+## 🧩 Integration with Queryable Properties
+
+You can extend from `BulkHookManager` to support formula fields or property querying.
+
+```python
+class MyManager(BulkHookManager, QueryablePropertiesManager):
+    pass
+```
+
+## 📝 License
+
+MIT © 2024 Augend / Konrad Beck

django_bulk_hooks-0.1.103/django_bulk_hooks/__init__.py

@@ -0,0 +1,4 @@
+from django_bulk_hooks.handler import Hook
+from django_bulk_hooks.manager import BulkHookManager
+
+__all__ = ["BulkHookManager", "Hook"]

django_bulk_hooks-0.1.103/django_bulk_hooks/conditions.py

@@ -0,0 +1,181 @@
+def resolve_dotted_attr(instance, dotted_path):
+    """
+    Recursively resolve a dotted attribute path, e.g., "type.category".
+    """
+    for attr in dotted_path.split("."):
+        if instance is None:
+            return None
+        instance = getattr(instance, attr, None)
+    return instance
+
+
+class HookCondition:
+    def check(self, instance, original_instance=None):
+        raise NotImplementedError
+
+    def __call__(self, instance, original_instance=None):
+        return self.check(instance, original_instance)
+
+    def __and__(self, other):
+        return AndCondition(self, other)
+
+    def __or__(self, other):
+        return OrCondition(self, other)
+
+    def __invert__(self):
+        return NotCondition(self)
+
+
+class IsNotEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
+        self.field = field
+        self.value = value
+        self.only_on_change = only_on_change
+
+    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
+            previous = resolve_dotted_attr(original_instance, self.field)
+            return previous == self.value and current != self.value
+        else:
+            return current != self.value
+
+
+class IsEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
+        self.field = field
+        self.value = value
+        self.only_on_change = only_on_change
+
+    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
+            previous = resolve_dotted_attr(original_instance, self.field)
+            return previous != self.value and current == self.value
+        else:
+            return current == self.value
+
+
+class HasChanged(HookCondition):
+    def __init__(self, field, has_changed=True):
+        self.field = field
+        self.has_changed = has_changed
+
+    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)
+        return (current != previous) == self.has_changed
+
+
+class WasEqual(HookCondition):
+    def __init__(self, field, value, only_on_change=False):
+        """
+        Check if a field's original value was `value`.
+        If only_on_change is True, only return True when the field has changed away from that value.
+        """
+        self.field = field
+        self.value = value
+        self.only_on_change = only_on_change
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            return False
+        previous = resolve_dotted_attr(original_instance, self.field)
+        if self.only_on_change:
+            current = resolve_dotted_attr(instance, self.field)
+            return previous == self.value and current != self.value
+        else:
+            return previous == self.value
+
+
+class ChangesTo(HookCondition):
+    def __init__(self, field, value):
+        """
+        Check if a field's value has changed to `value`.
+        Only returns True when original value != value and current value == value.
+        """
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        if original_instance is None:
+            return False
+        previous = resolve_dotted_attr(original_instance, self.field)
+        current = resolve_dotted_attr(instance, self.field)
+        return previous != self.value and current == self.value
+
+
+class IsGreaterThan(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current > self.value
+
+
+class IsGreaterThanOrEqual(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current >= self.value
+
+
+class IsLessThan(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current < self.value
+
+
+class IsLessThanOrEqual(HookCondition):
+    def __init__(self, field, value):
+        self.field = field
+        self.value = value
+
+    def check(self, instance, original_instance=None):
+        current = resolve_dotted_attr(instance, self.field)
+        return current is not None and current <= self.value
+
+
+class AndCondition(HookCondition):
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
+
+    def check(self, instance, original_instance=None):
+        return self.cond1.check(instance, original_instance) and self.cond2.check(
+            instance, original_instance
+        )
+
+
+class OrCondition(HookCondition):
+    def __init__(self, cond1, cond2):
+        self.cond1 = cond1
+        self.cond2 = cond2
+
+    def check(self, instance, original_instance=None):
+        return self.cond1.check(instance, original_instance) or self.cond2.check(
+            instance, original_instance
+        )
+
+
+class NotCondition(HookCondition):
+    def __init__(self, cond):
+        self.cond = cond
+
+    def check(self, instance, original_instance=None):
+        return not self.cond.check(instance, original_instance)