Share via

BatchMessage Class

  • Reference

A Batched AMQP message.

This batch message encodes multiple message bodies into a single message to increase through-put over the wire. It requires server-side support to unpackage the batched messages and so will not be universally supported.

Inheritance
Message
BatchMessage

Constructor

BatchMessage(data=None, properties=None, application_properties=None, annotations=None, header=None, multi_messages=False, encoding='UTF-8')

Parameters

Name Description
data
<xref:iterable>

An iterable source of data, where each value will be considered the body of a single message in the batch.

default value: None
properties
MessageProperties

Properties to add to the message. If multiple messages are created these properties will be applied to each message.

default value: None
application_properties
dict

Service specific application properties. If multiple messages are created these properties will be applied to each message.

default value: None
annotations
dict

Service specific message annotations. If multiple messages are created these properties will be applied to each message. Keys in the dictionary must be types.AMQPSymbol or types.AMQPuLong.

default value: None
header
MessageHeader

The message header. This header will be applied to each message in the batch.

default value: None
multi_messages
bool

Whether to send the supplied data across multiple messages. If set to False, all the data will be sent in a single message, and an error raised if the message is too large. If set to True, the data will automatically be divided across multiple messages of an appropriate size. The default is False.

default value: False
encoding
str

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

default value: UTF-8

Variables

Name Description
on_send_complete
callable[MessageSendResult, Exception]

A custom callback to be run on completion of the send operation of this message. The callback must take two parameters, a result (of type ~uamqp.constants.MessageSendResult) and an error (of type Exception). The error parameter may be None if no error ocurred or the error information was undetermined.
batch_format
int

The is the specific message format to inform the service the the body should be interpreted as multiple messages. The value is 0x80013700.
max_message_length
int

The maximum data size in bytes to allow in a single message. By default this is 256kb. If sending a single batch message, an error will be raised if the supplied data exceeds this maximum. If sending multiple batch messages, this value will be used to divide the supplied data between messages.

Methods

accept

Send a response disposition to the service to indicate that a received message has been accepted. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. Returns True is message was accepted, or False if the message was already settled.
decode_from_bytes

Decode an AMQP message from a bytearray. The returned message will not have a delivery context and therefore will be considered to be in an "already settled" state.
encode_message

Encode message to AMQP wire-encoded bytearray.
gather

Return all the messages represented by this object. This will convert the batch data into individual Message objects, which may be one or more if multi_messages is set to True.
get_data

Get the body data of the message. The format may vary depending on the body type.
get_message

Get the underlying C message from this object.
get_message_encoded_size

Pre-emptively get the size of the message once it has been encoded to go over the wire so we can raise an error if the message will be rejected for being to large.

This method is not available for messages that have been received.
modify

Send a response disposition to the service to indicate that a received message has been modified. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. Returns True is message was modified, or False if the message was already settled.
reject

Send a response disposition to the service to indicate that a received message has been rejected. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. A rejected message will increment the messages delivery count. Returns True is message was rejected, or False if the message was already settled.
release

Send a response disposition to the service to indicate that a received message has been released. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. A released message will not incremenet the messages delivery count. Returns True is message was released, or False if the message was already settled.

accept

Send a response disposition to the service to indicate that a received message has been accepted. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. Returns True is message was accepted, or False if the message was already settled.

accept()

Returns

Type Description
bool

Exceptions

Type Description
TypeError if the message is being sent rather than received.

decode_from_bytes

Decode an AMQP message from a bytearray. The returned message will not have a delivery context and therefore will be considered to be in an "already settled" state.

decode_from_bytes(data)

Parameters

Name Description
data
Required
bytes or bytearray

The AMQP wire-encoded bytes to decode.

Exceptions

Type Description
TypeError if the message is being sent rather than received.

encode_message

Encode message to AMQP wire-encoded bytearray.

encode_message()

Returns

Type Description
bytearray

Exceptions

Type Description
TypeError if the message is being sent rather than received.

gather

Return all the messages represented by this object. This will convert the batch data into individual Message objects, which may be one or more if multi_messages is set to True.

gather()

Returns

Type Description
list[Message]

Exceptions

Type Description
TypeError if the message is being sent rather than received.

get_data

Get the body data of the message. The format may vary depending on the body type.

get_data()

Returns

Type Description
<xref:generator>

Exceptions

Type Description
TypeError if the message is being sent rather than received.

get_message

Get the underlying C message from this object.

get_message()

Returns

Type Description
cMessage

Exceptions

Type Description
TypeError if the message is being sent rather than received.

get_message_encoded_size

Pre-emptively get the size of the message once it has been encoded to go over the wire so we can raise an error if the message will be rejected for being to large.

This method is not available for messages that have been received.

get_message_encoded_size()

Returns

Type Description
int

Exceptions

Type Description
TypeError if the message is being sent rather than received.

modify

Send a response disposition to the service to indicate that a received message has been modified. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. Returns True is message was modified, or False if the message was already settled.

modify(failed, deliverable, annotations=None)

Parameters

Name Description
failed
Required
bool

Whether this delivery of this message failed. This does not indicate whether subsequence deliveries of this message would also fail.
deliverable
Required
bool

Whether this message will be deliverable to this client on subsequent deliveries - i.e. whether delivery is retryable.
annotations
dict

Annotations to attach to response.

default value: None

Returns

Type Description
bool

Exceptions

Type Description
TypeError if the message is being sent rather than received.

reject

Send a response disposition to the service to indicate that a received message has been rejected. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. A rejected message will increment the messages delivery count. Returns True is message was rejected, or False if the message was already settled.

reject(condition=None, description=None, info=None)

Parameters

Name Description
condition
bytes or str

The AMQP rejection code. By default this is amqp:internal-error.

default value: None
description
bytes or str

A description/reason to accompany the rejection.

default value: None
info
dict

Information about the error condition.

default value: None

Returns

Type Description
bool

Exceptions

Type Description
TypeError if the message is being sent rather than received.

release

Send a response disposition to the service to indicate that a received message has been released. If the client is running in PeekLock mode, the service will wait on this disposition. Otherwise it will be ignored. A released message will not incremenet the messages delivery count. Returns True is message was released, or False if the message was already settled.

release()

Returns

Type Description
bool

Exceptions

Type Description
TypeError if the message is being sent rather than received.

Attributes

annotations

application_properties

data

Returns an iterable source of data, where each value will be considered the body of a single message in the batch.

Returns

Type Description
<xref:iterable>

delivery_annotations

header

message_annotations

properties

sequence

settled

Whether the message transaction for this message has been completed. If this message is to be sent, the message will be settled=True once a disposition has been received from the service. If this message has been received, the message will be settled=True once a disposition has been sent to the service.

Returns

Type Description
bool

value

batch_format 

batch_format = 2147563264

max_message_length 

max_message_length = 1048576

size_offset 

size_offset = 0