]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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(): | |
20effc67 | 36 | print("{name}\t{created}".format( |
7c673cae FG |
37 | name = bucket.name, |
38 | created = bucket.creation_date, | |
20effc67 | 39 | )) |
7c673cae FG |
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(): | |
20effc67 | 68 | print("{name}\t{size}\t{modified}".format( |
7c673cae FG |
69 | name = key.name, |
70 | size = key.size, | |
71 | modified = key.last_modified, | |
20effc67 | 72 | )) |
7c673cae FG |
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!') | |
20effc67 TL |
109 | |
110 | ||
111 | Uploading an Object or a File | |
112 | ----------------------------- | |
113 | ||
114 | This creates a file ``logo.png`` with the contents from the file ``"logo.png"`` | |
115 | ||
116 | .. code-block:: python | |
117 | ||
118 | key = bucket.new_key('logo.png') | |
119 | key.set_contents_from_filename('logo.png') | |
7c673cae FG |
120 | |
121 | ||
122 | Change an Object's ACL | |
123 | ---------------------- | |
124 | ||
125 | This makes the object ``hello.txt`` to be publicly readable, and | |
126 | ``secret_plans.txt`` to be private. | |
127 | ||
128 | .. code-block:: python | |
129 | ||
130 | hello_key = bucket.get_key('hello.txt') | |
131 | hello_key.set_canned_acl('public-read') | |
132 | plans_key = bucket.get_key('secret_plans.txt') | |
133 | plans_key.set_canned_acl('private') | |
134 | ||
135 | ||
136 | Download an Object (to a file) | |
137 | ------------------------------ | |
138 | ||
139 | This downloads the object ``perl_poetry.pdf`` and saves it in | |
140 | ``/home/larry/documents/`` | |
141 | ||
142 | .. code-block:: python | |
143 | ||
144 | key = bucket.get_key('perl_poetry.pdf') | |
145 | key.get_contents_to_filename('/home/larry/documents/perl_poetry.pdf') | |
146 | ||
147 | ||
148 | Delete an Object | |
149 | ---------------- | |
150 | ||
151 | This deletes the object ``goodbye.txt`` | |
152 | ||
153 | .. code-block:: python | |
154 | ||
155 | bucket.delete_key('goodbye.txt') | |
156 | ||
157 | ||
158 | Generate Object Download URLs (signed and unsigned) | |
159 | --------------------------------------------------- | |
160 | ||
161 | This generates an unsigned download URL for ``hello.txt``. This works | |
162 | because we made ``hello.txt`` public by setting the ACL above. | |
163 | This then generates a signed download URL for ``secret_plans.txt`` that | |
164 | will work for 1 hour. Signed download URLs will work for the time | |
165 | period even if the object is private (when the time period is up, the | |
166 | URL will stop working). | |
167 | ||
168 | .. code-block:: python | |
169 | ||
170 | hello_key = bucket.get_key('hello.txt') | |
171 | hello_url = hello_key.generate_url(0, query_auth=False, force_http=True) | |
20effc67 | 172 | print(hello_url) |
7c673cae FG |
173 | |
174 | plans_key = bucket.get_key('secret_plans.txt') | |
175 | plans_url = plans_key.generate_url(3600, query_auth=True, force_http=True) | |
20effc67 | 176 | print(plans_url) |
7c673cae FG |
177 | |
178 | The output of this will look something like:: | |
179 | ||
180 | http://objects.dreamhost.com/my-bucket-name/hello.txt | |
181 | http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX | |
182 | ||
9f95a23c TL |
183 | Using S3 API Extensions |
184 | ----------------------- | |
185 | ||
186 | To use the boto3 client to tests the RadosGW extensions to the S3 API, the `extensions file`_ should be placed under: ``~/.aws/models/s3/2006-03-01/`` directory. | |
187 | For example, unordered list of objects could be fetched using: | |
188 | ||
189 | .. code-block:: python | |
190 | ||
20effc67 | 191 | print(conn.list_objects(Bucket='my-new-bucket', AllowUnordered=True)) |
9f95a23c TL |
192 | |
193 | ||
194 | Without the extensions file, in the above example, boto3 would complain that the ``AllowUnordered`` argument is invalid. | |
195 | ||
196 | ||
197 | .. _extensions file: https://github.com/ceph/ceph/blob/master/examples/boto3/service-2.sdk-extras.json |