Table Of Contents

Previous topic

Tutorial

This Page

API Overview

An overview of the model

Messages are transferred between connected peers over ‘links’. At the sending peer the link is called a sender. At the receiving peer it is called a receiver. Messages are sent by senders and received by receivers. Links may have named ‘source’ and ‘target’ addresses (for example to identify the queue from which message were to be received or to which they were to be sent).

Links are established over sessions. Sessions are established over connections. Connections are (generally) established between two uniquely identified containers. Though a connection can have multiple sessions, often this is not needed. The container API allows you to ignore sessions unless you actually require them.

The sending of a message over a link is called a delivery. The message is the content sent, including all meta-data such as headers and annotations. The delivery is the protocol exchange associated with the transfer of that content.

To indicate that a delivery is complete, either the sender or the receiver ‘settles’ it. When the other side learns that it has been settled, they will no longer communicate about that delivery. The receiver can also indicate whether they accept or reject the message.

Three different delivery levels or ‘guarantees’ can be achieved: at-most-once, at-least-once or exactly-once. See Delivery guarantees for more detail.

A summary of the most commonly used classes and members

A brief summary of some of the key classes follows.

The Container class is a convenient entry point into the API, allowing connections and links to be established. Applications are structured as one or more event handlers. Handlers can be set at Container, Connection, or Link scope. Messages are sent by establishing an approprate sender and invoking its send() method. This is typically done when the sender is sendable, a condition indicated by the on_sendable() event, to avoid execessive build up of messages. Messages can be received by establishing an appropriate receiver and handling the on_message() event.

class proton.reactor.Container(*handlers, **kwargs)

Bases: proton.reactor.Reactor

A representation of the AMQP concept of a ‘container’, which lossely speaking is something that establishes links to or from another container, over which messages are transfered. This is an extension to the Reactor class that adds convenience methods for creating connections and sender- or receiver- links.

container_id

The identifier used to identify this container in any connections it establishes. Container names should be unique. By default a UUID will be used.

The connect() method returns an instance of Connection, the create_receiver() method returns an instance of Receiver and the create_sender() method returns an instance of Sender.

connect(url=None, urls=None, address=None, handler=None, reconnect=None, heartbeat=None, ssl_domain=None, **kwargs)

Initiates the establishment of an AMQP connection. Returns an instance of proton.Connection.

@param url: URL string of process to connect to

@param urls: list of URL strings of process to try to connect to

Only one of url or urls should be specified.

@param reconnect: A value of False will prevent the library form automatically trying to reconnect if the underlying socket is disconnected before the connection has been closed.

@param heartbeat: A value in milliseconds indicating the desired frequency of heartbeats used to test the underlying socket is alive.

@param ssl_domain: SSL configuration in the form of an instance of proton.SSLdomain.

@param handler: a connection scoped handler that will be called to process any events in the scope of this connection or its child links

@param kwargs: sasl_enabled, which determines whether a sasl layer is used for the connection; allowed_mechs an optional list of SASL mechanisms to allow if sasl is enabled; allow_insecure_mechs a flag indicating whether insecure mechanisms, such as PLAIN over a non-encrypted socket, are allowed. These options can also be set at container scope.

create_receiver(context, source=None, target=None, name=None, dynamic=False, handler=None, options=None)

Initiates the establishment of a link over which messages can be received (aka a subscription). Returns an instance of proton.Receiver.

There are two patterns of use. (1) A connection can be passed as the first argument, in which case the link is established on that connection. In this case the source address can be specified as the second argument (or as a keyword argument). The target address can also be specified if desired. (2) Alternatively a URL can be passed as the first argument. In this case a new connection will be establised on which the link will be attached. If a path is specified and the source is not, then the path of the URL is used as the target address.

The name of the link may be specified if desired, otherwise a unique name will be generated.

Various LinkOptions can be specified to further control the attachment.

create_sender(context, target=None, source=None, name=None, handler=None, tags=None, options=None)

Initiates the establishment of a link over which messages can be sent. Returns an instance of proton.Sender.

There are two patterns of use. (1) A connection can be passed as the first argument, in which case the link is established on that connection. In this case the target address can be specified as the second argument (or as a keyword argument). The source address can also be specified if desired. (2) Alternatively a URL can be passed as the first argument. In this case a new connection will be establised on which the link will be attached. If a path is specified and the target is not, then the path of the URL is used as the target address.

