5. API — Django-tornado-websockets 0.2.1 documentation

# 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 (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.