django-lifecycle

Instead of using Django Signals or overriding save() and __init__, use the @hook decorator to attach logic to specific lifecycle events. You can use conditions to ensure the hook only runs when specific criteria are met (e.g., when a field has changed or a field matches a specific value).

Commonly used event constants include BEFORE_UPDATE and AFTER_UPDATE.

from django_lifecycle import LifecycleModel, hook, BEFORE_UPDATE, AFTER_UPDATE


class Article(LifecycleModel):
    contents = models.TextField()
    updated_at = models.DateTimeField(null=True)
    status = models.ChoiceField(choices=['draft', 'published'])
    editor = models.ForeignKey(AuthUser)

    @hook(
        BEFORE_UPDATE, 
        condition=WhenFieldHasChanged('contents', has_changed=True),
    )
    def on_content_change(self):
        self.updated_at = timezone.now()

    @hook(
        AFTER_UPDATE,
        condition=(
            WhenFieldValueWas("status", value="draft")
            & WhenFieldValueIs("status", value="published")
        ),
    )
    def on_publish(self):
        send_email(self.editor.email, "An article has published!")

You can define custom logic to control when a @hook is executed.

Function-based conditions

A simple function that accepts (instance, update_fields=None) and returns a bool can be passed to the condition argument of a hook.

Chainable conditions

To allow complex logic using bitwise operators (like & or |), create a class that inherits from ChainableCondition. This allows you to combine your custom condition with built-in conditions like WhenFieldHasChanged.

from django_lifecycle import BEFORE_SAVE
from django_lifecycle.conditions import WhenFieldHasChanged
from django_lifecycle.conditions.base import ChainableCondition


class IsNedFlanders(ChainableCondition):
    def __call__(self, instance, update_fields=None):
        return (
            instance.first_name == "Ned" 
            and instance.last_name == "Flanders"
        )


@hook(
    BEFORE_SAVE,
    condition=(
        WhenFieldHasChanged("first_name")
        & WhenFieldHasChanged("last_name")
        & IsNedFlanders()
    )
)
def foo():
    ...

You can trigger a hook based on the value of a field residing on a related model by using dot-notation in the WhenFieldValueChangesTo condition. For example, employer.name allows you to watch the name field on the Organization model related to UserAccount.

Performance Warning: N+1 Problem

Using dot-notation requires the related model to be loaded during the initial model state capture. To avoid a major N+1 performance hit, you must always load these models using .select_related() in your Django QuerySets.

Example: If watching employer.name, use UserAccount.objects.select_related("employer").

class Organization(models.Model):
    name = models.CharField(max_length=100)


class UserAccount(LifecycleModel):
    username = models.CharField(max_length=100)
    email = models.CharField(max_length=600)
    employer = models.ForeignKey(Organization, on_delete=models.SET_NULL)

    @hook(AFTER_UPDATE, condition=WhenFieldValueChangesTo("employer.name", value="Google"))
    def notify_user_of_google_buy_out(self):
        mail.send_mail("Update", "Google bought your employer!", ["to@example.com"],)

Instead of using Django Signals or overriding save() and __init__ to track state changes, you can use the @hook decorator on methods within a model that inherits from LifecycleModel. This allows you to define logic that executes at specific points in the model's lifecycle (like BEFORE_UPDATE or AFTER_UPDATE) based on specific conditions, such as field changes or specific value transitions.

To use this, your model must inherit from LifecycleModel and you must import the necessary hook constants and condition classes from django_lifecycle.

from django_lifecycle import LifecycleModel, hook, BEFORE_UPDATE, AFTER_UPDATE
from django_lifecycle.conditions import WhenFieldValueIs, WhenFieldValueWas, WhenFieldHasChanged

class Article(LifecycleModel):
    contents = models.TextField()
    updated_at = models.DateTimeField(null=True)
    status = models.ChoiceField(choices=['draft', 'published'])
    editor = models.ForeignKey(AuthUser)

    @hook(BEFORE_UPDATE, WhenFieldHasChanged("contents", has_changed=True))
    def on_content_change(self):
        self.updated_at = timezone.now()

    @hook(
        AFTER_UPDATE, 
        condition=(
            WhenFieldValueWas("status", value="draft")
            & WhenFieldValueIs("status", value="published")
        )
    )
    def on_publish(self):
        send_email(self.editor.email, "An article has published!")

Use the @hook decorator to execute logic at specific points in a Django model's lifecycle. Common lifecycle moments include AFTER_CREATE, AFTER_DELETE, and BEFORE_SAVE. You can also use the on_commit=True argument to ensure the hooked method only runs after the database transaction has been successfully committed, which is useful for enqueuing background jobs.

@hook(AFTER_CREATE)
def do_after_create_jobs(self):
    enqueue_job(process_thumbnail, self.picture_url)

    mail.send_mail(
        'Welcome!', 'Thank you for joining.',
        'from@example.com', ['to@example.com'],
    )

@hook(AFTER_DELETE)
def email_deleted_user(self):
    mail.send_mail(
        'We have deleted your account', 'We will miss you!.',
        'customerservice@corporate.com', ['human@gmail.com'],
    )

@hook(AFTER_CREATE, on_commit=True)
def do_after_create_jobs(self):
    enqueue_job(send_item_shipped_notication, self.item_id)

To trigger a hook when a ForeignKey field itself is changed (i.e., the ID of the related object changes), use WhenFieldHasChanged in the condition parameter of the @hook decorator. Pass the name of the ForeignKey field as a string to the when parameter of the condition.

Note: This monitors the database column storing the foreign key (e.g., employer_id), not the attributes of the related object.

class Organization(models.Model):
    name = models.CharField(max_length=100)


class UserAccount(LifecycleModel):
    username = models.CharField(max_length=100)
    email = models.CharField(max_length=600)
    employer = models.ForeignKey(Organization, on_delete=models.SET_NULL)

    @hook(AFTER_UPDATE, condition=WhenFieldHasChanged("employer", has_changed=True))
    def notify_user_of_employer_change(self):
        mail.send_mail("Update", "You now work for someone else!", [self.email])