
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 class boto.sqs.attributes.Attributes(parent)

   endElement(name, value, connection)

   startElement(name, attrs, connection)


boto.sqs.connection
===================

class 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_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 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 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 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 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 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 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_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, 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 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 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 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)
