src/ceph/doc/radosgw/s3/python.rst

   1 .. _python:
   2
   3 Python S3 Examples
   4 ==================
   5
   6 Creating a Connection
   7 ---------------------
   8
   9 This creates a connection so that you can interact with the server.
  10
  11 .. code-block:: python
  12
  13         import boto
  14         import boto.s3.connection
  15         access_key = 'put your access key here!'
  16         secret_key = 'put your secret key here!'
  17
  18         conn = boto.connect_s3(
  19                 aws_access_key_id = access_key,
  20                 aws_secret_access_key = secret_key,
  21                 host = 'objects.dreamhost.com',
  22                 #is_secure=False,               # uncomment if you are not using ssl
  23                 calling_format = boto.s3.connection.OrdinaryCallingFormat(),
  24                 )
  25
  26
  27 Listing Owned Buckets
  28 ---------------------
  29
  30 This gets a list of Buckets that you own.
  31 This also prints out the bucket name and creation date of each bucket.
  32
  33 .. code-block:: python
  34
  35         for bucket in conn.get_all_buckets():
  36                 print "{name}\t{created}".format(
  37                         name = bucket.name,
  38                         created = bucket.creation_date,
  39                 )
  40
  41 The output will look something like this::
  42
  43    mahbuckat1   2011-04-21T18:05:39.000Z
  44    mahbuckat2   2011-04-21T18:05:48.000Z
  45    mahbuckat3   2011-04-21T18:07:18.000Z
  46
  47
  48 Creating a Bucket
  49 -----------------
  50
  51 This creates a new bucket called ``my-new-bucket``
  52
  53 .. code-block:: python
  54
  55         bucket = conn.create_bucket('my-new-bucket')
  56
  57
  58 Listing a Bucket's Content
  59 --------------------------
  60
  61 This gets a list of objects in the bucket.
  62 This also prints out each object's name, the file size, and last
  63 modified date.
  64
  65 .. code-block:: python
  66
  67         for key in bucket.list():
  68                 print "{name}\t{size}\t{modified}".format(
  69                         name = key.name,
  70                         size = key.size,
  71                         modified = key.last_modified,
  72                         )
  73
  74 The output will look something like this::
  75
  76    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
  77    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
  78
  79
  80 Deleting a Bucket
  81 -----------------
  82
  83 .. note::
  84
  85    The Bucket must be empty! Otherwise it won't work!
  86
  87 .. code-block:: python
  88
  89         conn.delete_bucket(bucket.name)
  90
  91
  92 Forced Delete for Non-empty Buckets
  93 -----------------------------------
  94
  95 .. attention::
  96
  97    not available in python
  98
  99
 100 Creating an Object
 101 ------------------
 102
 103 This creates a file ``hello.txt`` with the string ``"Hello World!"``
 104
 105 .. code-block:: python
 106
 107         key = bucket.new_key('hello.txt')
 108         key.set_contents_from_string('Hello World!')
 109
 110
 111 Change an Object's ACL
 112 ----------------------
 113
 114 This makes the object ``hello.txt`` to be publicly readable, and
 115 ``secret_plans.txt`` to be private.
 116
 117 .. code-block:: python
 118
 119         hello_key = bucket.get_key('hello.txt')
 120         hello_key.set_canned_acl('public-read')
 121         plans_key = bucket.get_key('secret_plans.txt')
 122         plans_key.set_canned_acl('private')
 123
 124
 125 Download an Object (to a file)
 126 ------------------------------
 127
 128 This downloads the object ``perl_poetry.pdf`` and saves it in
 129 ``/home/larry/documents/``
 130
 131 .. code-block:: python
 132
 133         key = bucket.get_key('perl_poetry.pdf')
 134         key.get_contents_to_filename('/home/larry/documents/perl_poetry.pdf')
 135
 136
 137 Delete an Object
 138 ----------------
 139
 140 This deletes the object ``goodbye.txt``
 141
 142 .. code-block:: python
 143
 144         bucket.delete_key('goodbye.txt')
 145
 146
 147 Generate Object Download URLs (signed and unsigned)
 148 ---------------------------------------------------
 149
 150 This generates an unsigned download URL for ``hello.txt``. This works
 151 because we made ``hello.txt`` public by setting the ACL above.
 152 This then generates a signed download URL for ``secret_plans.txt`` that
 153 will work for 1 hour. Signed download URLs will work for the time
 154 period even if the object is private (when the time period is up, the
 155 URL will stop working).
 156
 157 .. code-block:: python
 158
 159         hello_key = bucket.get_key('hello.txt')
 160         hello_url = hello_key.generate_url(0, query_auth=False, force_http=True)
 161         print hello_url
 162
 163         plans_key = bucket.get_key('secret_plans.txt')
 164         plans_url = plans_key.generate_url(3600, query_auth=True, force_http=True)
 165         print plans_url
 166
 167 The output of this will look something like::
 168
 169    http://objects.dreamhost.com/my-bucket-name/hello.txt
 170    http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 171