Navigation

SQS

boto.sqs

boto.sqs.connect_to_region(region_name, **kw_params)
boto.sqs.regions()

Get all available regions for the SQS service.

Return type:list
Returns:A list of boto.sqs.regioninfo.RegionInfo

boto.sqs.attributes

Represents an SQS Attribute Name/Value set

class boto.sqs.attributes.Attributes(parent)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.sqs.connection

class boto.sqs.connection.SQSConnection(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, debug=0, https_connection_factory=None, region=None, path='/', security_token=None, validate_certs=True, profile_name=None)

A Connection to the SQS Service.

APIVersion = '2012-11-05'
AuthServiceName = 'sqs'
DefaultContentType = 'text/plain'
DefaultRegionEndpoint = 'queue.amazonaws.com'
DefaultRegionName = 'us-east-1'
ResponseError

alias of SQSError

add_permission(queue, label, aws_account_id, action_name)

Add a permission to a queue.

Parameters:
  • queue (boto.sqs.queue.Queue) – The queue object
  • label (str or unicode) – A unique identification of the permission you are setting. Maximum of 80 characters [0-9a-zA-Z_-] Example, AliceSendMessage
  • principal_id – The AWS account number of the principal who will be given permission. The principal must have an AWS account, but does not need to be signed up for Amazon SQS. For information about locating the AWS account identification.
  • action_name (str or unicode) – The action. Valid choices are: * * * SendMessage * ReceiveMessage * DeleteMessage * ChangeMessageVisibility * GetQueueAttributes
Return type:

bool
Returns:

True if successful, False otherwise.
change_message_visibility(queue, receipt_handle, visibility_timeout)

Extends the read lock timeout for the specified message from the specified queue to the specified value.

Parameters:
  • queue (A boto.sqs.queue.Queue object) – The Queue from which messages are read.
  • receipt_handle (str) – The receipt handle associated with the message whose visibility timeout will be changed.
  • visibility_timeout (int) – The new value of the message’s visibility timeout in seconds.
change_message_visibility_batch(queue, messages)

A batch version of change_message_visibility that can act on up to 10 messages at a time.

Parameters:
  • queue (A boto.sqs.queue.Queue object.) – The Queue to which the messages will be written.
  • messages (List of tuples.) – A list of tuples where each tuple consists of a boto.sqs.message.Message object and an integer that represents the new visibility timeout for that message.
create_queue(queue_name, visibility_timeout=None)

Create an SQS Queue.

Parameters:
  • queue_name (str or unicode) – The name of the new queue. Names are scoped to an account and need to be unique within that account. Calling this method on an existing queue name will not return an error from SQS unless the value for visibility_timeout is different than the value of the existing queue of that name. This is still an expensive operation, though, and not the preferred way to check for the existence of a queue. See the boto.sqs.connection.SQSConnection.lookup() method.
  • visibility_timeout (int) – The default visibility timeout for all messages written in the queue. This can be overridden on a per-message.
Return type:

boto.sqs.queue.Queue
Returns:

The newly created queue.
delete_message(queue, message)

Delete a message from a queue.

Parameters:
Return type:

bool
Returns:

True if successful, False otherwise.
delete_message_batch(queue, messages)

Deletes a list of messages from a queue in a single request.

Parameters:
delete_message_from_handle(queue, receipt_handle)

Delete a message from a queue, given a receipt handle.

Parameters:
  • queue (A boto.sqs.queue.Queue object) – The Queue from which messages are read.
  • receipt_handle (str) – The receipt handle for the message
Return type:

bool
Returns:

True if successful, False otherwise.
delete_queue(queue, force_deletion=False)

Delete an SQS Queue.

Parameters:
  • queue (A Queue object) – The SQS queue to be deleted
  • force_deletion (Boolean) – A deprecated parameter that is no longer used by SQS’s API.
Return type:

bool
Returns:

True if the command succeeded, False otherwise
get_all_queues(prefix='')

Retrieves all queues.

Parameters:prefix (str) – Optionally, only return queues that start with this value.
Return type:list
Returns:A list of boto.sqs.queue.Queue instances.
get_dead_letter_source_queues(queue)

