Tutorial

In this tutorial, we’re going to go over building a simple client and server, implementing the well-known “echo” protocol (where the client sends a message, and the server sends it back to the client), except with a slight twist.

We’re going to name our server, and our server will reply back with the message the client sends, but prefix it with “$name says:”. For example, if our server is called “Bob”, and the client sends “hello”, the server will send back “Bob says: hello”.

Server

Let’s start by writing the server. We need to get the name of the server first, so we’ll just grab that from sys.argv:

import sys
name, = sys.argv[1:]

Then, we need to create a Server object, which needs to know the name of this server, as well as what kind of server it is. I’ve decided to call it "simon", since the interaction reminds me of the game “Simon says”.

from network import Server
server = Server(name, "simon")

We now need to write a function which will handle each message that the client sends to the server, which looks like this:

@server.handler
def handle(message):
    return name + ' says: ' + message

Note

ZeroMQ doesn’t provide a way to distinguish between clients (because they can disconnect and reconnect arbitrarily, which hides network failures from your application). If you want to keep track, your client will need to provide some kind of token.

A typical pattern would be for a client to send a “login” message with a username and password, to which the server will provide a token, which the client then sends with every message until they logout.

Finally, we just need to run the server:

server.run()

Client

The client is just as easy as the server was. First, we need to create a new Client object, telling it what kind of protocol it implements, and then connect to a server.

from network import Client

client = Client("simon")
client.find_server()

When you run this code, the find_server() method will show all the “simon” servers on your local network, and you can type a number and press enter to connect to it.

You can try running the client now, just to see what it looks like. I’m running three servers in the background which means it looks like this:

$ python example_client.py
1: Alice @ heraan.local (192.168.3.251:64288)
2: Bob @ heraan.local (192.168.3.251:53779)
3: Charlie @ heraan.local (192.168.3.251:59351)

Note

In order for find_server() to work, there’s a lot of magic happening behind the scenes. When you call this function, it connects to Avahi to scan the local network for servers advertising the “simon” protocol. It also creates a ConsoleServerBrowser to show the discovered servers and to allow the user to pick one.

It’s possible to write your own ServerBrowser (for example, to integrate with pyglet or GTK), but you really need to read the source code to understand what the interaction is.

Now that we’ve connected to the server, we can send some messages to it. We’ll just let the user continually send messages and print the response:

while True:
    message = raw_input('> ')
    response = client.send(message)
    print response

Now you should be able to connect to a server, and have it respond. Here’s what it should look like:

$ python example_server.py Alice &
$ python example_client.py
1: Alice @ heraan.local (192.168.3.251:64288)
1
> hello
Alice says: hello
>