Module proton.handlers

Module Summary

MessagingHandler	A general purpose handler that makes the proton-c events somewhat simpler to deal with and/or avoids repetitive tasks for common use cases.
TransactionHandler	The interface for transaction handlers - ie objects that want to be notified of state changes related to a transaction.
TransactionalClientHandler	An extension to the MessagingHandler for applications using transactions.

Exceptions

Reject	An exception that indicates a message should be rejected.
Release	An exception that indicates a message should be released.

Module Detail

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

Bases: proton._events.Handler, proton._handlers.Acking

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

Parameters:

• prefetch (int) – Initial flow credit for receiving messages, defaults to 10.
• auto_accept (bool) – If True, accept all messages (default). Otherwise messages must be individually accepted or rejected.
• auto_settle (bool) – If True, settle all messages (default). Otherwise messages must be explicitly settled.
• peer_close_is_error (bool) – If True, a peer endpoint closing will be treated as an error with an error callback. Otherwise (default), the normal callbacks for the closing will occur.

accept(delivery)

Accepts a received message.

Note

This method cannot currently be used in combination with transactions. See proton.reactor.Transaction for transactional methods.

Parameters:delivery (proton.Delivery) – The message delivery tracking object

on_accepted(event)

Called when the remote peer accepts an outgoing message.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_connection_closed(event)

Called when the connection is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_connection_closing(event)

