Qpid Proton Python API Documentation¶
The Proton module provides a Python 2.7 and 3.x API for Qpid Proton. It enables a developer to write Python applications that send and receive AMQP messages.
Modules¶
About AMQP and the Qpid Proton Python API¶
Key API Features¶
Event-driven API
SSL/TLS secured communication
SASL authentication
Automatic reconnect and failover
Seamless conversion between AMQP and Python data types
AMQP 1.0
Basic API Concepts¶
The Qpid Python client API and library allows applications to send and receive AMQP messages. See API Overview for a more detailed explanation.
Containers¶
Messages are transferred between connected peers (or nodes) using senders and receivers. Each sender
or receiver is established over a connection. Each connection is established between two unique containers,
the entry point for the API. The container class proton.reactor.Container is found in the proton.reactor
module.
Connections¶
A connection object tracks the status of an AMQP connection. For applications which don’t require either
authorization or encryption, these may be automatically created by convenience methods
proton.reactor.Container.create_sender() and/or proton.reactor.Container.create_receiver().
However, for applications which do require either of these services, a connection object should be created
using the convenience method proton.reactor.Container.connect(), providing the required parameters.
This object should then be passed to the convenience methods proton.reactor.Container.create_sender()
and/or proton.reactor.Container.create_receiver() as needed. The connection class may be found at
proton.Connection.
Senders¶
The peer that sends messages uses a sender to send messages, which includes the target queue or topic which is
to receive the messages. The sender may be found at proton.Sender. Note that senders are most commonly
obtained by using the convenience method proton.reactor.Container.create_sender().
Receivers¶
The peer that receives messages uses a receiver to receive messages, and includes a source queue or topic from
which to receive messages. The receiver may be found at proton.Receiver. Note that senders are most commonly
obtained by using the convenience method proton.reactor.Container.create_receiver().
Message Delivery¶
The process of sending a message is known as delivery. Each sent message has a delivery object which tracks the
status of the message as it is sent from the sender to the receiver. This also includes actions such as settling the
delivery (ie causing the delivery status to be forgotten when it is no longer needed). The delivery class may be found
at proton.Delivery. The delivery object is most commonly obtained
when a message-related event occurs through the event object. See Event Handlers below.
Event Handlers¶
A handler is a class that handles events associated with the sending and receiving of messages. This includes
callbacks for events such as the arrival of a new message, error conditions that might arise, and the closing
of the connection over which messages are sent. An application developer must handle some key events to
successfully send and receive messages. When an event handler callback is called by the library, an Event object is
passed to it which contains an object associated with the event. For example,
when a message is received, the event object will have the property event.message by which the message itself may
be obtained. See proton.Event for more details.
The following are some of the important event callbacks that may be implemented by a developer:
- on_start(): This indicates that the event loop in the container has started, and that a new sender and/or
receiver may now be created.
To send a message, the following events may need to be handled:
- on_sendable(): This callback indicates that send credit has now been set by the receiver, and that a message may
now be sent.
on_accepted(): This callback indicates that a message has been received and accepted by the receiving peer.
To receive a message, the following event may need to be handled:
- on_message(): This callback indicates that a message has been received. The message and its delivery object may
be retreived, and if needed, the message can be either accepted or rejected.
Many other events exist for the handling of transactions and other message events and errors, and if present in your handler will be called as the corresponding events arise. See the Tutorial for examples of handling some other events.
Several event handlers are provided which provide default behavior for most events. These may be found in the
proton.handlers module. The proton.handlers.MessagingHandler is the most commonly used handler for
non-transactional applications. Developers would typically directly inherit from this handler to provide the
application’s event behavior, and override callbacks as needed to provide additional behavior they may require.
AMQP types¶
The types defined by the AMQP specification are mapped to either native Python types or to special proton classes which represent the AMQP type. See AMQP Types for a summary.
Examples¶
Several examples may be found in the Apache Qpid Proton Examples whcih illustrate the techniques and concepts of sending messages. They are also present in the source. These make an excellent starting point for developers new to this API. Make sure to read the README file, which gives instructions on how to run them and a brief explanation of each example.