# Django Whisperer
[![Build status](https://img.shields.io/bitbucket/pipelines/akinonteam/dj-whisperer)](https://bitbucket.org/akinonteam/dj-whisperer/addon/pipelines/home)
[![Documentation status](https://readthedocs.org/projects/dj-whisperer/badge/?version=latest)](https://dj-whisperer.readthedocs.io/en/latest/?badge=latest)
![PyPI](https://img.shields.io/pypi/v/dj-whisperer)
![PyPI - Django version](https://img.shields.io/pypi/djversions/dj-whisperer)
![PyPI - Python version](https://img.shields.io/pypi/pyversions/dj-whisperer)
![PyPI - License](https://img.shields.io/pypi/l/dj-whisperer)
Whisperer informs subscribed users via an URL when a specific event occurs.
## Installation
Installation using pip:
```
pip install dj-whisperer
```
`whisperer` package has to be added to `INSTALLED_APPS` and `migrate` command has to be run.
```python
INSTALLED_APPS = (
# other apps here...
'whisperer',
)
```
## Sample Scenario
Let's give an example using `Package` model. When an event occurs related to a package, subscribed users are gonna be informed. To do so, firstly which events to subscribe must be determined. In order to learn when a package created:
```python
from django.db.models.signals import post_save
from whisperer.events import WhispererEvent, registry
from whisperer.tasks import deliver_event
class PackageCreateEvent(WhispererEvent):
serializer_class = PackageSerializer
event_type = 'package-created'
registry.register(PackageCreateEvent)
def signal_receiver(instance, created=False, **kwargs):
if created:
deliver_event(instance, 'package-created')
post_save.connect(signal_receiver, Package)
```
When database transaction succeeds, in short when `transaction.on_commit()`, `deliver_event` must be triggered.
Subscribed users now can be informed that a package created if they have created a `Webhook`.
```python
import requests
requests.post(
url='https://your-app.com/whisperer/hooks/',
headers={
'Authorization': 'Token <secret-login-token>',
},
json={
'event_type': 'package-created',
'secret_key': 'secret',
'target_url': 'https://example.com/',
}
)
```
When a package created, `uuid`, `type` & `data` passed through `PackageSerializer` will be posted to https://example.com/.
```python
import requests
requests.post(
url='https://example.com/',
headers={
'Content-Type': 'application/json',
'X-Whisperer-Event': 'package-created',
},
json={
'event': {
'type': 'package-created',
'uuid': 'da81e85139824c6187dd1e58a7d3f971',
},
'data': {
'id': 61,
'transfer_id': 49,
'order_number': '248398923123',
'.....': '......',
}
}
)
```
In order to cancel the subscription:
```python
import requests
requests.delete(
url='https://your-app.com/whisperer/hooks/<webhook-id>/',
headers={
'Authorization': 'Token <secret-login-token>',
}
)
```
To re-trigger events that lost on the queue you must call `whisperer.tasks.trigger_event_queue_events` with scheduler
To automate the removal of outdated event records, schedule the task `whisperer.tasks.delete_outdated_webhook_events` using a scheduler. By default, it targets records older than 12 weeks.
Raw data
{
"_id": null,
"home_page": "https://bitbucket.org/akinonteam/dj-whisperer",
"name": "dj-whisperer",
"maintainer": "Akinon",
"docs_url": null,
"requires_python": null,
"maintainer_email": "dev@akinon.com",
"keywords": null,
"author": "Akinon",
"author_email": "dev@akinon.com",
"download_url": "https://files.pythonhosted.org/packages/7c/57/6e553cac8dc6e4161dfddcb82059c84337ea8f74eef666eb940b7ea3b2f2/dj-whisperer-0.3.1.tar.gz",
"platform": "any",
"description": "# Django Whisperer\n\n[![Build status](https://img.shields.io/bitbucket/pipelines/akinonteam/dj-whisperer)](https://bitbucket.org/akinonteam/dj-whisperer/addon/pipelines/home)\n[![Documentation status](https://readthedocs.org/projects/dj-whisperer/badge/?version=latest)](https://dj-whisperer.readthedocs.io/en/latest/?badge=latest)\n![PyPI](https://img.shields.io/pypi/v/dj-whisperer)\n![PyPI - Django version](https://img.shields.io/pypi/djversions/dj-whisperer)\n![PyPI - Python version](https://img.shields.io/pypi/pyversions/dj-whisperer)\n![PyPI - License](https://img.shields.io/pypi/l/dj-whisperer)\n\nWhisperer informs subscribed users via an URL when a specific event occurs.\n\n## Installation\n\nInstallation using pip:\n\n```\npip install dj-whisperer\n```\n\n`whisperer` package has to be added to `INSTALLED_APPS` and `migrate` command has to be run.\n\n```python\nINSTALLED_APPS = (\n # other apps here...\n 'whisperer',\n)\n```\n\n## Sample Scenario\n\nLet's give an example using `Package` model. When an event occurs related to a package, subscribed users are gonna be informed. To do so, firstly which events to subscribe must be determined. In order to learn when a package created:\n\n```python\nfrom django.db.models.signals import post_save\nfrom whisperer.events import WhispererEvent, registry\nfrom whisperer.tasks import deliver_event\n\nclass PackageCreateEvent(WhispererEvent):\n serializer_class = PackageSerializer\n event_type = 'package-created'\n\nregistry.register(PackageCreateEvent)\n\n\ndef signal_receiver(instance, created=False, **kwargs):\n if created:\n deliver_event(instance, 'package-created')\n\npost_save.connect(signal_receiver, Package)\n```\n\nWhen database transaction succeeds, in short when `transaction.on_commit()`, `deliver_event` must be triggered.\nSubscribed users now can be informed that a package created if they have created a `Webhook`.\n\n```python\nimport requests\n\nrequests.post(\n url='https://your-app.com/whisperer/hooks/',\n headers={\n 'Authorization': 'Token <secret-login-token>',\n },\n json={\n 'event_type': 'package-created',\n 'secret_key': 'secret',\n 'target_url': 'https://example.com/',\n }\n)\n```\n\nWhen a package created, `uuid`, `type` & `data` passed through `PackageSerializer` will be posted to https://example.com/.\n\n```python\nimport requests\n\nrequests.post(\n url='https://example.com/',\n headers={\n 'Content-Type': 'application/json',\n 'X-Whisperer-Event': 'package-created',\n },\n json={\n 'event': {\n 'type': 'package-created',\n 'uuid': 'da81e85139824c6187dd1e58a7d3f971',\n },\n 'data': {\n 'id': 61,\n 'transfer_id': 49,\n 'order_number': '248398923123',\n '.....': '......',\n }\n }\n)\n```\n\nIn order to cancel the subscription:\n\n```python\nimport requests\n\nrequests.delete(\n url='https://your-app.com/whisperer/hooks/<webhook-id>/',\n headers={\n 'Authorization': 'Token <secret-login-token>',\n }\n)\n```\n\nTo re-trigger events that lost on the queue you must call `whisperer.tasks.trigger_event_queue_events` with scheduler\n\nTo automate the removal of outdated event records, schedule the task `whisperer.tasks.delete_outdated_webhook_events` using a scheduler. By default, it targets records older than 12 weeks.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Stay informed of it",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://dj-whisperer.readthedocs.io",
"Homepage": "https://bitbucket.org/akinonteam/dj-whisperer",
"Source Code": "https://bitbucket.org/akinonteam/dj-whisperer"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5abecd113c3e8d0664aeee7d78cacd8c7a01740b80d230aa3cdfd7436ab9956c",
"md5": "bd329fc59e0a3fd7fa26a767bfacc13c",
"sha256": "63676f2d20b9a25e804264d7ed9f9957cb2dbf70c03554dce5522423ec3ed7b6"
},
"downloads": -1,
"filename": "dj_whisperer-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd329fc59e0a3fd7fa26a767bfacc13c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22717,
"upload_time": "2024-05-02T14:46:12",
"upload_time_iso_8601": "2024-05-02T14:46:12.152309Z",
"url": "https://files.pythonhosted.org/packages/5a/be/cd113c3e8d0664aeee7d78cacd8c7a01740b80d230aa3cdfd7436ab9956c/dj_whisperer-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c576e553cac8dc6e4161dfddcb82059c84337ea8f74eef666eb940b7ea3b2f2",
"md5": "c6be7ec10bc14cd316974971b7655736",
"sha256": "504f8b349577d400a2dd9a1c70f03c7d5980ccd9996966b3ed8f791de258fd5c"
},
"downloads": -1,
"filename": "dj-whisperer-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c6be7ec10bc14cd316974971b7655736",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27424,
"upload_time": "2024-05-02T14:46:15",
"upload_time_iso_8601": "2024-05-02T14:46:15.174051Z",
"url": "https://files.pythonhosted.org/packages/7c/57/6e553cac8dc6e4161dfddcb82059c84337ea8f74eef666eb940b7ea3b2f2/dj-whisperer-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 14:46:15",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "akinonteam",
"bitbucket_project": "dj-whisperer",
"lcname": "dj-whisperer"
}