Lifecycle Hooks
Lex App models support lifecycle hooks — methods that run automatically at specific points in a model's lifecycle. Hooks are declared with the @hook decorator from django-lifecycle, making execution explicit and traceable.
Basic Example
from django_lifecycle import hook, AFTER_CREATE
from lex.core.models.LexModel import LexModel
from django.db import models
class UploadBalanceSheet(LexModel):
quarter = models.ForeignKey('Quarter', on_delete=models.CASCADE)
balance_sheet_file = models.FileField(upload_to='balance_sheets/')
processed_rows = models.IntegerField(default=0)
@hook(AFTER_CREATE)
def process_file(self):
import pandas as pd
df = pd.read_excel(self.balance_sheet_file.path)
for _, row in df.iterrows():
BalanceSheetEntry.objects.create(
quarter=self.quarter,
account_name=row['Account'],
amount=row['Amount']
)
self.processed_rows = len(df)
self.save(skip_hooks=True)The @hook(AFTER_CREATE) decorator tells the framework to call process_file() immediately after the record is saved for the first time. The method name is yours to choose — what matters is the decorator.
Available Hooks
Hook | When It Fires |
|---|---|
| Before the first |
| After the first |
| Before subsequent |
| After subsequent |
| Before any |
| After any |
| Before |
| After |
Conditional Hooks
You can add conditions to hooks so the method only runs when a specific criteria is met:
from django_lifecycle import hook, AFTER_UPDATE
from django_lifecycle.conditions import WhenFieldValueIs, WhenFieldHasChanged
class Invoice(LexModel):
status = models.CharField(max_length=50)
amount = models.DecimalField(max_digits=10, decimal_places=2)
@hook(AFTER_UPDATE, condition=WhenFieldValueIs("status", "Paid"))
def send_receipt(self):
EmailService.send_receipt(self)
@hook(AFTER_UPDATE, condition=WhenFieldHasChanged("amount"))
def log_amount_change(self):
LexLogger().add_text(f"Amount changed to {self.amount}").log()Preventing Recursion
When calling save() inside a hook, always use skip_hooks=True to prevent infinite loops:
@hook(AFTER_CREATE)
def process_and_save(self):
self.status = "Done"
self.save(skip_hooks=True) # prevents the hook from firing againCalling
self.save()withoutskip_hooks=Trueinside a hook will cause infinite recursion. Always useskip_hooks=Truewhen saving inside hooks.
Validation Hooks
LexModel also provides two built-in validation hooks that run as part of the save lifecycle. These are not Django's standard clean() / full_clean() — they're Lex App–specific hooks with a powerful rollback mechanism.
flowchart TD
A["model.save() called"] --> B["pre_validation()"]
B --> C{"passes?"}
C -- "Yes" --> D["Django saves to DB"]
C -- "Raises exception" --> E["Save CANCELLED"]
D --> F["post_validation()"]
F --> G{"passes?"}
G -- "Yes" --> H["Done"]
G -- "Raises exception" --> I["ROLLBACK to pre-save state"]
style E fill:#F44336,color:#fff
style I fill:#F44336,color:#fff
style H fill:#4CAF50,color:#fffpre_validation() — Guard Before Save
Use this to block invalid data from being saved. If you raise an exception, the save is cancelled entirely — nothing is written to the database.
class Invoice(LexModel):
amount = models.DecimalField(max_digits=10, decimal_places=2)
due_date = models.DateField()
status = models.CharField(max_length=50, default="Draft")
def pre_validation(self):
if self.amount < 0:
raise ValueError("Invoice amount cannot be negative.")
if not self.pk and self.due_date < timezone.now().date():
raise ValueError("Due date must be in the future for new invoices.")
pre_validation()vs. serializer validation
These look similar — both block bad data before save — but they run at different layers.pre_validation()runs on everysave(), no matter how it's triggered (API, hook, management command, calculation). Serializer validation only runs when data arrives through the REST API. Usepre_validation()for universal business rules; use serializer validation for API-specific concerns like formatting or permission-aware checks.
post_validation() — Verify After Save + Auto-Rollback
Use this for checks that need the saved state (e.g., aggregate constraints). If you raise an exception, the framework automatically rolls back the record to its pre-save state.
class ExpenseReport(LexModel):
amount = models.DecimalField(max_digits=10, decimal_places=2)
quarter = models.ForeignKey('Quarter', on_delete=models.CASCADE)
def post_validation(self):
total = ExpenseReport.objects.filter(
quarter=self.quarter
).aggregate(total=models.Sum('amount'))['total'] or 0
if total > self.quarter.expense_budget:
raise ValueError(
f"Total expenses ({total}) exceed quarterly budget "
f"({self.quarter.expense_budget}). This expense was rolled back."
)How the rollback works internally
Beforepre_validation()runs, the framework captures a snapshot of all model field values. Ifpost_validation()raises an exception:
- Field values are restored from the snapshot
- A
save(skip_hooks=True)is executed to persist the rollback- The operation is wrapped in
transaction.atomic()with savepoints- A
ValidationErroris raised to the caller
Which Pattern Should I Use?
Use Case | Pattern |
|---|---|
User-initiated, long-running calculation with progress tracking | CalculationModel + |
Automatic processing on create (fire-and-forget) |
|
Block invalid data before save |
|
Verify constraints after save (with auto-rollback) |
|
Side effects after save (logging, notifications) |
|
Migrating from V1?
If you're coming fromUploadModelMixin, here's what changes:
Aspect
V1 (Old)
Current
Base class
UploadModelMixin
LexModelTrigger mechanism
Implicit global signals
Explicit
@hookdecoratorsMethod name
update()Any name you choose
When it runs
Hidden — hard to trace
Clearly declared on the decorator
Migration Steps
- Change base class:
UploadModelMixin→LexModel- Add
from django_lifecycle import hook, AFTER_CREATE- Replace
def update(self):with@hook(AFTER_CREATE)+ a descriptive method name- Add
self.save(skip_hooks=True)if saving inside the hook
Was this helpful?
Your feedback shapes what we write next.
