django-gearman-proxy 1.0.1
Proxy backends/workers for asynchronous email and sms sending using gearman as message queue.
License: BSD
Keywords: django gearman email sms asynchronous message queue

django-gearman-proxy
====================

django-gearman-proxy is django app containing backends/workers for asynchronous email and sms sending
using gearman as message queue.


How it works
------------

**Emails**

This app enables you to send email asynchronously without blocking current threads, while
sending email messages via various backends.

This setting in your project settings file does the following: ::

 # E-mails are sent to proxy backend.
 EMAIL_BACKEND = 'django_gearman_proxy.backends.mail.EmailBackend'

 # Email backend to be used inside of mail sender worker.
 GEARMAN_EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'


All email messages are sent to proxy email backend defined in settings *EMAIL_BACKEND*, in this example
*'django_gearman_proxy.backends.mail.EmailBackend'*. This backend serializes email message to json format and
submit it as background job to gearman message queue. django-gearman-proxy contains asynchronous email worker
implemented as django command. You have to start this command to make the magic work. ::

 $ python manage.py send_email

Right after *send_email* command is up and running, it pulls email message job from gearman message queue,
unserialize it from json and send it via backend defined in *GEARMAN_EMAIL_BACKEND*, in this example
*'django.core.mail.backends.smtp.EmailBackend'*. This architecture allows to send email messages directly from
your django application, without blocking request/response cycles because email messages are sent in background.

**Sms messages**

This app enables you to send sms messages asynchronously without blocking current threads, while
sending sms messages via various backends.

This setting in your project settings file does the following: ::

 # Sms messages are sent to proxy backend.
 SMS_BACKEND = 'sendsms.backends.smssluzbacz.SmsBackend' = 'django_gearman_proxy.backends.sms.SmsBackend'

 # Sms backend to be used inside of sms sender worker.
 GEARMAN_SMSL_BACKEND = 'sendsms.backends.smssluzbacz.SmsBackend'


All sms messages are sent to proxy sms backend defined in settings *SMS_BACKEND*, in this example
*'django_gearman_proxy.backends.sms.SmsBackend'*. This backend serializes sms message to json format and
submit it as background job to gearman message queue. django-gearman-proxy contains asynchronous sms worker
implemented as django command. You have to start this command to make the magic work. ::

 $ python manage.py send_sms

Right after *send_sms* command is up and running, it pulls sms message job from gearman message queue,
unserialize it from json and send it via backend defined in *GEARMAN_SMS_BACKEND*, in this example
*'sendsms.backends.smssluzbacz.SmsBackend'*. This architecture allows to send sms messages directly from
your django application, without blocking request/response cycles because sms messages are sent in background.


For more information how to run command as asynchronous workers, please
refer to `django-gearman-commands <http://github.com/CodeScaleInc/django-gearman-commands>`_.


Requirements
------------

 - python 2.7+
 - django
 - django_gearman_commands
 - smssluzbacz-api
 - django-sendsms
 - python-gearman
 - running gearman daemon


Installation
------------

Install via pypi or copy this module into your project or into your PYTHONPATH.


**Put django_gearman_proxy into INSTALLED_APPS in your projects settings.py file**

::

 INSTALLED_APPS = (
     'localeurl',
     'django.contrib.auth',
     'django.contrib.contenttypes',
     'django.contrib.sessions',
     'django.contrib.sites',
     'django.contrib.admin',
     'django.contrib.sitemaps',
     'web',
     'debug_toolbar',
     'rosetta',
     'south',
     'django_gearman_proxy'
 )


Configuration
-------------

**django settings.py constants**

::

 # E-mails are sent to proxy backend.
 EMAIL_BACKEND = 'django_gearman_proxy.backends.mail.EmailBackend'

 # Email backend to be used inside of mail sender worker.
 GEARMAN_EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'

 # Serializers for transporting EmailMessage object via gearman protocol.
 GEARMAN_EMAIL_SERIALIZER = 'django_gearman_proxy.serializers.mail.json.serialize'
 GEARMAN_EMAIL_UNSERIALIZER = 'django_gearman_proxy.serializers.mail.json.unserialize'


 # Sms messages are sent to proxy backend.
 SMS_BACKEND = 'django_gearman_proxy.backends.sms.SmsBackend'

 # SMS backend to be used inside of sms sender worker.
 GEARMAN_SMS_BACKEND = 'sendsms.backends.smssluzbacz.SmsBackend'

 # Serializers for transporting SmsMessage object via gearman protocol.
 GEARMAN_SMS_SERIALIZER = 'django_gearman_proxy.serializers.sms.json.serialize'
 GEARMAN_SMS_UNSERIALIZER = 'django_gearman_proxy.serializers.sms.json.unserialize'


Tests
-----

**Tested on evnironment**

 - Xubuntu Linux 12.04.1 LTS precise 64-bit
 - python 2.7.3+
 - python unittest
 - django 1.4.5
 - gearmand 1.1.1

**Running tests**

To run the tests from your django project, run command: ::

 $ python manage.py test django_gearman_proxy


Author
------

| char0n (Vladimír Gorej, CodeScale s.r.o.)
| email: gorej@codescale.net
| web: http://www.codescale.net/


References
----------

 - http://github.com/CodeScaleInc/django-gearman-proxy
 - http://pypi.python.org/pypi/django-gearman-proxy/
 - http://www.codescale.net/en/community#django-gearman-proxy