SendClient Class

An AMQP client for sending messages.

Inheritance
SendClient

Constructor

SendClient(target, auth=None, client_name=None, debug=False, msg_timeout=0, error_policy=None, keep_alive_interval=None, **kwargs)

Parameters

Name Description
target
Required

The target AMQP service endpoint. This can either be the URI as a string or a ~uamqp.address.Target object.

auth

Authentication for the connection. This should be one of the subclasses of uamqp.authentication.AMQPAuth. Currently this includes:

  • uamqp.authentication.SASLAnonymous

  • uamqp.authentication.SASLPlain

  • uamqp.authentication.SASTokenAuth

  • uamqp.authentication.JWTTokenAuth

If no authentication is supplied, SASLAnnoymous will be used by default.

Default value: None
client_name
str or bytes

The name for the client, also known as the Container ID. If no name is provided, a random GUID will be used.

Default value: None
debug

Whether to turn on network trace logs. If True, trace logs will be logged at INFO level. Default is False.

Default value: False
msg_timeout
int

A timeout in milliseconds for messages from when they have been added to the send queue to when the message is actually sent. This prevents potentially expired data from being sent. If set to 0, messages will not expire. Default is 0.

Default value: 0
error_policy

A policy for parsing errors on link, connection and message disposition to determine whether the error should be retryable.

Default value: None
keep_alive_interval
int

If set, a thread will be started to keep the connection alive during periods of user inactivity. The value will determine how long the thread will sleep (in seconds) between pinging the connection. If 0 or None, no thread will be started.

Default value: None
send_settle_mode
Required

The mode by which to settle message send operations. If set to Unsettled, the client will wait for a confirmation from the service that the message was successfully sent. If set to 'Settled', the client will not wait for confirmation and assume success.

receive_settle_mode
Required

The mode by which to settle message receive operations. If set to PeekLock, the receiver will lock a message once received until the client accepts or rejects the message. If set to ReceiveAndDelete, the service will assume successful receipt of the message and clear it from the queue. The default is PeekLock.

desired_capabilities
Required

The extension capabilities desired from the peer endpoint. To create a desired_capabilities object, please do as follows:

    1. Create an array of desired capability symbols: capabilities_symbol_array = [types.AMQPSymbol(string)]
    1. Transform the array to AMQPValue object: utils.data_factory(types.AMQPArray(capabilities_symbol_array))
max_message_size
Required
int

The maximum allowed message size negotiated for the Link.

link_properties
Required

Metadata to be sent in the Link ATTACH frame.

link_credit
Required
int

The sender Link credit that determines how many messages the Link will attempt to handle per connection iteration.

max_frame_size
Required
int

Maximum AMQP frame size. Default is 63488 bytes.

channel_max
Required
int

Maximum number of Session channels in the Connection.

idle_timeout
Required
int

Timeout in milliseconds after which the Connection will close if there is no further activity.

properties
Required

Connection properties.

remote_idle_timeout_empty_frame_send_ratio
Required

Ratio of empty frames to idle time for Connections with no activity. Value must be between 0.0 and 1.0 inclusive. Default is 0.5.

incoming_window
Required
int

The size of the allowed window for incoming messages.

outgoing_window
Required
int

The size of the allowed window for outgoing messages.

handle_max
Required
int

The maximum number of concurrent link handles.

on_attach
Required

A callback function to be run on receipt of an ATTACH frame. The function must take 4 arguments: source, target, properties and error.

encoding
Required
str

The encoding to use for parameters supplied as strings. Default is 'UTF-8'

Methods

auth_complete

Whether the authentication handshake is complete during connection initialization.

client_ready

Whether the handler has completed all start up processes such as establishing the connection, session, link and authentication, and is not ready to process messages.

close

Close the client. This includes closing the Session and CBS authentication layer as well as the Connection. If the client was opened using an external Connection, this will be left intact.

No further messages can be sent or received and the client cannot be re-opened.

All pending, unsent messages will remain uncleared to allow them to be inspected and queued to a new client.

do_work

Run a single connection iteration. This will return True if the connection is still open and ready to be used for further work, or False if it needs to be shut down.

messages_pending

Check whether the client is holding any unsent messages in the queue.

mgmt_request

Run a request/response operation. These are frequently used for management tasks against a $management node, however any node name can be specified and the available options will depend on the target service.

open

Open the client. The client can create a new Connection or an existing Connection can be passed in. This existing Connection may have an existing CBS authentication Session, which will be used for this client as well. Otherwise a new Session will be created.

queue_message

