HowToUseIt

Firstly, pubsubclient is written in Python, so if you’re not using Python then you may have some more than minor headaches. If you are using Python, however, then pubsubclient is written specifically to be self-contained API-wise. Although it has some dependencies, these are an implementation issue and do not affect any programs using pubsubclient. So, let’s see how we can do something interesting!

Dependencies

Pubsubclient needs a Python interpreter (currently only tested in CPython 2.4+). Along with this you will also need xmpppy and lxml (in Debian-based systems these are the packages python-xmpp and python-lxml).

A Quick Example of Pubsubclient

The simplest way to start using pubsubclient is by getting the code from GitHub and putting the pubsubclient.py file in your program’s working directory.

We can then write a simple Python application to use it, like the following:

#!/usr/bin/env python
import pubsubclient

If that program runs without errors then your dependencies are OK, so we can start using it. First we need a client for the publish/subscribe network, this is called PubSubClient, so let’s make one:

#!/usr/bin/env python
import pubsubclient
client = pubsubclient.PubSubClient("me@myserver.org", "mypassword")

We then need to log in, which is as simple as:

client.connect()

Now we should be online.

To check for messages we use the PubSubClient’s process method. We should call this regularly, the way you call it being dependent on the way you are programming (for example it could be in a while loop, whenever a web page is accessed, or it could be in a toolkit’s main loop, etc.). Here we’ll use a while loop, with a sleep command to stop us abusing resources needlessly:

#!/usr/bin/env python
import pubsubclient
import time		# Needed for time.sleep
client = pubsubclient.PubSubClient("me@myserver.org", "mypassword")
client.connect()
while True:
	client.process()
	time.sleep(1)

This will process new messages every second until you stop the program (for example with Ctrl-C). However, process doesn’t mean anything yet, since we haven’t told it what to do with messages.

Pubsubclient works asynchronously, so that your programs can get on with something else instead of waiting for a reply. This is implemented with return functions (callbacks), which are functions you write and give to pubsubclient whenever you make a request. When pubsubclient receives a reply it will run that function (during the next process() call). Return functions for different requests may need to take different arguments.

As an example, this is how to print the top-level nodes on a server then exit:

#!/usr/bin/env python
import pubsubclient
import time

# This will run when we get a reply
def handle_nodes(node_list):
	global wait
	# This function should take one argument, a list of pubsubclient.Node objects
	for node in node_list:
		print "Found node " + str(node)		# str on a Node will give its name/ID
	# We can exit now
	wait = False

global wait
# Make a client
client = pubsubclient.PubSubClient("me@myserver.org", "mypassword")
# Log on
client.connect()

# The following line requests the top-level nodes on aserver.com and makes handle_nodes the return function
client.get_nodes('aserver.com', node=None, return_function=handle_nodes)

# This tells us to keep waiting for a reply (we could be doing anything here, since it's asynchronous)
# Needs to be global since we're using it in the function too
wait = True
while wait:
	# Handle any replies
	client.process()
	# Wait for a second
	time.sleep(1)
# Now we can close

We can expand on this by using some of pubsubclient’s built-in types. Although all of the library’s functionality can be accessed via a PubSubClient object, other objects like Node make the interface more intuitive.

For example, instead of just printing the top-level nodes on a server by using PubSubClient.get_nodes, we can print every node on the server if we use Node.get_sub_nodes on every node we find (these methods must be given a PubSubClient to send messages over). For example:

#!/usr/bin/env python
import pubsubclient
import time

# This will run when we get a reply
def handle_nodes(node_list):
	# This function should take one argument, a list of pubsubclient.Node objects
	global client
	# We've received a reply, so reduce the amount we're waiting for by one
	global wait
	wait -= 1

	for node in node_list:
		print "Found node " + str(node)		# str on a Node will give its name/ID
		# Now we can request this Node's children
		# We need to supply a PubSubClient to use and a return function
		node.get_sub_nodes(client, handle_nodes)
		# We're now waiting for another reply, so increment wait
		wait += 1
	

global wait
global client
# Make a client
client = pubsubclient.PubSubClient("me@myserver.org", "mypassword")
# Log on
client.connect()

# The following line requests the top-level nodes on aserver.com and makes handle_nodes the return function
client.get_nodes('aserver.com', node=None, return_function=handle_nodes)

# This keeps track of how many replies we are waiting on
# Needs to be global since we're using it in the function too
wait = 1
while wait > 0:
	# Handle any replies
	client.process()
	# Wait for a second
	time.sleep(1)
# Now we can close

That gives a brief overview of the basics. More shall be added here when the library is more comprehensive (eg. message handling, form handling, etc.).