Merge pull request #44 from kyleknap/waiter-top-level-docs

Added more docs about waiters

docs/source/guide/clients.rst

@@ -66,3 +66,44 @@ The ``response`` in the example above looks something like this:
            "http://url3"
        ]
    }
+
+Waiters
+-------
+Waiters use a client's service operations to poll the status of an AWS resource
+and suspend execution until the AWS resource reaches the state that the
+waiter is polling for or a failure occurs while polling.
+Using clients, you can learn the name of each waiter that a client has access
+to::
+
+    import boto3
+
+    s3 = boto3.client('s3')
+    sqs = boto3.client('sqs')
+
+    # List all of the possible waiters for both clients
+    print("s3 waiters:")
+    s3.waiter_names
+
+    print("sqs waiters:")
+    sqs.waiter_names
+
+Note if a client does not have any waiters, it will return an empty list when
+accessing its ``waiter_names`` attribute::
+
+    s3 waiters:
+    [u'bucket_exists', u'bucket_not_exists', u'object_exists', u'object_not_exists']
+    sqs waiters:
+    []
+
+Using a client's ``get_waiter()`` method, you can obtain a specific waiter
+from its list of possible waiters::
+
+    # Retrieve waiter instance that will wait till a specified
+    # S3 bucket exists
+    s3_bucket_exists_waiter = s3.get_waiter('bucket_exists')
+
+Then to actually start waiting, you must call the waiter's ``wait()`` method
+with the method's appropriate parameters passed in::
+
+    # Begin waiting for the S3 bucket, mybucket, to exist
+    s3_bucket_exists_waiter.wait(Bucket='mybucket')

docs/source/guide/resources.rst

@@ -170,3 +170,18 @@ can be considered one-to-many. Examples of sub-resources::
 
 Because an SQS message cannot exist without a queue, and an S3 object cannot
 exist without a bucket, these are parent to child relationships.
+
+Waiters
+-------
+A waiter is similiar to an action. A waiter will poll the status of a
+resource and suspend execution until the resource reaches the state that is
+being polling for or a failure occurs while polling.
+Waiters automatically set the resource
+identifiers as parameters, but allow you to pass additional parameters via
+keyword arguments. Examples of waiters include::
+
+    # S3: Wait for a bucket to exist.
+    bucket.wait_until_exists()
+
+    # EC2: Wait for an instance to reach the running state.
+    instance.wait_until_running()