Upgrade gsutil to 3.4

third_party/gsutil/boto/docs/source/sqs_tut.rst

Index: third_party/gsutil/boto/docs/source/sqs_tut.rst
diff --git a/third_party/gsutil/20110627/boto/docs/source/sqs_tut.rst b/third_party/gsutil/boto/docs/source/sqs_tut.rst
similarity index 63%
rename from third_party/gsutil/20110627/boto/docs/source/sqs_tut.rst
rename to third_party/gsutil/boto/docs/source/sqs_tut.rst
index 8c3edc586b5064954b70d73f71e4330f7d1e5e22..742800f04fab06dec98f24751baf715c1d98fd5e 100644
--- a/third_party/gsutil/20110627/boto/docs/source/sqs_tut.rst
+++ b/third_party/gsutil/boto/docs/source/sqs_tut.rst
@@ -5,107 +5,145 @@ An Introduction to boto's SQS interface
 =======================================
 
 This tutorial focuses on the boto interface to the Simple Queue Service
-from Amazon Web Services.  This tutorial assumes that you have already
-downloaded and installed boto.
+from Amazon Web Services.  This tutorial assumes that you have boto already
+downloaded and installed.
 
 Creating a Connection
 ---------------------
 The first step in accessing SQS is to create a connection to the service.
-There are two ways to do this in boto.  The first is:
+There are two ways to do this in boto.  The first is::
 
->>> from boto.sqs.connection import SQSConnection
->>> conn = SQSConnection('<aws access key>', '<aws secret key>')
+    >>> from boto.sqs.connection import SQSConnection
+    >>> conn = SQSConnection('<aws access key>', '<aws secret key>')
 
-At this point the variable conn will point to an SQSConnection object.  In
+At this point the variable conn will point to an SQSConnection object. Bear in mind that
+just as any other AWS service SQS is region-specfic. Also important to note is that by default,
+if no region is provided, it'll connect to the US-EAST-1 region. In
 this example, the AWS access key and AWS secret key are passed in to the
 method explicitely.  Alternatively, you can set the environment variables:
 
 AWS_ACCESS_KEY_ID - Your AWS Access Key ID
 AWS_SECRET_ACCESS_KEY - Your AWS Secret Access Key
 
-and then call the constructor without any arguments, like this:
+and then call the constructor without any arguments, like this::
 
->>> conn = SQSConnection()
+    >>> conn = SQSConnection()
 
 There is also a shortcut function in the boto package, called connect_sqs
-that may provide a slightly easier means of creating a connection:
+that may provide a slightly easier means of creating a connection::
 
->>> import boto
->>> conn = boto.connect_sqs()
+    >>> import boto
+    >>> conn = boto.connect_sqs()
 
 In either case, conn will point to an SQSConnection object which we will
 use throughout the remainder of this tutorial.
 
 Creating a Queue
 ----------------
-
 Once you have a connection established with SQS, you will probably want to
-create a queue.  That can be accomplished like this:
+create a queue.  In its simplest form, that can be accomplished as follows::
 
->>> q = conn.create_queue('myqueue')
+    >>> q = conn.create_queue('myqueue')
 
-The create_queue method will create the requested queue if it does not
-exist or will return the existing queue if it does exist.  There is an
+The create_queue method will create (and return) the requested queue if it does not
+exist or will return the existing queue if it does.  There is an
 optional parameter to create_queue called visibility_timeout.  This basically
 controls how long a message will remain invisible to other queue readers
 once it has been read (see SQS documentation for more detailed explanation).
 If this is not explicitly specified the queue will be created with whatever
 default value SQS provides (currently 30 seconds).  If you would like to
-specify another value, you could do so like this:
+specify another value, you could do so like this::
 
->>> q = conn.create_queue('myqueue', 120)
+    >>> q = conn.create_queue('myqueue', 120)
 
 This would establish a default visibility timeout for this queue of 120
 seconds.  As you will see later on, this default value for the queue can
 also be overridden each time a message is read from the queue.  If you want
