ReceiveClient Class
An AMQP client for receiving messages.
- Inheritance
-
ReceiveClient
Constructor
ReceiveClient(source, auth=None, client_name=None, debug=False, timeout=0, auto_complete=True, error_policy=None, **kwargs)Parameters
The source AMQP service endpoint. This can either be the URI as a string or a ~uamqp.address.Source object.
- auth
- AMQPAuth
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.
The name for the client, also known as the Container ID. If no name is provided, a random GUID will be used.
- debug
- bool
Whether to turn on network trace logs. If True, trace logs will be logged at INFO level. Default is False.
- timeout
- float
A timeout in milliseconds. The receiver will shut down if no new messages are received after the specified timeout. If set to 0, the receiver will never timeout and will continue to listen. The default is 0. Set shutdown_after_timeout to False if keeping the receiver open after timeout is needed.
- shutdown_after_timeout
- bool
Whether to automatically shutdown the receiver if no new messages are received after the specified timeout. Default is True.
- auto_complete
- bool
Whether to automatically settle message received via callback or via iterator. If the message has not been explicitly settled after processing the message will be accepted. Alternatively, when used with batch receive, this setting will determine whether the messages are pre-emptively settled during batching, or otherwise let to the user to be explicitly settled.
- error_policy
- ErrorPolicy
A policy for parsing errors on link, connection and message disposition to determine whether the error should be retryable.
- 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.
- send_settle_mode
- SenderSettleMode
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
- ReceiverSettleMode
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
- AMQPValue
The extension capabilities desired from the peer endpoint. To create a desired_capabilities object, please do as follows:
-
- Create an array of desired capability symbols: capabilities_symbol_array = [types.AMQPSymbol(string)]
-
- Transform the array to AMQPValue object: utils.data_factory(types.AMQPArray(capabilities_symbol_array))
- prefetch
- int
The receiver Link credit that determines how many messages the Link will attempt to handle per connection iteration. The default is 300.
- idle_timeout
- int
Timeout in milliseconds after which the Connection will close if there is no further activity.
- remote_idle_timeout_empty_frame_send_ratio
- float
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.
- on_attach
- <xref:func>[Source, Target, dict, AMQPConnectionError]
A callback function to be run on receipt of an ATTACH frame. The function must take 4 arguments: source, target, properties and error.
Methods
| receive_message_batch |
Receive a batch of messages. Messages returned in the batch have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback. This method will return as soon as some messages are available rather than waiting to achieve a specific batch size, and therefore the number of messages returned per call will vary up to the maximum allowed. If the receive client is configured with auto_complete=True then the messages received in the batch returned by this function will already be settled. Alternatively, if auto_complete=False, then each message will need to be explicitly settled before it expires and is released. |
| receive_messages |
Receive messages. This function will run indefinitely, until the client closes either via timeout, error or forced interruption (e.g. keyboard interrupt). If the receive client is configured with auto_complete=True then the messages that have not been settled on completion of the provided callback will automatically be accepted provided it has not expired. If an error occurs or the message has expired it will be released. Alternatively if auto_complete=False, each message will need to be explicitly settled during the callback, otherwise it will be released. |
| receive_messages_iter |
Receive messages by generator. Messages returned in the generator have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback. |
| redirect |
Redirect the client endpoint using a Link DETACH redirect response. |
receive_message_batch
Receive a batch of messages. Messages returned in the batch have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback. This method will return as soon as some messages are available rather than waiting to achieve a specific batch size, and therefore the number of messages returned per call will vary up to the maximum allowed.
If the receive client is configured with auto_complete=True then the messages received in the batch returned by this function will already be settled. Alternatively, if auto_complete=False, then each message will need to be explicitly settled before it expires and is released.
receive_message_batch(max_batch_size=None, on_message_received=None, timeout=0)Parameters
- max_batch_size
- int
The maximum number of messages that can be returned in one call. This value cannot be larger than the prefetch value, and if not specified, the prefetch value will be used.
A callback to process messages as they arrive from the service. It takes a single argument, a ~uamqp.message.Message object.
- timeout
- float
I timeout in milliseconds for which to wait to receive any messages. If no messages are received in this time, an empty list will be returned. If set to 0, the client will continue to wait until at least one message is received. The default is 0.
receive_messages
Receive messages. This function will run indefinitely, until the client closes either via timeout, error or forced interruption (e.g. keyboard interrupt).
If the receive client is configured with auto_complete=True then the messages that have not been settled on completion of the provided callback will automatically be accepted provided it has not expired. If an error occurs or the message has expired it will be released. Alternatively if auto_complete=False, each message will need to be explicitly settled during the callback, otherwise it will be released.
receive_messages(on_message_received)Parameters
receive_messages_iter
Receive messages by generator. Messages returned in the generator have already been accepted - if you wish to add logic to accept or reject messages based on custom criteria, pass in a callback.
receive_messages_iter(on_message_received=None)Parameters
redirect
Redirect the client endpoint using a Link DETACH redirect response.
redirect(redirect, auth)Parameters
Feedback
Submit and view feedback for