5. API — Django-tornado-websockets 0.1.3 documentation

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