| # Copyright (c) 2006-2010 Mitch Garnaat http://garnaat.org/ |
| # Copyright (c) 2010, Eucalyptus Systems, Inc. |
| # All rights reserved. |
| # |
| # Permission is hereby granted, free of charge, to any person obtaining a |
| # copy of this software and associated documentation files (the |
| # "Software"), to deal in the Software without restriction, including |
| # without limitation the rights to use, copy, modify, merge, publish, dis- |
| # tribute, sublicense, and/or sell copies of the Software, and to permit |
| # persons to whom the Software is furnished to do so, subject to the fol- |
| # lowing conditions: |
| # |
| # The above copyright notice and this permission notice shall be included |
| # in all copies or substantial portions of the Software. |
| # |
| # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS |
| # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL- |
| # ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT |
| # SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, |
| # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
| # IN THE SOFTWARE. |
| |
| import boto |
| from boto import handler |
| from boto.resultset import ResultSet |
| from boto.exception import BotoClientError |
| from boto.s3.acl import Policy, CannedACLStrings, Grant |
| from boto.s3.key import Key |
| from boto.s3.prefix import Prefix |
| from boto.s3.deletemarker import DeleteMarker |
| from boto.s3.multipart import MultiPartUpload |
| from boto.s3.multipart import CompleteMultiPartUpload |
| from boto.s3.multidelete import MultiDeleteResult |
| from boto.s3.multidelete import Error |
| from boto.s3.bucketlistresultset import BucketListResultSet |
| from boto.s3.bucketlistresultset import VersionedBucketListResultSet |
| from boto.s3.bucketlistresultset import MultiPartUploadListResultSet |
| from boto.s3.lifecycle import Lifecycle |
| from boto.s3.tagging import Tags |
| from boto.s3.cors import CORSConfiguration |
| from boto.s3.bucketlogging import BucketLogging |
| from boto.s3 import website |
| import boto.jsonresponse |
| import boto.utils |
| import xml.sax |
| import xml.sax.saxutils |
| import StringIO |
| import urllib |
| import re |
| import base64 |
| from collections import defaultdict |
| |
| # as per http://goo.gl/BDuud (02/19/2011) |
| |
| |
| class S3WebsiteEndpointTranslate: |
| |
| trans_region = defaultdict(lambda: 's3-website-us-east-1') |
| trans_region['eu-west-1'] = 's3-website-eu-west-1' |
| trans_region['us-west-1'] = 's3-website-us-west-1' |
| trans_region['us-west-2'] = 's3-website-us-west-2' |
| trans_region['sa-east-1'] = 's3-website-sa-east-1' |
| trans_region['ap-northeast-1'] = 's3-website-ap-northeast-1' |
| trans_region['ap-southeast-1'] = 's3-website-ap-southeast-1' |
| |
| @classmethod |
| def translate_region(self, reg): |
| return self.trans_region[reg] |
| |
| S3Permissions = ['READ', 'WRITE', 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'] |
| |
| |
| class Bucket(object): |
| |
| LoggingGroup = 'http://acs.amazonaws.com/groups/s3/LogDelivery' |
| |
| BucketPaymentBody = """<?xml version="1.0" encoding="UTF-8"?> |
| <RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> |
| <Payer>%s</Payer> |
| </RequestPaymentConfiguration>""" |
| |
| VersioningBody = """<?xml version="1.0" encoding="UTF-8"?> |
| <VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> |
| <Status>%s</Status> |
| <MfaDelete>%s</MfaDelete> |
| </VersioningConfiguration>""" |
| |
| WebsiteBody = """<?xml version="1.0" encoding="UTF-8"?> |
| <WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> |
| <IndexDocument><Suffix>%s</Suffix></IndexDocument> |
| %s |
| </WebsiteConfiguration>""" |
| |
| WebsiteErrorFragment = """<ErrorDocument><Key>%s</Key></ErrorDocument>""" |
| |
| VersionRE = '<Status>([A-Za-z]+)</Status>' |
| MFADeleteRE = '<MfaDelete>([A-Za-z]+)</MfaDelete>' |
| |
| def __init__(self, connection=None, name=None, key_class=Key): |
| self.name = name |
| self.connection = connection |
| self.key_class = key_class |
| |
| def __repr__(self): |
| return '<Bucket: %s>' % self.name |
| |
| def __iter__(self): |
| return iter(BucketListResultSet(self)) |
| |
| def __contains__(self, key_name): |
| return not (self.get_key(key_name) is None) |
| |
| def startElement(self, name, attrs, connection): |
| return None |
| |
| def endElement(self, name, value, connection): |
| if name == 'Name': |
| self.name = value |
| elif name == 'CreationDate': |
| self.creation_date = value |
| else: |
| setattr(self, name, value) |
| |
| def set_key_class(self, key_class): |
| """ |
| Set the Key class associated with this bucket. By default, this |
| would be the boto.s3.key.Key class but if you want to subclass that |
| for some reason this allows you to associate your new class with a |
| bucket so that when you call bucket.new_key() or when you get a listing |
| of keys in the bucket you will get an instances of your key class |
| rather than the default. |
| |
| :type key_class: class |
| :param key_class: A subclass of Key that can be more specific |
| """ |
| self.key_class = key_class |
| |
| def lookup(self, key_name, headers=None): |
| """ |
| Deprecated: Please use get_key method. |
| |
| :type key_name: string |
| :param key_name: The name of the key to retrieve |
| |
| :rtype: :class:`boto.s3.key.Key` |
| :returns: A Key object from this bucket. |
| """ |
| return self.get_key(key_name, headers=headers) |
| |
| def get_key(self, key_name, headers=None, version_id=None, |
| response_headers=None): |
| """ |
| Check to see if a particular key exists within the bucket. This |
| method uses a HEAD request to check for the existance of the key. |
| Returns: An instance of a Key object or None |
| |
| :type key_name: string |
| :param key_name: The name of the key to retrieve |
| |
| :type response_headers: dict |
| :param response_headers: A dictionary containing HTTP |
| headers/values that will override any headers associated |
| with the stored object in the response. See |
| http://goo.gl/EWOPb for details. |
| |
| :rtype: :class:`boto.s3.key.Key` |
| :returns: A Key object from this bucket. |
| """ |
| query_args_l = [] |
| if version_id: |
| query_args_l.append('versionId=%s' % version_id) |
| if response_headers: |
| for rk, rv in response_headers.iteritems(): |
| query_args_l.append('%s=%s' % (rk, urllib.quote(rv))) |
| |
| key, resp = self._get_key_internal(key_name, headers, query_args_l) |
| return key |
| |
| def _get_key_internal(self, key_name, headers, query_args_l): |
| query_args = '&'.join(query_args_l) or None |
| response = self.connection.make_request('HEAD', self.name, key_name, |
| headers=headers, |
| query_args=query_args) |
| response.read() |
| # Allow any success status (2xx) - for example this lets us |
| # support Range gets, which return status 206: |
| if response.status / 100 == 2: |
| k = self.key_class(self) |
| provider = self.connection.provider |
| k.metadata = boto.utils.get_aws_metadata(response.msg, provider) |
| k.etag = response.getheader('etag') |
| k.content_type = response.getheader('content-type') |
| k.content_encoding = response.getheader('content-encoding') |
| k.content_disposition = response.getheader('content-disposition') |
| k.content_language = response.getheader('content-language') |
| k.last_modified = response.getheader('last-modified') |
| # the following machinations are a workaround to the fact that |
| # apache/fastcgi omits the content-length header on HEAD |
| # requests when the content-length is zero. |
| # See http://goo.gl/0Tdax for more details. |
| clen = response.getheader('content-length') |
| if clen: |
| k.size = int(response.getheader('content-length')) |
| else: |
| k.size = 0 |
| k.cache_control = response.getheader('cache-control') |
| k.name = key_name |
| k.handle_version_headers(response) |
| k.handle_encryption_headers(response) |
| k.handle_restore_headers(response) |
| return k, response |
| else: |
| if response.status == 404: |
| return None, response |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, '') |
| |
| def list(self, prefix='', delimiter='', marker='', headers=None): |
| """ |
| List key objects within a bucket. This returns an instance of an |
| BucketListResultSet that automatically handles all of the result |
| paging, etc. from S3. You just need to keep iterating until |
| there are no more results. |
| |
| Called with no arguments, this will return an iterator object across |
| all keys within the bucket. |
| |
| The Key objects returned by the iterator are obtained by parsing |
| the results of a GET on the bucket, also known as the List Objects |
| request. The XML returned by this request contains only a subset |
| of the information about each key. Certain metadata fields such |
| as Content-Type and user metadata are not available in the XML. |
| Therefore, if you want these additional metadata fields you will |
| have to do a HEAD request on the Key in the bucket. |
| |
| :type prefix: string |
| :param prefix: allows you to limit the listing to a particular |
| prefix. For example, if you call the method with |
| prefix='/foo/' then the iterator will only cycle through |
| the keys that begin with the string '/foo/'. |
| |
| :type delimiter: string |
| :param delimiter: can be used in conjunction with the prefix |
| to allow you to organize and browse your keys |
| hierarchically. See http://goo.gl/Xx63h for more details. |
| |
| :type marker: string |
| :param marker: The "marker" of where you are in the result set |
| |
| :rtype: :class:`boto.s3.bucketlistresultset.BucketListResultSet` |
| :return: an instance of a BucketListResultSet that handles paging, etc |
| """ |
| return BucketListResultSet(self, prefix, delimiter, marker, headers) |
| |
| def list_versions(self, prefix='', delimiter='', key_marker='', |
| version_id_marker='', headers=None): |
| """ |
| List version objects within a bucket. This returns an |
| instance of an VersionedBucketListResultSet that automatically |
| handles all of the result paging, etc. from S3. You just need |
| to keep iterating until there are no more results. Called |
| with no arguments, this will return an iterator object across |
| all keys within the bucket. |
| |
| :type prefix: string |
| :param prefix: allows you to limit the listing to a particular |
| prefix. For example, if you call the method with |
| prefix='/foo/' then the iterator will only cycle through |
| the keys that begin with the string '/foo/'. |
| |
| :type delimiter: string |
| :param delimiter: can be used in conjunction with the prefix |
| to allow you to organize and browse your keys |
| hierarchically. See: |
| |
| http://aws.amazon.com/releasenotes/Amazon-S3/213 |
| |
| for more details. |
| |
| :type marker: string |
| :param marker: The "marker" of where you are in the result set |
| |
| :rtype: :class:`boto.s3.bucketlistresultset.BucketListResultSet` |
| :return: an instance of a BucketListResultSet that handles paging, etc |
| """ |
| return VersionedBucketListResultSet(self, prefix, delimiter, |
| key_marker, version_id_marker, |
| headers) |
| |
| def list_multipart_uploads(self, key_marker='', |
| upload_id_marker='', |
| headers=None): |
| """ |
| List multipart upload objects within a bucket. This returns an |
| instance of an MultiPartUploadListResultSet that automatically |
| handles all of the result paging, etc. from S3. You just need |
| to keep iterating until there are no more results. |
| |
| :type marker: string |
| :param marker: The "marker" of where you are in the result set |
| |
| :rtype: :class:`boto.s3.bucketlistresultset.BucketListResultSet` |
| :return: an instance of a BucketListResultSet that handles paging, etc |
| """ |
| return MultiPartUploadListResultSet(self, key_marker, |
| upload_id_marker, |
| headers) |
| |
| def _get_all(self, element_map, initial_query_string='', |
| headers=None, **params): |
| l = [] |
| for k, v in params.items(): |
| k = k.replace('_', '-') |
| if k == 'maxkeys': |
| k = 'max-keys' |
| if isinstance(v, unicode): |
| v = v.encode('utf-8') |
| if v is not None and v != '': |
| l.append('%s=%s' % (urllib.quote(k), urllib.quote(str(v)))) |
| if len(l): |
| s = initial_query_string + '&' + '&'.join(l) |
| else: |
| s = initial_query_string |
| response = self.connection.make_request('GET', self.name, |
| headers=headers, |
| query_args=s) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 200: |
| rs = ResultSet(element_map) |
| h = handler.XmlHandler(rs, self) |
| xml.sax.parseString(body, h) |
| return rs |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_all_keys(self, headers=None, **params): |
| """ |
| A lower-level method for listing contents of a bucket. This |
| closely models the actual S3 API and requires you to manually |
| handle the paging of results. For a higher-level method that |
| handles the details of paging for you, you can use the list |
| method. |
| |
| :type max_keys: int |
| :param max_keys: The maximum number of keys to retrieve |
| |
| :type prefix: string |
| :param prefix: The prefix of the keys you want to retrieve |
| |
| :type marker: string |
| :param marker: The "marker" of where you are in the result set |
| |
| :type delimiter: string |
| :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. |
| |
| :rtype: ResultSet |
| :return: The result from S3 listing the keys requested |
| |
| """ |
| return self._get_all([('Contents', self.key_class), |
| ('CommonPrefixes', Prefix)], |
| '', headers, **params) |
| |
| def get_all_versions(self, headers=None, **params): |
| """ |
| A lower-level, version-aware method for listing contents of a |
| bucket. This closely models the actual S3 API and requires |
| you to manually handle the paging of results. For a |
| higher-level method that handles the details of paging for |
| you, you can use the list method. |
| |
| :type max_keys: int |
| :param max_keys: The maximum number of keys to retrieve |
| |
| :type prefix: string |
| :param prefix: The prefix of the keys you want to retrieve |
| |
| :type key_marker: string |
| :param key_marker: The "marker" of where you are in the result set |
| with respect to keys. |
| |
| :type version_id_marker: string |
| :param version_id_marker: The "marker" of where you are in the result |
| set with respect to version-id's. |
| |
| :type delimiter: string |
| :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. |
| |
| :rtype: ResultSet |
| :return: The result from S3 listing the keys requested |
| """ |
| return self._get_all([('Version', self.key_class), |
| ('CommonPrefixes', Prefix), |
| ('DeleteMarker', DeleteMarker)], |
| 'versions', headers, **params) |
| |
| def get_all_multipart_uploads(self, headers=None, **params): |
| """ |
| A lower-level, version-aware method for listing active |
| MultiPart uploads for a bucket. This closely models the |
| actual S3 API and requires you to manually handle the paging |
| of results. For a higher-level method that handles the |
| details of paging for you, you can use the list method. |
| |
| :type max_uploads: int |
| :param max_uploads: The maximum number of uploads to retrieve. |
| Default value is 1000. |
| |
| :type key_marker: string |
| :param key_marker: Together with upload_id_marker, this |
| parameter specifies the multipart upload after which |
| listing should begin. If upload_id_marker is not |
| specified, only the keys lexicographically greater than |
| the specified key_marker will be included in the list. |
| |
| If upload_id_marker is specified, any multipart uploads |
| for a key equal to the key_marker might also be included, |
| provided those multipart uploads have upload IDs |
| lexicographically greater than the specified |
| upload_id_marker. |
| |
| :type upload_id_marker: string |
| :param upload_id_marker: Together with key-marker, specifies |
| the multipart upload after which listing should begin. If |
| key_marker is not specified, the upload_id_marker |
| parameter is ignored. Otherwise, any multipart uploads |
| for a key equal to the key_marker might be included in the |
| list only if they have an upload ID lexicographically |
| greater than the specified upload_id_marker. |
| |
| :rtype: ResultSet |
| :return: The result from S3 listing the uploads requested |
| |
| """ |
| return self._get_all([('Upload', MultiPartUpload), |
| ('CommonPrefixes', Prefix)], |
| 'uploads', headers, **params) |
| |
| def new_key(self, key_name=None): |
| """ |
| Creates a new key |
| |
| :type key_name: string |
| :param key_name: The name of the key to create |
| |
| :rtype: :class:`boto.s3.key.Key` or subclass |
| :returns: An instance of the newly created key object |
| """ |
| if not key_name: |
| raise ValueError('Empty key names are not allowed') |
| return self.key_class(self, key_name) |
| |
| def generate_url(self, expires_in, method='GET', headers=None, |
| force_http=False, response_headers=None, |
| expires_in_absolute=False): |
| return self.connection.generate_url(expires_in, method, self.name, |
| headers=headers, |
| force_http=force_http, |
| response_headers=response_headers, |
| expires_in_absolute=expires_in_absolute) |
| |
| def delete_keys(self, keys, quiet=False, mfa_token=None, headers=None): |
| """ |
| Deletes a set of keys using S3's Multi-object delete API. If a |
| VersionID is specified for that key then that version is removed. |
| Returns a MultiDeleteResult Object, which contains Deleted |
| and Error elements for each key you ask to delete. |
| |
| :type keys: list |
| :param keys: A list of either key_names or (key_name, versionid) pairs |
| or a list of Key instances. |
| |
| :type quiet: boolean |
| :param quiet: In quiet mode the response includes only keys |
| where the delete operation encountered an error. For a |
| successful deletion, the operation does not return any |
| information about the delete in the response body. |
| |
| :type mfa_token: tuple or list of strings |
| :param mfa_token: A tuple or list consisting of the serial |
| number from the MFA device and the current value of the |
| six-digit token associated with the device. This value is |
| required anytime you are deleting versioned objects from a |
| bucket that has the MFADelete option on the bucket. |
| |
| :returns: An instance of MultiDeleteResult |
| """ |
| ikeys = iter(keys) |
| result = MultiDeleteResult(self) |
| provider = self.connection.provider |
| query_args = 'delete' |
| |
| def delete_keys2(hdrs): |
| hdrs = hdrs or {} |
| data = u"""<?xml version="1.0" encoding="UTF-8"?>""" |
| data += u"<Delete>" |
| if quiet: |
| data += u"<Quiet>true</Quiet>" |
| count = 0 |
| while count < 1000: |
| try: |
| key = ikeys.next() |
| except StopIteration: |
| break |
| if isinstance(key, basestring): |
| key_name = key |
| version_id = None |
| elif isinstance(key, tuple) and len(key) == 2: |
| key_name, version_id = key |
| elif (isinstance(key, Key) or isinstance(key, DeleteMarker)) and key.name: |
| key_name = key.name |
| version_id = key.version_id |
| else: |
| if isinstance(key, Prefix): |
| key_name = key.name |
| code = 'PrefixSkipped' # Don't delete Prefix |
| else: |
| key_name = repr(key) # try get a string |
| code = 'InvalidArgument' # other unknown type |
| message = 'Invalid. No delete action taken for this object.' |
| error = Error(key_name, code=code, message=message) |
| result.errors.append(error) |
| continue |
| count += 1 |
| data += u"<Object><Key>%s</Key>" % xml.sax.saxutils.escape(key_name) |
| if version_id: |
| data += u"<VersionId>%s</VersionId>" % version_id |
| data += u"</Object>" |
| data += u"</Delete>" |
| if count <= 0: |
| return False # no more |
| data = data.encode('utf-8') |
| fp = StringIO.StringIO(data) |
| md5 = boto.utils.compute_md5(fp) |
| hdrs['Content-MD5'] = md5[1] |
| hdrs['Content-Type'] = 'text/xml' |
| if mfa_token: |
| hdrs[provider.mfa_header] = ' '.join(mfa_token) |
| response = self.connection.make_request('POST', self.name, |
| headers=hdrs, |
| query_args=query_args, |
| data=data) |
| body = response.read() |
| if response.status == 200: |
| h = handler.XmlHandler(result, self) |
| xml.sax.parseString(body, h) |
| return count >= 1000 # more? |
| else: |
| raise provider.storage_response_error(response.status, |
| response.reason, |
| body) |
| while delete_keys2(headers): |
| pass |
| return result |
| |
| def delete_key(self, key_name, headers=None, version_id=None, |
| mfa_token=None): |
| """ |
| Deletes a key from the bucket. If a version_id is provided, |
| only that version of the key will be deleted. |
| |
| :type key_name: string |
| :param key_name: The key name to delete |
| |
| :type version_id: string |
| :param version_id: The version ID (optional) |
| |
| :type mfa_token: tuple or list of strings |
| :param mfa_token: A tuple or list consisting of the serial |
| number from the MFA device and the current value of the |
| six-digit token associated with the device. This value is |
| required anytime you are deleting versioned objects from a |
| bucket that has the MFADelete option on the bucket. |
| |
| :rtype: :class:`boto.s3.key.Key` or subclass |
| :returns: A key object holding information on what was |
| deleted. The Caller can see if a delete_marker was |
| created or removed and what version_id the delete created |
| or removed. |
| """ |
| return self._delete_key_internal(key_name, headers=headers, |
| version_id=version_id, |
| mfa_token=mfa_token, |
| query_args_l=None) |
| |
| def _delete_key_internal(self, key_name, headers=None, version_id=None, |
| mfa_token=None, query_args_l=None): |
| query_args_l = query_args_l or [] |
| provider = self.connection.provider |
| if version_id: |
| query_args_l.append('versionId=%s' % version_id) |
| query_args = '&'.join(query_args_l) or None |
| if mfa_token: |
| if not headers: |
| headers = {} |
| headers[provider.mfa_header] = ' '.join(mfa_token) |
| response = self.connection.make_request('DELETE', self.name, key_name, |
| headers=headers, |
| query_args=query_args) |
| body = response.read() |
| if response.status != 204: |
| raise provider.storage_response_error(response.status, |
| response.reason, body) |
| else: |
| # return a key object with information on what was deleted. |
| k = self.key_class(self) |
| k.name = key_name |
| k.handle_version_headers(response) |
| return k |
| |
| def copy_key(self, new_key_name, src_bucket_name, |
| src_key_name, metadata=None, src_version_id=None, |
| storage_class='STANDARD', preserve_acl=False, |
| encrypt_key=False, headers=None, query_args=None): |
| """ |
| Create a new key in the bucket by copying another existing key. |
| |
| :type new_key_name: string |
| :param new_key_name: The name of the new key |
| |
| :type src_bucket_name: string |
| :param src_bucket_name: The name of the source bucket |
| |
| :type src_key_name: string |
| :param src_key_name: The name of the source key |
| |
| :type src_version_id: string |
| :param src_version_id: The version id for the key. This param |
| is optional. If not specified, the newest version of the |
| key will be copied. |
| |
| :type metadata: dict |
| :param metadata: Metadata to be associated with new key. If |
| metadata is supplied, it will replace the metadata of the |
| source key being copied. If no metadata is supplied, the |
| source key's metadata will be copied to the new key. |
| |
| :type storage_class: string |
| :param storage_class: The storage class of the new key. By |
| default, the new key will use the standard storage class. |
| Possible values are: STANDARD | REDUCED_REDUNDANCY |
| |
| :type preserve_acl: bool |
| :param preserve_acl: If True, the ACL from the source key will |
| be copied to the destination key. If False, the |
| destination key will have the default ACL. Note that |
| preserving the ACL in the new key object will require two |
| additional API calls to S3, one to retrieve the current |
| ACL and one to set that ACL on the new object. If you |
| don't care about the ACL, a value of False will be |
| significantly more efficient. |
| |
| :type encrypt_key: bool |
| :param encrypt_key: If True, the new copy of the object will |
| be encrypted on the server-side by S3 and will be stored |
| in an encrypted form while at rest in S3. |
| |
| :type headers: dict |
| :param headers: A dictionary of header name/value pairs. |
| |
| :type query_args: string |
| :param query_args: A string of additional querystring arguments |
| to append to the request |
| |
| :rtype: :class:`boto.s3.key.Key` or subclass |
| :returns: An instance of the newly created key object |
| """ |
| headers = headers or {} |
| provider = self.connection.provider |
| src_key_name = boto.utils.get_utf8_value(src_key_name) |
| if preserve_acl: |
| if self.name == src_bucket_name: |
| src_bucket = self |
| else: |
| src_bucket = self.connection.get_bucket(src_bucket_name) |
| acl = src_bucket.get_xml_acl(src_key_name) |
| if encrypt_key: |
| headers[provider.server_side_encryption_header] = 'AES256' |
| src = '%s/%s' % (src_bucket_name, urllib.quote(src_key_name)) |
| if src_version_id: |
| src += '?versionId=%s' % src_version_id |
| headers[provider.copy_source_header] = str(src) |
| # make sure storage_class_header key exists before accessing it |
| if provider.storage_class_header and storage_class: |
| headers[provider.storage_class_header] = storage_class |
| if metadata is not None: |
| headers[provider.metadata_directive_header] = 'REPLACE' |
| headers = boto.utils.merge_meta(headers, metadata, provider) |
| elif not query_args: # Can't use this header with multi-part copy. |
| headers[provider.metadata_directive_header] = 'COPY' |
| response = self.connection.make_request('PUT', self.name, new_key_name, |
| headers=headers, |
| query_args=query_args) |
| body = response.read() |
| if response.status == 200: |
| key = self.new_key(new_key_name) |
| h = handler.XmlHandler(key, self) |
| xml.sax.parseString(body, h) |
| if hasattr(key, 'Error'): |
| raise provider.storage_copy_error(key.Code, key.Message, body) |
| key.handle_version_headers(response) |
| if preserve_acl: |
| self.set_xml_acl(acl, new_key_name) |
| return key |
| else: |
| raise provider.storage_response_error(response.status, |
| response.reason, body) |
| |
| def set_canned_acl(self, acl_str, key_name='', headers=None, |
| version_id=None): |
| assert acl_str in CannedACLStrings |
| |
| if headers: |
| headers[self.connection.provider.acl_header] = acl_str |
| else: |
| headers = {self.connection.provider.acl_header: acl_str} |
| |
| query_args = 'acl' |
| if version_id: |
| query_args += '&versionId=%s' % version_id |
| response = self.connection.make_request('PUT', self.name, key_name, |
| headers=headers, query_args=query_args) |
| body = response.read() |
| if response.status != 200: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_xml_acl(self, key_name='', headers=None, version_id=None): |
| query_args = 'acl' |
| if version_id: |
| query_args += '&versionId=%s' % version_id |
| response = self.connection.make_request('GET', self.name, key_name, |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| if response.status != 200: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| return body |
| |
| def set_xml_acl(self, acl_str, key_name='', headers=None, version_id=None, |
| query_args='acl'): |
| if version_id: |
| query_args += '&versionId=%s' % version_id |
| response = self.connection.make_request('PUT', self.name, key_name, |
| data=acl_str.encode('UTF-8'), |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| if response.status != 200: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_acl(self, acl_or_str, key_name='', headers=None, version_id=None): |
| if isinstance(acl_or_str, Policy): |
| self.set_xml_acl(acl_or_str.to_xml(), key_name, |
| headers, version_id) |
| else: |
| self.set_canned_acl(acl_or_str, key_name, |
| headers, version_id) |
| |
| def get_acl(self, key_name='', headers=None, version_id=None): |
| query_args = 'acl' |
| if version_id: |
| query_args += '&versionId=%s' % version_id |
| response = self.connection.make_request('GET', self.name, key_name, |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| if response.status == 200: |
| policy = Policy(self) |
| h = handler.XmlHandler(policy, self) |
| xml.sax.parseString(body, h) |
| return policy |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_subresource(self, subresource, value, key_name='', headers=None, |
| version_id=None): |
| """ |
| Set a subresource for a bucket or key. |
| |
| :type subresource: string |
| :param subresource: The subresource to set. |
| |
| :type value: string |
| :param value: The value of the subresource. |
| |
| :type key_name: string |
| :param key_name: The key to operate on, or None to operate on the |
| bucket. |
| |
| :type headers: dict |
| :param headers: Additional HTTP headers to include in the request. |
| |
| :type src_version_id: string |
| :param src_version_id: Optional. The version id of the key to |
| operate on. If not specified, operate on the newest |
| version. |
| """ |
| if not subresource: |
| raise TypeError('set_subresource called with subresource=None') |
| query_args = subresource |
| if version_id: |
| query_args += '&versionId=%s' % version_id |
| response = self.connection.make_request('PUT', self.name, key_name, |
| data=value.encode('UTF-8'), |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| if response.status != 200: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_subresource(self, subresource, key_name='', headers=None, |
| version_id=None): |
| """ |
| Get a subresource for a bucket or key. |
| |
| :type subresource: string |
| :param subresource: The subresource to get. |
| |
| :type key_name: string |
| :param key_name: The key to operate on, or None to operate on the |
| bucket. |
| |
| :type headers: dict |
| :param headers: Additional HTTP headers to include in the request. |
| |
| :type src_version_id: string |
| :param src_version_id: Optional. The version id of the key to |
| operate on. If not specified, operate on the newest |
| version. |
| |
| :rtype: string |
| :returns: The value of the subresource. |
| """ |
| if not subresource: |
| raise TypeError('get_subresource called with subresource=None') |
| query_args = subresource |
| if version_id: |
| query_args += '&versionId=%s' % version_id |
| response = self.connection.make_request('GET', self.name, key_name, |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| if response.status != 200: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| return body |
| |
| def make_public(self, recursive=False, headers=None): |
| self.set_canned_acl('public-read', headers=headers) |
| if recursive: |
| for key in self: |
| self.set_canned_acl('public-read', key.name, headers=headers) |
| |
| def add_email_grant(self, permission, email_address, |
| recursive=False, headers=None): |
| """ |
| Convenience method that provides a quick way to add an email grant |
| to a bucket. This method retrieves the current ACL, creates a new |
| grant based on the parameters passed in, adds that grant to the ACL |
| and then PUT's the new ACL back to S3. |
| |
| :type permission: string |
| :param permission: The permission being granted. Should be one of: |
| (READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL). |
| |
| :type email_address: string |
| :param email_address: The email address associated with the AWS |
| account your are granting the permission to. |
| |
| :type recursive: boolean |
| :param recursive: A boolean value to controls whether the |
| command will apply the grant to all keys within the bucket |
| or not. The default value is False. By passing a True |
| value, the call will iterate through all keys in the |
| bucket and apply the same grant to each key. CAUTION: If |
| you have a lot of keys, this could take a long time! |
| """ |
| if permission not in S3Permissions: |
| raise self.connection.provider.storage_permissions_error( |
| 'Unknown Permission: %s' % permission) |
| policy = self.get_acl(headers=headers) |
| policy.acl.add_email_grant(permission, email_address) |
| self.set_acl(policy, headers=headers) |
| if recursive: |
| for key in self: |
| key.add_email_grant(permission, email_address, headers=headers) |
| |
| def add_user_grant(self, permission, user_id, recursive=False, |
| headers=None, display_name=None): |
| """ |
| Convenience method that provides a quick way to add a canonical |
| user grant to a bucket. This method retrieves the current ACL, |
| creates a new grant based on the parameters passed in, adds that |
| grant to the ACL and then PUT's the new ACL back to S3. |
| |
| :type permission: string |
| :param permission: The permission being granted. Should be one of: |
| (READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL). |
| |
| :type user_id: string |
| :param user_id: The canonical user id associated with the AWS |
| account your are granting the permission to. |
| |
| :type recursive: boolean |
| :param recursive: A boolean value to controls whether the |
| command will apply the grant to all keys within the bucket |
| or not. The default value is False. By passing a True |
| value, the call will iterate through all keys in the |
| bucket and apply the same grant to each key. CAUTION: If |
| you have a lot of keys, this could take a long time! |
| |
| :type display_name: string |
| :param display_name: An option string containing the user's |
| Display Name. Only required on Walrus. |
| """ |
| if permission not in S3Permissions: |
| raise self.connection.provider.storage_permissions_error( |
| 'Unknown Permission: %s' % permission) |
| policy = self.get_acl(headers=headers) |
| policy.acl.add_user_grant(permission, user_id, |
| display_name=display_name) |
| self.set_acl(policy, headers=headers) |
| if recursive: |
| for key in self: |
| key.add_user_grant(permission, user_id, headers=headers, |
| display_name=display_name) |
| |
| def list_grants(self, headers=None): |
| policy = self.get_acl(headers=headers) |
| return policy.acl.grants |
| |
| def get_location(self): |
| """ |
| Returns the LocationConstraint for the bucket. |
| |
| :rtype: str |
| :return: The LocationConstraint for the bucket or the empty |
| string if no constraint was specified when bucket was created. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='location') |
| body = response.read() |
| if response.status == 200: |
| rs = ResultSet(self) |
| h = handler.XmlHandler(rs, self) |
| xml.sax.parseString(body, h) |
| return rs.LocationConstraint |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_xml_logging(self, logging_str, headers=None): |
| """ |
| Set logging on a bucket directly to the given xml string. |
| |
| :type logging_str: unicode string |
| :param logging_str: The XML for the bucketloggingstatus which |
| will be set. The string will be converted to utf-8 before |
| it is sent. Usually, you will obtain this XML from the |
| BucketLogging object. |
| |
| :rtype: bool |
| :return: True if ok or raises an exception. |
| """ |
| body = logging_str.encode('utf-8') |
| response = self.connection.make_request('PUT', self.name, data=body, |
| query_args='logging', headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def enable_logging(self, target_bucket, target_prefix='', |
| grants=None, headers=None): |
| """ |
| Enable logging on a bucket. |
| |
| :type target_bucket: bucket or string |
| :param target_bucket: The bucket to log to. |
| |
| :type target_prefix: string |
| :param target_prefix: The prefix which should be prepended to the |
| generated log files written to the target_bucket. |
| |
| :type grants: list of Grant objects |
| :param grants: A list of extra permissions which will be granted on |
| the log files which are created. |
| |
| :rtype: bool |
| :return: True if ok or raises an exception. |
| """ |
| if isinstance(target_bucket, Bucket): |
| target_bucket = target_bucket.name |
| blogging = BucketLogging(target=target_bucket, prefix=target_prefix, |
| grants=grants) |
| return self.set_xml_logging(blogging.to_xml(), headers=headers) |
| |
| def disable_logging(self, headers=None): |
| """ |
| Disable logging on a bucket. |
| |
| :rtype: bool |
| :return: True if ok or raises an exception. |
| """ |
| blogging = BucketLogging() |
| return self.set_xml_logging(blogging.to_xml(), headers=headers) |
| |
| def get_logging_status(self, headers=None): |
| """ |
| Get the logging status for this bucket. |
| |
| :rtype: :class:`boto.s3.bucketlogging.BucketLogging` |
| :return: A BucketLogging object for this bucket. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='logging', headers=headers) |
| body = response.read() |
| if response.status == 200: |
| blogging = BucketLogging() |
| h = handler.XmlHandler(blogging, self) |
| xml.sax.parseString(body, h) |
| return blogging |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_as_logging_target(self, headers=None): |
| """ |
| Setup the current bucket as a logging target by granting the necessary |
| permissions to the LogDelivery group to write log files to this bucket. |
| """ |
| policy = self.get_acl(headers=headers) |
| g1 = Grant(permission='WRITE', type='Group', uri=self.LoggingGroup) |
| g2 = Grant(permission='READ_ACP', type='Group', uri=self.LoggingGroup) |
| policy.acl.add_grant(g1) |
| policy.acl.add_grant(g2) |
| self.set_acl(policy, headers=headers) |
| |
| def get_request_payment(self, headers=None): |
| response = self.connection.make_request('GET', self.name, |
| query_args='requestPayment', headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return body |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_request_payment(self, payer='BucketOwner', headers=None): |
| body = self.BucketPaymentBody % payer |
| response = self.connection.make_request('PUT', self.name, data=body, |
| query_args='requestPayment', headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def configure_versioning(self, versioning, mfa_delete=False, |
| mfa_token=None, headers=None): |
| """ |
| Configure versioning for this bucket. |
| |
| ..note:: This feature is currently in beta. |
| |
| :type versioning: bool |
| :param versioning: A boolean indicating whether version is |
| enabled (True) or disabled (False). |
| |
| :type mfa_delete: bool |
| :param mfa_delete: A boolean indicating whether the |
| Multi-Factor Authentication Delete feature is enabled |
| (True) or disabled (False). If mfa_delete is enabled then |
| all Delete operations will require the token from your MFA |
| device to be passed in the request. |
| |
| :type mfa_token: tuple or list of strings |
| :param mfa_token: A tuple or list consisting of the serial |
| number from the MFA device and the current value of the |
| six-digit token associated with the device. This value is |
| required when you are changing the status of the MfaDelete |
| property of the bucket. |
| """ |
| if versioning: |
| ver = 'Enabled' |
| else: |
| ver = 'Suspended' |
| if mfa_delete: |
| mfa = 'Enabled' |
| else: |
| mfa = 'Disabled' |
| body = self.VersioningBody % (ver, mfa) |
| if mfa_token: |
| if not headers: |
| headers = {} |
| provider = self.connection.provider |
| headers[provider.mfa_header] = ' '.join(mfa_token) |
| response = self.connection.make_request('PUT', self.name, data=body, |
| query_args='versioning', headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_versioning_status(self, headers=None): |
| """ |
| Returns the current status of versioning on the bucket. |
| |
| :rtype: dict |
| :returns: A dictionary containing a key named 'Versioning' |
| that can have a value of either Enabled, Disabled, or |
| Suspended. Also, if MFADelete has ever been enabled on the |
| bucket, the dictionary will contain a key named |
| 'MFADelete' which will have a value of either Enabled or |
| Suspended. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='versioning', headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 200: |
| d = {} |
| ver = re.search(self.VersionRE, body) |
| if ver: |
| d['Versioning'] = ver.group(1) |
| mfa = re.search(self.MFADeleteRE, body) |
| if mfa: |
| d['MfaDelete'] = mfa.group(1) |
| return d |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def configure_lifecycle(self, lifecycle_config, headers=None): |
| """ |
| Configure lifecycle for this bucket. |
| |
| :type lifecycle_config: :class:`boto.s3.lifecycle.Lifecycle` |
| :param lifecycle_config: The lifecycle configuration you want |
| to configure for this bucket. |
| """ |
| xml = lifecycle_config.to_xml() |
| xml = xml.encode('utf-8') |
| fp = StringIO.StringIO(xml) |
| md5 = boto.utils.compute_md5(fp) |
| if headers is None: |
| headers = {} |
| headers['Content-MD5'] = md5[1] |
| headers['Content-Type'] = 'text/xml' |
| response = self.connection.make_request('PUT', self.name, |
| data=fp.getvalue(), |
| query_args='lifecycle', |
| headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_lifecycle_config(self, headers=None): |
| """ |
| Returns the current lifecycle configuration on the bucket. |
| |
| :rtype: :class:`boto.s3.lifecycle.Lifecycle` |
| :returns: A LifecycleConfig object that describes all current |
| lifecycle rules in effect for the bucket. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='lifecycle', headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 200: |
| lifecycle = Lifecycle() |
| h = handler.XmlHandler(lifecycle, self) |
| xml.sax.parseString(body, h) |
| return lifecycle |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def delete_lifecycle_configuration(self, headers=None): |
| """ |
| Removes all lifecycle configuration from the bucket. |
| """ |
| response = self.connection.make_request('DELETE', self.name, |
| query_args='lifecycle', |
| headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 204: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def configure_website(self, suffix=None, error_key=None, |
| redirect_all_requests_to=None, |
| routing_rules=None, |
| headers=None): |
| """ |
| Configure this bucket to act as a website |
| |
| :type suffix: str |
| :param suffix: Suffix that is appended to a request that is for a |
| "directory" on the website endpoint (e.g. if the suffix is |
| index.html and you make a request to samplebucket/images/ |
| the data that is returned will be for the object with the |
| key name images/index.html). The suffix must not be empty |
| and must not include a slash character. |
| |
| :type error_key: str |
| :param error_key: The object key name to use when a 4XX class |
| error occurs. This is optional. |
| |
| :type redirect_all_requests_to: :class:`boto.s3.website.RedirectLocation` |
| :param redirect_all_requests_to: Describes the redirect behavior for |
| every request to this bucket's website endpoint. If this value is |
| non None, no other values are considered when configuring the |
| website configuration for the bucket. This is an instance of |
| ``RedirectLocation``. |
| |
| :type routing_rules: :class:`boto.s3.website.RoutingRules` |
| :param routing_rules: Object which specifies conditions |
| and redirects that apply when the conditions are met. |
| |
| """ |
| config = website.WebsiteConfiguration( |
| suffix, error_key, redirect_all_requests_to, |
| routing_rules) |
| body = config.to_xml() |
| response = self.connection.make_request('PUT', self.name, data=body, |
| query_args='website', |
| headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_website_configuration(self, headers=None): |
| """ |
| Returns the current status of website configuration on the bucket. |
| |
| :rtype: dict |
| :returns: A dictionary containing a Python representation |
| of the XML response from S3. The overall structure is: |
| |
| * WebsiteConfiguration |
| |
| * IndexDocument |
| |
| * Suffix : suffix that is appended to request that |
| is for a "directory" on the website endpoint |
| * ErrorDocument |
| |
| * Key : name of object to serve when an error occurs |
| """ |
| return self.get_website_configuration_with_xml(headers)[0] |
| |
| def get_website_configuration_with_xml(self, headers=None): |
| """ |
| Returns the current status of website configuration on the bucket as |
| unparsed XML. |
| |
| :rtype: 2-Tuple |
| :returns: 2-tuple containing: |
| 1) A dictionary containing a Python representation |
| of the XML response. The overall structure is: |
| * WebsiteConfiguration |
| * IndexDocument |
| * Suffix : suffix that is appended to request that |
| is for a "directory" on the website endpoint |
| * ErrorDocument |
| * Key : name of object to serve when an error occurs |
| 2) unparsed XML describing the bucket's website configuration. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='website', headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| |
| if response.status != 200: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| e = boto.jsonresponse.Element() |
| h = boto.jsonresponse.XmlHandler(e, None) |
| h.parse(body) |
| return e, body |
| |
| def delete_website_configuration(self, headers=None): |
| """ |
| Removes all website configuration from the bucket. |
| """ |
| response = self.connection.make_request('DELETE', self.name, |
| query_args='website', headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 204: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_website_endpoint(self): |
| """ |
| Returns the fully qualified hostname to use is you want to access this |
| bucket as a website. This doesn't validate whether the bucket has |
| been correctly configured as a website or not. |
| """ |
| l = [self.name] |
| l.append(S3WebsiteEndpointTranslate.translate_region(self.get_location())) |
| l.append('.'.join(self.connection.host.split('.')[-2:])) |
| return '.'.join(l) |
| |
| def get_policy(self, headers=None): |
| """ |
| Returns the JSON policy associated with the bucket. The policy |
| is returned as an uninterpreted JSON string. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='policy', headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return body |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_policy(self, policy, headers=None): |
| """ |
| Add or replace the JSON policy associated with the bucket. |
| |
| :type policy: str |
| :param policy: The JSON policy as a string. |
| """ |
| response = self.connection.make_request('PUT', self.name, |
| data=policy, |
| query_args='policy', |
| headers=headers) |
| body = response.read() |
| if response.status >= 200 and response.status <= 204: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def delete_policy(self, headers=None): |
| response = self.connection.make_request('DELETE', self.name, |
| data='/?policy', |
| query_args='policy', |
| headers=headers) |
| body = response.read() |
| if response.status >= 200 and response.status <= 204: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_cors_xml(self, cors_xml, headers=None): |
| """ |
| Set the CORS (Cross-Origin Resource Sharing) for a bucket. |
| |
| :type cors_xml: str |
| :param cors_xml: The XML document describing your desired |
| CORS configuration. See the S3 documentation for details |
| of the exact syntax required. |
| """ |
| fp = StringIO.StringIO(cors_xml) |
| md5 = boto.utils.compute_md5(fp) |
| if headers is None: |
| headers = {} |
| headers['Content-MD5'] = md5[1] |
| headers['Content-Type'] = 'text/xml' |
| response = self.connection.make_request('PUT', self.name, |
| data=fp.getvalue(), |
| query_args='cors', |
| headers=headers) |
| body = response.read() |
| if response.status == 200: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_cors(self, cors_config, headers=None): |
| """ |
| Set the CORS for this bucket given a boto CORSConfiguration |
| object. |
| |
| :type cors_config: :class:`boto.s3.cors.CORSConfiguration` |
| :param cors_config: The CORS configuration you want |
| to configure for this bucket. |
| """ |
| return self.set_cors_xml(cors_config.to_xml()) |
| |
| def get_cors_xml(self, headers=None): |
| """ |
| Returns the current CORS configuration on the bucket as an |
| XML document. |
| """ |
| response = self.connection.make_request('GET', self.name, |
| query_args='cors', headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 200: |
| return body |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def get_cors(self, headers=None): |
| """ |
| Returns the current CORS configuration on the bucket. |
| |
| :rtype: :class:`boto.s3.cors.CORSConfiguration` |
| :returns: A CORSConfiguration object that describes all current |
| CORS rules in effect for the bucket. |
| """ |
| body = self.get_cors_xml(headers) |
| cors = CORSConfiguration() |
| h = handler.XmlHandler(cors, self) |
| xml.sax.parseString(body, h) |
| return cors |
| |
| def delete_cors(self, headers=None): |
| """ |
| Removes all CORS configuration from the bucket. |
| """ |
| response = self.connection.make_request('DELETE', self.name, |
| query_args='cors', |
| headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 204: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def initiate_multipart_upload(self, key_name, headers=None, |
| reduced_redundancy=False, |
| metadata=None, encrypt_key=False, |
| policy=None): |
| """ |
| Start a multipart upload operation. |
| |
| :type key_name: string |
| :param key_name: The name of the key that will ultimately |
| result from this multipart upload operation. This will be |
| exactly as the key appears in the bucket after the upload |
| process has been completed. |
| |
| :type headers: dict |
| :param headers: Additional HTTP headers to send and store with the |
| resulting key in S3. |
| |
| :type reduced_redundancy: boolean |
| :param reduced_redundancy: In multipart uploads, the storage |
| class is specified when initiating the upload, not when |
| uploading individual parts. So if you want the resulting |
| key to use the reduced redundancy storage class set this |
| flag when you initiate the upload. |
| |
| :type metadata: dict |
| :param metadata: Any metadata that you would like to set on the key |
| that results from the multipart upload. |
| |
| :type encrypt_key: bool |
| :param encrypt_key: If True, the new copy of the object will |
| be encrypted on the server-side by S3 and will be stored |
| in an encrypted form while at rest in S3. |
| |
| :type policy: :class:`boto.s3.acl.CannedACLStrings` |
| :param policy: A canned ACL policy that will be applied to the |
| new key (once completed) in S3. |
| """ |
| query_args = 'uploads' |
| provider = self.connection.provider |
| headers = headers or {} |
| if policy: |
| headers[provider.acl_header] = policy |
| if reduced_redundancy: |
| storage_class_header = provider.storage_class_header |
| if storage_class_header: |
| headers[storage_class_header] = 'REDUCED_REDUNDANCY' |
| # TODO: what if the provider doesn't support reduced redundancy? |
| # (see boto.s3.key.Key.set_contents_from_file) |
| if encrypt_key: |
| headers[provider.server_side_encryption_header] = 'AES256' |
| if metadata is None: |
| metadata = {} |
| |
| headers = boto.utils.merge_meta(headers, metadata, |
| self.connection.provider) |
| response = self.connection.make_request('POST', self.name, key_name, |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 200: |
| resp = MultiPartUpload(self) |
| h = handler.XmlHandler(resp, self) |
| xml.sax.parseString(body, h) |
| return resp |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def complete_multipart_upload(self, key_name, upload_id, |
| xml_body, headers=None): |
| """ |
| Complete a multipart upload operation. |
| """ |
| query_args = 'uploadId=%s' % upload_id |
| if headers is None: |
| headers = {} |
| headers['Content-Type'] = 'text/xml' |
| response = self.connection.make_request('POST', self.name, key_name, |
| query_args=query_args, |
| headers=headers, data=xml_body) |
| contains_error = False |
| body = response.read() |
| # Some errors will be reported in the body of the response |
| # even though the HTTP response code is 200. This check |
| # does a quick and dirty peek in the body for an error element. |
| if body.find('<Error>') > 0: |
| contains_error = True |
| boto.log.debug(body) |
| if response.status == 200 and not contains_error: |
| resp = CompleteMultiPartUpload(self) |
| h = handler.XmlHandler(resp, self) |
| xml.sax.parseString(body, h) |
| # Use a dummy key to parse various response headers |
| # for versioning, encryption info and then explicitly |
| # set the completed MPU object values from key. |
| k = self.key_class(self) |
| k.handle_version_headers(response) |
| k.handle_encryption_headers(response) |
| resp.version_id = k.version_id |
| resp.encrypted = k.encrypted |
| return resp |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def cancel_multipart_upload(self, key_name, upload_id, headers=None): |
| query_args = 'uploadId=%s' % upload_id |
| response = self.connection.make_request('DELETE', self.name, key_name, |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status != 204: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def delete(self, headers=None): |
| return self.connection.delete_bucket(self.name, headers=headers) |
| |
| def get_tags(self): |
| response = self.get_xml_tags() |
| tags = Tags() |
| h = handler.XmlHandler(tags, self) |
| xml.sax.parseString(response, h) |
| return tags |
| |
| def get_xml_tags(self): |
| response = self.connection.make_request('GET', self.name, |
| query_args='tagging', |
| headers=None) |
| body = response.read() |
| if response.status == 200: |
| return body |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| |
| def set_xml_tags(self, tag_str, headers=None, query_args='tagging'): |
| if headers is None: |
| headers = {} |
| md5 = boto.utils.compute_md5(StringIO.StringIO(tag_str)) |
| headers['Content-MD5'] = md5[1] |
| headers['Content-Type'] = 'text/xml' |
| response = self.connection.make_request('PUT', self.name, |
| data=tag_str.encode('utf-8'), |
| query_args=query_args, |
| headers=headers) |
| body = response.read() |
| if response.status != 204: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
| return True |
| |
| def set_tags(self, tags, headers=None): |
| return self.set_xml_tags(tags.to_xml(), headers=headers) |
| |
| def delete_tags(self, headers=None): |
| response = self.connection.make_request('DELETE', self.name, |
| query_args='tagging', |
| headers=headers) |
| body = response.read() |
| boto.log.debug(body) |
| if response.status == 204: |
| return True |
| else: |
| raise self.connection.provider.storage_response_error( |
| response.status, response.reason, body) |
