NOTE:

What Are Signals?

Django includes an internal "dispatcher" which provides two pieces of functionality:

  1. Pieces of code which want to advertise what they're doing can use the dispatcher to send "signals" which contain information about what's happening.
  2. Pieces of code which want to do something whenever a certain event happens can use the dispatcher to "listen" for particular signals, then execute the functions they want when those signals are sent out.

The actual mechanism comes from a third-party library called ​PyDispatcher, which is bundled with Django and which lives at django.dispatch.dispatcher. To improve performance the API and implementation has been refactored, as described at the end of this document.

How signals work

A signal is an instance of django.dispatch.Signal acting as reference point for a single activity, and requires nothing special to set up. For example, the post_save signal, found in django.db.models.signals, is defined like so: 

post_save = django.dispatch.Signal()

When a piece of code wants to send a signal, it needs to do two things:

  1. Import the signal from wherever it's been defined.
  2. Use the signal's send function to send the signal.

An example of this can be found in the save method of the base model class, django.db.models.Model; the file in which that class is defined imports the signals defined in the django.db.models module: 

from django.db.models import signals

And in the very last line of the save method, it sends the post_save signal: 

signals.post_save.send(sender=self.__class__, instance=self)

The first argument is fairly clear, and is common for all uses of the dispatcher; sender is the object which is sending the signal; in this case, self.__class__; this will be whatever model class the object which was just saved belongs to.

The second argument, instance, is one of the more interesting features of the dispatcher: when sending a signal, you are free to include any extra arguments beyond the first; if a function which is listening for the signal is expecting certain information to be passed in as arguments, the dispatcher will ensure that the extra arguments to send are used. In this case the extra argument instance is self, which means it will be the object which was just saved. This means that functions which are listening for the post_save signal can, if they want to do something with the object that was just saved, specify that they take an argument named instance.

To listen for a signal, first define a function that you want to execute when the signal is sent; if you know that the signal will be sent with extra arguments and you want to use those arguments, make sure your function accepts them. Then you need to do three things:

  1. Make sure there is a reference to your signal handler somewhere. If it is defined as a local function, chances are it will be garbage collected and won't receive any signals.
  2. Make sure that the signal handler has kwargs as the last parameter.
  3. Import the signal object you'll be listening for.
  4. Use the signal's connect method to tell the dispatcher you want to listen for something.

A good example of this is found in Django's bundled "contenttypes" application, which creates and maintains a registry of all the installed models in your database. In order to do this, the contenttypes app defines a ContentType model, and it needs to know any time a new model is installed so it can create the appropriate ContentType object for that model. To do this, it includes a file called management.py; whenever manage.py syncdb is run, it loops through every application in the INSTALLED_APPS setting, and looks to see if any apps contain a module called management; if they do, manage.py imports them before installing any models, which means that any dispatcher connections listed in an app's management module will be set up before model installation happens.

In its management.py file, the contenttypes app defines a function called update_contenttypes, which takes three arguments: app, created_models and verbosity. These correspond to the extra arguments manage.py will use with dispatcher.send when it sends the post_syncdb signal after installing each new application, and provide enough information to determine which models need to have new ContentType objects created (actually, just app and created_models would be enough; the extra argument, verbosity, is used by manage.py to indicate whether any listening functions should be "verbose" and echo output to the console, or be quiet and not echo any output.

The management.py file also imports django.db.models.signals and django.dispatch.dispatcher; after the update_contenttypes function is defined, it sets up that function to listen for the post_syncdb signal: 

signals.post_syncdb.connect(update_contenttypes)

The method is called on an instance of django.dispatch.Signal, identifying the signal to listen for. The first argument, update_contenttypes, is a reference to the function to execute when the signal is sent out. There is another optional argument, sender, which is not used in this example; sender can be used to narrow down exactly what will be listened for; when you specify sender, your function will only be executed when the object which sent the signal is the same as the object you specify as the sender argument.

An example of this can be found in Django's authentication application: django.contrib.auth.management defines a function called create_superuser, and uses the dispatcher to connect to the post_syncdb signal -- but only when post_syncdb is being sent as a result of installing the auth application. To do this, the auth app's management.py file imports its own models: 

from django.contrib.auth import models as auth_app

And then uses the sender argument to Signal.connect: 

signals.post_syncdb.connect(create_superuser, sender=auth_app)

Here's a breakdown of exactly why that works:

  1. Whenever manage.py syncdb finishes installing the models for a particular application, it sends the post_syncdb signal. You'll remember that dispatcher.send takes an optional argument, sender, which is the object that's "sending" the signal. In this case, manage.py syncdb sets sender to be the models module of the app it just installed.
  2. django.contrib.auth.management import the auth app's models as auth_app, which means that, within that file, the variable auth_app is the module django.contrib.auth.models.
  3. So when manage.py syncdb send the post_syncdb signal with django.contrib.auth.models as the sender argument, the dispatcher notices that this is the same as the sender specified in the dispatcher.connect call in django.contrib.auth.management, and so the create_superuser function is executed.

In case you've ever wondered, that's how Django knows to prompt you to create a superuser whenever you install the auth app for the first time. The auth app also sets up another function -- create_permissions -- which doesn't specify sender in its call to dispatcher.connect, so it runs any time post_syncdb is sent. That's how the auth app creates the add, change and delete Permission objects for each application you install.

List of signals built in to Django

Django defines several sets of signals which are used internally, and which you can listen for in order to run your own custom code at specific moments.

​See built-in signal reference

Refactoring differences

[8223] refactored signals and django.dispatch with an eye towards speed. The net result was up to a 90% improvement in the speed of signal handling, but along the way some backwards-incompatible changes were made:

  • All handlers now must be declared as accepting **kwargs.
  • Signals are now instances of django.dispatch.Signal instead of anonymous objects.
  • Connecting, disconnecting, and sending signals are done via methods on the Signal object instead of through module methods in django.dispatch.dispatcher. The module-level methods are deprecated.
  • The Anonymous and Any sender options no longer exist. You can still receive signals sent by any sender by using sender=None

So, a quick summary of the code changes you'd need to make:

Before After
def my_handler(sender) def my_handler(sender, **kwargs)
my_signal = object() my_signal = django.dispatch.Signal()
dispatcher.connect(my_handler, my_signal) my_signal.connect(my_handler)
dispatcher.send(my_signal, sender) my_signal.send(sender)
dispatcher.connect(my_handler, my_signal, sender=Any) my_signal.connect(my_handler, sender=None)

Tips and Troubleshooting

Help, post_save seems to be emitted twice for each save!

The source of this is documented nicely in #3951 and solved in #6814 (AKA Signals-refactor, r8223).

The short of it is that the signal is bound twice due to double-importing of whatever module is doing the binding. The workaround is to pass dispatch_uid="some.unique.identifier" when binding signals:

signals.post_save.connect(my_handler, MyModel, dispatch_uid="path.to.this.module")

The dispatch_uid string can be any unique string. Since the goal is to prevent connect() from being called twice due to its parent module being imported twice, a good value to use for dispatch_uid is the module's name or path. However, dispatch_uid can be any unique identifier. The net effect is that signals.signal_name.connect will only bind the signal once for each dispatch_uid, even if connect is called multiple times.

Other documentation

Applications not bundled with Django which use signals

Last modified 3 months ago Last modified on Oct 3, 2024, 9:16:49 AM
Note: See TracWiki for help on using the wiki.
Back to Top