Merge pull request #12 from Koed00/docs

Adding examples to the docs

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 <https://github.com/Koed00/django-q/>`__.
+
+
+

docs/index.rst

@@ -37,6 +37,7 @@ Contents:
     Cluster <cluster>
     Monitor <monitor>
     Admin <admin>
+    Examples <examples>
 
 * :ref:`genindex`
 * :ref:`search`