Retrieves the dead letter source queues for a given queue.

Parameters:queue (A boto.sqs.queue.Queue object.) – The queue for which to get DL source queues
Return type:list
Returns:A list of boto.sqs.queue.Queue instances.
get_queue(queue_name, owner_acct_id=None)

Retrieves the queue with the given name, or None if no match was found.

Parameters:
  • queue_name (str) – The name of the queue to retrieve.
  • owner_acct_id (str) – Optionally, the AWS account ID of the account that created the queue.
Return type:

boto.sqs.queue.Queue or None
Returns:

The requested queue, or None if no match was found.
get_queue_attributes(queue, attribute='All')

Gets one or all attributes of a Queue

Parameters:queue (A Queue object) – The SQS queue to get attributes for
Return type:boto.sqs.attributes.Attributes
Returns:An Attributes object containing request value(s).
lookup(queue_name, owner_acct_id=None)

Retrieves the queue with the given name, or None if no match was found.

Parameters:
  • queue_name (str) – The name of the queue to retrieve.
  • owner_acct_id (str) – Optionally, the AWS account ID of the account that created the queue.
Return type:

boto.sqs.queue.Queue or None
Returns:

The requested queue, or None if no match was found.
receive_message(queue, number_messages=1, visibility_timeout=None, attributes=None, wait_time_seconds=None, message_attributes=None)

Read messages from an SQS Queue.

Parameters:
  • queue (A Queue object) – The Queue from which messages are read.
  • number_messages (int) – The maximum number of messages to read (default=1)
  • visibility_timeout (int) – The number of seconds the message should remain invisible to other queue readers (default=None which uses the Queues default)
  • attributes (str) – The name of additional attribute to return with response or All if you want all attributes. The default is to return no additional attributes. Valid values: * All * SenderId * SentTimestamp * ApproximateReceiveCount * ApproximateFirstReceiveTimestamp
  • wait_time_seconds (int) – The duration (in seconds) for which the call will wait for a message to arrive in the queue before returning. If a message is available, the call will return sooner than wait_time_seconds.
  • message_attributes (list) – The name(s) of additional message attributes to return. The default is to return no additional message attributes. Use ['All'] or ['.*'] to return all.
Return type:

list
Returns:

A list of boto.sqs.message.Message objects.
remove_permission(queue, label)

Remove a permission from a queue.

Parameters:
  • queue (boto.sqs.queue.Queue) – The queue object
  • label (str or unicode) – The unique label associated with the permission being removed.
Return type:

bool
Returns:

True if successful, False otherwise.
send_message(queue, message_content, delay_seconds=None, message_attributes=None)

Send a new message to the queue.

Parameters:
  • queue (A boto.sqs.queue.Queue object.) – The Queue to which the messages will be written.
  • message_content (string) – The body of the message
  • delay_seconds (int) – Number of seconds (0 - 900) to delay this message from being processed.
  • message_attributes (dict) –

    Message attributes to set. Should be of the form:

    {
    “name1”: {
    “data_type”: “Number”, “string_value”: “1”

    }, “name2”: {

    “data_type”: “String”, “string_value”: “Bob”

    }

    }
send_message_batch(queue, messages)

Delivers up to 10 messages to a queue in a single request.

Parameters:
  • queue (A boto.sqs.queue.Queue object.) – The Queue to which the messages will be written.
  • messages (List of lists.) – A list of lists or tuples. Each inner tuple represents a single message to be written and consists of and ID (string) that must be unique within the list of messages, the message body itself which can be a maximum of 64K in length, an integer which represents the delay time (in seconds) for the message (0-900) before the message will be delivered to the queue, and an optional dict of message attributes like those passed to send_message above.
set_queue_attribute(queue, attribute, value)

boto.sqs.jsonmessage

class boto.sqs.jsonmessage.JSONMessage(queue=None, body=None, xml_attrs=None)

Acts like a dictionary but encodes it’s data as a Base64 encoded JSON payload.

decode(value)
encode(value)

boto.sqs.message

SQS Message

