Quickstart

This page is intended to provide steamlined method for getting the AMPS Python Client installed and examples running.

Installation

$ pip install amps-python-client

Additional client install options can be found in Installation Options

Examples

Now that you have the client installed, here are some code examples showing how the python client is used.

info

These examples are all runnable, but they require an AMPS instance to connect to. The instructions for starting an instance of AMPS are available in the Introduction to AMPS guide.

tip

For more comprehensive detail on the python client see the other sections of this Developer Guide and the Python Client API Reference

Example 1: Connect and Subscribe

import AMPS

uri = "tcp://localhost:9007/amps/json"

amps = AMPS.Client("subscribe-example")

try:
  amps.connect(uri)
  amps.logon()

  for message in amps.subscribe("messages"):
     print(message.get_data())

except AMPS.AMPSException, e:
   print (e)

In this example, we connect to an AMPS server running locally and initiate a subscription to the "orders" topic. As new orders are posted, myListener is invoked with each message, and prints the data of each order to the console.

Example 2: Publish a Message

import AMPS
import sys

uri = "tcp://localhost:9007/amps/json"

client = AMPS.Client("publish-example")

try:
    client.connect(uri)
    client.logon()
    client.publish("messages", '{"hi" : "Hello, world!"}')

except AMPS.AMPSException as e:
    sys.stderr.write(str(e))

client.publish_flush()

With AMPS, publishing is simple, as shown in this example. We connect to an AMPS server running locally, and publish a single message to the messages topic. To simply publish a message, there is no need to predeclare the topic or configure complex routing. Any subscription that has asked for JSON messages on the messages topic will receive the message.

Example 3: Query the Contents of a "SOW" Topic

State-of-the-World ("SOW") topics in AMPS combine the power of a database table with the performance of a publish-subscribe system. Use the AMPS Python client to query the contents of a SOW topic.

def execute_sow_query(client):
    # runs the SOW query, processes all of the messages
    # from the query, and then returns.
    for message in client.sow("orders",
                              "/symbol='ROL'",
                              batch_size=100,
                              timeout=5000):

        if message.get_command() == Message.Command.SOW:
           print(message.get_data())

Example 4: Automatic Reconnection and Resubscription

Rock-solid applications must be able to recover from network outages. The AMPS Python client includes an HAClient class that includes automatic reconnection and resubscription. Best of all, easy-to-implement interfaces control reconnection and resubscription behavior, allowing you to easily customize failover.

client = AMPS.HAClient("reconnectingSubscriber")

# The ServerChooser interface tells the HAClient which server
# to connect to, both for the initial connection and failover.
# The DefaultServerChooser is included with the client: many
# applications implement a ServerChooser to control failover
# behavior.

sc = AMPS.DefaultServerChooser()
sc.add("tcp://amps-server:9007/amps/json")
sc.add("tcp://amps-failover-server:9007/amps/json")

client.set_server_chooser(sc)
client.connect_and_logon()

def handle_messages(message):
     print(message.get_data())

# Enter subscriptions. If the connection to the server
# is lost, the HAClient will restore the connection to
# the server or the failover partner, and restore
# subscriptions.

client.subscribe(handle_messages, "messages")

The HAClient class can, optionally, also provide store-and-forward for reliable publish. With the AMPS transaction log, the class can provide resumable subscriptions that are guaranteed not to miss messages or receive duplicate messages, even in the case of failover between replicated servers.

This example queries for all orders for the symbol ROL, and simply prints the messages to the console.

Example 5: Automatic Failover

The AMPS Python client includes both a basic client, and a high availability client with additional features, including the ability to automatically failover if the client is disconnected. This example shows how to set up a high availability client for failover:

client = AMPS.HAClient("myClient")

# primary.amps.xyz.com is the primary AMPS instance, and
# secondary.amps.xyz.com is the secondary

# create a server chooser
chooser = AMPS.DefaultServerChooser()

# add the addresses to use for failover
chooser.add("tcp://primary.amps.xyz.com:12345/amps/json")
chooser.add("tcp://secondary.amps.xyz.com:12345/amps/json")

# set the server chooser for the client
client.set_server_chooser(chooser)

# connect and logon
client.connect_and_logon()

# now, use the client: if the client detects
# a disconnection, it will reconnect.

...

# at the end of the program, disconnect

client.disconnect()

This example creates an HA client and a server chooser for the client. The code then populates the server chooser with the list of failover servers, adds the chooser to the client, and then connects.

Once the client is connected, you can use the HAClient object just like a regular AMPS client. You can take advantage of the extended features, such as durable publish, duplicate message protection, and so on -- see the Developer's Guide for more information!

Additional Examples

More examples can be found in the other section of this Developer Guide as well as in the API Reference.