'''NOTE''': 
 * Read the current [http://docs.djangoproject.com/en/dev/topics/signals/ Signal Documentation]
 * Signals have been refactored in a backwards-incompatible way. See [BackwardsIncompatibleChanges#Signalrefactoring BackwardsIncompatibleChanges] for more details.

== 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 [http://pydispatcher.sourceforge.net/ 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.

[http://docs.djangoproject.com/en/dev/ref/signals/ 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 ==

 * [http://feh.holsman.net/articles/2006/06/13/django-signals Django signals] -- blog entry by Ian Holsman which discusses signals in general.
 * [http://www.bright-green.com/blog/2006_07_12/initialising_application_data_.html Initializing application data in Django] -- blog entry by Alan Green which discusses use of the `post_syncdb` signal to provide initial application data.
 * [http://www.b-list.org/weblog/2006/09/10/django-tips-laying-out-application Django tips: laying out an application] -- blog entry by James Bennett which mentions the use of the `post_syncdb` signal to execute custom functions when an application is installed.
 * [http://www.mercurytide.com/whitepapers/django-signals/ Django signals] -- Mercurytide whitepaper explaining Django's dispatcher.

== Applications not bundled with Django which use signals ==

 * [http://pinaxproject.com/ Pinax]
 * [http://zyons.com/ Zyons]
 * http://django-utils.googlecode.com/svn/branches/0.1/thumbnail/field.py
 * [http://satchmoproject.com/ Satchmo]
 * [http://getbanjo.com/ Banjo]
 * [http://code.google.com/p/django-announcements/ Django Announcements]
 * [http://code.google.com/p/django-evolution/ Django Evolution]
 * [http://code.google.com/p/django-stdimage/ Django Standarized Image Field]
 * [http://code.google.com/p/django-reversion/ Django Reversion]