The name of the link may be specified if desired, otherwise a unique name will be generated.

Various LinkOptions can be specified to further control the attachment.

run()
schedule(delay, task)
class proton.Connection(impl=<built-in function pn_connection>)

A representation of an AMQP connection

open()

Opens the connection.

In more detail, this moves the local state of the connection to the ACTIVE state and triggers an open frame to be sent to the peer. A connection is fully active once both peers have opened it.

close()

Closes the connection.

In more detail, this moves the local state of the connection to the CLOSED state and triggers a close frame to be sent to the peer. A connection is fully closed once both peers have closed it.

state

The state of the connection as a bit field. The state has a local and a remote component. Each of these can be in one of three states: UNINIT, ACTIVE or CLOSED. These can be tested by masking against LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, REMOTE_UNINIT, REMOTE_ACTIVE and REMOTE_CLOSED.

session()

Returns a new session on this connection.

hostname
container
remote_container

The container identifier specified by the remote peer for this connection.

remote_desired_capabilities

The capabilities desired by the remote peer for this connection.

remote_hostname

The hostname specified by the remote peer for this connection.

remote_offered_capabilities

The capabilities offered by the remote peer for this connection.

remote_properties

The properties specified by the remote peer for this connection.

class proton.Receiver(impl)

Bases: proton.Link

A link over which messages are received.

flow(n)

Increases the credit issued to the remote sender by the specified number of messages.

recv(limit)
drain(n)
draining()
class proton.Sender(impl)

Bases: proton.Link

A link over which messages are sent.

offered(n)
send(obj, tag=None)

Send specified object over this sender; the object is expected to have a send() method on it that takes the sender and an optional tag as arguments.

Where the object is a Message, this will send the message over this link, creating a new delivery for the purpose.

A representation of an AMQP link, of which there are two concrete implementations, Sender and Receiver.

The source(), target(), remote_source() and remote_target() methods all return an instance of Terminus.

name

Returns the name of the link

state

The state of the link as a bit field. The state has a local and a remote component. Each of these can be in one of three states: UNINIT, ACTIVE or CLOSED. These can be tested by masking against LOCAL_UNINIT, LOCAL_ACTIVE, LOCAL_CLOSED, REMOTE_UNINIT, REMOTE_ACTIVE and REMOTE_CLOSED.

is_sender

Returns true if this link is a sender.

is_receiver

Returns true if this link is a receiver.

credit

The amount of oustanding credit on this link.

queued
session
connection

The connection on which this link was attached.

source

The source of the link as described by the local peer.

target

The target of the link as described by the local peer.

remote_source

The source of the link as described by the remote peer.

remote_target

The target of the link as described by the remote peer.

class proton.Delivery(impl)

Tracks and/or records the delivery of a message over a link.

update(state)

Set the local state of the delivery e.g. ACCEPTED, REJECTED, RELEASED.

settle()

Settles the delivery locally. This indicates the aplication considers the delivery complete and does not wish to receive any further events about it. Every delivery should be settled locally.

settled

Returns true if the delivery has been settled by the remote peer.

remote_state

Returns the state of the delivery as indicated by the remote peer.

local_state

Returns the local state of the delivery.

partial

Returns true for an incoming delivery if not all the data is yet available.

readable

Returns true for an incoming delivery that has data to read.

writable

Returns true for an outgoing delivery to which data can now be written.

Returns the link on which the delivery was sent or received.

session

Returns the session over which the delivery was sent or received.

connection

Returns the connection over which the delivery was sent or received.

class proton.handlers.MessagingHandler(prefetch=10, auto_accept=True, auto_settle=True, peer_close_is_error=False)

A general purpose handler that makes the proton-c events somewhat simpler to deal with and/or avoids repetitive tasks for common use cases.

on_start(event)

Called when the event loop starts. (Just an alias for on_reactor_init)

on_reactor_init(event)

Called when the event loop - the reactor - starts.

on_message(event)

