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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Called when the socket is disconnected.

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

Called when the link is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the 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.

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.

Called when the link is closed.

Parameters:event (proton.Event) – The underlying event object. Use this to obtain further information on the 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.

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[source]

Bases: proton._exceptions.ProtonException

An exception that indicates a message should be rejected.

args
message

class proton.handlers.Release[source]

Bases: proton._exceptions.ProtonException

An exception that indicates a message should be released.

args
message