-to check what the default visibility timeout is for a queue:
+to check what the default visibility timeout is for a queue::
+
+    >>> q.get_timeout()
+    30
+
+Listing all Queues
+------------------
+
+To retrieve a list of the queues for your account in the current region::
+
+    >>> conn.get_all_queues()
+    [
+        Queue(https://queue.amazonaws.com/411358162645/myqueue),
+        Queue(https://queue.amazonaws.com/411358162645/another_queue),
+        Queue(https://queue.amazonaws.com/411358162645/another_queue2)
+    ]
+
+This will leave you with a list of all of your :py:class:`boto.sqs.queue.Queue`
+instances. Alternatively, if you wanted to only list the queues that started
+with ``'another'``::
 
->>> q.get_timeout()
-30
->>>
+    >>> conn.get_all_queues(prefix='another')
+    [
+        Queue(https://queue.amazonaws.com/411358162645/another_queue),
+        Queue(https://queue.amazonaws.com/411358162645/another_queue2)
+    ]
+
+Getting a Queue (by name)
+-------------------------
+If you wish to explicitly retrieve an existing queue and the name of the queue is known, 
+you can retrieve the queue as follows::
+
+    >>> my_queue = conn.get_queue('myqueue')
+    Queue(https://queue.amazonaws.com/411358162645/myqueue)
+
+This leaves you with a single :py:class:`boto.sqs.queue.Queue`, which abstracts
+the SQS Queue named 'myqueue'.
 
 Writing Messages
 ----------------
-
-Once you have a queue, presumably you will want to write some messages
+Once you have a queue setup, presumably you will want to write some messages
 to it.  SQS doesn't care what kind of information you store in your messages
 or what format you use to store it.  As long as the amount of data per
-message is less than or equal to 256Kb, it's happy.
+message is less than or equal to 256Kb, SQS won't complain.
+
+So, first we need to create a Message object::
 
-However, you may have a lot of specific requirements around the format of
-that data.  For example, you may want to store one big string or you might
+>>> from boto.sqs.message import Message
+>>> m = Message()
+>>> m.set_body('This is my first message.')
+>>> status = q.write(m)
+
+The write method returns a True if everything went well.  If the write
+didn't succeed it will either return a False (meaning SQS simply chose
+not to write the message for some reason) or an exception if there was
+some sort of problem with the request.
+
+Writing Messages (Custom Format)
+--------------------------------
+The technique above will work only if you use boto's default Message payload format;
+however, you may have a lot of specific requirements around the format of
+the message data.  For example, you may want to store one big string or you might
 want to store something that looks more like RFC822 messages or you might want
 to store a binary payload such as pickled Python objects.
 
-The way boto deals with this is to define a simple Message object that
+The way boto deals with this issue is to define a simple Message object that
 treats the message data as one big string which you can set and get.  If that
 Message object meets your needs, you're good to go.  However, if you need to
 incorporate different behavior in your message or handle different types of
 data you can create your own Message class.  You just need to register that
-class with the queue so that it knows that when you read a message from the
-queue that it should create one of your message objects rather than the
-default boto Message object.  To register your message class, you would:
+class with the boto queue object so that it knows that, when you read a message from the
+queue, it should create one of your message objects rather than the
+default boto Message object.  To register your message class, you would::
 
+>>> import MyMessage
 >>> q.set_message_class(MyMessage)
+>>> m = MyMessage()
+>>> m.set_body('This is my first message.')
+>>> status = q.write(m)
 
 where MyMessage is the class definition for your message class.  Your
 message class should subclass the boto Message because there is a small
 bit of Python magic happening in the __setattr__ method of the boto Message
 class.
 
-For this tutorial, let's just assume that we are using the boto Message
-class.  So, first we need to create a Message object:
-
->>> from boto.sqs.message import Message
->>> m = Message()
->>> m.set_body('This is my first message.')
->>> status = q.write(m)
-
-The write method returns a True if everything went well.  If the write
-didn't succeed it will either return a False (meaning SQS simply chose
-not to write the message for some reason) or an exception if there was
-some sort of problem with the request.
-
 Reading Messages
 ----------------
 
@@ -129,9 +167,9 @@ familiar to Python programmers.
 
 At this point, we have read the message from the queue and SQS will make
 sure that this message remains invisible to other readers of the queue
-until the visibility timeout period for the queue expires.  If I delete
-the message before the timeout period expires then no one will ever see
-the message again.  However, if I don't delete it (maybe because I crashed
+until the visibility timeout period for the queue expires.  If you delete
+the message before the timeout period expires then no one else will ever see
+the message again.  However, if you don't delete it (maybe because your reader crashed
 or failed in some way, for example) it will magically reappear in my queue
 for someone else to read.  If you aren't happy with the default visibility
 timeout defined for the queue, you can override it when you read a message:
@@ -171,10 +209,8 @@ u'This is my first message'
 
 Deleting Messages and Queues
 ----------------------------
-
-Note that the first message we put in the queue is still there, even though
-we have read it a number of times.  That's because we never deleted it.  To
-remove a message from a queue:
+As stated above, messages are never deleted by the queue unless explicitly told to do so. 
+To remove a message from a queue:
 
 >>> q.delete_message(m)
 []
@@ -183,30 +219,11 @@ If I want to delete the entire queue, I would use:
 
 >>> conn.delete_queue(q)
 
-However, this won't succeed unless the queue is empty.
-
-Listing All Available Queues
-----------------------------
-In addition to accessing specific queues via the create_queue method
-you can also get a list of all available queues that you have created.
-
->>> rs = conn.get_all_queues()
-
-This returns a ResultSet object, as described above.  The ResultSet
-can be used as a sequence or list type object to retrieve Queue objects.
-
->>> len(rs)
-11
->>> for q in rs:
-... print q.id
-...
-<listing of available queues>
->>> q = rs[0]
-
-Other Stuff
------------
+However, and this is a good safe guard, this won't succeed unless the queue is empty.
 
-That covers the basic operations of creating queues, writing messages,
+Additional Information
+----------------------
+The above tutorial covers the basic operations of creating queues, writing messages,
 reading messages, deleting messages, and deleting queues.  There are a
 few utility methods in boto that might be useful as well.  For example,
 to count the number of messages in a queue: