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: int = 10, auto_accept: bool = True, auto_settle: bool = True, peer_close_is_error: bool = False)

Bases: Handler, 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 – Initial flow credit for receiving messages, defaults to 10.

• auto_accept – If True, accept all messages (default). Otherwise messages must be individually accepted or rejected.

• auto_settle – If True (default), automatically settle messages upon receiving a settled disposition for that delivery. Otherwise messages must be explicitly settled.

• peer_close_is_error – 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: Delivery) → None

Accepts a received message.

Note

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

Parameters:

delivery – The message delivery tracking object

on_accepted(event: Event) → None

Called when the remote peer accepts an outgoing message.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_connection_closed(event: Event) → None

Called when the connection is closed.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_connection_closing(event: Event) → None

Called when the peer initiates the closing of the connection.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_connection_error(event: Event) → None

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: Event) → None

Called when the socket is disconnected.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_link_closed(event: Event) → None

Called when the link is closed.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_link_closing(event: Event) → None

Called when the peer initiates the closing of the link.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_link_error(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_message(event: Event) → None

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 – 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: Event) → None

Called when the event loop - the reactor - starts.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_rejected(event: Event) → None

Called when the remote peer rejects an outgoing message.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_released(event: Event) → None

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 – The underlying event object. Use this to obtain further information on the event.

on_sendable(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_session_closed(event: Event) → None

Called when the session is closed.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_session_closing(event: Event) → None

Called when the peer initiates the closing of the session.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_session_error(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_settled(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_start(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transport_error(event: Event) → None

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 – The underlying event object. Use this to obtain further information on the event.

on_unhandled(method: str, *args) → None

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

Parameters:

• method – The name of the intended handler method.

• args – Arguments for the intended handler method.

reject(delivery: Delivery) → None

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 – The message delivery tracking object

release(delivery: Delivery, delivered: bool = True) → None

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 – The message delivery tracking object

• delivered – 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: Delivery, state: DispositionType | None = None) → None

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

Parameters:

• delivery – The message delivery tracking object

• state – The delivery state, or None if no 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: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_commit_failed(event: Event) → None

Called when the commit of a local transaction fails.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_committed(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_declare_failed(event: Event) → None

Called when a local transaction declare fails.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_declared(event: Event) → None

Called when a local transaction is declared.

Parameters:

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: int = 10, auto_accept: bool = False, auto_settle: bool = True, peer_close_is_error: bool = False)

Bases: MessagingHandler, 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 – Initial flow credit for receiving messages, defaults to 10.

• auto_accept – If True, accept all messages. Otherwise (default), messages must be individually accepted or rejected.

• auto_settle – If True (default), automatically settle messages upon receiving a settled disposition for that delivery. Otherwise messages must be explicitly settled.

• peer_close_is_error – 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: Delivery, transaction: Transaction | None = 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 – Delivery tracking object for received message.

• 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: Event) → None

Called when the remote peer accepts an outgoing message.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_connection_closed(event: Event) → None

Called when the connection is closed.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_connection_closing(event: Event) → None

Called when the peer initiates the closing of the connection.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_connection_error(event: Event) → None

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: Event) → None

Called when the socket is disconnected.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_link_closed(event: Event) → None

Called when the link is closed.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_link_closing(event: Event) → None

Called when the peer initiates the closing of the link.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_link_error(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_message(event: Event) → None

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 – 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: Event) → None

Called when the event loop - the reactor - starts.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_rejected(event: Event) → None

Called when the remote peer rejects an outgoing message.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_released(event: Event) → None

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 – The underlying event object. Use this to obtain further information on the event.

on_sendable(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_session_closed(event: Event) → None

Called when the session is closed.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_session_closing(event: Event) → None

Called when the peer initiates the closing of the session.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_session_error(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_settled(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_start(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_aborted(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_commit_failed(event: Event) → None

Called when the commit of a local transaction fails.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_committed(event: Event) → None

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

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_declare_failed(event: Event) → None

Called when a local transaction declare fails.

Parameters:

event – The underlying event object. Use this to obtain further information on the event.

on_transaction_declared(event: Event) → None

Called when a local transaction is declared.

Parameters:

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: Event) → None

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 – The underlying event object. Use this to obtain further information on the event.

on_unhandled(method: str, *args) → None

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

Parameters:

• method – The name of the intended handler method.

• args – Arguments for the intended handler method.

reject(delivery: Delivery) → None

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 – The message delivery tracking object

release(delivery: Delivery, delivered: bool = True) → None

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 – The message delivery tracking object

• delivered – 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: Delivery, state: DispositionType | None = None) → None

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

Parameters:

• delivery – The message delivery tracking object

• state – The delivery state, or None if no update is to be performed.

---

class proton.handlers.Reject

Bases: ProtonException

An exception that indicates a message should be rejected.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

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

---

class proton.handlers.Release

Bases: ProtonException

An exception that indicates a message should be released.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

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