| Name | wc-django-envoyer JSON |
| Version |
0.2.15
JSON |
| download |
| home_page | None |
| Summary | Message sender to different channels. |
| upload_time | 2024-06-07 13:45:57 |
| maintainer | None |
| docs_url | None |
| author | WebCase |
| requires_python | >=3.6 |
| license | MIT License |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# WebCase message sender
Message sender to different channels.
## Installation
```sh
pip install wc-django-envoyer
```
In `settings.py`:
```python
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': lambda x: 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-importable `envoyer.py` app submodule.
`envoyer.py`
```python
from django.utils.translation import pgettext_lazy
from wcd_envoyer import events, 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',
})
```
## Usage
Simple shortcut usage is `send` shortcut.
```python
from wcd_envoyer.shortcuts import send, default_sender
send(
# 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,
)
```
### Signals
App 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.
### Celery
Celery support is provided via `wcd_envoyer.contrib.celery` package.
`tasks.py`
```python
from .celery import app
from wcd_envoyer.contrib.celery.shortcuts import task, make_task
from wcd_envoyer.shortcuts import send
# Decorator for task creation is the easiest way to make things work.
@task(app)
def sending_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_1 or sending_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 in `Message` admin class:
```python
from wcd_envoyer.admin import MessageAdmin
# Looking hacky, but you you need - just inherit from `MessageAdmin`
# and re-register admin for `Message` model.
MessageAdmin.messages_sender = created_task.sender
```
### Error tracking
You can track failed messages with signals. Or there is a simple connector for `px-django-actions-tracker` lib. Just add `'wcd_envoyer.contrib.pxd_actions_tracker'` to `INSTALLED_APPS`.
### Scheduled message sender
There 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.
Add `wcd_envoyer.contrib.scheduled` near the `wcd_envoyer.contrib.celery` package in the `INSTALLED_APPS` django configuration.
```python
# Instead of:
from wcd_envoyer.contrib.celery.shortcuts import task, make_task
# Import task generator from `scheduled` app:
from wcd_envoyer.contrib.scheduled.shortcuts import (
task, make_task, make_scheduled_task,
)
# Made new task as before:
celery_send_task = make_task(app)
celery_sender = celery_send_task.sender
send = 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)
```
#### Configuration
You 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.
#### Sending
In 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.
```python
send(
'app-event', [{'email': 'some@email.com'}], {'var': 'data'},
)
```
Or, with an additional configuration:
```python
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 like `tz`, `now`, `immediate` and all possible others are configurable in a `Sender` class. So you may extend the default one and override those parameters.
### User "attachment"
By default `recipients` in 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 addon `wcd_envoyer.contrib.attached_users`, that must be added to `INSTALLED_APPS` config.
After that it you may extend your currently used `Sender` with `wcd_envoyer.contrib.attached_users.services.sender.AttachedUserSenderMixin` mixin.
```python
from wcd_envoyer.contrib.attached_users.services.sender import AttachedUserSenderMixin
class MySender(AttachedUserSenderMixin, OldSender):
pass
```
Now, to attach users to messages simply add `'user_id': user.pk` to the recipient on send:
```python
send(
'app-event',
[
{
'email': user.email,
# `user_id` key may be changed in `MySender.USER_ID_KEY` attribute.
'user_id': user.pk,
}
],
{'var': 'data'},
)
```
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.2.15]
### Fixed
- Channel config `is_active` parameter admin field.
## [0.2.14]
### Added
- Channel config `is_active` parameter to be able to disable channel at any time without deleting configuration.
## [0.2.13]
### Changed
- Template legend extended with an additional column with template-language key representation.
## [0.2.9]
### Fixed
- Attached users translations and admin.
## [0.2.8]
### Added
- Ability to attach `auth.User` users to messages with `wcd_envoyer.contrib.attached_users`.
-
## [0.2.7]
### Added
- Scheduled message sending using `wcd_envoyer.contrib.scheduled`.
## [0.2.3]
### Added
- Messages use the same form as templates for data field.
## [0.2.2]
### Added
- Errors tracking.
## [0.2.0]
### Added
- Celery sender.
### Fixed
- API improvements.
## [0.1.0]
Initial version.
Raw data
{
"_id": null,
"home_page": null,
"name": "wc-django-envoyer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "WebCase",
"author_email": "info@webcase.studio",
"download_url": "https://files.pythonhosted.org/packages/d4/53/64ecc433b727137828a5179801f3285a99b9fce7ebc925e7a0b4ddb31cb0/wc-django-envoyer-0.2.15.tar.gz",
"platform": null,
"description": "# WebCase message sender\n\nMessage sender to different channels.\n\n## Installation\n\n```sh\npip install wc-django-envoyer\n```\n\nIn `settings.py`:\n\n```python\nINSTALLED_APPS += [\n 'wcd_envoyer',\n]\n\nWCD_ENVOYER = {\n # Channels list, that will be available in admin interface to message\n # create templates.\n 'CHANNELS': [\n {\n # Unique channel key.\n 'key': 'console',\n 'verbose_name': 'Console',\n # Messaging backend class.\n # Console backend here is a simple message printing backend:\n 'backend': 'wcd_envoyer.channels.backends.console.ConsoleBackend',\n 'options': {\n # Options that backend receives on initialization.\n # Basic ones are:\n # Actual recipients data resolver for a specific case:\n 'recipient_resolver': lambda x: x,\n # Form for additional in-admin backend configuration options.\n 'config_form_class': 'wcd_envoyer.channels.forms.BaseConfigForm',\n # In-admin form for template config.\n 'template_form_class': 'wcd_envoyer.channels.forms.BaseTemplateForm',\n # Custom string template renderer.\n 'template_renderer': 'wcd_envoyer.channels.renderers.django_template_renderer',\n # Separate class that is responsible for messages data transformations.\n 'messages_maker_class': 'wcd_envoyer.channels.backend.MessagesMaker',\n }\n },\n ],\n 'EVENTS': [\n {\n # Unique event key.\n 'key': 'something-happened',\n # Event's verbose name that will be displayed in admin.\n 'verbose_name': 'Something happened event',\n # List of variables available on template generation.\n 'context': [\n (\n # Key\n 'when',\n # Verbose name.\n 'When',\n # Additional variable description\n 'Time when something happened.'\n ),\n # Variable can be defined as a simple string key:\n 'what',\n # Or this could be tuple with only 2 parameters\n ('other', 'Other'),\n ],\n }\n ],\n # JSON encoder class for in-lib postgres json fields:\n 'JSON_ENCODER': 'django.core.serializers.json.DjangoJSONEncoder',\n}\n```\n\n**Builtin backends:**\n\n- `wcd_envoyer.channels.backends.console.ConsoleBackend` - Simple backend to send messages to console. For debug purposes.\n- `wcd_envoyer.channels.backends.django_sendmail.SendMailBackend` - Backend with django's email sending mechanics underneath.\n\nEvents and Channels can be registered in special auto-importable `envoyer.py` app submodule.\n\n`envoyer.py`\n```python\nfrom django.utils.translation import pgettext_lazy\n\nfrom wcd_envoyer import events, channels\n\n\n# Events is better to register here. Because it's more related to\n# particular app, not project itself.\nevents.registry.add({\n 'key': 'app-event',\n 'verbose_name': 'App event',\n 'context': ['var1', 'var2'],\n})\n\n# But channels is other case. Better describe them in `settings.py`\nchannels.registry.add({\n 'key': 'sms',\n 'verbose_name': 'Sms sender',\n 'backend': 'app.envoyer.backends.SMSBackend',\n})\n```\n\n## Usage\n\nSimple shortcut usage is `send` shortcut.\n\n```python\nfrom wcd_envoyer.shortcuts import send, default_sender\n\nsend(\n # Event name\n 'app-event',\n # Recipients list.\n # Recipient object is a dict with any key-values, from which different\n # backends will get data they need.\n [\n # This recipient will be used only by sms, or phone call backend.\n {'phone': '+0000000000'},\n # This will be user by email sending backend.\n {'email': 'some@email.com'},\n # And both backends will send message to recipient like that.\n {'phone': '+0000000000', 'email': 'some@email.com'},\n ],\n # Data object, what will be used to render Message.\n # It could be dict with any data.\n # For event probably there will be data for event's context.\n {\n 'var1': 'data',\n 'var2': 'data',\n # If you need to send messages with specific language, you may add it here:\n 'language': 'en',\n # And also any other backend-specific options could be passed to context.\n # ...\n },\n # You may additionally limit channels that message will be send.\n channels=['sms'],\n # Or. None - all channels possible.\n channels=None,\n # Optional parameter, with which you may change sender instance, to your\n # custom one.\n sender=default_sender,\n)\n```\n\n### Signals\n\nApp has internal signals, that you may use to take actions after messages were sended.\n\n- `wcd_envoyer.signals.messages_sent` - Messages sent signal.\n- `wcd_envoyer.signals.messages_sent_succeeded` - Signal for messages that were successfully sent.\n- `wcd_envoyer.signals.messages_sent_failed` - Signal that fires if any messages were failed to send.\n\n### Celery\n\nCelery support is provided via `wcd_envoyer.contrib.celery` package.\n\n`tasks.py`\n```python\nfrom .celery import app\n\nfrom wcd_envoyer.contrib.celery.shortcuts import task, make_task\nfrom wcd_envoyer.shortcuts import send\n\n\n# Decorator for task creation is the easiest way to make things work.\n@task(app)\ndef sending_task_1(result, context):\n # Callback for task will run AFTER all messages sending happened.\n succeeded, failed = result\n # - succeeded - List of successfully sent messages.\n # - failed - List of messages that we failed to send.\n # And context - is the same context that were passed on `send`.\n\n# OR\n\n# If you do not need any callback and default signals is enough then just\n# create task:\nsending_task_2 = make_task(app)\n\ncreated_task = (sending_task_1 or sending_task2)\n\n# An now, after you've created task and sender you may easily send messages:\nsend(\n 'app-event', [{'email': 'some@email.com'}], {'var': 'data'},\n # You may use sender in initial shortcut:\n sender=created_task.sender,\n)\n# OR\n# Execute the same `send` from task:\ncreated_task.send(\n 'app-event', [{'email': 'some@email.com'}], {'var': 'data'},\n)\n# OR\n# Just use created sender directly:\ncreated_task.sender.send(...)\n```\n\nTo use celery sender in admin interface instead of the \"straight\" one you should change sender in `Message` admin class:\n\n```python\nfrom wcd_envoyer.admin import MessageAdmin\n\n# Looking hacky, but you you need - just inherit from `MessageAdmin`\n# and re-register admin for `Message` model.\nMessageAdmin.messages_sender = created_task.sender\n```\n\n### Error tracking\n\nYou can track failed messages with signals. Or there is a simple connector for `px-django-actions-tracker` lib. Just add `'wcd_envoyer.contrib.pxd_actions_tracker'` to `INSTALLED_APPS`.\n\n\n### Scheduled message sender\n\nThere 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.\n\nThere are only small changes required to enable the control.\n\nAdd `wcd_envoyer.contrib.scheduled` near the `wcd_envoyer.contrib.celery` package in the `INSTALLED_APPS` django configuration.\n\n```python\n# Instead of:\nfrom wcd_envoyer.contrib.celery.shortcuts import task, make_task\n# Import task generator from `scheduled` app:\nfrom wcd_envoyer.contrib.scheduled.shortcuts import (\n task, make_task, make_scheduled_task,\n)\n\n# Made new task as before:\ncelery_send_task = make_task(app)\ncelery_sender = celery_send_task.sender\nsend = celery_send_task.send\n\n# And add another task, that you will run from time to time using Celery beat\n# or crontab or anyway else you want.\n# It will send the messages that were scheduled before.\ncelery_scheduled_send_task = make_scheduled_task(app, sender=celery_sender)\n```\n\n#### Configuration\n\nYou may configure availability time ranges:\n- For every event: `/admin/wcd_envoyer_scheduled/eventavailability/`.\n- For every channel configuration: `/admin/wcd_envoyer/channelconfig/`.\n\nIf configured both - message will be send only at the intersecting time.\n\nIf, 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.\n\n#### Sending\n\nIn terms of sending there is not much that have changed.\nYou may \"send\" messages just as before, so all of your old code could stay the same.\n\n```python\nsend(\n 'app-event', [{'email': 'some@email.com'}], {'var': 'data'},\n)\n```\n\nOr, with an additional configuration:\n```python\nsend(\n 'app-event',\n [\n {\n 'email': 'some@email.com',\n # If there is a timezone passed to a recipient data - message send time\n # will be adjusted to fit it.\n 'tz': 'Europe/Berlin',\n # If for this particular recipient message must be sent right now -\n # `send_immediate` key must be set as True:\n 'send_immediate': True,\n }\n ],\n {\n 'var': 'data',\n # If all the messages must be sent immediately, no matter the\n # configurations you may pass `send_immediate` configuration here:\n 'send_immediate': True,\n # Also if for some reason you need to change the current time, based on\n # which library will calculate messages send time you may add `now` to\n # context.\n # By default django's built in `django.utils.timezone.now` will be used.\n 'now': timezone.now(),\n },\n)\n```\n\nAll the keys like `tz`, `now`, `immediate` and all possible others are configurable in a `Sender` class. So you may extend the default one and override those parameters.\n\n\n### User \"attachment\"\n\nBy default `recipients` in 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 addon `wcd_envoyer.contrib.attached_users`, that must be added to `INSTALLED_APPS` config.\n\nAfter that it you may extend your currently used `Sender` with `wcd_envoyer.contrib.attached_users.services.sender.AttachedUserSenderMixin` mixin.\n\n```python\nfrom wcd_envoyer.contrib.attached_users.services.sender import AttachedUserSenderMixin\n\n\nclass MySender(AttachedUserSenderMixin, OldSender):\n pass\n```\n\nNow, to attach users to messages simply add `'user_id': user.pk` to the recipient on send:\n\n```python\nsend(\n 'app-event',\n [\n {\n 'email': user.email,\n # `user_id` key may be changed in `MySender.USER_ID_KEY` attribute.\n 'user_id': user.pk,\n }\n ],\n {'var': 'data'},\n)\n```\n# Changelog\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.2.15]\n### Fixed\n- Channel config `is_active` parameter admin field.\n\n## [0.2.14]\n### Added\n- Channel config `is_active` parameter to be able to disable channel at any time without deleting configuration.\n\n## [0.2.13]\n### Changed\n- Template legend extended with an additional column with template-language key representation.\n\n## [0.2.9]\n### Fixed\n- Attached users translations and admin.\n\n## [0.2.8]\n### Added\n- Ability to attach `auth.User` users to messages with `wcd_envoyer.contrib.attached_users`.\n-\n## [0.2.7]\n### Added\n- Scheduled message sending using `wcd_envoyer.contrib.scheduled`.\n\n## [0.2.3]\n### Added\n- Messages use the same form as templates for data field.\n\n## [0.2.2]\n### Added\n- Errors tracking.\n\n## [0.2.0]\n### Added\n- Celery sender.\n### Fixed\n- API improvements.\n\n## [0.1.0]\nInitial version.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Message sender to different channels.",
"version": "0.2.15",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d45364ecc433b727137828a5179801f3285a99b9fce7ebc925e7a0b4ddb31cb0",
"md5": "4e66ed6d68930d577185fc298083d1da",
"sha256": "67a5694c3cf8cc3eb9ae9f6fdb496169ceb68d1b4f2a2d7f3e5387410d18ad6f"
},
"downloads": -1,
"filename": "wc-django-envoyer-0.2.15.tar.gz",
"has_sig": false,
"md5_digest": "4e66ed6d68930d577185fc298083d1da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 56795,
"upload_time": "2024-06-07T13:45:57",
"upload_time_iso_8601": "2024-06-07T13:45:57.622808Z",
"url": "https://files.pythonhosted.org/packages/d4/53/64ecc433b727137828a5179801f3285a99b9fce7ebc925e7a0b4ddb31cb0/wc-django-envoyer-0.2.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-07 13:45:57",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "wc-django-envoyer"
}
