# 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
## 📦 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
```
## 🧩 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
Raw data
{
"_id": null,
"home_page": "https://github.com/AugendLimited/django-bulk-hooks",
"name": "django-bulk-hooks",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "django, bulk, hooks",
"author": "Konrad Beck",
"author_email": "konrad.beck@merchantcapital.co.za",
"download_url": "https://files.pythonhosted.org/packages/87/97/b0d73406852b1a6fa8ea119c3b8ad400fe27e9dcc9b708efd6402f95f937/django_bulk_hooks-0.1.72.tar.gz",
"platform": null,
"description": "\n# django-bulk-hooks\n\n\u26a1 Bulk hooks for Django bulk operations and individual model lifecycle events.\n\n`django-bulk-hooks` brings a declarative, hook-like experience to Django's `bulk_create`, `bulk_update`, and `bulk_delete` \u2014 including support for `BEFORE_` and `AFTER_` hooks, conditions, batching, and transactional safety. It also provides comprehensive lifecycle hooks for individual model operations.\n\n## \u2728 Features\n\n- Declarative hook system: `@hook(AFTER_UPDATE, condition=...)`\n- BEFORE/AFTER hooks for create, update, delete\n- Hook-aware manager that wraps Django's `bulk_` operations\n- **NEW**: `HookModelMixin` for individual model lifecycle events\n- Hook chaining, hook deduplication, and atomicity\n- Class-based hook handlers with DI support\n- Support for both bulk and individual model operations\n\n## \ud83d\ude80 Quickstart\n\n```bash\npip install django-bulk-hooks\n```\n\n### Define Your Model\n\n```python\nfrom django.db import models\nfrom django_bulk_hooks.models import HookModelMixin\n\nclass Account(HookModelMixin):\n balance = models.DecimalField(max_digits=10, decimal_places=2)\n # The HookModelMixin automatically provides BulkHookManager\n```\n\n### Create a Hook Handler\n\n```python\nfrom django_bulk_hooks import hook, AFTER_UPDATE, Hook\nfrom django_bulk_hooks.conditions import WhenFieldHasChanged\nfrom .models import Account\n\nclass AccountHooks(Hook):\n @hook(AFTER_UPDATE, model=Account, condition=WhenFieldHasChanged(\"balance\"))\n def log_balance_change(self, new_records, old_records):\n print(\"Accounts updated:\", [a.pk for a in new_records])\n \n @hook(BEFORE_CREATE, model=Account)\n def before_create(self, new_records, old_records):\n for account in new_records:\n if account.balance < 0:\n raise ValueError(\"Account cannot have negative balance\")\n \n @hook(AFTER_DELETE, model=Account)\n def after_delete(self, new_records, old_records):\n print(\"Accounts deleted:\", [a.pk for a in old_records])\n```\n\n## \ud83d\udee0 Supported Hook Events\n\n- `BEFORE_CREATE`, `AFTER_CREATE`\n- `BEFORE_UPDATE`, `AFTER_UPDATE`\n- `BEFORE_DELETE`, `AFTER_DELETE`\n\n## \ud83d\udd04 Lifecycle Events\n\n### Individual Model Operations\n\nThe `HookModelMixin` automatically triggers hooks for individual model operations:\n\n```python\n# These will trigger BEFORE_CREATE and AFTER_CREATE hooks\naccount = Account.objects.create(balance=100.00)\naccount.save() # for new instances\n\n# These will trigger BEFORE_UPDATE and AFTER_UPDATE hooks\naccount.balance = 200.00\naccount.save() # for existing instances\n\n# This will trigger BEFORE_DELETE and AFTER_DELETE hooks\naccount.delete()\n```\n\n### Bulk Operations\n\nBulk operations also trigger the same hooks:\n\n```python\n# Bulk create - triggers BEFORE_CREATE and AFTER_CREATE hooks\naccounts = [\n Account(balance=100.00),\n Account(balance=200.00),\n]\nAccount.objects.bulk_create(accounts)\n\n# Bulk update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks\nfor account in accounts:\n account.balance *= 1.1\nAccount.objects.bulk_update(accounts, ['balance'])\n\n# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks\nAccount.objects.bulk_delete(accounts)\n```\n\n### Queryset Operations\n\nQueryset operations are also supported:\n\n```python\n# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks\nAccount.objects.update(balance=0.00)\n\n# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks\nAccount.objects.delete()\n```\n\n## \ud83e\udde0 Why?\n\nDjango's `bulk_` methods bypass signals and `save()`. This package fills that gap with:\n\n- Hooks that behave consistently across creates/updates/deletes\n- **NEW**: Individual model lifecycle hooks that work with `save()` and `delete()`\n- Scalable performance via chunking (default 200)\n- Support for `@hook` decorators and centralized hook classes\n- **NEW**: Automatic hook triggering for admin operations and other Django features\n\n## \ud83d\udce6 Usage Examples\n\n### Individual Model Operations\n\n```python\n# These automatically trigger hooks\naccount = Account.objects.create(balance=100.00)\naccount.balance = 200.00\naccount.save()\naccount.delete()\n```\n\n### Bulk Operations\n\n```python\n# These also trigger hooks\nAccount.objects.bulk_create(accounts)\nAccount.objects.bulk_update(accounts, ['balance'])\nAccount.objects.bulk_delete(accounts)\n```\n\n### Advanced Hook Usage\n\n```python\nclass AdvancedAccountHooks(Hook):\n @hook(BEFORE_UPDATE, model=Account, condition=WhenFieldHasChanged(\"balance\"))\n def validate_balance_change(self, new_records, old_records):\n for new_account, old_account in zip(new_records, old_records):\n if new_account.balance < 0 and old_account.balance >= 0:\n raise ValueError(\"Cannot set negative balance\")\n \n @hook(AFTER_CREATE, model=Account)\n def send_welcome_email(self, new_records, old_records):\n for account in new_records:\n # Send welcome email logic here\n pass\n```\n\n## \ud83e\udde9 Integration with Queryable Properties\n\nYou can extend from `BulkHookManager` to support formula fields or property querying.\n\n```python\nclass MyManager(BulkHookManager, QueryablePropertiesManager):\n pass\n```\n\n## \ud83d\udcdd License\n\nMIT \u00a9 2024 Augend / Konrad Beck\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Hook-style hooks for Django bulk operations like bulk_create and bulk_update.",
"version": "0.1.72",
"project_urls": {
"Homepage": "https://github.com/AugendLimited/django-bulk-hooks",
"Repository": "https://github.com/AugendLimited/django-bulk-hooks"
},
"split_keywords": [
"django",
" bulk",
" hooks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "55dbb03f11d5e4d18b0c29d6c3ce9c127ad26dc5c06ce4dc31a5b29437ceedd7",
"md5": "4f9b6f08755af3ac80f3fc3b47cbceb5",
"sha256": "8d9d2c02fb5d81d0158e2cd5bc62ccd919ece6317de9d61686733c0969797a3d"
},
"downloads": -1,
"filename": "django_bulk_hooks-0.1.72-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f9b6f08755af3ac80f3fc3b47cbceb5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 14385,
"upload_time": "2025-07-20T11:25:51",
"upload_time_iso_8601": "2025-07-20T11:25:51.245642Z",
"url": "https://files.pythonhosted.org/packages/55/db/b03f11d5e4d18b0c29d6c3ce9c127ad26dc5c06ce4dc31a5b29437ceedd7/django_bulk_hooks-0.1.72-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8797b0d73406852b1a6fa8ea119c3b8ad400fe27e9dcc9b708efd6402f95f937",
"md5": "1963e64ea68e7000c831d637628e0494",
"sha256": "0cbafee44c5cdac98460b8baed2c0cdb7dc68b5842b9ad9b31b3e202e3ab234d"
},
"downloads": -1,
"filename": "django_bulk_hooks-0.1.72.tar.gz",
"has_sig": false,
"md5_digest": "1963e64ea68e7000c831d637628e0494",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 10689,
"upload_time": "2025-07-20T11:25:52",
"upload_time_iso_8601": "2025-07-20T11:25:52.319128Z",
"url": "https://files.pythonhosted.org/packages/87/97/b0d73406852b1a6fa8ea119c3b8ad400fe27e9dcc9b708efd6402f95f937/django_bulk_hooks-0.1.72.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 11:25:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AugendLimited",
"github_project": "django-bulk-hooks",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-bulk-hooks"
}
JSON
