Package: wc-django-envoyer
WebCase message senderMessage sender to different channels.Installationpipinstallwc-django-envoyerInsettings.py:INSTALLED_APPS+=['wcd_envoyer',]WCD_ENVOYER={# Channels list, that will be available in admin interface to message# create templates.'CHANNELS':[{# Unique channel key.'key':'console','verbose_name':'Console',# Messaging backend class.# Console backend here is a simple message printing backend:'backend':'wcd_envoyer.channels.backends.console.ConsoleBackend','options':{# Options that backend receives on initialization.# Basic ones are:# Actual recipients data resolver for a specific case:'recipient_resolver':lambdax:x,# Form for additional in-admin backend configuration options.'config_form_class':'wcd_envoyer.channels.forms.BaseConfigForm',# In-admin form for template config.'template_form_class':'wcd_envoyer.channels.forms.BaseTemplateForm',# Custom string template renderer.'template_renderer':'wcd_envoyer.channels.renderers.django_template_renderer',# Separate class that is responsible for messages data transformations.'messages_maker_class':'wcd_envoyer.channels.backend.MessagesMaker',}},],'EVENTS':[{# Unique event key.'key':'something-happened',# Event's verbose name that will be displayed in admin.'verbose_name':'Something happened event',# List of variables available on template generation.'context':[(# Key'when',# Verbose name.'When',# Additional variable description'Time when something happened.'),# Variable can be defined as a simple string key:'what',# Or this could be tuple with only 2 parameters('other','Other'),],}],# JSON encoder class for in-lib postgres json fields:'JSON_ENCODER':'django.core.serializers.json.DjangoJSONEncoder',}Builtin backends:wcd_envoyer.channels.backends.console.ConsoleBackend- Simple backend to send messages to console. For debug purposes.wcd_envoyer.channels.backends.django_sendmail.SendMailBackend- Backend with django's email sending mechanics underneath.Events and Channels can be registered in special auto-importableenvoyer.pyapp submodule.envoyer.pyfromdjango.utils.translationimportpgettext_lazyfromwcd_envoyerimportevents,channels# Events is better to register here. Because it's more related to# particular app, not project itself.events.registry.add({'key':'app-event','verbose_name':'App event','context':['var1','var2'],})# But channels is other case. Better describe them in `settings.py`channels.registry.add({'key':'sms','verbose_name':'Sms sender','backend':'app.envoyer.backends.SMSBackend',})UsageSimple shortcut usage issendshortcut.fromwcd_envoyer.shortcutsimportsend,default_sendersend(# Event name'app-event',# Recipients list.# Recipient object is a dict with any key-values, from which different# backends will get data they need.[# This recipient will be used only by sms, or phone call backend.{'phone':'+0000000000'},# This will be user by email sending backend.{'email':'some@email.com'},# And both backends will send message to recipient like that.{'phone':'+0000000000','email':'some@email.com'},],# Data object, what will be used to render Message.# It could be dict with any data.# For event probably there will be data for event's context.{'var1':'data','var2':'data',# If you need to send messages with specific language, you may add it here:'language':'en',# And also any other backend-specific options could be passed to context.# ...},# You may additionally limit channels that message will be send.channels=['sms'],# Or. None - all channels possible.channels=None,# Optional parameter, with which you may change sender instance, to your# custom one.sender=default_sender,)SignalsApp has internal signals, that you may use to take actions after messages were sended.wcd_envoyer.signals.messages_sent- Messages sent signal.wcd_envoyer.signals.messages_sent_succeeded- Signal for messages that were successfully sent.wcd_envoyer.signals.messages_sent_failed- Signal that fires if any messages were failed to send.CeleryCelery support is provided viawcd_envoyer.contrib.celerypackage.tasks.pyfrom.celeryimportappfromwcd_envoyer.contrib.celery.shortcutsimporttask,make_taskfromwcd_envoyer.shortcutsimportsend# Decorator for task creation is the easiest way to make things work.@task(app)defsending_task_1(result,context):# Callback for task will run AFTER all messages sending happened.succeeded,failed=result# - succeeded - List of successfully sent messages.# - failed - List of messages that we failed to send.# And context - is the same context that were passed on `send`.# OR# If you do not need any callback and default signals is enough then just# create task:sending_task_2=make_task(app)created_task=(sending_task_1orsending_task2)# An now, after you've created task and sender you may easily send messages:send('app-event',[{'email':'some@email.com'}],{'var':'data'},# You may use sender in initial shortcut:sender=created_task.sender,)# OR# Execute the same `send` from task:created_task.send('app-event',[{'email':'some@email.com'}],{'var':'data'},)# OR# Just use created sender directly:created_task.sender.send(...)To use celery sender in admin interface instead of the "straight" one you should change sender inMessageadmin class:fromwcd_envoyer.adminimportMessageAdmin# Looking hacky, but you you need - just inherit from `MessageAdmin`# and re-register admin for `Message` model.MessageAdmin.messages_sender=created_task.senderError trackingYou can track failed messages with signals. Or there is a simple connector forpx-django-actions-trackerlib. Just add'wcd_envoyer.contrib.pxd_actions_tracker'toINSTALLED_APPS.Scheduled message senderThere is an more complex Celery sender, that adds an ability to configure the time of day when the messages could be sent to user. Because we do not want to send messages like "New article added" near midnight, because people are tend to sleep at that time.There are only small changes required to enable the control.Addwcd_envoyer.contrib.schedulednear thewcd_envoyer.contrib.celerypackage in theINSTALLED_APPSdjango configuration.# Instead of:fromwcd_envoyer.contrib.celery.shortcutsimporttask,make_task# Import task generator from `scheduled` app:fromwcd_envoyer.contrib.scheduled.shortcutsimport(task,make_task,make_scheduled_task,)# Made new task as before:celery_send_task=make_task(app)celery_sender=celery_send_task.sendersend=celery_send_task.send# And add another task, that you will run from time to time using Celery beat# or crontab or anyway else you want.# It will send the messages that were scheduled before.celery_scheduled_send_task=make_scheduled_task(app,sender=celery_sender)ConfigurationYou may configure availability time ranges:For every event:/admin/wcd_envoyer_scheduled/eventavailability/.For every channel configuration:/admin/wcd_envoyer/channelconfig/.If configured both -  message will be send only at the intersecting time.If, for whatever reason, you've configured that there is not intersection for a pair of channel+event availability ranges - then messages will be sent immediately.SendingIn terms of sending there is not much that have changed.
You may "send" messages just as before, so all of your old code could stay the same.send('app-event',[{'email':'some@email.com'}],{'var':'data'},)Or, with an additional configuration:send('app-event',[{'email':'some@email.com',# If there is a timezone passed to a recipient data - message send time# will be adjusted to fit it.'tz':'Europe/Berlin',# If for this particular recipient message must be sent right now -# `send_immediate` key must be set as True:'send_immediate':True,}],{'var':'data',# If all the messages must be sent immediately, no matter the# configurations you may pass `send_immediate` configuration here:'send_immediate':True,# Also if for some reason you need to change the current time, based on# which library will calculate messages send time you may add `now` to# context.# By default django's built in `django.utils.timezone.now` will be used.'now':timezone.now(),},)All the keys liketz,now,immediateand all possible others are configurable in aSenderclass. So you may extend the default one and override those parameters.User "attachment"By defaultrecipientsin library have no connections to django's auth system. But in most scenarios it, in fact, will be. So for that case there is an addonwcd_envoyer.contrib.attached_users, that must be added toINSTALLED_APPSconfig.After that it you may extend your currently usedSenderwithwcd_envoyer.contrib.attached_users.services.sender.AttachedUserSenderMixinmixin.fromwcd_envoyer.contrib.attached_users.services.senderimportAttachedUserSenderMixinclassMySender(AttachedUserSenderMixin,OldSender):passNow, to attach users to messages simply add'user_id': user.pkto the recipient on send:send('app-event',[{'email':user.email,# `user_id` key may be changed in `MySender.USER_ID_KEY` attribute.'user_id':user.pk,}],{'var':'data'},)ChangelogAll notable changes to this project will be documented in this file.The format is based onKeep a Changelog,
and this project adheres toSemantic Versioning.[Unreleased][0.2.13]ChangedTemplate legend extended with an additional column with template-language key representation.[0.2.9]FixedAttached users translations and admin.[0.2.8]AddedAbility to attachauth.Userusers to messages withwcd_envoyer.contrib.attached_users.[0.2.7]AddedScheduled message sending usingwcd_envoyer.contrib.scheduled.[0.2.3]AddedMessages use the same form as templates for data field.[0.2.2]AddedErrors tracking.[0.2.0]AddedCelery sender.FixedAPI improvements.[0.1.0]Initial version.