Django includes a “signal dispatcher” which helps allow decoupled applications
get notified when actions occur elsewhere in the framework. In a nutshell,
signals allow certain senders to notify a set of receivers that some action
has taken place. They’re especially useful when many pieces of code may be
interested in the same events.
Django provides a set of built-in signals that let user
code get notified by Django itself of certain actions. These include some useful
Sent before or after a model’s
Sent when a
ManyToManyFieldon a model is changed.
Sent when Django starts or finishes an HTTP request.
See the built-in signal documentation for a complete list,
and a complete explanation of each signal.
You can also define and send your own custom signals; see below.
Listening to signals¶
To receive a signal, register a receiver function using the
Signal.connect() method. The receiver function is called when the signal
connect(receiver, sender=None, weak=True, dispatch_uid=None)¶
- receiver — The callback function which will be connected to this
signal. See Receiver functions for more information.
- sender — Specifies a particular sender to receive signals from. See
Connecting to signals sent by specific senders for more information.
- weak — Django stores signal handlers as weak references by
default. Thus, if your receiver is a local function, it may be
garbage collected. To prevent this, pass
weak=Falsewhen you call
- dispatch_uid — A unique identifier for a signal receiver in cases
where duplicate signals may be sent. See
Preventing duplicate signals for more information.
- receiver — The callback function which will be connected to this
Let’s see how this works by registering a signal that
gets called after each HTTP request is finished. We’ll be connecting to the
First, we need to define a receiver function. A receiver can be any Python
function or method:
def my_callback(sender, **kwargs): print("Request finished!")
Notice that the function takes a
sender argument, along with wildcard
keyword arguments (
**kwargs); all signal handlers must take these arguments.
We’ll look at senders a bit later, but right now look at the
argument. All signals send keyword arguments, and may change those keyword
arguments at any time. In the case of
request_finished, it’s documented as sending no
arguments, which means we might be tempted to write our signal handling as
This would be wrong — in fact, Django will throw an error if you do so. That’s
because at any point arguments could get added to the signal and your receiver
must be able to handle those new arguments.
Connecting receiver functions¶
There are two ways you can connect a receiver to a signal. You can take the
manual connect route:
from django.core.signals import request_finished request_finished.connect(my_callback)
Alternatively, you can use a
Parameters: signal — A signal or a list of signals to connect a function to.
Here’s how you connect with the decorator:
from django.core.signals import request_finished from django.dispatch import receiver @receiver(request_finished) def my_callback(sender, **kwargs): print("Request finished!")
my_callback function will be called each time a request finishes.
Strictly speaking, signal handling and registration code can live anywhere
you like, although it’s recommended to avoid the application’s root module
models module to minimize side-effects of importing code.
In practice, signal handlers are usually defined in a
submodule of the application they relate to. Signal receivers are
connected in the
ready() method of your
application configuration class. If you’re using the
decorator, simply import the
signals submodule inside
Connecting to signals sent by specific senders¶
Some signals get sent many times, but you’ll only be interested in receiving a
certain subset of those signals. For example, consider the
django.db.models.signals.pre_save signal sent before a model gets saved.
Most of the time, you don’t need to know when any model gets saved — just
when one specific model is saved.
In these cases, you can register to receive signals sent only by particular
senders. In the case of
django.db.models.signals.pre_save, the sender
will be the model class being saved, so you can indicate that you only want
signals sent by some model:
from django.db.models.signals import pre_save from django.dispatch import receiver from myapp.models import MyModel @receiver(pre_save, sender=MyModel) def my_handler(sender, **kwargs): ...
my_handler function will only be called when an instance of
Different signals use different objects as their senders; you’ll need to consult
the built-in signal documentation for details of each
Preventing duplicate signals¶
In some circumstances, the code connecting receivers to signals may run
multiple times. This can cause your receiver function to be registered more
than once, and thus called multiple times for a single signal event.
If this behavior is problematic (such as when using signals to
send an email whenever a model is saved), pass a unique identifier as
dispatch_uid argument to identify your receiver function. This
identifier will usually be a string, although any hashable object will
suffice. The end result is that your receiver function will only be
bound to the signal once for each unique
from django.core.signals import request_finished request_finished.connect(my_callback, dispatch_uid="my_unique_identifier")
Defining and sending signals¶
Your applications can take advantage of the signal infrastructure and provide
its own signals.
All signals are
django.dispatch.Signal instances. The
providing_args is a list of the names of arguments the signal will provide
to listeners. This is purely documentational, however, as there is nothing that
checks that the signal actually provides these arguments to its listeners.
import django.dispatch pizza_done = django.dispatch.Signal(providing_args=["toppings", "size"])
This declares a
pizza_done signal that will provide receivers with
Remember that you’re allowed to change this list of arguments at any time, so
getting the API right on the first try isn’t necessary.
There are two ways to send signals in Django.
To send a signal, call either
Signal.send() (all built-in signals use
Signal.send_robust(). You must provide the
(which is a class most of the time) and may provide as many other keyword
arguments as you like.
For example, here’s how sending our
pizza_done signal might look:
class PizzaStore: ... def send_pizza(self, toppings, size): pizza_done.send(sender=self.__class__, toppings=toppings, size=size) ...
send_robust() return a list of tuple pairs
[(receiver, response), ... ], representing the list of called receiver
functions and their response values.
send() differs from
send_robust() in how exceptions raised by receiver
functions are handled.
send() does not catch any exceptions raised by
receivers; it simply allows errors to propagate. Thus not all receivers may
be notified of a signal in the face of an error.
send_robust() catches all errors derived from Python’s
and ensures all receivers are notified of the signal. If an error occurs, the
error instance is returned in the tuple pair for the receiver that raised the error.
The tracebacks are present on the
__traceback__ attribute of the errors
returned when calling
disconnect(receiver=None, sender=None, dispatch_uid=None)¶
receiver argument indicates the registered receiver to disconnect. It
dispatch_uid is used to identify the receiver.