Add one or more messages to the send queue. No further action will be taken until either SendClient.wait() or SendClient.send_all_messages() has been called. The client does not need to be open yet for messages to be added to the queue. Multiple messages can be queued at once:

  • send_client.queue_message(my_message)

  • send_client.queue_message(message_1, message_2, message_3)

  • *send_client.queue_message(my_message_list)

redirect

Redirect the client endpoint using a Link DETACH redirect response.

send_all_messages

Send all pending messages in the queue. This will return a list of the send result of all the pending messages so it can be determined if any messages failed to send. This function will open the client if it is not already open.

send_message

Send a single message or batched message.

wait

Run the client until all pending message in the queue have been processed. Returns whether the client is still running after the messages have been processed, or whether a shutdown has been initiated.

auth_complete

Whether the authentication handshake is complete during connection initialization.

auth_complete()

Returns

Type Description

client_ready

Whether the handler has completed all start up processes such as establishing the connection, session, link and authentication, and is not ready to process messages.

client_ready()

Returns

Type Description

close

Close the client. This includes closing the Session and CBS authentication layer as well as the Connection. If the client was opened using an external Connection, this will be left intact.

No further messages can be sent or received and the client cannot be re-opened.

All pending, unsent messages will remain uncleared to allow them to be inspected and queued to a new client.

close()

do_work

Run a single connection iteration. This will return True if the connection is still open and ready to be used for further work, or False if it needs to be shut down.

do_work(**kwargs)

Returns

Type Description

Exceptions

Type Description
TimeoutError or uamqp.errors.ClientTimeout if CBS authentication timeout reached.

messages_pending

Check whether the client is holding any unsent messages in the queue.

messages_pending()

Returns

Type Description

mgmt_request

Run a request/response operation. These are frequently used for management tasks against a $management node, however any node name can be specified and the available options will depend on the target service.

mgmt_request(message, operation, op_type=None, node=None, callback=None, **kwargs)

Parameters

Name Description
message
Required

The message to send in the management request.

operation
Required

The type of operation to be performed. This value will be service-specific, but common values include READ, CREATE and UPDATE. This value will be added as an application property on the message.

op_type

The type on which to carry out the operation. This will be specific to the entities of the service. This value will be added as an application property on the message.

Default value: None
node

The target node. Default is b"$management".

Default value: None
timeout
Required

Provide an optional timeout in milliseconds within which a response to the management request must be received.

callback

The function to process the returned parameters of the management request including status code and a description if available. This can be used to reformat the response or raise an error based on content. The function must take 3 arguments - status code, response message and description.

Default value: None
status_code_field
Required

Provide an alternate name for the status code in the response body which can vary between services due to the spec still being in draft. The default is b"statusCode".

description_fields
Required

Provide an alternate name for the description in the response body which can vary between services due to the spec still being in draft. The default is b"statusDescription".

Returns

Type Description

open

Open the client. The client can create a new Connection or an existing Connection can be passed in. This existing Connection may have an existing CBS authentication Session, which will be used for this client as well. Otherwise a new Session will be created.

open(connection=None)

Parameters

Name Description
connection

An existing Connection that may be shared between multiple clients.

Default value: None

queue_message

Add one or more messages to the send queue. No further action will be taken until either SendClient.wait() or SendClient.send_all_messages() has been called. The client does not need to be open yet for messages to be added to the queue. Multiple messages can be queued at once:

  • send_client.queue_message(my_message)

  • send_client.queue_message(message_1, message_2, message_3)

  • *send_client.queue_message(my_message_list)

queue_message(*messages)

Parameters

Name Description
messages
Required

A message to send. This can either be a single instance of Message, or multiple messages wrapped in an instance of BatchMessage.

redirect

Redirect the client endpoint using a Link DETACH redirect response.

redirect(redirect, auth)

Parameters

Name Description
redirect
Required

The Link DETACH redirect details.

auth
Required

Authentication credentials to the redirected endpoint.

send_all_messages

Send all pending messages in the queue. This will return a list of the send result of all the pending messages so it can be determined if any messages failed to send. This function will open the client if it is not already open.

send_all_messages(close_on_done=True)

Parameters

Name Description
close_on_done

Close the client once the messages are sent. Default is True.

Default value: True

Returns

Type Description

send_message

Send a single message or batched message.

send_message(messages, close_on_done=False)

Parameters

Name Description
messages
Required

A message to send. This can either be a single instance of Message, or multiple messages wrapped in an instance of BatchMessage.

close_on_done

Close the client once the message is sent. Default is False.

Default value: False

Exceptions

Type Description
uamqp.errors.MessageException if message fails to send after retry policyis exhausted.

wait

Run the client until all pending message in the queue have been processed. Returns whether the client is still running after the messages have been processed, or whether a shutdown has been initiated.

wait()

Returns

Type Description

Attributes

pending_messages