Django-tornado-websockets’s documentation¶

Automatic installation¶

$ pip install django-tornado-websockets

Manual installation¶

Clone this repo and run installation with pip or setup.py install:

$ git clone https://github.com/Kocal/django-tornado-websockets.git
$ cd django-tornado-websockets
# Installation with pip
$ pip install -e .
# or with setup.py
$ python setup.py install

Integration¶

In your settings.py file, you need to add tornado_websockets to your Django INSTALLED_APPS :

INSTALLED_APPS = [
    # ...
    'tornado_websockets',
]

Configuration¶

Since we use Tornado as a replacement of a WSGI server (Gunicorn, uWSGI, ...), you need to configure it a bit before using django-tornado-websockets.

# At the end of settings.py file

TORNADO = {
    'port': 1337,    # 8000 by default
    'handlers': [],  # [] by default
    'settings': {},  # {} by default
}

import tornado_websockets

# ...

TORNADO = {
    # ...
    'handlers': [
        # ...
        tornado_websockets.django_app,  # django_app is using a "wildcard" route, so it should be the last element
    ],
}

import tornado.web

# ...

# Django specific configuration about static files
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static')

TORNADO = {
    # ...
    'handlers': [
        (r'%s(.*)' % STATIC_URL, tornado.web.StaticFileHandler, {'path': STATIC_ROOT}),
        # ...
    ]
}

TORNADO = {
    # ...
    'settings': {
        'debug': True,
    }
}

Run Tornado server¶

Django-tornado-websockets provides an easy solution to run your Tornado server. When you add tornado_websockets to your INSTALLED_APPS, you obtain a new management command called runtornado:

$ python manage.py runtornado

Using WebSockets (server side)¶

It’s preferable to write your WebSocket applications in your views.py file, or import these in views.py.

from tornado_websockets.websocket import WebSocket

# Make a new instance of WebSocket and automatically add handler '/ws/my_ws' to Tornado handlers
my_ws = WebSocket('/my_ws')

class MyClass(object):

    def __init__(self):
        my_ws.context = self

# On a function
@my_ws.on
def my_event(socket, data):
    print('Catch "my_event" event from a client')
    print('But I know this client, it is the one using this websocket connection: %s' % socket)


# On a class method
class MyClass(object):

    def __init__(self):
        # Do not forget the context, otherwise the `self` value for all class methods decorated by `@my_ws.on`
        # decorator will be `None`
        my_ws.context = self

    @wy_ws.on
    def my_other_event(self, socket, data):
        # `self` value is a MyClass instance due to `my_ws.context = self` in `__init__()` method
        print('Catch "my_other_event" from a client')
        print('And same as before, I know that this client is using this websocket connection: %s' % socket)

from tornado_websockets.websocket import WebSocket

ws_echo = WebSocket('/echo')

@ws_echo.on
def open(socket):
    # Notify all clients about a new connection
    ws_echo.emit('new_connection')

@ws_echo.on
def message(socket, data):
    # Reply to the client
    socket.emit('message', data)

    # Wow we got a spammer, let's inform the first client :^)
    if 'spam' in data.message:
        # wow
        ws_echo[0].emit('got_spam', {
            'message': data.get('message'),
            'socket': socket
        })

Using WebSockets (client side)¶

Django-tornado-websockets uses its own wrapper for using JavaScript WebSocket in client-side: django-tornado-websockets-client. By using this wrapper, you will be able to write:

var ws = new TornadoWebSocket(...);

ws.on('open', () => {
    ws.emit('my_event', { foo: 'bar' });
});

// instead of
var ws = new WebSocket(...);

ws.onopen = () => {
    ws.send({ event: 'my_event', data: { foo: 'bar' }});
};

But you can simply ignore this wrapper and use raw WebSocket if you want. Just remember that data passed by Django-tornado-websockets are in JSON: {event: 'evt', data: {}}.

{% load static %}
<script src="{% static 'tornado_websockets/client.js' %}"></script>

var ws = new TornadoWebSocket(path, options);
var ws = TornadoWebSocket(path, options); // shortcut to new TornadoWebSocket(path, options)
var ws = tws(path, options);  // shortcut to new TornadoWebSocket(path, options)

// Bind to WebSocket.onopen
ws.on('open', event => {
    console.log('Connection: OPEN', event);

    // Add an event/callback combination into TornadoWebSocket.events private object.
    // Will be called when we receive a JSON like that: {event: 'my_event', data: {...}}
    ws.on('my_event', data => {
        console.log('Got data from « my_event »', data);
    });
});

// Bind to WebSocket.onclose
ws.on('close', event => {
    console.log('Connection: ERROR', event);
});

// Bind to WebSocket.onerror
ws.on('error', event => {
    console.log('Connection: CLOSED', event);
});

ws.on('open', event => {
    ws.emit('my_event'); // will send {}

    ws.emit('my_event', 'My message'); // will send {message: 'My message'}

    ws.emit('my_event', {my: 'data'}); // will send {my: 'data}
});

Progress bar¶

Provide an interface to easily handle a progress bar on both server and client sides.

