Expand the comments to be more descriptive

Author: Andrew Fitz Gibbon

s3_sample.py

@@ -16,30 +16,58 @@
 import boto
 import uuid
 
-# Create an S3 client
+# Instantiate a new client for Amazon Simple Storage Service (S3). With no
+# parameters or configuration, the AWS SDK for Python (Boto) will look for
+# access keys in these environment variables:
+#
+#    AWS_ACCESS_KEY_ID='...'
+#    AWS_SECRET_ACCESS_KEY='...'
+#
+# For more information about this interface to Amazon S3, see:
+# http://boto.readthedocs.org/en/latest/s3_tut.html
 s3 = boto.connect_s3()
 
-# Create a new bucket.
+# Everything uploaded to Amazon S3 must belong to a bucket. These buckets are
+# in the global namespace, and must have a unique name.
+#
+# For more information about bucket name restrictions, see:
+# http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html
 bucket_name = "python-sdk-sample-%s" % uuid.uuid4()
 print "Creating new bucket with name: " + bucket_name
 bucket = s3.create_bucket(bucket_name)
 
-# Upload some data
+# Files in Amazon S3 are called "objects" and are stored in buckets. A specific
+# object is referred to by its key (i.e., name) and holds data. Here, we create
+# a new object with the key "python_sample_key.txt" and content "Hello World!".
+#
+# For more information on keys and set_contents_from_string, see:
+# http://boto.readthedocs.org/en/latest/s3_tut.html#storing-data
 from boto.s3.key import Key
 k = Key(bucket)
-k.key = 'hello_world.txt'
+k.key = 'python_sample_key.txt'
 
 print "Uploading some data to " + bucket_name + " with key: " + k.key
-k.set_contents_from_string('This is a test of S3. Hello World!')
+k.set_contents_from_string('Hello World!')
 
-# Fetch the key to show that we stored something.
-print "Downloading the object we just uploaded:"
+# Fetch the key to show that we stored something. Key.generate_url will
+# construct a URL that can be used to access the object for a limited time.
+# Here, we set it to expire in 30 minutes.
+#
+# For a more detailed overview of generate_url's options, see:
+# http://boto.readthedocs.org/en/latest/ref/s3.html#boto.s3.key.Key.generate_url
+expires_in_seconds = 1800
+
+print "Generating a public URL for the object we just uploaded. This URL will be active for %d seconds" % expires_in_seconds
 print
-print k.get_contents_as_string()
+print k.generate_url(expires_in_seconds)
 print
+raw_input("Press enter to delete both the object and the bucket...")
 
-print "Now delete the same object"
+# Buckets cannot be deleted unless they're empty. Since we still have a
+# reference to the key (object), we can just delete it.
+print "Deleting the object."
 k.delete()
 
-print "And finally, delete the bucket."
+# Now that the bucket is empty, we can delete it.
+print "Deleting the bucket."
 s3.delete_bucket(bucket_name)