A Message represents the data stored in an SQS queue. The rules for what is allowed within an SQS Message are here:

So, at it’s simplest level a Message just needs to allow a developer to store bytes in it and get the bytes back out. However, to allow messages to have richer semantics, the Message class must support the following interfaces:

The constructor for the Message class must accept a keyword parameter “queue” which is an instance of a boto Queue object and represents the queue that the message will be stored in. The default value for this parameter is None.

The constructor for the Message class must accept a keyword parameter “body” which represents the content or body of the message. The format of this parameter will depend on the behavior of the particular Message subclass. For example, if the Message subclass provides dictionary-like behavior to the user the body passed to the constructor should be a dict-like object that can be used to populate the initial state of the message.

The Message class must provide an encode method that accepts a value of the same type as the body parameter of the constructor and returns a string of characters that are able to be stored in an SQS message body (see rules above).

The Message class must provide a decode method that accepts a string of characters that can be stored (and probably were stored!) in an SQS message and return an object of a type that is consistent with the “body” parameter accepted on the class constructor.

The Message class must provide a __len__ method that will return the size of the encoded message that would be stored in SQS based on the current state of the Message object.

The Message class must provide a get_body method that will return the body of the message in the same format accepted in the constructor of the class.

The Message class must provide a set_body method that accepts a message body in the same format accepted by the constructor of the class. This method should alter to the internal state of the Message object to reflect the state represented in the message body parameter.

The Message class must provide a get_body_encoded method that returns the current body of the message in the format in which it would be stored in SQS.

class boto.sqs.message.EncodedMHMessage(queue=None, body=None, xml_attrs=None)

The EncodedMHMessage class provides a message that provides RFC821-like headers like this:

HeaderName: HeaderValue

This variation encodes/decodes the body of the message in base64 automatically. The message instance can be treated like a mapping object, i.e. m[‘HeaderName’] would return ‘HeaderValue’.

decode(value)
encode(value)
class boto.sqs.message.MHMessage(queue=None, body=None, xml_attrs=None)

The MHMessage class provides a message that provides RFC821-like headers like this:

HeaderName: HeaderValue

The encoding/decoding of this is handled automatically and after the message body has been read, the message instance can be treated like a mapping object, i.e. m[‘HeaderName’] would return ‘HeaderValue’.

decode(value)
encode(value)
get(key, default=None)
has_key(key)
items()
keys()
update(d)
values()
class boto.sqs.message.Message(queue=None, body='')

The default Message class used for SQS queues. This class automatically encodes/decodes the message body using Base64 encoding to avoid any illegal characters in the message body. See:

https://forums.aws.amazon.com/thread.jspa?threadID=13067

for details on why this is a good idea. The encode/decode is meant to be transparent to the end-user.

decode(value)
encode(value)
class boto.sqs.message.RawMessage(queue=None, body='')

Base class for SQS messages. RawMessage does not encode the message in any way. Whatever you store in the body of the message is what will be written to SQS and whatever is returned from SQS is stored directly into the body of the message.

change_visibility(visibility_timeout)
decode(value)

Transform seralized byte array into any object.

delete()
encode(value)

Transform body object into serialized byte array format.

endElement(name, value, connection)
endNode(connection)
get_body()
get_body_encoded()

This method is really a semi-private method used by the Queue.write method when writing the contents of the message to SQS. You probably shouldn’t need to call this method in the normal course of events.

set_body(body)

Override the current body for this object, using decoded format.

startElement(name, attrs, connection)

boto.sqs.queue

Represents an SQS Queue

class boto.sqs.queue.Queue(connection=None, url=None, message_class=<class 'boto.sqs.message.Message'>)
add_permission(label, aws_account_id, action_name)

Add a permission to a queue.

Parameters:
  • label (str or unicode) – A unique identification of the permission you are setting. Maximum of 80 characters [0-9a-zA-Z_-] Example, AliceSendMessage
  • principal_id – The AWS account number of the principal who will be given permission. The principal must have an AWS account, but does not need to be signed up for Amazon SQS. For information about locating the AWS account identification.
  • action_name (str or unicode) – The action. Valid choices are: SendMessage|ReceiveMessage|DeleteMessage| ChangeMessageVisibility|GetQueueAttributes|*
