5. API

5.1. WebSocket

class tornado_websockets.websocket.WebSocket(path)

Class that you should to make WebSocket applications 👍.

WebSocket.on(callback)

Should be used as a decorator.

It will execute the decorated function when WebSocketHandler will receive an event where its name correspond to the function one (by using __name__ magic attribute).

Parameters:

callback (callable) – Function to decorate.

Raises:

tornado_websockets.exceptions.NotCallableError –

Example:

>>> ws = WebSocket('/example')
>>> @ws.on
... def hello(socket, data):
...     print('Received event « hello » 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_handler(handler)

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

Parameters:handler (list|tuple) – An handler which conforms

classmethod TornadoWrapper.start_app(handlers=None, settings=None)

Initialize the Tornado web application with given handlers and settings.

Parameters:

• handlers (list) – Handlers (routes) for 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.