5. API

5.1. WebSocket

class tornado_websockets.websocket.WebSocket(path, add_to_handlers=True)

Class that you should to make WebSocket applications 👍.

WebSocket.on(callback)

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)

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.

5.2. WebSocketHandler

class tornado_websockets.websockethandler.WebSocketHandler(application, request, **kwargs)

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)

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

Parameters:websocket (WebSocket) – instance of WebSocket.

WebSocketHandler.on_message(message)

Handle incoming messages on the WebSocket.

Parameters:message (str) – JSON string

WebSocketHandler.on_close()

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

WebSocketHandler.emit(event, data)

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

5.3. TornadoWrapper

class tornado_websockets.tornadowrapper.TornadoWrapper

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)

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)

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()

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

Returns:None

classmethod TornadoWrapper.listen(tornado_port)

Start the Tornado HTTP server on given port.

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

Todo

Add support for HTTPS server.

5.4. Exceptions

exception tornado_websockets.exceptions.TornadoWebSocketsError

Base exception of all django-tornado-websockets exceptions.

exception tornado_websockets.exceptions.EmitHandlerError(event, path)

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)

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)

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)

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.