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. |
Exceptions¶
An exception that indicates a message should be rejected. |
|
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
) – 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.
- class proton.handlers.Release[source]¶
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.