Intro to Orbited with Python

This tutorial will demonstrate how the Orbited client API interacts with the Orbited daemon. The great thing about Python is the interpreter, and Orbited is no special case. By the end of this tutorial you will have sent real-time events from a Python interpreter to specific browser windows.

Prerequisites

Orbited

This tutorial assumes you have already installed Orbited. If you haven’t then check out the tutorial on Installing Orbited.

PyOrbited

PyOrbited is a library of Python implementations of the Orbited client API. It currently consists of a basic socket based implementation, a twisted implementation, and a pyevent/libevent implementation. For our purposes we only need the basic implementation, but all three come with PyOrbited. To install the library simply run

easy_install pyorbited

SimpleJSON

SimpleJSON is Python library for encoding and decoding the JSON format. To install it run:

easy_install simplejson

Tutorial

First off, we need to start up the Orbited daemon. This can be done by running the command orbited in a console or command window. You should see a note that a configuration file wasn’t found. By default Orbited looks for the default config file orbited.cfg in the directory where you run the command. You can also specify a config file as the first argument when running the daemon. The console output should look like this (with a few more messages):

orbited.cfg could not be found. Using default configuration
2007-10-20 05:12:45,705 - Router - INFO - register_static, /_/admin_screen/static/, [...]
2007-10-20 05:12:45,774 - OrbitedDaemon - INFO - Listening on port 9000

This indicates that the Orbited daemon is listening for incoming HTTP connections on port 8000 and incoming orbit connections on port 9000. Now open a browser window and visit the URL http://localhost:8000/_/about. This page should display something similar to the following:

Orbited 0.2.0

Python 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] on win32

This indicates that you have successfully made contact with the Orbited server. Now point your browser to the URL http://localhost:8000/demo?user=user&session=0&transport=basic. This page will seem to hang and you’ll see a Loading message in your browser’s status. If you visited the URL in a browser window that had a previous page, you may still see the contents of that previous page. Don’t worry though, this is normal behavior. The next step is to open a Python interpreter. Next execute the commands:

>>> import pyorbited.simple
>>> client = pyorbited.simple.Client()
>>> user_key = "user, 0, /demo"
>>> client.event( [ user_key ], "Hello from python!<br>", False)

The first two lines import the Orbited client API and create a client object. The next line is the user_key we use to identify the browser window we want to communicate with. If you recall, we accessed /demo?user=user&session=0&transport=raw. This indicates that the location we are sending is /demo and the username is user, and the session key is 0. Therefore the unique key identifying that browser window is "user, 0, /demo". The last line is where we actually send the event. The client.event function takes 2 arguments and a third optional argument. The first argument is a list of unique user keys that determine the recipients of the event. The second argument is the event data itself, and the third argument which we specify as false determines wether we wish to encode the data in the JSON format. We want to send raw HTML so we don’t encode the data.

At this point you can try sending events to user keys that you know don’t exist and see what sort of response you get. You can also send events to multiple open browsers simply by including each recipient user key in the first argument to the event function.

Conclusion

Now you have some idea of how Orbited works. Granted, most applications will need interaction more complex then raw HTML. The main use case of Orbited is to send data that is interpreted by JavaScript. Then JavaScript can do the appropriate action based on the contents of the event. A good place to go from here is the CherryChat Tutorial. It will show you how to weave Python, JavaScript, and Orbited together into a meaningful application.