Return type:

bool
Returns:

True if successful, False otherwise.
arn
change_message_visibility_batch(messages)

A batch version of change_message_visibility that can act on up to 10 messages at a time.

Parameters:messages (List of tuples.) – A list of tuples where each tuple consists of a boto.sqs.message.Message object and an integer that represents the new visibility timeout for that message.
clear(page_size=10, vtimeout=10)

Utility function to remove all messages from a queue

count(page_size=10, vtimeout=10)

Utility function to count the number of messages in a queue. Note: This function now calls GetQueueAttributes to obtain an ‘approximate’ count of the number of messages in a queue.

count_slow(page_size=10, vtimeout=10)

Deprecated. This is the old ‘count’ method that actually counts the messages by reading them all. This gives an accurate count but is very slow for queues with non-trivial number of messasges. Instead, use get_attributes(‘ApproximateNumberOfMessages’) to take advantage of the new SQS capability. This is retained only for the unit tests.

delete()

Delete the queue.

delete_message(message)

Delete a message from the queue.

Parameters:message (boto.sqs.message.Message) – The boto.sqs.message.Message object to delete.
Return type:bool
Returns:True if successful, False otherwise
delete_message_batch(messages)

Deletes a list of messages in a single request.

Parameters:messages (List of boto.sqs.message.Message objects.) – A list of message objects.
dump(file_name, page_size=10, vtimeout=10, sep='\n')

Utility function to dump the messages in a queue to a file NOTE: Page size must be < 10 else SQS errors

endElement(name, value, connection)
get_attributes(attributes='All')

Retrieves attributes about this queue object and returns them in an Attribute instance (subclass of a Dictionary).

Parameters:attributes (string) – String containing one of: ApproximateNumberOfMessages, ApproximateNumberOfMessagesNotVisible, VisibilityTimeout, CreatedTimestamp, LastModifiedTimestamp, Policy ReceiveMessageWaitTimeSeconds
Return type:Attribute object
Returns:An Attribute object which is a mapping type holding the requested name/value pairs
get_messages(num_messages=1, visibility_timeout=None, attributes=None, wait_time_seconds=None, message_attributes=None)

Get a variable number of messages.

Parameters:
  • num_messages (int) – The maximum number of messages to read from the queue.
  • visibility_timeout (int) – The VisibilityTimeout for the messages read.
  • attributes (str) – The name of additional attribute to return with response or All if you want all attributes. The default is to return no additional attributes. Valid values: All SenderId SentTimestamp ApproximateReceiveCount ApproximateFirstReceiveTimestamp
  • wait_time_seconds (int) – The duration (in seconds) for which the call will wait for a message to arrive in the queue before returning. If a message is available, the call will return sooner than wait_time_seconds.
  • message_attributes (list) – The name(s) of additional message attributes to return. The default is to return no additional message attributes. Use ['All'] or ['.*'] to return all.
Return type:

list
Returns:

A list of boto.sqs.message.Message objects.
get_timeout()

Get the visibility timeout for the queue.

Return type:int
Returns:The number of seconds as an integer.
id
load(file_name, sep='\n')

Utility function to load messages from a local filename to a queue

load_from_file(fp, sep='\n')

Utility function to load messages from a file-like object to a queue

load_from_filename(file_name, sep='\n')

Utility function to load messages from a local filename to a queue

load_from_s3(bucket, prefix=None)

Load messages previously saved to S3.

name
new_message(body='', **kwargs)

Create new message of appropriate class.

Parameters:body (message body) – The body of the newly created message (optional).
Return type:boto.sqs.message.Message
Returns:A new Message object
read(visibility_timeout=None, wait_time_seconds=None, message_attributes=None)

Read a single message from the queue.

Parameters:
  • visibility_timeout (int) – The timeout for this message in seconds
  • wait_time_seconds (int) – The duration (in seconds) for which the call will wait for a message to arrive in the queue before returning. If a message is available, the call will return sooner than wait_time_seconds.
  • message_attributes (list) – The name(s) of additional message attributes to return. The default is to return no additional message attributes. Use ['All'] or ['.*'] to return all.
