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: str | Url | None = None, timeout: float | None = None, container: Container | None = None, ssl_domain: SSLDomain | None = None, heartbeat: float | None = None, urls: List[str] | None = None, reconnect: None | Literal[False] | Backoff = None, **kwargs)

Bases: 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 – The connection URL.

• timeout – 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 – A value in seconds indicating the desired frequency of heartbeats used to test the underlying socket is alive.

• urls – A list of connection URLs to try to connect to.

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

add(handler: Any, on_error: Callable[[Tuple[Type[BaseException], BaseException, TracebackType]], None] | None = None) → None

Add a child handler

Parameters:

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

• on_error – Not used

close() → None

Close the connection.

create_receiver(address: str | None = None, credit: int | None = None, dynamic: bool = False, handler: Handler | None = None, name: str | None = None, options: ReceiverOption | List[ReceiverOption] | LinkOption | List[LinkOption] | None = None) → BlockingReceiver

Create a blocking receiver.

Parameters:

• address – Address of source node.

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

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

• handler – Event handler for this receiver.

• name – Receiver name.

• options – A single option, or a list of receiver options

Returns:

New blocking receiver instance.

create_sender(address: str | None, handler: Handler | None = None, name: str | None = None, options: SenderOption | List[SenderOption] | LinkOption | List[LinkOption] | None = None) → BlockingSender

Create a blocking sender.

Parameters:

• address – Address of target node.

• handler – Event handler for this sender.

• name – Sender name.

• options – A single option, or a list of sender options

Returns:

New blocking sender instance.

handlers

on_connection_remote_close(event: Event) → None

Event callback for when the link peer closes the connection.

on_link_remote_close(event: Event) → None

Event callback for when the remote terminus closes.

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.

run() → None

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

property url: str

The address for this connection.

wait(condition: Callable[[], bool], timeout: None | Literal[False] | float = False, msg: str | None = None) → None

Process events until condition() returns True.

Parameters:

• condition – Condition which determines when the wait will end.

• timeout – 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 – Context message for proton.Timeout exception

---

class proton.utils.BlockingSender(connection: BlockingConnection, sender: Sender)

Bases: BlockingLink

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

close()

Close the link.

send(msg: Message, timeout: None | Literal[False] | float = False, error_states: List[DispositionType] | None = None) → Delivery

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

Parameters:

• timeout – 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 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.

---

class proton.utils.BlockingReceiver(connection: BlockingConnection, receiver: Receiver, fetcher: Fetcher | None, credit: int = 1)

Bases: BlockingLink

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

accept() → None

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

close()

Close the link.

receive(timeout: None | Literal[False] | float = False) → Message

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

Parameters:

timeout – 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() → None

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

release(delivered: bool = True) → None

Release the received message.

Parameters:

delivered – 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: DispositionType | None = None)

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: Connection)

Bases: ConnectionException

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

Parameters:

connection – The connection which closed unexpectedly.

add_note()

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

---

class proton.utils.LinkDetached(link: Link)

Bases: LinkException

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

Parameters:

link – The link which closed unexpectedly.

add_note()

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

---

class proton.utils.SendException(state: int)

Bases: ProtonException

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

Parameters:

state – The delivery state which caused the exception.

add_note()

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

---

class proton.utils.SyncRequestResponse(connection: BlockingConnection, address: str | None = None)

Bases: 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 – Connection for requests and responses.

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

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

add(handler: Any, on_error: Callable[[Tuple[Type[BaseException], BaseException, TracebackType]], None] | None = None) → None

Add a child handler

Parameters:

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

• on_error – Not used

call(request: Message) → Message

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

Parameters:

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

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

Parameters:

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

on_delivery(event: Event) → None

on_message(event: Event) → None

Called when we receive a message for our receiver.

Parameters:

event – The event which occurs when a message is received.

on_settled(event: Event)

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

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

property reply_to: str

The dynamic address of our receiver.

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.