Tornado-sent events¶

Data storage and publishing¶

In order to publish data to listeners, Tornadose utilizes a data store concept somewhat reminiscent of that used in Flux. In short, subscribers start listening to a data store and are notified when there are updates.

class tornadose.stores.BaseStore(*args, **kwargs)[source]¶

Base class for all data store types.

At a minimum, derived classes should implement submit and publish methods.

deregister(subscriber)[source]¶

Stop publishing to a subscriber.

initialize(*args, **kwargs)[source]¶

Hook for doing custom initialization. Child classes should implement this method instead of overwriting __init__.

publish()[source]¶

Push messages to all listeners. This method must be implemented by child classes. A recommended way to implement this method is as a looping coroutine which yields until new data is available via the submit() method.

register(subscriber)[source]¶

Register a new subscriber. This method should be invoked by listeners to start receiving messages.

submit(message)[source]¶

Add a new message to be pushed to subscribers. This method must be implemented by child classes.

This method exists to store new data. To actually publish the data, implement the publish method.

class tornadose.stores.DataStore(*args, **kwargs)[source]¶

Generic object for producing data to feed to clients.

To use this, simply instantiate and update the data property whenever new data is available. When creating a new EventSource handler, specify the DataStore instance so that the EventSource can listen for updates.

class tornadose.stores.QueueStore(*args, **kwargs)[source]¶

Publish data via queues.

This class is meant to be used in cases where subscribers should not miss any data. Compared to the DataStore class, new messages to be broadcast to clients are put in a queue to be processed in order.

QueueStore will work with any tornado.web.RequestHandler subclasses which implement a submit method. It is recommended that a custom subscription handler’s submit() method also utilize a queue to avoid losing data. The subscriber must also register/deregister itself with the QueueStore via the QueueStore.register() and QueueStore.deregister() methods.

A QueueStore-compatible request handler is included in tornadose.handlers.WebSocketSubscriber.

Request handlers¶

Tornadose defines handlers for using the EventSource interface or WebSockets. For other handlers, the BaseHandler class is provided.

class tornadose.handlers.BaseHandler(application, request, **kwargs)[source]¶

Bases: tornado.web.RequestHandler

Base handler for subscribers. To be compatible with data stores defined in tornadose.stores, custom handlers should inherit this class and implement the submit() and publish() methods.

initialize(store)[source]¶

Common initialization of handlers happens here. If additional initialization is required, this method must either be called with super or the child class must assign the store attribute and register itself with the store.

publish()[source]¶

Push a message to the subscriber. This method must be implemented by child classes.

submit(*args, **kwargs)[source]¶

Submit a new message to be published.

class tornadose.handlers.EventSource(application, request, **kwargs)[source]¶

Bases: tornadose.handlers.BaseHandler

Handler for server-sent events a.k.a. EventSource.

The EventSource interface has a few advantages over websockets:

• It is a normal HTTP connection and so can be more easily monitored than websockets using tools like curl or HTTPie.
• Browsers generally automatically try to reestablish a lost connection.
• The publish/subscribe pattern is better suited to some applications than the full duplex model of websockets.

publish(*args, **kwargs)[source]¶

Pushes data to a listener.

class tornadose.handlers.WebSocketSubscriber(application, request, **kwargs)[source]¶

Bases: tornadose.handlers.BaseHandler, tornado.websocket.WebSocketHandler

A Websocket-based subscription handler.

open(*args, **kwargs)[source]¶

Register with the publisher.

publish(*args, **kwargs)[source]¶

Push a new message to the client. The data will be available as a JSON object with the key data.

Changelog¶