Return type:

boto.sqs.message.Message
Returns:

A single message or None if queue is empty
remove_permission(label)

Remove a permission from a queue.

Parameters:label (str or unicode) – The unique label associated with the permission being removed.
Return type:bool
Returns:True if successful, False otherwise.
save(file_name, sep='\n')

Read all messages from the queue and persist them to local file. Messages are written to the file and the ‘sep’ string is written in between messages. Messages are deleted from the queue after being written to the file. Returns the number of messages saved.

save_to_file(fp, sep='\n')

Read all messages from the queue and persist them to file-like object. Messages are written to the file and the ‘sep’ string is written in between messages. Messages are deleted from the queue after being written to the file. Returns the number of messages saved.

save_to_filename(file_name, sep='\n')

Read all messages from the queue and persist them to local file. Messages are written to the file and the ‘sep’ string is written in between messages. Messages are deleted from the queue after being written to the file. Returns the number of messages saved.

save_to_s3(bucket)

Read all messages from the queue and persist them to S3. Messages are stored in the S3 bucket using a naming scheme of:

<queue_id>/<message_id>

Messages are deleted from the queue after being saved to S3. Returns the number of messages saved.

set_attribute(attribute, value)

Set a new value for an attribute of the Queue.

Parameters:
  • attribute (String) – The name of the attribute you want to set. The only valid value at this time is: VisibilityTimeout
  • value (int) – The new value for the attribute. For VisibilityTimeout the value must be an integer number of seconds from 0 to 86400.
Return type:

bool
Returns:

True if successful, otherwise False.
set_message_class(message_class)

Set the message class that should be used when instantiating messages read from the queue. By default, the class boto.sqs.message.Message is used but this can be overriden with any class that behaves like a message.

Parameters:message_class (Message-like class) – The new Message class
set_timeout(visibility_timeout)

Set the visibility timeout for the queue.

Parameters:visibility_timeout (int) – The desired timeout in seconds
startElement(name, attrs, connection)
write(message, delay_seconds=None)

Add a single message to the queue.

Parameters:message (Message) – The message to be written to the queue
Return type:boto.sqs.message.Message
Returns:The boto.sqs.message.Message object that was written.
write_batch(messages)

Delivers up to 10 messages in a single request.

Parameters:messages (List of lists.) – A list of lists or tuples. Each inner tuple represents a single message to be written and consists of and ID (string) that must be unique within the list of messages, the message body itself which can be a maximum of 64K in length, an integer which represents the delay time (in seconds) for the message (0-900) before the message will be delivered to the queue, and an optional dict of message attributes like those passed to send_message in the connection class.

boto.sqs.regioninfo

class boto.sqs.regioninfo.SQSRegionInfo(connection=None, name=None, endpoint=None, connection_cls=None)

boto.sqs.batchresults

A set of results returned by SendMessageBatch.

class boto.sqs.batchresults.BatchResults(parent)

A container for the results of a send_message_batch request.

Variables:
  • results – A list of successful results. Each item in the list will be an instance of ResultEntry.
  • errors – A list of unsuccessful results. Each item in the list will be an instance of ResultEntry.
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.sqs.batchresults.ResultEntry

The result (successful or unsuccessful) of a single message within a send_message_batch request.

In the case of a successful result, this dict-like object will contain the following items:

Variables:
  • id – A string containing the user-supplied ID of the message.
  • message_id – A string containing the SQS ID of the new message.
  • message_md5 – A string containing the MD5 hash of the message body.

In the case of an error, this object will contain the following items:

Variables:
  • id – A string containing the user-supplied ID of the message.
  • sender_fault – A boolean value.
  • error_code – A string containing a short description of the error.
  • error_message – A string containing a description of the error.
endElement(name, value, connection)
startElement(name, attrs, connection)

Table Of Contents

Previous topic

SNS

Next topic

STS

This Page

PDF Version

Navigation

© Copyright 2009,2010, Mitch Garnaat. Created using Sphinx 1.2.3.