diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..21aa63a --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,88 @@ +Examples +-------- + +Sending mails +============= + +Sending an email can take a while so why not queue it:: + + # Welcome mail with follow up + from datetime import timedelta + from django.utils import timezone + from django_q import async, schedule, Schedule + + + def welcome_mail(user): + msg = 'Welcome to our website' + # send this message right away + async('django.core.mail.send_mail', + 'Welcome', + msg, + 'from@example.com', + [user.email]) + # and this follow up email in one hour + msg = 'Here are some tips to get you started...' + schedule('django.core.mail.send_mail', + 'Follow up', + msg, + 'from@example.com', + [user.email], + schedule_type=Schedule.ONCE, + next_run=timezone.now() + timedelta(hours=1)) + + # since the `repeats` defaults to -1 + # this schedule will erase itself after having run + + +Signals +======= + +A good place to use async tasks are Django's model signals. You don't want to delay the saving or creation of objects, but sometimes you want to trigger a lot of actions:: + + # Message on object change + from django.contrib.auth.models import User + from django.db.models.signals import pre_save + from django.dispatch import receiver + from django_q import async + + # set up the pre_save signal for our user + @receiver(pre_save, sender=User) + def email_changed(sender, instance, **kwargs): + try: + user = sender.objects.get(pk=instance.pk) + except sender.DoesNotExist: + pass # new user + else: + # has his email changed? + if not user.email == instance.email: + # tell everyone + async('tasks.inform_everyone', instance) + +The task will send a message to everyone else informing them that the users email address has changed. Note that this has adds almost no overhead to the save action:: + + # tasks.py + def inform_everyone(user): + mails = [] + for u in User.objects.exclude(pk=user.pk): + msg = 'Dear {}, {} has a new email address: {}' + msg = msg.format(u.username, user.username, user.email) + mails.append(('New email', msg, + 'from@example.com', [u.email])) + return send_mass_mail(mails) + + + # or do it async again + def inform_everyone_async(user): + for u in User.objects.exclude(pk=user.pk): + msg = 'Dear {}, {} has a new email address: {}' + msg = msg.format(u.username, user.username, user.email) + async('django.core.mail.send_mail', + 'New email', msg, 'from@example.com', [u.email]) + + +.. note:: + + If you have an example you want to share, please submit a pull request on `github `__. + + + diff --git a/docs/index.rst b/docs/index.rst index 3bb6677..a4241e4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ Contents: Cluster Monitor Admin + Examples * :ref:`genindex` * :ref:`search`