SQS — boto v2.16.0

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.16.0 »

# 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)

  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: | queue (A `boto.sqs.queue.Queue` object) – The Queue from which messages are read. message (A `boto.sqs.message.Message` object) – The Message to be deleted
    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: | queue (A `boto.sqs.queue.Queue` object.) – The Queue to which the messages will be written. messages (List of `boto.sqs.message.Message` objects.) – A list of message objects.

  `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_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 be deleted
    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)

    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.
    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)
  `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, and an integer which represents the delay time (in seconds) for the message (0-900) before the message will be delivered to the queue.

  `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:

> http://docs.amazonwebservices.com/AWSSimpleQueueService/2008-01-01/SQSDeveloperGuide/Query_QuerySendMessage.html

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 at 0x1082b0870>)
  `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_attribute(‘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)

    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.
    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='')

    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)

    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.
    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, and an integer which represents the delay time (in seconds) for the message (0-900) before the message will be delivered to the queue.

## boto.sqs.regioninfo

class `boto.sqs.regioninfo.` `SQSRegionInfo`(connection=None, name=None, endpoint=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)

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.16.0 »