Called when the peer initiates the closing of the connection.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_connection_error(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_disconnected(event)

Called when the socket is disconnected.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_link_closed(event)

Called when the link is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_link_closing(event)

Called when the peer initiates the closing of the link.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_link_error(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

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.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event. In particular, the message itself may be obtained by accessing event.message.

on_reactor_init(event)

Called when the event loop - the reactor - starts.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_rejected(event)

Called when the remote peer rejects an outgoing message.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_released(event)

Called when the remote peer releases an outgoing message. Note that this may be in response to either the RELEASE or MODIFIED state as defined by the AMQP specification.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_sendable(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_session_closed(event)

Called when the session is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_session_closing(event)

Called when the peer initiates the closing of the session.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_session_error(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_settled(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_start(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transport_error(event)

Called when some error is encountered with the transport over which the AMQP connection is to be established. This includes authentication errors as well as socket errors.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_unhandled(method, *args)

The callback for handling events which are not handled by any other handler.

Parameters:

• method (str) – The name of the intended handler method.
• args – Arguments for the intended handler method.

reject(delivery)

Rejects a received message that is considered invalid or unprocessable.

Note

This method cannot currently be used in combination with transactions. See proton.reactor.Transaction for transactional methods.

Parameters:delivery (proton.Delivery) – The message delivery tracking object

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.

Note

This method cannot currently be used in combination with transactions. See proton.reactor.Transaction for transactional methods.

Parameters:

• delivery (proton.Delivery) – The message delivery tracking object
• delivered (bool) – If True, the message will be annotated with a delivery attempt (setting delivery flag proton.Delivery.MODIFIED). Otherwise, the message will be returned without the annotation and released (setting delivery flag proton.Delivery.RELEASED

settle(delivery, state=None)

Settles the message delivery, and optionally updating the delivery state.

Parameters:

• delivery (proton.Delivery) – The message delivery tracking object
• state (int or None) – The delivery state, or None if not update is to be performed.

---

class proton.handlers.TransactionHandler

Bases: object

The interface for transaction handlers - ie objects that want to be notified of state changes related to a transaction.

on_transaction_aborted(event)

Called when a local transaction is discharged unsuccessfully (aborted).

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_commit_failed(event)

Called when the commit of a local transaction fails.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_committed(event)

Called when a local transaction is discharged successfully (committed).

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_declare_failed(event)

Called when a local transaction declare fails.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_declared(event)

Called when a local transaction is declared.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event. In particular, the proton.reactor.Transaction object may be obtained by accessing event.transaction.

---

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

Bases: proton._handlers.MessagingHandler, proton._handlers.TransactionHandler

An extension to the MessagingHandler for applications using transactions. This handler provides all of the callbacks found in MessagingHandler and TransactionHandler, and provides a convenience method accept() for performing a transactional acceptance of received messages.

Parameters:

• prefetch (int) – Initial flow credit for receiving messages, defaults to 10.
• auto_accept (bool) – If True, accept all messages (default). Otherwise messages must be individually accepted or rejected.
• auto_settle (bool) – If True, settle all messages (default). Otherwise messages must be explicitly settled.
• peer_close_is_error (bool) – If True, a peer endpoint closing will be treated as an error with an error callback. Otherwise (default), the normal callbacks for the closing will occur.

accept(delivery, transaction=None)

A convenience method for accepting a received message as part of a transaction. If no transaction object is supplied, a regular non-transactional acceptance will be performed.

Parameters:

• delivery (proton.Delivery) – Delivery tracking object for received message.
• transaction (proton.reactor.Transaction) – Transaction tracking object which is required if the message is being accepted under the transaction. If None (default), then a normal non-transactional accept occurs.

on_accepted(event)

Called when the remote peer accepts an outgoing message.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_connection_closed(event)

Called when the connection is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_connection_closing(event)

Called when the peer initiates the closing of the connection.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_connection_error(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_disconnected(event)

Called when the socket is disconnected.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_link_closed(event)

Called when the link is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_link_closing(event)

Called when the peer initiates the closing of the link.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_link_error(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

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.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event. In particular, the message itself may be obtained by accessing event.message.

on_reactor_init(event)

Called when the event loop - the reactor - starts.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_rejected(event)

Called when the remote peer rejects an outgoing message.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_released(event)

Called when the remote peer releases an outgoing message. Note that this may be in response to either the RELEASE or MODIFIED state as defined by the AMQP specification.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_sendable(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_session_closed(event)

Called when the session is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_session_closing(event)

Called when the peer initiates the closing of the session.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_session_error(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_settled(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_start(event)

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

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_aborted(event)

Called when a local transaction is discharged unsuccessfully (aborted).

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_commit_failed(event)

Called when the commit of a local transaction fails.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_committed(event)

Called when a local transaction is discharged successfully (committed).

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_declare_failed(event)

Called when a local transaction declare fails.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_transaction_declared(event)

Called when a local transaction is declared.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event. In particular, the proton.reactor.Transaction object may be obtained by accessing event.transaction.

on_transport_error(event)

Called when some error is encountered with the transport over which the AMQP connection is to be established. This includes authentication errors as well as socket errors.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the event.

on_unhandled(method, *args)

The callback for handling events which are not handled by any other handler.

Parameters:

• method (str) – The name of the intended handler method.
• args – Arguments for the intended handler method.

reject(delivery)

Rejects a received message that is considered invalid or unprocessable.

Note

This method cannot currently be used in combination with transactions. See proton.reactor.Transaction for transactional methods.

Parameters:delivery (proton.Delivery) – The message delivery tracking object

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.

Note

This method cannot currently be used in combination with transactions. See proton.reactor.Transaction for transactional methods.

Parameters:

• delivery (proton.Delivery) – The message delivery tracking object
• delivered (bool) – If True, the message will be annotated with a delivery attempt (setting delivery flag proton.Delivery.MODIFIED). Otherwise, the message will be returned without the annotation and released (setting delivery flag proton.Delivery.RELEASED

settle(delivery, state=None)

Settles the message delivery, and optionally updating the delivery state.

Parameters:

• delivery (proton.Delivery) – The message delivery tracking object
• state (int or None) – The delivery state, or None if not update is to be performed.

---

class proton.handlers.Reject

Bases: proton._exceptions.ProtonException

An exception that indicates a message should be rejected.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

---

class proton.handlers.Release

Bases: proton._exceptions.ProtonException

An exception that indicates a message should be released.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.