# Loudhailer
 [](https://pypi.org/project/loudhailer/) [](https://github.com/cloudblue/loudhailer/actions/workflows/test.yml) [](https://sonarcloud.io/dashboard?id=loudhailer) [](https://sonarcloud.io/dashboard?id=loudhailer) [](https://sonarcloud.io/dashboard?id=loudhailer)
## Introduction
`Loudhailer` is a python library that allows to send broadcast messages to groups of consumers. It has been designed for being used in asynchronous applications.
This initial release natively supports RabbitMQ and Redis backends and can be easily extended to support more backends.
`Loudhailer` includes an extension that allows you to use in django-channels based projects.
> Please note that the current version of Loudhailer have to be considered a beta release since it is still under heavy development.
## Install
`Loudhailer` requires python 3.8 or later.
`Loudhailer` can be installed from [pypi.org](https://pypi.org/project/loudhailer/) using pip:
```
$ pip install loudhailer
```
If you plan to use it with django-channels you must install the optional channels dependency:
```
$ pip install loudhailer[channels]
```
## Basic usage
### Publishing messages
```python
from loudhailer import Loudhailer
async with Loudhailer('amqp://localhost') as loudhailer:
await loudhailer.publish('my_group', {'message': 'data'})
```
### Subscribe to group and receive messages
```python
from loudhailer import Loudhailer
with Loudhailer('amqp://localhost') as loudhailer:
with loudhailer.subscribe('my_group') as messages:
message = await messages.get()
print(f'received message: {message}')
```
## Django channels extension
The django-channels extension is an implementation of the Channel Layers specifications.
In order to properly works it need to add a ASGI lifespan handler to your channels application.
> Please note that Channel Layers specification are not yet fully implemented, only group messaging is supported in this
initial release.
### Django settings
Add the following Channel Layers configuration to your Django settings module:
```python
CHANNEL_LAYERS = {
'default': {
'BACKEND': 'loudhailer.ext.channels.LoudhailerChannelLayer',
'CONFIG': {
'url': 'amqp://localhost',
},
},
}
```
### Configure the ASGI lifespan handler
Add the following configuration to your root channels routing module:
```python
from channels.routing import ProtocolTypeRouter, URLRouter
from loudhailer.ext.channels import LoudhailerChannelLifespan
application = ProtocolTypeRouter(
{
'lifespan': LoudhailerChannelLifespan.as_asgi(),
'websocket': URLRouter(...),
},
)
```
In case you already have an handler to process lifespan **startup** and **shutdown** events you can be notified of
such event by the *LoudhailerChannelLifespan* handler in two ways:
#### Using django signals
You can register your signal handler for **startup** and **shutdown** events in the following way:
```python
from django.dispatch import receiver
from loudhailer.ext.channels import asgi_application_shutdown, asgi_application_startup
@receiver(asgi_application_startup)
def handle_startup(sender, **kwargs):
pass
@receiver(asgi_application_shutdown)
def handle_shutdown(sender, **kwargs):
pass
```
#### Using **on_startup** and **on_shutdown** hooks
```python
from channels.routing import ProtocolTypeRouter, URLRouter
from loudhailer.ext.channels import LoudhailerChannelLifespan
async def on_startup():
pass
async def on_shutdown():
pass
application = ProtocolTypeRouter(
{
'lifespan': LoudhailerChannelLifespan.as_asgi(
on_startup=on_startup, on_shutdown=on_shutdown,
),
'websocket': URLRouter(...),
},
)
```
Please note that the **on_startup** and **on_shutdown** hooks can be implemented both as synchronous or asynchronous functions.
## License
`Loudhailer` is released under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
Raw data
{
"_id": null,
"home_page": "https://connect.cloudblue.com",
"name": "loudhailer",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4",
"maintainer_email": "",
"keywords": "",
"author": "CloudBlue LLC",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/47/3b/e16f06ac3e64427057eec0ad3e758ec9244ee6ff544dfe0d9b6b1df288db/loudhailer-0.3.3.tar.gz",
"platform": null,
"description": "# Loudhailer\n\n [](https://pypi.org/project/loudhailer/) [](https://github.com/cloudblue/loudhailer/actions/workflows/test.yml) [](https://sonarcloud.io/dashboard?id=loudhailer) [](https://sonarcloud.io/dashboard?id=loudhailer) [](https://sonarcloud.io/dashboard?id=loudhailer)\n\n## Introduction\n\n`Loudhailer` is a python library that allows to send broadcast messages to groups of consumers. It has been designed for being used in asynchronous applications.\n\nThis initial release natively supports RabbitMQ and Redis backends and can be easily extended to support more backends.\n\n`Loudhailer` includes an extension that allows you to use in django-channels based projects.\n\n\n> Please note that the current version of Loudhailer have to be considered a beta release since it is still under heavy development.\n\n\n\n\n## Install\n\n`Loudhailer` requires python 3.8 or later.\n\n\n`Loudhailer` can be installed from [pypi.org](https://pypi.org/project/loudhailer/) using pip:\n\n```\n$ pip install loudhailer\n```\n\nIf you plan to use it with django-channels you must install the optional channels dependency:\n\n```\n$ pip install loudhailer[channels]\n```\n\n\n## Basic usage\n\n### Publishing messages\n\n```python\nfrom loudhailer import Loudhailer\n\n\nasync with Loudhailer('amqp://localhost') as loudhailer:\n await loudhailer.publish('my_group', {'message': 'data'})\n```\n\n### Subscribe to group and receive messages\n\n```python\n\nfrom loudhailer import Loudhailer\n\n\nwith Loudhailer('amqp://localhost') as loudhailer:\n with loudhailer.subscribe('my_group') as messages:\n message = await messages.get()\n print(f'received message: {message}')\n```\n\n## Django channels extension\n\nThe django-channels extension is an implementation of the Channel Layers specifications.\n\nIn order to properly works it need to add a ASGI lifespan handler to your channels application.\n\n\n> Please note that Channel Layers specification are not yet fully implemented, only group messaging is supported in this\ninitial release.\n\n\n### Django settings\n\nAdd the following Channel Layers configuration to your Django settings module:\n\n```python \nCHANNEL_LAYERS = {\n 'default': {\n 'BACKEND': 'loudhailer.ext.channels.LoudhailerChannelLayer',\n 'CONFIG': {\n 'url': 'amqp://localhost',\n },\n },\n}\n```\n\n### Configure the ASGI lifespan handler\n\nAdd the following configuration to your root channels routing module:\n\n```python\nfrom channels.routing import ProtocolTypeRouter, URLRouter\nfrom loudhailer.ext.channels import LoudhailerChannelLifespan\n\napplication = ProtocolTypeRouter(\n {\n 'lifespan': LoudhailerChannelLifespan.as_asgi(),\n 'websocket': URLRouter(...),\n },\n)\n```\n\nIn case you already have an handler to process lifespan **startup** and **shutdown** events you can be notified of\nsuch event by the *LoudhailerChannelLifespan* handler in two ways:\n\n#### Using django signals\n\nYou can register your signal handler for **startup** and **shutdown** events in the following way:\n\n```python\nfrom django.dispatch import receiver\nfrom loudhailer.ext.channels import asgi_application_shutdown, asgi_application_startup\n\n\n@receiver(asgi_application_startup)\ndef handle_startup(sender, **kwargs):\n pass\n\n@receiver(asgi_application_shutdown)\ndef handle_shutdown(sender, **kwargs):\n pass\n```\n\n#### Using **on_startup** and **on_shutdown** hooks\n\n```python\nfrom channels.routing import ProtocolTypeRouter, URLRouter\nfrom loudhailer.ext.channels import LoudhailerChannelLifespan\n\nasync def on_startup():\n pass\n\n\nasync def on_shutdown():\n pass\n\n\napplication = ProtocolTypeRouter(\n {\n 'lifespan': LoudhailerChannelLifespan.as_asgi(\n on_startup=on_startup, on_shutdown=on_shutdown,\n ),\n 'websocket': URLRouter(...),\n },\n)\n```\n\nPlease note that the **on_startup** and **on_shutdown** hooks can be implemented both as synchronous or asynchronous functions.\n\n\n## License\n\n`Loudhailer` is released under the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://connect.cloudblue.com",
"Repository": "https://github.com/cloudblue/loudhailer"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c83d3e55ecaab16c901953cda7206274fa46adeb73542a7b0b0f752901dadc4a",
"md5": "810b1ee50064cb6f2c3d9b5d92ced279",
"sha256": "433725ee4d8dd0965f6d335517c064a4fcde57c90ab978f24c49a6a7f51a093c"
},
"downloads": -1,
"filename": "loudhailer-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "810b1ee50064cb6f2c3d9b5d92ced279",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4",
"size": 14690,
"upload_time": "2023-05-18T18:49:30",
"upload_time_iso_8601": "2023-05-18T18:49:30.045200Z",
"url": "https://files.pythonhosted.org/packages/c8/3d/3e55ecaab16c901953cda7206274fa46adeb73542a7b0b0f752901dadc4a/loudhailer-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "473be16f06ac3e64427057eec0ad3e758ec9244ee6ff544dfe0d9b6b1df288db",
"md5": "ddbc0abe6e39675516ef23f98c943d2b",
"sha256": "e417340c1fc5bf6379bb9c2f838f1c0a027ab13768c3c9b38d8c189e2ca4171b"
},
"downloads": -1,
"filename": "loudhailer-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "ddbc0abe6e39675516ef23f98c943d2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4",
"size": 13415,
"upload_time": "2023-05-18T18:49:32",
"upload_time_iso_8601": "2023-05-18T18:49:32.262914Z",
"url": "https://files.pythonhosted.org/packages/47/3b/e16f06ac3e64427057eec0ad3e758ec9244ee6ff544dfe0d9b6b1df288db/loudhailer-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-18 18:49:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloudblue",
"github_project": "loudhailer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "loudhailer"
}
JSON
