Django Instant
Websockets for Django with Centrifugo.
- Push events into public or private channels.
- Handle the events in javascript client-side.
:sunny: Compatible: plug it on an existing Django instance without any modification in your main stack
Example
Push events in channels from anywhere in the code:
from instant.producers import publish
# Publish to a public channel
publish("public", "Message for everyone")
# Publish to a private channel with an event class set
publish("$users", "Message in logged in users channel", event_class="important")
# Publish to a group channel
publish("$group1", "Message for users in group1")
# Publish to the staff channel with an extra json data payload
data = {"field1":"value1","field2":[1,2]}
publish("$staff", "Message for staff", data=data)
Quick start
Install the Django package
pip install django-instant
Add "instant" to INSTALLED_APPS and update urls.py:
urlpatterns = [
# ...
path("instant/", include("instant.urls")),
]
Install the websockets server
Using the installer
Use the Centrifugo installer management command (for Linux and MacOs):
python manage.py installws
This will download a Centrifugo binary release and install it under a centrifugo directory. It will generate the Django settings to use.
Install manualy
Install the Centrifugo websockets server: see the detailled doc
Download a release https://github.com/centrifugal/centrifugo/releases/latest and generate a configuration file:
./centrifugo genconfig
The generated config.json file looks like this:
{
"v3_use_offset": true,
"token_hmac_secret_key": "46b38493-147e-4e3f-86e0-dc5ec54f5133",
"admin_password": "ad0dff75-3131-4a02-8d64-9279b4f1c57b",
"admin_secret": "583bc4b7-0fa5-4c4a-8566-16d3ce4ad401",
"api_key": "aaaf202f-b5f8-4b34-bf88-f6c03a1ecda6",
"allowed_origins": []
}
Configure the Django settings
Use the parameters from the installer's output or from Centrifugo's config.json file
to update your Django's settings.py:
CENTRIFUGO_HOST = "http://localhost"
CENTRIFUGO_PORT = 8001
CENTRIFUGO_HMAC_KEY = "46b38493-147e-4e3f-86e0-dc5ec54f5133"
CENTRIFUGO_API_KEY = "aaaf202f-b5f8-4b34-bf88-f6c03a1ecda6"
SITE_NAME = "My site" # used in the messages to identify where they come from
Create channels
Go into the admin to create channels or create them programatically:
from instant.models import Channel
Channel.objects.create(name="superuser", level=Channel.Level.Superuser)
Api: channel create parameters:
name: the channel name. Required and uniquelevel: access authorization level for a channel: Public, Users, Groups, Staff, Superuser. Default: Superuseris_active: a boolean to disable a channelgroups: a list of authorized Django groups for a channel
Avalailable endpoints
/instant/login/: takes a username and password as parameter and will login the
user in Django and return a Centrifugo connection token
/instant/get_token/: get a Centrifugo connection token for a logged in user
The two methods above return some connection information: a token for the websockets connection, a Django csrf token and a list of authorized channels for the user:
{
"csrf_token": "fvO61oyhcfzrW3SjPCYxYfzDAQFO6Yz7yaAQkxDbhC0NhlwoP1cecqLEYv8SCDLK",
"ws_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJnZ2ciLCJleHAiOjE2M..",
"channels": [
{
"name": "public",
"level": "public"
},
{
"name": "$users",
"level": "users"
},
{
"name": "$group1",
"level": "groups"
}
]
}
/instant/subscribe/: get tokens for Centrifugo channels subscriptions
(doc)
Publish method
The required parameters are channel and either message or data
publish("$users", "A message", data={
"foo": "bar"}, event_class="important", bucket="notifications")
The other parameters are optional
Javascript client
Several options are available for the client side
Use the official Centrifugo js client
Manage your websockets connection manually with the official Centrifugo js library: Centrifuge-js
Use the embeded client in a script tag
In a Django template:
{% load static %}
<script src="{% static 'instant/index.min.js' %}"></script>
<script>
const instant = $instant.useInstant();
</script>
Use the npm client
A dedicated client is available from npm to handle the messages and connections client side in javascript or typescript
Example
An example with a backend and a frontend is available
Tests
To run the tests:
tox
1 maintainer
Metadata
1 maintainer
Release files for django-instant 4.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| django-instant-4.2.0.tar.gz | 27.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_instant-4.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 62.0 kB
Release files / django-instant-4.2.0.tar.gz
| Download URL | django-instant-4.2.0.tar.gz |
|---|---|
| Size | 27.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
355693c6a27b8e906fa34bb3490b3269a465401229f8f737258577f500b125d6
|
|
BLAKE2b-256 checksum How to use checksums |
a6da86eada6230c24226d8d2f39e964c29c68cef5c618aaf64910fcfd7ddce24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.10.8
|
Release files / django_instant-4.2.0-py3-none-any.whl
| Download URL | django_instant-4.2.0-py3-none-any.whl |
|---|---|
| Size | 34.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bf4288480a042639ec7f71ded209a47c7e029ea2eb5723e3669632b7098977ae
|
|
BLAKE2b-256 checksum How to use checksums |
41cf209fc30cf4e8c11e05dfb1c80a95839aaedc2df7cc910ebeb85080d75f75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.10.8
|
