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. |
Module Detail¶
-
class
proton.handlers.
MessagingHandler
(prefetch: int = 10, auto_accept: bool = True, auto_settle: bool = True, peer_close_is_error: bool = 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 – 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
, settle all messages (default). 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: proton._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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[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 – 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[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 – The underlying event object. Use this to obtain further information on the event.
-
on_sendable
(event: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[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 – 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: proton._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: proton._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 flagproton.Delivery.MODIFIED
). Otherwise, the message will be returned without the annotation and released (setting delivery flagproton.Delivery.RELEASED
-
settle
(delivery: proton._delivery.Delivery, state: Union[_ForwardRef('DispositionType'), NoneType] = 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
[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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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: proton._events.Event) → None[source]¶ 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 accessingevent.transaction
.
-
-
class
proton.handlers.
TransactionalClientHandler
(prefetch: int = 10, auto_accept: bool = False, auto_settle: bool = True, peer_close_is_error: bool = 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
andTransactionHandler
, and provides a convenience methodaccept()
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 (default). Otherwise messages must be individually accepted or rejected. - auto_settle – If
True
, settle all messages (default). 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: proton._delivery.Delivery, transaction: Union[_ForwardRef('Transaction'), NoneType] = 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 – 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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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: proton._events.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 accessingevent.transaction
.
-
on_transport_error
(event: proton._events.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: proton._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: proton._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 flagproton.Delivery.MODIFIED
). Otherwise, the message will be returned without the annotation and released (setting delivery flagproton.Delivery.RELEASED
-
settle
(delivery: proton._delivery.Delivery, state: Union[_ForwardRef('DispositionType'), NoneType] = 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
[source]¶ 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.
-