
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.

         * **queue** -- 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*) -- Normally, SQS will not
           delete a queue that contains messages.  However, if the
           force_deletion argument is True, the queue will be deleted
           regardless of whether there are messages in the queue or
           not.  USE WITH CAUTION.  This will delete all messages in
           the queue as well.

      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)

      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.

      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)

      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.

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

   http://developer.amazonwebservices.com/connect/thread.jspa?messageI
   D=49680%EC%88%90

   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)

   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 at 0x7d4f1bcc>)

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