I’ve just spent the last few hours learning how to use signals in Django. After many, many searches on Google and much trial and error, I think I finally have a grasp on these silly things, and since I’m an all around nice guy, I’m going to spare those lucky few that happen upon this post the same hell.
Before I start, I want to go ahead and give credit to those who provided some of the crucial pieces to the puzzle during my quest.
Okay, now let’s get started.
Creating Custom Signals
In the application I’m working on, I needed to send an email whenever a user reset his/her password, a pretty common use case. Unfortunately, none of Django’s built-in signals fit the bill. The User model gets saved when the password is reset (allowing the use of the post_save signal), but it also gets saved in a lot of other scenarios. The password reset is a special case and needed to be handled as such.
Turns out that it’s actually not that difficult to set this up. If you haven’t already, create a file named signals.py in directory of the application you’re working on. Then in that file, add the following:
# myapp/signals.py
password_reset = object()
The name `password_reset` is inconsequential; use whatever name best conveys the action that causes the signal to be sent.
Next, set up a listener for that signal. The following code can technically go just about anywhere, as long as it gets executed before the signal is sent. I put it in models.py for ease.
# myapp/models.py
from django.dispatch import dispatcher
from myproject.myapp import signals as custom_signals
…
dispatcher.connect(send_password_reset_email, signal=custom_signals.password_reset)
`send_password_reset_email` is the function that will be called when the signal is received. Obviously, we’ll need to set that up. Back to signals.py:
# myapp/signals.py
from django.conf import settings
from django.core.mail import send_mail
from django.contrib.sites.models import Site
from django.template.loader import render_to_string
…
def send_password_reset_email(sender, user, new_pass, signal, *args, **kwargs):
current_site = Site.objects.get_current()
subject = “Password Reset on %(site_name)s” % { ’site_name’: current_site.name }
message = render_to_string(
‘account/password_reset_email.txt’,
{ ‘username’: user.username,
‘new_pass’: new_pass,
‘current_site’: current_site }
)
send_mail(subject, message, settings.DEFAULT_FROM_EMAIL, [user.email])
Exactly how this code works is left as an exercise to the reader. I provided it merely to be comprehensive. What the function that gets called when the signal is received does will be specific to your purposes.
However, there are a few points worth mentioning. When you use Django’s built-in signals, your function definition will almost invariably look like the following:
def my_function(sender, instance, signal, *args, **kwargs):
Notice that my definition didn’t include `instance` and had `user` and `new_pass` arguments instead. You can pass whatever arguments you like when you send the signal (we’ll get to this in a second). The only requirement is that the function that gets called can handle them. Django simply chose to use an argument named `instance`, nothing more, nothing less.
Finally, at the exact point where you want function associated with the signal executed (in my case, right after a new password is generated and the User instance is saved) insert the following:
dispatcher.send(signal=custom_signals.password_reset, user=self.user, new_pass=new_pass)
The only required part is obviously the signal you want to send. Everything after is simply data you’d like to pass along. Remember that the function definition in signals.py must accept all the arguments you choose to pass in.
Also don’t forget to add the following to your imports in the file where you call dispatcher.send():
from django.dispatch import dispatcher
from myproject.myapp import signals as custom_signals
And we’re done. Easy as pie, once you know what you’re doing.
Signaling Just When an Object is Created
Conspicuously missing from Django’s built-in signals is one for the creation of an object. We have pre_save and post_save signals, but both of those work whether the object is being created or just being updated.
Again, finding a solution to this little issue was spurred by my own needs. I wanted to send a welcome email when a user first registers, another common use case. Obviously, I didn’t want the same welcome email sent everytime the user updates their details so post_save was out. Or was it?
After a fair amount of digging, I found the solution squirreled away in Django’s model tests. Apparently, Django automagically passes in a `created` flag if the object was created, so all that’s required is to test for that flag before you whatever you plan on doing (sending the welcome email in my case).
def send_welcome_email(sender, instance, signal, *args, **kwargs):
if ‘created’ in kwargs:
if kwargs['created']:
# Send email
First, we test that a `created` argument was passed in. If it was, we verify that it’s value is True.
Finally, set up a listener as usual. Again, where you put it matters not as long as it gets executed before the signal gets sent; models.py is a good place.
# myapp/models.py
from django.dispatch import dispatcher
from django.db.models import signals
…
dispatcher.connect(send_welcome_email, signal=signals.post_save, sender=UserProfile)
The `sender` argument limits the signal to being sent only for that particular model. I chose to send it upon the creation of UserProfile, the profile module associated with User in my app. If you left this part out, our send_welcome_email function would be called everytime any model in your application was saved, which would obviously not be desirable.
And, just like that, you get code that will only execute when the model is first created.
Handling Signals Asynchronously
Both of the above examples send emails. It normally doesn’t take much time to send an email, but if the server load is heavy, it could take longer than normal. Ideally, anytime you do anything like this, you want it to be done asynchronously so that users don’t have to wait for the processing to finish before they can move on to something else.
Django’s signals provide half the functionality by decoupling the code for sending the email from the view. However, by default, Django’s signals are synchronous; the signal gets sent and the application waits for its successful completion before moving on. Thankfully, Python has the answer in its threading module.
A thread, extremely simplified, can be thought of as a branch of a running program (Django in this case). It becomes its own entity, able to run independently of its parent process. Extremely simplified, again, you could think of it as a little mini-Django tasked with a very specific and finite purpose. Once it completes its function, it goes away. This purchases us the ability to let something run, while still continuing on in our application in general.
While it sounds rather complicated, it’s actually relatively easy to set up. The following is the actual code I’m using for the welcome email discussed earlier:
import threading
…
class WelcomeEmailThread(threading.Thread):
def __init__(self, instance):
self.instance = instance
threading.Thread.__init__(self)
def run (self):
# The actual code we want to run, i.e. sending the email
def send_welcome_email(sender, instance, signal, *args, **kwargs):
if ‘created’ in kwargs:
if kwargs['created']:
WelcomeEmailThread(instance).start()
First, we create a new class which subclasses threading.Thread. The name of the class is inconsequential; just pick something descriptive. In this class, we have two functions defined: `__init__` and `run`.
The `__init__` function is provided to allow us to pass in the instance we received from the signal. We store the instance as an attribute so it can be retrieved later, and then we call the `__init__` method on threading.Thread. This is necessary because we have overloaded (replaced) the `__init__` function inherited from threading.Thread, but we did not replace all of its functionality as well. Therefore, it still needs to complete its normal initialization procedures.
The `run` function is the heart of the class. This is where the email sending will now occur.
Finally, in the `send_welcome_email` function, which previously housed the code for sending the email, we now start the thread instead. The `if` statements are just specifying that this code should only run if the object is being created instead of updated (see previous topic).
That’s all that’s required. Now, when the signal is received it will simply spawn off a thread to send the email and return processing back to the rest of our application. Not bad at all.
Wrap Up
That’s all I’ve got for now, but I think it covers the three most confusing areas of Django’s signals. Happy Django’ing.
