← Back to branch summary

~ubuntu-branches/ubuntu/karmic/python-boto/karmic

« back to all changes in this revision

Viewing changes to boto/s3/bucket.py

  • Committer: Bazaar Package Importer
  • Author(s): Soren Hansen
  • Date: 2008-08-18 17:08:12 UTC
  • mfrom: (1.1.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20080818170812-b19z47gj515lc5b4
Tags: 1.3a-0ubuntu1
https://launchpad.net/bugs/246824
New upstream release. (LP: #246824)

Show diffs side-by-side

added added

removed removed

Lines of Context:
boto/s3/bucket.py
26
26
from boto.s3.user import User
27
27
from boto.s3.key import Key
28
28
from boto.s3.prefix import Prefix
29
 
from boto.exception import S3ResponseError, S3PermissionsError
 
29
from boto.exception import S3ResponseError, S3PermissionsError, S3CopyError
30
30
from boto.s3.bucketlistresultset import BucketListResultSet
31
31
import boto.utils
32
32
import xml.sax
80
80
        bucket so that when you call bucket.new_key() or when you get a listing
81
81
        of keys in the bucket you will get an instances of your key class
82
82
        rather than the default.
 
83
        
 
84
        @type key_class: class
 
85
        @param key_class: A subclass of Key that can be more specific
83
86
        """
84
87
        self.key_class = key_class
85
88
 
86
89
    def lookup(self, key_name):
87
90
        """
88
91
        Deprecated: Please use get_key method.
 
92
        
 
93
        @type key_name: string
 
94
        @param key_name: The name of the key to retrieve
 
95
        
 
96
        @rtype: L{Key<boto.s3.key.Key>}
 
97
        @returns: A Key object from this bucket.
89
98
        """
90
99
        return self.get_key(key_name)
91
100
        
94
103
        Check to see if a particular key exists within the bucket.  This
95
104
        method uses a HEAD request to check for the existance of the key.
96
105
        Returns: An instance of a Key object or None
 
106
        
 
107
        @type key_name: string
 
108
        @param key_name: The name of the key to retrieve
 
109
        
 
110
        @rtype: L{Key<boto.s3.key.Key>}
 
111
        @returns: A Key object from this bucket.
97
112
        """
98
113
        response = self.connection.make_request('HEAD', self.name, key_name)
99
114
        if response.status == 200:
103
118
            k.etag = response.getheader('etag')
104
119
            k.content_type = response.getheader('content-type')
105
120
            k.last_modified = response.getheader('last-modified')
106
 
            k.size = response.getheader('content-length')
 
121
            k.size = int(response.getheader('content-length'))
107
122
            k.name = key_name
108
123
            return k
109
124
        else:
125
140
        there are no more results.
126
141
        Called with no arguments, this will return an iterator object across
127
142
        all keys within the bucket.
128
 
        The prefix parameter allows you to limit the listing to a particular
129
 
        prefix.  For example, if you call the method with prefix='/foo/'
130
 
        then the iterator will only cycle through the keys that begin with
131
 
        the string '/foo/'.
132
 
        The delimiter parameter can be used in conjunction with the prefix
133
 
        to allow you to organize and browse your keys hierarchically. See:
134
 
        http://docs.amazonwebservices.com/AmazonS3/2006-03-01/
135
 
        for more details.
 
143
        
 
144
        @type prefix: string
 
145
        @param prefix: allows you to limit the listing to a particular
 
146
                        prefix.  For example, if you call the method with prefix='/foo/'
 
147
                        then the iterator will only cycle through the keys that begin with
 
148
                        the string '/foo/'.
 
149
                        
 
150
        @type delimiter: string
 
151
        @param delimiter: can be used in conjunction with the prefix
 
152
                        to allow you to organize and browse your keys hierarchically. See:
 
153
                        http://docs.amazonwebservices.com/AmazonS3/2006-03-01/
 
154
                        for more details.
 
155
                        
 
156
        @rtype: L{BucketListResultSet<boto.s3.bucketlistresultset.BucketListResultSet>}
 
157
        @return: an instance of a BucketListResultSet that handles paging, etc
136
158
        """
137
159
        return BucketListResultSet(self, prefix, delimiter)
138
160
 
144
166
        as defined in S3 Developer's Guide, however since max-keys is not
145
167
        a legal variable in Python you have to pass maxkeys and this
146
168
        method will munge it (Ugh!)
 
169
        
 
170
        @type maxkeys: int
 
171
        @param maxkeys: The maximum number of keys to retrieve
 
172
        
 
173
        @type prefix: string
 
174
        @param prefix: The prefix of the keys you want to retrieve
 
175
        
 
176
        @type marker: string
 
177
        @param marker: The "marker" of where you are in the result set
 
178
        
 
179
        @type delimiter: string 
 
180
        @param delimiter: "If this optional, Unicode string parameter is included with your request, then keys that contain the same string between the prefix and the first occurrence of the delimiter will be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response."
 
181
 
 
182
        @rtype: ResultSet
 
183
        @return: The result from S3 listing the keys requested
 
184
        
147
185
        """
148
186
        l = []
149
187
        for k,v in params.items():
170
208
            raise S3ResponseError(response.status, response.reason, body)
171
209
 
172
210
    def new_key(self, key_name=None):
 
211
        """
 
212
        Creates a new key
 
213
        
 
214
        @type key_name: string
 
215
        @param key_name: The name of the key to create
 
216
        
 
217
        @rtype: L{Key<boto.s3.key.Key>} or subclass
 
218
        @returns: An instance of the newly created key object
 
219
        """
173
220
        return self.key_class(self, key_name)
174
221
 
175
222
    def generate_url(self, expires_in, method='GET', headers=None):
176
223
        return self.connection.generate_url(expires_in, method, self.name, headers=headers)
177
224
 
178
225
    def delete_key(self, key_name):
 
226
        """
 
227
        Deletes a key from the bucket.
 
228
        
 
229
        @type key_name: string
 
230
        @param key_name: The key name to delete
 
231
        """
179
232
        response = self.connection.make_request('DELETE', self.name, key_name)
180
233
        body = response.read()
181
234
        if response.status != 204:
182
235
            raise S3ResponseError(response.status, response.reason, body)
183
236
 
 
237
    def copy_key(self, new_key_name, src_bucket_name, src_key_name, metadata=None):
 
238
        """
 
239
        Create a new key in the bucket by copying another existing key.
 
240
 
 
241
        @type new_key_name: string
 
242
        @param new_key_name: The name of the new key
 
243
 
 
244
        @type src_bucket_name: string
 
245
        @param src_bucket_name: The name of the source bucket
 
246
 
 
247
        @type src_key_name: string
 
248
        @param src_key_name: The name of the source key
 
249
 
 
250
        @type metadata: dict
 
251
        @param metadata: Metadata to be associated with new key.
 
252
                         If metadata is supplied, it will replace the
 
253
                         metadata of the source key being copied.
 
254
                         If no metadata is supplied, the source key's
 
255
                         metadata will be copied to the new key.
 
256
 
 
257
        @rtype: L{Key<boto.s3.key.Key>} or subclass
 
258
        @returns: An instance of the newly created key object
 
259
        """
 
260
        if metadata:
 
261
            headers = metadata.copy()
 
262
            headers['x-amz-metadata-directive'] = 'REPLACE'
 
263
        else:
 
264
            headers = {'x-amz-copy-source' : '%s/%s' % (src_bucket_name, src_key_name),
 
265
                       'x-amz-metadata-directive' : 'COPY'}
 
266
        response = self.connection.make_request('PUT', self.name, new_key_name,
 
267
                                                headers=headers)
 
268
        body = response.read()
 
269
        if response.status == 200:
 
270
            key = self.new_key(new_key_name)
 
271
            h = handler.XmlHandler(key, self)
 
272
            xml.sax.parseString(body, h)
 
273
            if hasattr(key, 'Error'):
 
274
                raise S3CopyError(key.Code, key.Message, body)
 
275
            return key
 
276
        else:
 
277
            raise S3ResponseError(response.status, response.reason, body)
 
278
 
184
279
    def set_canned_acl(self, acl_str, key_name=''):
185
280
        assert acl_str in CannedACLStrings
186
281
        response = self.connection.make_request('PUT', self.name, key_name,
222
317
        else:
223
318
            raise S3ResponseError(response.status, response.reason, body)
224
319
 
 
320
    def make_public(self, recursive=False):
 
321
        self.set_canned_acl('public-read')
 
322
        if recursive:
 
323
            for key in self:
 
324
                self.set_canned_acl('public-read', key.name)
 
325
 
225
326
    def add_email_grant(self, permission, email_address, recursive=False):
226
327
        """
227
328
        Convenience method that provides a quick way to add an email grant to a bucket.
256
357
        Convenience method that provides a quick way to add a canonical user grant to a bucket.
257
358
        This method retrieves the current ACL, creates a new grant based on the parameters
258
359
        passed in, adds that grant to the ACL and then PUT's the new ACL back to S3.
259
 
        Inputs:
260
 
            permission - The permission being granted.  Should be one of:
261
 
                         READ|WRITE|READ_ACP|WRITE_ACP|FULL_CONTROL
262
 
                         See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingAuthAccess.html
263
 
                         for more details on permissions.
264
 
            user_id - The canonical user id associated with the AWS account your are granting
265
 
                      the permission to.
266
 
            recursive - A boolean value to controls whether the command will apply the
267
 
                        grant to all keys within the bucket or not.  The default value is False.
268
 
                        By passing a True value, the call will iterate through all keys in the
269
 
                        bucket and apply the same grant to each key.
270
 
                        CAUTION: If you have a lot of keys, this could take a long time!
271
 
        Returns:
272
 
            Nothing
 
360
        
 
361
        @type permission: string
 
362
        @param permission:  The permission being granted.  Should be one of:
 
363
                            READ|WRITE|READ_ACP|WRITE_ACP|FULL_CONTROL
 
364
                            See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingAuthAccess.html
 
365
                            for more details on permissions.
 
366
                            
 
367
        @type user_id: string
 
368
        @param user_id:     The canonical user id associated with the AWS account your are granting
 
369
                            the permission to.
 
370
                            
 
371
        @type recursive: bool
 
372
        @param recursive:   A boolean value that controls whether the command will apply the
 
373
                            grant to all keys within the bucket or not.  The default value is False.
 
374
                            By passing a True value, the call will iterate through all keys in the
 
375
                            bucket and apply the same grant to each key.
 
376
                            CAUTION: If you have a lot of keys, this could take a long time!
273
377
        """
274
378
        if permission not in S3Permissions:
275
379
            raise S3PermissionsError('Unknown Permission: %s' % permission)