Metadata-Version: 2.1
Name: loudhailer
Version: 0.3.3
Summary: 
Home-page: https://connect.cloudblue.com
License: Apache-2.0
Author: CloudBlue LLC
Requires-Python: >=3.8,<4
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Provides-Extra: channels
Requires-Dist: aiormq (>=6.3.3,<7.0.0)
Requires-Dist: async-timeout (>=4.0.2,<5.0.0)
Requires-Dist: backports.zoneinfo ; python_version < "3.9"
Requires-Dist: channels (>=3.0.0,<4.0.0) ; extra == "channels"
Requires-Dist: redis (>=4.3.4,<5.0.0)
Requires-Dist: tzdata ; sys_platform == "win32"
Project-URL: Repository, https://github.com/cloudblue/loudhailer
Description-Content-Type: text/markdown

# Loudhailer

![pyversions](https://img.shields.io/pypi/pyversions/loudhailer.svg) [![PyPi Status](https://img.shields.io/pypi/v/loudhailer.svg)](https://pypi.org/project/loudhailer/) [![Test Loudhailer](https://github.com/cloudblue/loudhailer/actions/workflows/test.yml/badge.svg)](https://github.com/cloudblue/loudhailer/actions/workflows/test.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=loudhailer&metric=alert_status)](https://sonarcloud.io/dashboard?id=loudhailer) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=loudhailer&metric=coverage)](https://sonarcloud.io/dashboard?id=loudhailer) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=loudhailer&metric=sqale_rating)](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).