Called when a message is received. The message itself can be obtained as a property on the event. For the purpose of refering to this message in further actions (e.g. if explicitly accepting it, the delivery should be used, also obtainable via a property on the event.

on_accepted(event)

Called when the remote peer accepts an outgoing message.

on_rejected(event)

Called when the remote peer rejects an outgoing message.

on_settled(event)

Called when the remote peer has settled the outgoing message. This is the point at which it shouod never be retransmitted.

on_sendable(event)

Called when the sender link has credit and messages can therefore be transferred.

on_connection_error(event)

Called when the peer closes the connection with an error condition.

Called when the peer closes the link with an error condition.

on_session_error(event)

Called when the peer closes the session with an error condition.

on_disconnected(event)

Called when the socket is disconnected.

accept(delivery)

Accepts a received message.

reject(delivery)

Rejects a received message that is considered invalid or unprocessable.

release(delivery, delivered=True)

Releases a received message, making it available at the source for any (other) interested receiver. The delivered parameter indicates whether this should be considered a delivery attempt (and the delivery count updated) or not.

settle(delivery, state=None)
class proton.Event(impl, number)
delivery

Returns the delivery associated with the event, or null if none is associated with it.

Returns the link associated with the event, or null if none is associated with it.

receiver

Returns the receiver link associated with the event, or null if none is associated with it. This is essentially an alias for link(), that does an additional checkon the type of the link.

sender

Returns the sender link associated with the event, or null if none is associated with it. This is essentially an alias for link(), that does an additional checkon the type of the link.

session

Returns the session associated with the event, or null if none is associated with it.

connection

Returns the connection associated with the event, or null if none is associated with it.

reactor

Returns the reactor associated with the event.

context

Returns the context object associated with the event. The type of this depend on the type of event.

class proton.Message(body=None, **kwargs)

The L{Message} class is a mutable holder of message content.

@ivar instructions: delivery instructions for the message @type instructions: dict @ivar annotations: infrastructure defined message annotations @type annotations: dict @ivar properties: application defined message properties @type properties: dict @ivar body: message body @type body: bytes | unicode | dict | list | int | long | float | UUID

address

The address of the message.

id

The id of the message.

priority

The priority of the message.

subject

The subject of the message.

ttl

The time to live of the message measured in seconds. Expired messages may be dropped.

reply_to

The reply-to address for the message.

correlation_id

The correlation-id for the message.

durable

The durable property indicates that the message should be held durably by any intermediaries taking responsibility for the message.

user_id

The user id of the message creator.

content_type

The content-type of the message.

content_encoding

The content-encoding of the message.

creation_time

The creation time of the message.

expiry_time

The expiry time of the message.

delivery_count

The number of delivery attempts made for this message.

first_acquirer

True iff the recipient is the first to acquire the message.

group_id

The group id of the message.

group_sequence

The sequence of the message within its group.

reply_to_group_id

The group-id for any replies.

send(sender, tag=None)
recv(link)

Receives and decodes the message content for the current delivery from the link. Upon success it will return the current delivery for the link. If there is no current delivery, or if the current delivery is incomplete, or if the link is not a receiver, it will return None.

@type link: Link @param link: the link to receive a message from @return the delivery associated with the decoded message (or None)

encode()
decode(data)
class proton.Terminus(impl)
address

The address that identifies the source or target node

dynamic

Indicates whether the source or target node was dynamically created

properties

Properties of a dynamic source or target.

capabilities

Capabilities of the source or target.

filter

A filter on a source allows the set of messages transfered over the link to be restricted

Delivery guarantees

For at-most-once, the sender settles the message as soon as it sends it. If the connection is lost before the message is received by the receiver, the message will not be delivered.

For at-least-once, the receiver accepts and settles the message on receipt. If the connection is lost before the sender is informed of the settlement, then the delivery is considered in-doubt and should be retried. This will ensure it eventually gets delivered (provided of course the connection and link can be reestablished). It may mean that it is delivered multiple times though.

Finally, for exactly-once, the receiver accepts the message but doesn’t settle it. The sender settles once it is aware that the receiver accepted it. In this way the receiver retains knowledge of an accepted message until it is sure the sender knows it has been accepted. If the connection is lost before settlement, the receiver informs the sender of all the unsettled deliveries it knows about, and from this the sender can deduce which need to be redelivered. The sender likewise informs the receiver which deliveries it knows about, from which the receiver can deduce which have already been settled.