Module proton.utils

Module Summary


BlockingConnection

A synchronous style connection wrapper.

BlockingSender

A synchronous sender wrapper.

BlockingReceiver

A synchronous receiver wrapper.

SyncRequestResponse

Implementation of the synchronous request-response (aka RPC) pattern.


Exceptions


SendException

Exception used to indicate an exceptional state/condition on a send request.

LinkDetached

The exception raised when the remote peer unexpectedly closes a link in a blocking context, or an unexpected link error occurs.

ConnectionClosed

The exception raised when the remote peer unexpectedly closes a connection in a blocking context, or an unexpected connection error occurs.


Module Detail


class proton.utils.BlockingConnection(url, timeout=None, container=None, ssl_domain=None, heartbeat=None, **kwargs)[source]

Bases: proton._events.Handler

A synchronous style connection wrapper.

This object’s implementation uses OS resources. To ensure they are released when the object is no longer in use, make sure that object operations are enclosed in a try block and that close() is always executed on exit.

Parameters
  • url (proton.Url or str) – Connection URL

  • timeout (None or float) – Connection timeout in seconds. If None, defaults to 60 seconds.

  • container – Container to process the events on the connection. If None, a new proton.Container will be created.

  • ssl_domain

  • heartbeat (float) – A value in seconds indicating the desired frequency of heartbeats used to test the underlying socket is alive.

  • kwargs – Container keyword arguments. See proton.reactor.Container for a list of the valid kwargs.

add(handler, on_error=None)

Add a child handler

Parameters
  • handler (Handler or one of its derivatives.) – A child handler

  • on_error – Not used

close()[source]

Close the connection.

create_receiver(address, credit=None, dynamic=False, handler=None, name=None, options=None)[source]

Create a blocking receiver.

Parameters
  • address (str) – Address of source node.

  • credit (int) – Initial link flow credit. If not set, will default to 1.

  • dynamic (bool) – If True, indicates dynamic creation of the receiver.

  • handler (Any child class of proton.Handler) – Event handler for this receiver.

  • name (str) – Receiver name.

  • options (ReceiverOption or [ReceiverOption, ReceiverOption, …]) – A single option, or a list of receiver options

Returns

New blocking receiver instance.

Return type

BlockingReceiver

create_sender(address, handler=None, name=None, options=None)[source]

Create a blocking sender.

Parameters
  • address (str) – Address of target node.

  • handler (Any child class of proton.Handler) – Event handler for this sender.

  • name (str) – Sender name.

  • options (SenderOption or [SenderOption, SenderOption, …]) – A single option, or a list of sender options

Returns

New blocking sender instance.

Return type

BlockingSender

handlers
on_connection_remote_close(event)[source]

Event callback for when the link peer closes the connection.

Event callback for when the remote terminus closes.

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.

run()[source]

Hand control over to the event loop (e.g. if waiting indefinitely for incoming messages)

wait(condition, timeout=False, msg=None)[source]

Process events until condition() returns True.

Parameters
  • condition (Function which returns bool) – Condition which determines when the wait will end.

  • timeout (None, False, float) – Timeout in seconds. If False, the value of timeout used in the constructor of this object will be used. If None, there is no timeout. Any other value is treated as a timeout in seconds.

  • msg (str) – Context message for proton.Timeout exception


class proton.utils.BlockingSender(connection, sender)[source]

Bases: proton._utils.BlockingLink

A synchronous sender wrapper. This is typically created by calling BlockingConnection.create_sender().

close()

Close the link.

send(msg, timeout=False, error_states=None)[source]

Blocking send which will return only when the send is complete and the message settled.

Parameters
  • timeout (None, False, float) – Timeout in seconds. If False, the value of timeout used in the constructor of the BlockingConnection object used in the constructor will be used. If None, there is no timeout. Any other value is treated as a timeout in seconds.

  • error_states (list) – List of delivery flags which when present in Delivery object will cause a SendException exception to be raised. If None, these will default to a list containing proton.Delivery.REJECTED and proton.Delivery.RELEASED.

Returns

Delivery object for this message.

Return type

proton.Delivery


class proton.utils.BlockingReceiver(connection, receiver, fetcher, credit=1)[source]

Bases: proton._utils.BlockingLink

A synchronous receiver wrapper. This is typically created by calling BlockingConnection.create_receiver().

accept()[source]

Accept and settle the received message. The delivery is set to proton.Delivery.ACCEPTED.

close()

Close the link.

receive(timeout=False)[source]

Blocking receive call which will return only when a message is received or a timeout (if supplied) occurs.

Parameters

timeout (None, False, float) – Timeout in seconds. If False, the value of timeout used in the constructor of the BlockingConnection object used in the constructor will be used. If None, there is no timeout. Any other value is treated as a timeout in seconds.

reject()[source]

Reject the received message. The delivery is set to proton.Delivery.REJECTED.

release(delivered=True)[source]

Release the received message.

Parameters

delivered (bool) – If True, the message delivery is being set to proton.Delivery.MODIFIED, ie being returned to the sender and annotated. If False, the message is returned without annotations and the delivery set to proton.Delivery.RELEASED.

settle(state=None)[source]

Settle any received messages.

Parameters

state (None or a valid delivery state (see proton.Delivery.) – Update the delivery of all unsettled messages with the supplied state, then settle them.


class proton.utils.ConnectionClosed(connection)[source]

Bases: proton._exceptions.ConnectionException

The exception raised when the remote peer unexpectedly closes a connection in a blocking context, or an unexpected connection error occurs.

Parameters

connection (proton.Connection) – The connection which closed unexpectedly.


class proton.utils.LinkDetached(link)[source]

Bases: proton._exceptions.LinkException

The exception raised when the remote peer unexpectedly closes a link in a blocking context, or an unexpected link error occurs.

Parameters

link (proton.Link) – The link which closed unexpectedly.


class proton.utils.SendException(state)[source]

Bases: proton._exceptions.ProtonException

Exception used to indicate an exceptional state/condition on a send request.

Parameters

state (int) – The delivery state which caused the exception.


class proton.utils.SyncRequestResponse(connection, address=None)[source]

Bases: proton._handlers.IncomingMessageHandler

Implementation of the synchronous request-response (aka RPC) pattern. A single instance can send many requests to the same or different addresses.

Parameters
  • connection (BlockingConnection) – Connection for requests and responses.

  • address (str or None) – Address for all requests. If not specified, each request must have the address property set. Successive messages may have different addresses.

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

add(handler, on_error=None)

Add a child handler

Parameters
  • handler (Handler or one of its derivatives.) – A child handler

  • on_error – Not used

call(request)[source]

Send a request message, wait for and return the response message.

Parameters

request (proton.Message) – Request message. If self.address is not set the request message address must be set and will be used.

correlation_id = <proton._utils.AtomicCount object>
handlers
on_aborted(event)

Callback for when a message delivery is aborted by the remote peer.

Parameters

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

on_delivery(event)
on_message(event)[source]

Called when we receive a message for our receiver.

Parameters

event (proton.Event) – The event which occurs when a message is received.

on_settled(event)

Callback for when a message delivery is settled by the remote peer.

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

property reply_to

The dynamic address of our receiver.

Type

str

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.