Module proton.handlers
¶
Module Summary¶
A general purpose handler that makes the proton-c events somewhat simpler to deal with and/or avoids repetitive tasks for common use cases. |
|
The interface for transaction handlers - ie objects that want to be notified of state changes related to a transaction. |
|
An extension to the MessagingHandler for applications using transactions. |
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
) – IfTrue
, accept all messages (default). Otherwise messages must be individually accepted or rejected.auto_settle (
bool
) – IfTrue
, settle all messages (default). Otherwise messages must be explicitly settled.peer_close_is_error (
bool
) – IfTrue
, 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.
-
on_link_closed
(event)[source]¶ 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)[source]¶ 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)[source]¶ 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 accessingevent.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 objectdelivered (
bool
) – IfTrue
, 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, state=None)¶ Settles the message delivery, and optionally updating the delivery state.
- Parameters
delivery (
proton.Delivery
) – The message delivery tracking objectstate (
int
orNone
) – The delivery state, orNone
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, theproton.reactor.Transaction
object may be obtained by accessingevent.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
andTransactionHandler
, and provides a convenience methodaccept()
for performing a transactional acceptance of received messages.- Parameters
prefetch (
int
) – Initial flow credit for receiving messages, defaults to 10.auto_accept (
bool
) – IfTrue
, accept all messages (default). Otherwise messages must be individually accepted or rejected.auto_settle (
bool
) – IfTrue
, settle all messages (default). Otherwise messages must be explicitly settled.peer_close_is_error (
bool
) – IfTrue
, 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. IfNone
(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 accessingevent.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, theproton.reactor.Transaction
object may be obtained by accessingevent.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 objectdelivered (
bool
) – IfTrue
, 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, state=None)¶ Settles the message delivery, and optionally updating the delivery state.
- Parameters
delivery (
proton.Delivery
) – The message delivery tracking objectstate (
int
orNone
) – The delivery state, orNone
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
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-