django-websocketclient is a WebSocket client for Django to connect to the WebSocket server and listen to incoming messages in persistent mode

This library uses async interator for websocket connection provided by websockets library and wrap it under django's manage.py command. The idea is taken from the discussion thread on the django's forum.

Use the package manager pip.

pip install django-websocketclient

Or using poetry.

poerty add django-websocketclient

1. Add websocketclient to INSTALLED_APPS in settings.py

INSTALLED_APPS = [
    "django.contrib.admin",
     ...
     ...
    "websocketclient",
]

2. Set Host and async message handler path for WebSocket client in settings.py. This async handler will be called to process data received over WebSocket connection

WEBSOCKETCLIENT_HOST = "localhost:8000"
WEBSOCKETCLIENT_MESSAGE_HANDLER = "myproject.handlers.message_handler"

3. Create handlers.py module at the root level of your project module. A typical django structure will looks like this.

myproject
├── 
├── myproject
│   ├── __init__.py
│   ├── asgi.py
│   ├── handlers.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py

4. Define async message handler coroutine under myproject/myproject/handlers.py

async def message_handler(message, websocket):
    # process message here
    print(message)
    
    # You can also send the message back to server
    await websocket.send("Message received from client")

Run manage.py command to connect to websocket server.

python manage.py runwebsocketclient

Optional CLI Arguments

usage: manage.py runwebsocketclient [--host HOST] [--path PATH]
  --host HOST   Websocket Server host
  --path PATH   Websocket Server path

DB operations like ORM query should be done using sync function wrap with sync_to_async

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

MIT