import time
import threading
from tornado_websockets.modules.progress_bar import ProgressBar

ws_pb = ProgressBar('/my_progress_bar', min=0, max=100)

# Client emitted ``start_progression`` event
@ws_pb.on
def start_progression():

    def my_func():
        for value in range(ws_pb.min, ws_pb.max):
            time.sleep(.1)  # Emulate a slow task :^)
            ws_pb.tick(label="[%d/%d] Task #%d is done" % (ws_pb.value, ws_pb.max, value))

    threading.Thread(None, my_func, None).start()

WebSocket¶

class tornado_websockets.websocket.WebSocket(path, add_to_handlers=True)[source]¶

Class that you should to make WebSocket applications 👍.

WebSocket.on(callback)[source]¶

Execute a callback when an event is received from a client, should be used as a decorator for a function or a class method.

Event name is determined by function/method __name__ attribute.

Parameters:	callback (Callable) – Function or a class method.
Returns:	callback parameter.
Example:	>>> ws = WebSocket('/example') >>> @ws.on ... def my_event(socket, data): ... print('Received "my_event" event from a client.')

WebSocket.emit(event, data=None)[source]¶

Send an event/data dictionnary to all clients connected to your WebSocket instance. To see all ways to emit an event, please read « Send an event to a client » section.

Parameters:	event (str) – event name data (dict or str) – a dictionary or a string which will be converted to {'message': data}
Raise:	EmitHandlerError if not used inside @WebSocket.on() decorator.
Raise:	tornado.websocket.WebSocketClosedError if connection is closed.

Warning

WebSocket.emit() method should be used inside a function or a class method decorated by @WebSocket.on() decorator, otherwise it will raise a EmitHandlerError exception.

WebSocketHandler¶

class tornado_websockets.websockethandler.WebSocketHandler(application, request, **kwargs)[source]¶

Represents a WebSocket connection, wrapper of tornado.websocket.WebSocketHandler class.

This class should not be instantiated directly; use the WebSocket class instead.

WebSocketHandler.initialize(websocket)[source]¶

Called when class initialization, makes a link between a WebSocket instance and this object.

Parameters:	websocket (WebSocket) – instance of WebSocket.

WebSocketHandler.on_message(message)[source]¶

Handle incoming messages on the WebSocket.

Parameters:	message (str) – JSON string

WebSocketHandler.on_close()[source]¶

Called when the WebSocket is closed, delete the link between this object and its WebSocket.

WebSocketHandler.emit(event, data)[source]¶

Sends a given event/data combinaison to the client of this WebSocket.

Wrapper for tornado.websocket.WebSocketHandler.write_message method.

Parameters:	event (str) – event name to emit data (dict) – associated data

TornadoWrapper¶

class tornado_websockets.tornadowrapper.TornadoWrapper[source]¶

Wrapper for Tornado application and server handling.

It let you access to Tornado app, handlers and settings everywhere in your code (it’s really useful when you run runtornado management command and WebSockets management).

classmethod TornadoWrapper.add_handlers(handlers)[source]¶

Add an handler to Tornado app if it’s defined, otherwise it add this handler to the TornadoWrapper.tornado_handlers list.

Parameters:	handlers (list|tuple) – Handler(s) to add
Returns:	Tornado application handlers
Return type:	list

classmethod TornadoWrapper.start_app(tornado_handlers=None, tornado_settings=None)[source]¶

Initialize the Tornado web application with given handlers and settings.

Parameters:	tornado_handlers (list) – Handlers (routes) for Tornado tornado_settings (dict) – Settings for Tornado
Returns:	None

classmethod TornadoWrapper.loop()[source]¶

Run Tornado main loop and display configuration about Tornado handlers and settings.

Returns:	None

classmethod TornadoWrapper.listen(tornado_port)[source]¶

Start the Tornado HTTP server on given port.

Parameters:	tornado_port (int) – Port to listen
Returns:	None

Todo

Add support for HTTPS server.

Exceptions¶

exception tornado_websockets.exceptions.TornadoWebSocketsError[source]¶

Base exception of all django-tornado-websockets exceptions.

exception tornado_websockets.exceptions.EmitHandlerError(event, path)[source]¶

Exception thrown when an user try to emit an event without being in a function or class method decorated by @WebSocket.on() decorator.

• event - name of the event under investigation.
• path - path where the offence have taken place.

exception tornado_websockets.exceptions.InvalidInstanceError(actual_instance, expected_instance_name)[source]¶

Exception thrown when an instance is not the expected one.

• actual_instance - actual instance which is trying to appear as expected_instance_name.
• expected_instance_name - name of expected instance.

exception tornado_websockets.exceptions.NotCallableError(thing)[source]¶

Exception thrown when an user try to use a decorator on a non-callable thing.

• thing - « The Thing ».

exception tornado_websockets.exceptions.WebSocketEventAlreadyBinded(event, path)[source]¶

Exception thrown when an user try to bind an already existing event for a given path.

• event - name of the event under investigation.
• path - path where the offence have taken place.