I recently took part in Django Dash, the annual hackathon where teams of up to three compete to build the best Django project they can within 48 hours. This year I worked with Travis White and Josh de Blank to build DrawnBy - a collaborative drawing application that allows people to sketch together in real-time.
DrawnBy makes extensive use of WebSockets which are mostly unheard of in web stacks like Django and Rails, or even antiquated stacks like PHP and ASP.NET, which are all designed around accepting a request and returning a response to the browser as quickly as possible. This is in contrast to WebSockets which allow full duplex communication between the browser and server, and therefore require long running requests per user.
A variety of patterns for dealing with WebSockets in Django emerged while developing DrawnBy, and since the Dash I’ve been working on abstracting these into a reusable Django application called django-socketio which I’ve released today. It’s available on GitHub, Bitbucket and PyPI.
Here’s an overview of the features.
The WebSocket implemented by gevent-websocket provides two methods for sending
data to other clients,
socket.send which sends data to the given socket
socket.broadcast which sends data to all socket instances
other than itself.
A common requirement for WebSocket based applications is to divide
communications up into separate channels. For example a chat site may have
multiple chat rooms and rather than using
broadcast which would send a chat
message to all chat rooms, each room would need a reference to each of the
connected sockets so that
send can be called on each socket when a new
message arrives for that room.
django-socketio extends Socket.IO both on the client and server to provide channels that can be subscribed and broadcast to.
Once the socket is subscribed to a channel, you can then broadcast to the
channel server-side in Python using the
django_socketio.events module provides a handful of events that can be
subscribed to, very much like connecting receiver functions to Django signals.
Each of these events are raised throughout the relevant stages of a Socket.IO
Events are subscribed to by applying each event as a decorator to your event handler functions:
Each event handler takes at least three arguments: the current Django
request, the Socket.IO
socket the event occurred for, and a
which is simply a dictionary that can be used to persist variables across all
events throughout the life-cycle of a single WebSocket connection.
on_connect— occurs once when the WebSocket connection is first established.
on_message— occurs every time data is sent to the WebSocket. Takes an extra
messageargument which contains the data sent.
on_subscribe— occurs when a channel is subscribed to. Takes an extra
channelargument which contains the channel subscribed to.
on_unsubscribe— occurs when a channel is unsubscribed from. Takes an extra
channelargument which contains the channel unsubscribed from.
on_error— occurs when an error is raised. Takes an extra
exceptionargument which contains the exception for the error.
on_disconnect— occurs once when the WebSocket disconnects.
on_finish— occurs once when the Socket.IO request is finished.
Like Django signals, event handlers can be defined anywhere so long as they end up being imported. Consider adding them to their own module that gets imported by your urlconf, or even adding them to your views module since they’re conceptually similar to views.
All events other than the
on_connect event can also be bound to particular
channels by passing a
channel argument to the event decorator. The channel
argument can contain a regular expression pattern used to match again multiple
channels of similar function.
For example, suppose you implemented a chat site with multiple rooms. WebSockets would be the basis for users communicating within each chat room, however you may want to use them elsewhere throughout the site for different purposes, perhaps for a real-time admin dashboard. In this case there would be two distinct WebSocket uses, with the chat rooms each requiring their own individual channels.
Suppose each chat room user subscribes to a channel client-side using the room’s ID:
Then server-side the different message handlers are bound to each type of channel:
The “hello world” of WebSocket applications is naturally the chat room. As such django-socketio comes with a demo chat application that provides examples of the different events and channel features available.