Events and Handlers

Events

An ‘event’ is generated when an ‘actor’ performs ‘verb’, involving ‘action’, in the ‘target’.

It could be

<actor> <verb>
<actor> <verb> <target>
<actor> <verb> <trigger> <target>

If is inspired in the Atom Activity Streams.

Event Handler Configuration

The base EventHandler class has the following definition:

class EventHandler:

    # Generic
    ephemeral: bool = False
    dispatch_config: dict = {"args": ("actor", "trigger", "target")}
    title: str | None = None
    text: str | None = None
    delay: int = 0
    notification_creation_async: bool = False
    notification_backends: list[Type["AbstractBackend"]] = []

    # Cool down
    cool_down_manager_class: Type["AbstractCoolDownManager"] | None = None

    # Email backend
    template_email_async: bool = False
    template_email_kwargs: dict = {}

    # Push notification backend
    action_attribute: str = "actor"
    action_type: str | None = None
    action_id: str | None = None
    click_action: str | None = None

Attributes

Each attribute is used to handle the behavior of the event once is dispatched.

ephemeral

Default: False

If this class variable is set to True, the notification object will no be created in the database.

dispatch_config

Default: {"args": ("actor", "trigger", "target")}

This dictionary is used to extract the actor, trigger and target from the arguments of the function that dispatch the event.

title

Default: None

If defined, it will be the default title string of the notification.

text

Default: None

If defined, it will be the default text body of the notification.

delay

Default: 0

De value of the attribute countdown in the launch of the task that launches the notification.

notification_creation_async`

Default: False

If it’s set to True, then a Celery task is used to create the notification model.

notification_backends`

Default: []

List of notification backends that the handler should use in order to send the notification to the audience.

cool_down_manager_class

Default: None

Indicates the class that should be used to handle the cool down. You should specify the class to use this function.

Django-snitch comes with the class snitch.CoolDownManager that can be used. It uses Django’s cache framework to handle the count of how many notifications are sent to a user.

cool_down_attempts

Default: 1

It handles the number of notifications that have to be sent in order to stop the sending. This can be an int, a callable that returns an integer number or a string and receives two arguments, and snitch.EventHandler and a receiver as a Django Model. If it’s a string, it should reference a method in the handler with and argument, the receiver .

cool_down_time

Default: 0

It handles the number of seconds to wait until the notifications will be send again. This can be an int, a callable that returns an integer number or a string and receives two arguments, and snitch.EventHandler and a receiver as a Django Model. If it’s a string, it should reference a method in the handler with and argument, the receiver .

template_email_async

Default: False

Sets if the email can use async, False by default, because the notification is already sent using a task.

template_email_kwargs

Default: {}

The kwargs values fot the TemplateEmailMessage used to send and email.

action_attribute

Default: actor

Attribute of the event used to set the action attribute in the push notification.

action_type

Default: None

The string to identify the class o type of the action attribute in the push notification.

action_id

Default: None

The string to identify the specific action to be send in the push notification.

click_action`

Default: None

The string used by the clients that receives the push notification.

use_localization_keys

Default: False

If set to True, the notifications will be sent using the get_title_localization_key``method and ``get_text_localization_key method.

Methods to overwrite

should_notify(self, receiver: 'models.Model')

Used by the event to create or not the notifications to the audience. If the notification is not created, there isn’t any notification sent (push, email, etc), and there isn’t any record in the database.

Parameters:

receiver (models.Model) – The receiver object of the notification.

Returns:

If the notification should be created.

Return type:

bool

should_send(self, receiver: 'models.Model')

Used by the notification to send or not the notification to the user. If returns False, the notification is created in the database but not sent.

Parameters:

receiver (models.Model) – The receiver object of the notification.

Returns:

If the notification should be sent.

Return type:

bool

get_text(self)

Override to handle different human readable implementations of the notification text.

Returns:

The text of the notification.

Return type:

str

get_title(self)

Override to handle different human readable implementations of the notification title.

Returns:

The title of the notification.

Return type:

str

audience(self)

Gets the audience of the event. None by default, to be hooked by the user.

Returns:

The QuerySet of the receivers of the notification.

Return type:

models.QuerySet