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.

Loudhailer requires python 3.8 or later.

Loudhailer can be installed from pypi.org 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]

from loudhailer import Loudhailer


async with Loudhailer('amqp://localhost') as loudhailer:
    await loudhailer.publish('my_group', {'message': 'data'})

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}')

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.

Add the following Channel Layers configuration to your Django settings module:

CHANNEL_LAYERS = {
    'default': {
        'BACKEND': 'loudhailer.ext.channels.LoudhailerChannelLayer',
        'CONFIG': {
            'url': 'amqp://localhost',
        },
    },
}

Add the following configuration to your root channels routing module:

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:

You can register your signal handler for startup and shutdown events in the following way:

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

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.

Loudhailer is released under the Apache License Version 2.0.