Chapter 5. Using the API

AMQ Python is an asynchronous event-driven API. To define how the application handles events, the user implements callback methods on the MessagingHandler class. These methods are then called as network activity or timers trigger new events.

class ExampleHandler(MessagingHandler):
    def on_start(self, event):
        print("The container event loop has started")

    def on_sendable(self, event):
        print("A message can be sent")

    def on_message(self, event):
        print("A message is received")

These are only a few common-case events. The full set is documented in the API reference.

The container is the top-level API object. It is the entry point for creating connections, and it is responsible for running the main event loop. It is often constructed with a global event handler.

handler = ExampleHandler()
container = Container(handler)
container.run()

Setting the Container Identity

Each container instance has a unique identity called the container ID. When AMQ Python makes a connection, it sends the container ID to the remote peer. To set the container ID, pass it to the Container constructor.

container = Container(handler, "job-processor-3")

If the user does not set the ID, the library will generate a UUID when the container is constucted.

Connection URLs encode the information used to establish new connections.

scheme://host[:port]

amqps://example.com
amqps://example.net:56720
amqp://127.0.0.1
amqp://[::1]:2000

To connect to a remote server, call the Container.connect() method with a connection URL. This is typically done inside the MessagingHandler.on_start() method.

class ExampleHandler(MessagingHandler):
    def on_start(self, event):
        event.container.connect("amqp://example.com")

    def on_connection_opened(self, event):
        print("Connection {0} is open".format(event.connection))

See the Section 5.3, “Security” section for information about creating secure connections.

Reconnect allows a client to recover from lost connections. It is used to ensure that the components in a distributed system reestablish communication after temporary network or component failures.

AMQ Python enables reconnect by default. If a connection is lost or a connection attempt fails, the client will try again after a brief delay. The delay increases exponentially for each new attempt, up to a default maximum of 10 seconds.

To disable reconnect, set the reconnect connection option to False.

container.connect("amqp://example.com", reconnect=False)

To control the delays between connection attempts, define a class implementing the reset and next methods and set the reconnect connection option to an instance of that class.

class ExampleReconnect(object):
    def init(self):
        self.delay = 0

    def reset(self):
        self.delay = 0

    def next(self):
        if self.delay == 0:
            self.delay = 0.1
        else:
            self.delay = min(10, 2 * self.delay)

        return self.delay

container.connect("amqp://example.com", reconnect=ExampleReconnect())

The next method returns the next delay in seconds. The reset method is called once before the reconnect process begins.

AMQ Python allows you to configure multiple connection endpoints. If connecting to one fails, the client attempts to connect to the next in the list. If the list is exhausted, the process starts over.

To specify multiple connection endpoints, set the urls connection option to a list of connection URLs.

urls = ["amqp://alpha.example.com", "amqp://beta.example.com"]
container.connect(urls=urls)

It is an error to use the url and urls options at the same time.

AMQ Python uses SSL/TLS to encrypt communication between clients and servers.

To connect to a remote server with SSL/TLS, use a connection URL with the amqps scheme.

container.connect("amqps://example.com")

AMQ Python can authenticate connections with a user and password.

To specify the credentials used for authentication, set the user and password options on the connect method.

container.connect("amqps://example.com", user="alice", password="secret")

AMQ Python uses the SASL protocol to perform authentication. SASL can use a number of different authentication mechanisms. When two network peers connect, they exchange their allowed mechanisms, and the strongest mechanism allowed by both is selected.

By default, AMQ Python allows all of the mechanisms supported by the local SASL library configuration. To restrict the allowed mechanisms and thereby control what mechanisms can be negotiated, use the allowed_mechs connection option. It takes a string containing a space-separated list of mechanism names.

container.connect("amqps://example.com", allowed_mechs="ANONYMOUS")

This example forces the connection to authenticate using the ANONYMOUS mechanism even if the server we connect to offers other options. Valid mechanisms include ANONYMOUS, PLAIN, SCRAM-SHA-256, SCRAM-SHA-1, GSSAPI, and EXTERNAL.

AMQ Python enables SASL by default. To disable it, set the sasl_enabled connection option to false.

event.container.connect("amqps://example.com", sasl_enabled=False)

Kerberos is a network protocol for centrally managed authentication based on the exchange of encrypted tickets. See Using Kerberos for more information.