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 appropriate 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 excessive 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 loosely 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 ofConnection
, thecreate_receiver()
method returns an instance ofReceiver
and thecreate_sender()
method returns an instance ofSender
.-
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: Reconnect is enabled by default. You can pass in an instance of Backoff to control reconnect behavior. A value of False will prevent the library from 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 string specifying the SASL mechanisms allowed for this connection; the value is a space-separated list of mechanism names; the mechanisms allowed by default are determined by your SASL library and system configuration, with two exceptions: GSSAPI and GSS-SPNEGO are disabled by default; to enable them, you must explicitly add them using this option; clients must set the allowed mechanisms before the the outgoing connection is attempted; servers must set them before the listening connection is setup. ‘allow_insecure_mechs’, a flag indicating whether insecure mechanisms, such as PLAIN over a non-encrypted socket, are allowed. ‘virtual_host’, the hostname to set in the Open performative used by peer to determine the correct back-end service for the client; if ‘virtual_host’ is not supplied the host field from the URL is used instead. ‘user’, the user to authenticate. ‘password’, the authentication secret.
-
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 established 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 established 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
-
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.
-
container
¶
-
hostname
¶ Set the name of the host (either fully qualified or relative) to which this connection is connecting to. This information may be used by the remote peer to determine the correct back-end service to connect the client to. This value will be sent in the Open performative, and will be used by SSL and SASL layers to identify the peer.
-
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.
-
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.
-
session
()¶ Returns a new session on this connection.
-
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.
-
-
class
proton.
Receiver
(impl)¶ Bases:
proton._endpoints.Link
A link over which messages are received.
-
drain
(n)¶
-
draining
()¶
-
flow
(n)¶ Increases the credit issued to the remote sender by the specified number of messages.
-
recv
(limit)¶
-
-
class
proton.
Sender
(impl)¶ Bases:
proton._endpoints.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.
-
-
class
proton.
Link
(impl)¶ A representation of an AMQP link, of which there are two concrete implementations, Sender and Receiver.
The
source()
,target()
,remote_source()
andremote_target()
methods all return an instance ofTerminus
.-
connection
¶ The connection on which this link was attached.
-
credit
¶ The amount of outstanding credit on this link.
-
is_receiver
¶ Returns true if this link is a receiver.
-
is_sender
¶ Returns true if this link is a sender.
-
name
¶ Returns the name of the link
-
queued
¶
-
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.
-
session
¶
-
source
¶ The source of the link as described by the local peer.
-
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.
-
target
¶ The target of the link as described by the local peer.
-
-
class
proton.
Delivery
(impl)¶ Tracks and/or records the delivery of a message over a link.
-
connection
¶ Returns the connection over which the delivery was sent or received.
-
link
¶ Returns the link on which the delivery was sent or received.
-
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.
-
remote_state
¶ Returns the state of the delivery as indicated by the remote peer.
-
session
¶ Returns the session over which the delivery was sent or received.
-
settle
()¶ Settles the delivery locally. This indicates the application 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.
-
update
(state)¶ Set the local state of the delivery e.g. ACCEPTED, REJECTED, RELEASED.
-
writable
¶ Returns true for an outgoing delivery to which data can now be written.
-
-
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.
-
accept
(delivery)¶ Accepts a received message.
Note that this method cannot currently be used in combination with transactions.
-
on_accepted
(event)¶ Called when the remote peer accepts an outgoing message.
-
on_connection_error
(event)¶ Called when the peer closes the connection with an error condition.
-
on_disconnected
(event)¶ Called when the socket is disconnected.
-
on_link_error
(event)¶ Called when the peer closes the link with an error condition.
-
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 referring 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_reactor_init
(event)¶ Called when the event loop - the reactor - starts.
-
on_rejected
(event)¶ Called when the remote peer rejects an outgoing message.
-
on_sendable
(event)¶ Called when the sender link has credit and messages can therefore be transferred.
-
on_session_error
(event)¶ Called when the peer closes the session with an error condition.
-
on_settled
(event)¶ Called when the remote peer has settled the outgoing message. This is the point at which it should never be retransmitted.
-
on_start
(event)¶ Called when the event loop starts. (Just an alias for on_reactor_init)
-
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)¶ -
connection
¶ Returns the connection associated with the event, or null if none is associated with it.
-
context
¶ Returns the context object associated with the event. The type of this depend on the type of event.
-
delivery
¶ Returns the delivery associated with the event, or null if none is associated with it.
-
link
¶ Returns the link associated with the event, or null if none is associated with it.
-
reactor
¶ Returns the reactor associated with the event.
-
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.
-
-
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.
-
content_encoding
¶ The content-encoding of the message.
-
content_type
¶ The content-type of the message.
-
correlation_id
¶ The correlation-id for the message.
-
creation_time
¶ The creation time of the message.
-
decode
(data)¶
-
delivery_count
¶ The number of delivery attempts made for this message.
-
durable
¶ The durable property indicates that the message should be held durably by any intermediaries taking responsibility for the message.
-
encode
()¶
-
expiry_time
¶ The expiry time of the 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.
-
id
¶ The id of the message.
-
priority
¶ The priority of the message.
-
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)
-
reply_to
¶ The reply-to address for the message.
-
reply_to_group_id
¶ The group-id for any replies.
-
send
(sender, tag=None)¶
-
subject
¶ The subject of the message.
-
ttl
¶ The time to live of the message measured in seconds. Expired messages may be dropped.
-
user_id
¶ The user id of the message creator.
-
-
class
proton.
Terminus
(impl)¶ -
address
¶ The address that identifies the source or target node
-
capabilities
¶ Capabilities of the source or target.
-
dynamic
¶ Indicates whether the source or target node was dynamically created
-
filter
¶ A filter on a source allows the set of messages transfered over the link to be restricted
-
properties
¶ Properties of a dynamic source or target.
-
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.