django-realtime-events 1.0.3

Django Realtime Events

🚀 django-realtime-events

Lightweight realtime updates for Django using WebSocket (Django Channels).

django-realtime-events allows you to automatically send realtime events (create, update, delete) from your Django models to the frontend — with minimal setup.

---

✨ Features

• ⚡ Realtime model updates (create, update, delete)
• 🧩 Plug & play (just register your model)
• 🎯 Per-model WebSocket channel
• 🔍 Select specific fields (optimized payload)
• 🔥 Custom serializer support (full control)
• 🧠 Safe default (ID-only payload)
• 🔌 Supports Redis & InMemoryChannelLayer
• 🪶 Lightweight and easy to integrate

---

📦 Installation

pip install django-realtime-events

Add to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "channels",
    "django_realtime_events",
]

---

⚙️ Django Channels Setup

1. ASGI Configuration

asgi.py:

from channels.routing import ProtocolTypeRouter, URLRouter
from django.core.asgi import get_asgi_application
from django_realtime_events.routing import websocket_urlpatterns

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": URLRouter(websocket_urlpatterns),
})

settings.py:

ASGI_APPLICATION = "your_project.asgi.application"

---

2. Channel Layer (Development)

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels.layers.InMemoryChannelLayer"
    }
}

---

3. (Optional) Production with Redis

Install:

pip install channels-redis

Configure:

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": [("127.0.0.1", 6379)],
        },
    },
}

---

🚀 Quick Start

1. Register a Model

from django_channels_helper import register_model

register_model("shop.Product")

---

2. WebSocket Endpoint

ws://localhost:8000/ws/realtime/product/

---

3. Frontend Example

const socket = new WebSocket("ws://localhost:8000/ws/realtime/product/");

socket.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log(data);
};

---

📡 Event Format

{
  "model": "Product",
  "action": "created",
  "data": {
    "id": 1
  }
}

---

🎯 Data Configuration

🔹 1. Default (ID only)

register_model("shop.Product")

Output:

{ "id": 1 }

---

🔹 2. Select Fields

register_model(
    "shop.Product",
    fields=["id", "name"]
)

Output:

{
  "id": 1,
  "name": "Laptop"
}

---

🔹 3. Custom Serializer 🔥

def product_serializer(obj):
    return {
        "id": obj.id,
        "name": obj.name,
        "category": obj.category.name
    }

register_model(
    "shop.Product",
    serializer=product_serializer
)

Output:

{
  "id": 1,
  "name": "Laptop",
  "category": "Electronics"
}

---

⚠️ Data Priority Rule

serializer > fields > default (id only)

• If serializer is provided → it will be used
• Else if fields is provided → selected fields will be used
• Else → only id will be sent

---

🧠 Why ID-only by Default?

The default behavior sends only the model ID to ensure:

• 🔐 No accidental data exposure
• ⚡ Minimal payload (fast & efficient)
• 🧩 Works well with event-driven architecture
• 🎯 Full flexibility for developers

---

🧱 Multiple Models

You can register multiple models:

register_model("shop.Product")
register_model("shop.Order")

WebSocket endpoints:

/ws/realtime/product/
/ws/realtime/order/

---

⚠️ Model Signals Behavior

This package relies on Django model signals:

• post_save → for create & update
• post_delete → for delete

🔹 Create

Realtime events are triggered when .save() is called:

product = Product(name="Laptop", category="Electronic")
product.save()

Or:

Product.objects.create(name=name, category=category)

🔹 Update

Must use .save()

product = Product.objects.filter(id=id).first()

if product and name:
    product.name = name
    product.save()

🔹 Delete

Product.objects.filter(id=id).delete()

---

🧩 Example Use Cases

• 📊 Live dashboards
• 🛒 Realtime product updates
• 🔔 Notification systems
• 📋 Auto-refresh tables
• 💬 Chat triggers

---

⚠️ Best Practices

• Use fields for better performance
• Use serializer for relations and transformations
• Avoid heavy queries inside serializer
• Use Redis in production environments

---

🛠️ Requirements

• Python 3.12+
• Django 5.1+
• Django Channels
• Daphne 4.2+ (Optional)

---

⚡ Running the Server

This package uses WebSocket via Django Channels, which requires an ASGI server.

Development

If Django Channels is properly configured, you can use:

python manage.py runserver

Alternative (Recommended for stability)

You can also run the project using Daphne:

daphne your_project.asgi:application

If WebSocket is not working with runserver, try using Daphne.

---