Wednesday, January 14, 2015

A Python Client Example for Lightstreamer

Recently, some folks asked on our forum for some advice on how to properly create a Lightstreamer client based on the Python language.

An official release of a Lightstreamer Python client is not available yet, so it seems a good moment to show an example of a simple client application written in this wonderful language.

The proposed script provides a very simple version of the well known Stock-List demo. In this new adaption, soon after submitting a single subscription to a set of items with related fields, the real-time data coming from the server are displayed on the console until the user hits the CR key.

The script is aimed to show only the essential steps needed to establish a minimal interaction with Lightstreamer Server:
  1. Connecting to Lightstreamer Server and creating a new Session
  2. Subscribing to a set of items with specific fields
  3. Notifying about real-time data updates
  4. Unsubscribing from items
  5. Disconnecting
In the remainder of this post, we will dig into the code example to analyze each single step.
The code presented has been tested with Python 2 since version 2.6.3.

The complete example is available on GitHub:
https://github.com/Weswit/Lightstreamer-example-StockList-client-python

A Bit of Modeling

First of all, let's code a couple of classes needed to model two major entities in the domain of Lightstreamer technology: Session and Subscription.

The LSClient Class

The LSClient class wraps a Lightstreamer Session. It is a simple client-side implementation of the Lightstreamer Server Text mode Protocol, hence its main job is to manage all HTTP requests and responses required to correctly communicate with Lightstreamer Server.
In the snippet below, an outline version of the class is shown, where only high level operations have been included:


As you can see, the class offers basic operations to manage the life-cycle of a Lightstreamer Session (by means of connect and disconnect methods) and to deal with a Subscription (subscribe and unsubscribe methods).

The Subscription Class

The Subscription class abstracts a subscription to be submitted to Lightstreamer Server. It contains subscription details in terms of item names, field names and management modeIt also specifies the Data Adapter which supplies all the items.
Furthermore, it keeps an internal list to allow the registration of generic listeners (by means of addlistener method), which are interested in being notified about real-time updates for further processing: once new item events arrive from the server, the Subscription instance will dispatch them to all registered listeners (notifyupdate method).


The snippet above shows the complete implementation, which also includes the decoding logic of each text response, as indicated by the Text mode Protocol specifications (_decode method).

Connecting to Lightstreamer

To connect to Lightstreamer Server a new session has to be established. This task is easily accomplished by creating a new instance of the LSClient class and invoking its connect method, as in the following snippet:

As you can see, the LSClient class constructor takes takes two arguments: the server address (if not specified, port 80 is the default) and the Adapter Set. In this case, we connect to the online Lightstreamer demo server, but obviously these settings could be changed to reflect your deployment environment.

Subscribing

The next step is to make a subscription to activate the real-time updates flow from the Lightstreamer Server to the client. To do that, we need to follow these simple actions:
  1. Create an instance of the Subscription class, which takes four arguments: the subscription mode ("MERGE"), the list of items to be subscribed, the list of field names and the name of the Data Adapter ("QUOTE_ADAPTER").
  2. Make a minimal subscription listener, by defining a simple function (on_item_update) which incorporates the action to trigger for each new item update.
  3. Bind such function to the Subscription instance, by invoking the its addlistener method.
  4. Register the Subscription to the LSClient instance by means of the subscribe method, which will return a subscription key be used for later unsubscription.


Just to keep things simple, the example subscribes only to a subset of all available items offered by the Stock-List Data Adapter. Moreover, a limited set of fields has been specified in order to make the incoming events easily readable whenever displayed on the console.

Notifying

Once the subscription is activated, real-time events start to be pushed by Lightstreamer Server through the persistent HTTP connection established in the connecting phase. Such item events (which carry the updated stock-list values) are then forwarded by the LSClient to the registered Subscription instance, which in turn dispatches them to the on_item_update function where are extracted, formatted and, finally, printed out on the console, as shown in the following picture:

Unsubscribing

Data keeps on streaming down until the user hits the CR key. After that, the unsubscription process takes places, by invoking the LSClient's unsubscribe method, which takes as unique argument the subscription-key we got as a return value during the subscription step:


Disconnecting

In order to proceed with a graceful disconnection from Lightstreamer Server, it is simply required to invoke the disconnect method provided by the LSClient class as follows:


Conclusion

It is important to highlight that the example was not meant to be a complete and robust Lightstreamer Client Python library (for example, the Stream-Sense mechanism, to fall back to Long Polling if Streaming is unavailable, is not present). It was instead intended to show how the powerful of the Python Language combined with the richness of its standard library makes it possible to quickly develop a real-working example, which could be used as a starting point to build more complex interactions with the Lightstreamer Server to manage all the possible scenarios included in the Lightstreamer Server Text mode Protocol.

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.