You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
705 lines
31 KiB
Python
705 lines
31 KiB
Python
# Copyright 2010 Google Inc.
|
|
#
|
|
# 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 base64
|
|
import binascii
|
|
import os
|
|
import re
|
|
import StringIO
|
|
from boto.exception import BotoClientError
|
|
from boto.s3.key import Key as S3Key
|
|
from boto.s3.keyfile import KeyFile
|
|
|
|
class Key(S3Key):
|
|
"""
|
|
Represents a key (object) in a GS bucket.
|
|
|
|
:ivar bucket: The parent :class:`boto.gs.bucket.Bucket`.
|
|
:ivar name: The name of this Key object.
|
|
:ivar metadata: A dictionary containing user metadata that you
|
|
wish to store with the object or that has been retrieved from
|
|
an existing object.
|
|
:ivar cache_control: The value of the `Cache-Control` HTTP header.
|
|
:ivar content_type: The value of the `Content-Type` HTTP header.
|
|
:ivar content_encoding: The value of the `Content-Encoding` HTTP header.
|
|
:ivar content_disposition: The value of the `Content-Disposition` HTTP
|
|
header.
|
|
:ivar content_language: The value of the `Content-Language` HTTP header.
|
|
:ivar etag: The `etag` associated with this object.
|
|
:ivar last_modified: The string timestamp representing the last
|
|
time this object was modified in GS.
|
|
:ivar owner: The ID of the owner of this object.
|
|
:ivar storage_class: The storage class of the object. Currently, one of:
|
|
STANDARD | DURABLE_REDUCED_AVAILABILITY.
|
|
:ivar md5: The MD5 hash of the contents of the object.
|
|
:ivar size: The size, in bytes, of the object.
|
|
:ivar generation: The generation number of the object.
|
|
:ivar meta_generation: The generation number of the object metadata.
|
|
:ivar encrypted: Whether the object is encrypted while at rest on
|
|
the server.
|
|
"""
|
|
generation = None
|
|
meta_generation = None
|
|
|
|
def __repr__(self):
|
|
if self.generation and self.meta_generation:
|
|
ver_str = '#%s.%s' % (self.generation, self.meta_generation)
|
|
else:
|
|
ver_str = ''
|
|
if self.bucket:
|
|
return '<Key: %s,%s%s>' % (self.bucket.name, self.name, ver_str)
|
|
else:
|
|
return '<Key: None,%s%s>' % (self.name, ver_str)
|
|
|
|
def endElement(self, name, value, connection):
|
|
if name == 'Key':
|
|
self.name = value
|
|
elif name == 'ETag':
|
|
self.etag = value
|
|
elif name == 'IsLatest':
|
|
if value == 'true':
|
|
self.is_latest = True
|
|
else:
|
|
self.is_latest = False
|
|
elif name == 'LastModified':
|
|
self.last_modified = value
|
|
elif name == 'Size':
|
|
self.size = int(value)
|
|
elif name == 'StorageClass':
|
|
self.storage_class = value
|
|
elif name == 'Owner':
|
|
pass
|
|
elif name == 'VersionId':
|
|
self.version_id = value
|
|
elif name == 'Generation':
|
|
self.generation = value
|
|
elif name == 'MetaGeneration':
|
|
self.meta_generation = value
|
|
else:
|
|
setattr(self, name, value)
|
|
|
|
def handle_version_headers(self, resp, force=False):
|
|
self.meta_generation = resp.getheader('x-goog-metageneration', None)
|
|
self.generation = resp.getheader('x-goog-generation', None)
|
|
|
|
def get_file(self, fp, headers=None, cb=None, num_cb=10,
|
|
torrent=False, version_id=None, override_num_retries=None,
|
|
response_headers=None):
|
|
query_args = None
|
|
if self.generation:
|
|
query_args = ['generation=%s' % self.generation]
|
|
self._get_file_internal(fp, headers=headers, cb=cb, num_cb=num_cb,
|
|
override_num_retries=override_num_retries,
|
|
response_headers=response_headers,
|
|
query_args=query_args)
|
|
|
|
def delete(self):
|
|
return self.bucket.delete_key(self.name, version_id=self.version_id,
|
|
generation=self.generation)
|
|
|
|
def add_email_grant(self, permission, email_address):
|
|
"""
|
|
Convenience method that provides a quick way to add an email grant to a
|
|
key. 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 GS.
|
|
|
|
:type permission: string
|
|
:param permission: The permission being granted. Should be one of:
|
|
READ|FULL_CONTROL
|
|
See http://code.google.com/apis/storage/docs/developer-guide.html#authorization
|
|
for more details on permissions.
|
|
|
|
:type email_address: string
|
|
:param email_address: The email address associated with the Google
|
|
account to which you are granting the permission.
|
|
"""
|
|
acl = self.get_acl()
|
|
acl.add_email_grant(permission, email_address)
|
|
self.set_acl(acl)
|
|
|
|
def add_user_grant(self, permission, user_id):
|
|
"""
|
|
Convenience method that provides a quick way to add a canonical user
|
|
grant to a key. 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 GS.
|
|
|
|
:type permission: string
|
|
:param permission: The permission being granted. Should be one of:
|
|
READ|FULL_CONTROL
|
|
See http://code.google.com/apis/storage/docs/developer-guide.html#authorization
|
|
for more details on permissions.
|
|
|
|
:type user_id: string
|
|
:param user_id: The canonical user id associated with the GS account to
|
|
which you are granting the permission.
|
|
"""
|
|
acl = self.get_acl()
|
|
acl.add_user_grant(permission, user_id)
|
|
self.set_acl(acl)
|
|
|
|
def add_group_email_grant(self, permission, email_address, headers=None):
|
|
"""
|
|
Convenience method that provides a quick way to add an email group
|
|
grant to a key. 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 GS.
|
|
|
|
:type permission: string
|
|
:param permission: The permission being granted. Should be one of:
|
|
READ|FULL_CONTROL
|
|
See http://code.google.com/apis/storage/docs/developer-guide.html#authorization
|
|
for more details on permissions.
|
|
|
|
:type email_address: string
|
|
:param email_address: The email address associated with the Google
|
|
Group to which you are granting the permission.
|
|
"""
|
|
acl = self.get_acl(headers=headers)
|
|
acl.add_group_email_grant(permission, email_address)
|
|
self.set_acl(acl, headers=headers)
|
|
|
|
def add_group_grant(self, permission, group_id):
|
|
"""
|
|
Convenience method that provides a quick way to add a canonical group
|
|
grant to a key. 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 GS.
|
|
|
|
:type permission: string
|
|
:param permission: The permission being granted. Should be one of:
|
|
READ|FULL_CONTROL
|
|
See http://code.google.com/apis/storage/docs/developer-guide.html#authorization
|
|
for more details on permissions.
|
|
|
|
:type group_id: string
|
|
:param group_id: The canonical group id associated with the Google
|
|
Groups account you are granting the permission to.
|
|
"""
|
|
acl = self.get_acl()
|
|
acl.add_group_grant(permission, group_id)
|
|
self.set_acl(acl)
|
|
|
|
def set_contents_from_file(self, fp, headers=None, replace=True,
|
|
cb=None, num_cb=10, policy=None, md5=None,
|
|
res_upload_handler=None, size=None, rewind=False,
|
|
if_generation=None):
|
|
"""
|
|
Store an object in GS using the name of the Key object as the
|
|
key in GS and the contents of the file pointed to by 'fp' as the
|
|
contents.
|
|
|
|
:type fp: file
|
|
:param fp: the file whose contents are to be uploaded
|
|
|
|
:type headers: dict
|
|
:param headers: additional HTTP headers to be sent with the PUT request.
|
|
|
|
:type replace: bool
|
|
:param replace: If this parameter is False, the method will first check
|
|
to see if an object exists in the bucket with the same key. If it
|
|
does, it won't overwrite it. The default value is True which will
|
|
overwrite the object.
|
|
|
|
:type cb: function
|
|
:param cb: a callback function that will be called to report
|
|
progress on the upload. The callback should accept two integer
|
|
parameters, the first representing the number of bytes that have
|
|
been successfully transmitted to GS and the second representing the
|
|
total number of bytes that need to be transmitted.
|
|
|
|
:type num_cb: int
|
|
:param num_cb: (optional) If a callback is specified with the cb
|
|
parameter, this parameter determines the granularity of the callback
|
|
by defining the maximum number of times the callback will be called
|
|
during the file transfer.
|
|
|
|
:type policy: :class:`boto.gs.acl.CannedACLStrings`
|
|
:param policy: A canned ACL policy that will be applied to the new key
|
|
in GS.
|
|
|
|
:type md5: A tuple containing the hexdigest version of the MD5 checksum
|
|
of the file as the first element and the Base64-encoded version of
|
|
the plain checksum as the second element. This is the same format
|
|
returned by the compute_md5 method.
|
|
:param md5: If you need to compute the MD5 for any reason prior to
|
|
upload, it's silly to have to do it twice so this param, if present,
|
|
will be used as the MD5 values of the file. Otherwise, the checksum
|
|
will be computed.
|
|
|
|
:type res_upload_handler: ResumableUploadHandler
|
|
:param res_upload_handler: If provided, this handler will perform the
|
|
upload.
|
|
|
|
:type size: int
|
|
:param size: (optional) The Maximum number of bytes to read from
|
|
the file pointer (fp). This is useful when uploading
|
|
a file in multiple parts where you are splitting the
|
|
file up into different ranges to be uploaded. If not
|
|
specified, the default behaviour is to read all bytes
|
|
from the file pointer. Less bytes may be available.
|
|
Notes:
|
|
|
|
1. The "size" parameter currently cannot be used when
|
|
a resumable upload handler is given but is still
|
|
useful for uploading part of a file as implemented
|
|
by the parent class.
|
|
2. At present Google Cloud Storage does not support
|
|
multipart uploads.
|
|
|
|
:type rewind: bool
|
|
:param rewind: (optional) If True, the file pointer (fp) will be
|
|
rewound to the start before any bytes are read from
|
|
it. The default behaviour is False which reads from
|
|
the current position of the file pointer (fp).
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the
|
|
object will only be written to if its current generation number is
|
|
this value. If set to the value 0, the object will only be written
|
|
if it doesn't already exist.
|
|
|
|
:rtype: int
|
|
:return: The number of bytes written to the key.
|
|
|
|
TODO: At some point we should refactor the Bucket and Key classes,
|
|
to move functionality common to all providers into a parent class,
|
|
and provider-specific functionality into subclasses (rather than
|
|
just overriding/sharing code the way it currently works).
|
|
"""
|
|
provider = self.bucket.connection.provider
|
|
if res_upload_handler and size:
|
|
# could use size instead of file_length if provided but...
|
|
raise BotoClientError('"size" param not supported for resumable uploads.')
|
|
headers = headers or {}
|
|
if policy:
|
|
headers[provider.acl_header] = policy
|
|
|
|
if rewind:
|
|
# caller requests reading from beginning of fp.
|
|
fp.seek(0, os.SEEK_SET)
|
|
else:
|
|
# The following seek/tell/seek logic is intended
|
|
# to detect applications using the older interface to
|
|
# set_contents_from_file(), which automatically rewound the
|
|
# file each time the Key was reused. This changed with commit
|
|
# 14ee2d03f4665fe20d19a85286f78d39d924237e, to support uploads
|
|
# split into multiple parts and uploaded in parallel, and at
|
|
# the time of that commit this check was added because otherwise
|
|
# older programs would get a success status and upload an empty
|
|
# object. Unfortuantely, it's very inefficient for fp's implemented
|
|
# by KeyFile (used, for example, by gsutil when copying between
|
|
# providers). So, we skip the check for the KeyFile case.
|
|
# TODO: At some point consider removing this seek/tell/seek
|
|
# logic, after enough time has passed that it's unlikely any
|
|
# programs remain that assume the older auto-rewind interface.
|
|
if not isinstance(fp, KeyFile):
|
|
spos = fp.tell()
|
|
fp.seek(0, os.SEEK_END)
|
|
if fp.tell() == spos:
|
|
fp.seek(0, os.SEEK_SET)
|
|
if fp.tell() != spos:
|
|
# Raise an exception as this is likely a programming
|
|
# error whereby there is data before the fp but nothing
|
|
# after it.
|
|
fp.seek(spos)
|
|
raise AttributeError('fp is at EOF. Use rewind option '
|
|
'or seek() to data start.')
|
|
# seek back to the correct position.
|
|
fp.seek(spos)
|
|
|
|
if hasattr(fp, 'name'):
|
|
self.path = fp.name
|
|
if self.bucket != None:
|
|
if isinstance(fp, KeyFile):
|
|
# Avoid EOF seek for KeyFile case as it's very inefficient.
|
|
key = fp.getkey()
|
|
size = key.size - fp.tell()
|
|
self.size = size
|
|
# At present both GCS and S3 use MD5 for the etag for
|
|
# non-multipart-uploaded objects. If the etag is 32 hex
|
|
# chars use it as an MD5, to avoid having to read the file
|
|
# twice while transferring.
|
|
if (re.match('^"[a-fA-F0-9]{32}"$', key.etag)):
|
|
etag = key.etag.strip('"')
|
|
md5 = (etag, base64.b64encode(binascii.unhexlify(etag)))
|
|
if size:
|
|
self.size = size
|
|
else:
|
|
# If md5 is provided, still need to size so
|
|
# calculate based on bytes to end of content
|
|
spos = fp.tell()
|
|
fp.seek(0, os.SEEK_END)
|
|
self.size = fp.tell() - spos
|
|
fp.seek(spos)
|
|
size = self.size
|
|
|
|
if md5 == None:
|
|
md5 = self.compute_md5(fp, size)
|
|
self.md5 = md5[0]
|
|
self.base64md5 = md5[1]
|
|
|
|
if self.name == None:
|
|
self.name = self.md5
|
|
|
|
if not replace:
|
|
if self.bucket.lookup(self.name):
|
|
return
|
|
|
|
if if_generation is not None:
|
|
headers['x-goog-if-generation-match'] = str(if_generation)
|
|
|
|
if res_upload_handler:
|
|
res_upload_handler.send_file(self, fp, headers, cb, num_cb)
|
|
else:
|
|
# Not a resumable transfer so use basic send_file mechanism.
|
|
self.send_file(fp, headers, cb, num_cb, size=size)
|
|
|
|
def set_contents_from_filename(self, filename, headers=None, replace=True,
|
|
cb=None, num_cb=10, policy=None, md5=None,
|
|
reduced_redundancy=None,
|
|
res_upload_handler=None,
|
|
if_generation=None):
|
|
"""
|
|
Store an object in GS using the name of the Key object as the
|
|
key in GS and the contents of the file named by 'filename'.
|
|
See set_contents_from_file method for details about the
|
|
parameters.
|
|
|
|
:type filename: string
|
|
:param filename: The name of the file that you want to put onto GS
|
|
|
|
:type headers: dict
|
|
:param headers: Additional headers to pass along with the request to GS.
|
|
|
|
:type replace: bool
|
|
:param replace: If True, replaces the contents of the file if it
|
|
already exists.
|
|
|
|
:type cb: function
|
|
:param cb: (optional) a callback function that will be called to report
|
|
progress on the download. The callback should accept two integer
|
|
parameters, the first representing the number of bytes that have
|
|
been successfully transmitted from GS and the second representing
|
|
the total number of bytes that need to be transmitted.
|
|
|
|
:type cb: int
|
|
:param num_cb: (optional) If a callback is specified with the cb
|
|
parameter this parameter determines the granularity of the callback
|
|
by defining the maximum number of times the callback will be called
|
|
during the file transfer.
|
|
|
|
:type policy: :class:`boto.gs.acl.CannedACLStrings`
|
|
:param policy: A canned ACL policy that will be applied to the new key
|
|
in GS.
|
|
|
|
:type md5: A tuple containing the hexdigest version of the MD5 checksum
|
|
of the file as the first element and the Base64-encoded version of
|
|
the plain checksum as the second element. This is the same format
|
|
returned by the compute_md5 method.
|
|
:param md5: If you need to compute the MD5 for any reason prior to
|
|
upload, it's silly to have to do it twice so this param, if present,
|
|
will be used as the MD5 values of the file. Otherwise, the checksum
|
|
will be computed.
|
|
|
|
:type res_upload_handler: ResumableUploadHandler
|
|
:param res_upload_handler: If provided, this handler will perform the
|
|
upload.
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the
|
|
object will only be written to if its current generation number is
|
|
this value. If set to the value 0, the object will only be written
|
|
if it doesn't already exist.
|
|
"""
|
|
# Clear out any previously computed md5 hashes, since we are setting the content.
|
|
self.md5 = None
|
|
self.base64md5 = None
|
|
|
|
fp = open(filename, 'rb')
|
|
self.set_contents_from_file(fp, headers, replace, cb, num_cb,
|
|
policy, md5, res_upload_handler,
|
|
if_generation=if_generation)
|
|
fp.close()
|
|
|
|
def set_contents_from_string(self, s, headers=None, replace=True,
|
|
cb=None, num_cb=10, policy=None, md5=None,
|
|
if_generation=None):
|
|
"""
|
|
Store an object in S3 using the name of the Key object as the
|
|
key in S3 and the string 's' as the contents.
|
|
See set_contents_from_file method for details about the
|
|
parameters.
|
|
|
|
:type headers: dict
|
|
:param headers: Additional headers to pass along with the
|
|
request to AWS.
|
|
|
|
:type replace: bool
|
|
:param replace: If True, replaces the contents of the file if
|
|
it already exists.
|
|
|
|
:type cb: function
|
|
:param cb: a callback function that will be called to report
|
|
progress on the upload. The callback should accept
|
|
two integer parameters, the first representing the
|
|
number of bytes that have been successfully
|
|
transmitted to S3 and the second representing the
|
|
size of the to be transmitted object.
|
|
|
|
:type cb: int
|
|
:param num_cb: (optional) If a callback is specified with
|
|
the cb parameter this parameter determines the
|
|
granularity of the callback by defining
|
|
the maximum number of times the callback will
|
|
be called during the file transfer.
|
|
|
|
:type policy: :class:`boto.s3.acl.CannedACLStrings`
|
|
:param policy: A canned ACL policy that will be applied to the
|
|
new key in S3.
|
|
|
|
:type md5: A tuple containing the hexdigest version of the MD5
|
|
checksum of the file as the first element and the
|
|
Base64-encoded version of the plain checksum as the
|
|
second element. This is the same format returned by
|
|
the compute_md5 method.
|
|
:param md5: If you need to compute the MD5 for any reason prior
|
|
to upload, it's silly to have to do it twice so this
|
|
param, if present, will be used as the MD5 values
|
|
of the file. Otherwise, the checksum will be computed.
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the
|
|
object will only be written to if its current generation number is
|
|
this value. If set to the value 0, the object will only be written
|
|
if it doesn't already exist.
|
|
"""
|
|
|
|
# Clear out any previously computed md5 hashes, since we are setting the content.
|
|
self.md5 = None
|
|
self.base64md5 = None
|
|
|
|
if isinstance(s, unicode):
|
|
s = s.encode("utf-8")
|
|
fp = StringIO.StringIO(s)
|
|
r = self.set_contents_from_file(fp, headers, replace, cb, num_cb,
|
|
policy, md5,
|
|
if_generation=if_generation)
|
|
fp.close()
|
|
return r
|
|
|
|
def set_contents_from_stream(self, *args, **kwargs):
|
|
"""
|
|
Store an object using the name of the Key object as the key in
|
|
cloud and the contents of the data stream pointed to by 'fp' as
|
|
the contents.
|
|
|
|
The stream object is not seekable and total size is not known.
|
|
This has the implication that we can't specify the
|
|
Content-Size and Content-MD5 in the header. So for huge
|
|
uploads, the delay in calculating MD5 is avoided but with a
|
|
penalty of inability to verify the integrity of the uploaded
|
|
data.
|
|
|
|
:type fp: file
|
|
:param fp: the file whose contents are to be uploaded
|
|
|
|
:type headers: dict
|
|
:param headers: additional HTTP headers to be sent with the
|
|
PUT request.
|
|
|
|
:type replace: bool
|
|
:param replace: If this parameter is False, the method will first check
|
|
to see if an object exists in the bucket with the same key. If it
|
|
does, it won't overwrite it. The default value is True which will
|
|
overwrite the object.
|
|
|
|
:type cb: function
|
|
:param cb: a callback function that will be called to report
|
|
progress on the upload. The callback should accept two integer
|
|
parameters, the first representing the number of bytes that have
|
|
been successfully transmitted to GS and the second representing the
|
|
total number of bytes that need to be transmitted.
|
|
|
|
:type num_cb: int
|
|
:param num_cb: (optional) If a callback is specified with the
|
|
cb parameter, this parameter determines the granularity of
|
|
the callback by defining the maximum number of times the
|
|
callback will be called during the file transfer.
|
|
|
|
:type policy: :class:`boto.gs.acl.CannedACLStrings`
|
|
:param policy: A canned ACL policy that will be applied to the new key
|
|
in GS.
|
|
|
|
:type reduced_redundancy: bool
|
|
:param reduced_redundancy: If True, this will set the storage
|
|
class of the new Key to be REDUCED_REDUNDANCY. The Reduced
|
|
Redundancy Storage (RRS) feature of S3, provides lower
|
|
redundancy at lower storage cost.
|
|
|
|
:type size: int
|
|
:param size: (optional) The Maximum number of bytes to read from
|
|
the file pointer (fp). This is useful when uploading a
|
|
file in multiple parts where you are splitting the file up
|
|
into different ranges to be uploaded. If not specified,
|
|
the default behaviour is to read all bytes from the file
|
|
pointer. Less bytes may be available.
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the
|
|
object will only be written to if its current generation number is
|
|
this value. If set to the value 0, the object will only be written
|
|
if it doesn't already exist.
|
|
"""
|
|
if_generation = kwargs.pop('if_generation', None)
|
|
if if_generation is not None:
|
|
headers = kwargs.get('headers', {})
|
|
headers['x-goog-if-generation-match'] = str(if_generation)
|
|
kwargs['headers'] = headers
|
|
super(Key, self).set_contents_from_stream(*args, **kwargs)
|
|
|
|
def set_acl(self, acl_or_str, headers=None, generation=None,
|
|
if_generation=None, if_metageneration=None):
|
|
"""Sets the ACL for this object.
|
|
|
|
:type acl_or_str: string or :class:`boto.gs.acl.ACL`
|
|
:param acl_or_str: A canned ACL string (see
|
|
:data:`~.gs.acl.CannedACLStrings`) or an ACL object.
|
|
|
|
:type headers: dict
|
|
:param headers: Additional headers to set during the request.
|
|
|
|
:type generation: int
|
|
:param generation: If specified, sets the ACL for a specific generation
|
|
of a versioned object. If not specified, the current version is
|
|
modified.
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the acl
|
|
will only be updated if its current generation number is this value.
|
|
|
|
:type if_metageneration: int
|
|
:param if_metageneration: (optional) If set to a metageneration number,
|
|
the acl will only be updated if its current metageneration number is
|
|
this value.
|
|
"""
|
|
if self.bucket != None:
|
|
self.bucket.set_acl(acl_or_str, self.name, headers=headers,
|
|
generation=generation,
|
|
if_generation=if_generation,
|
|
if_metageneration=if_metageneration)
|
|
|
|
def get_acl(self, headers=None, generation=None):
|
|
"""Returns the ACL of this object.
|
|
|
|
:param dict headers: Additional headers to set during the request.
|
|
|
|
:param int generation: If specified, gets the ACL for a specific
|
|
generation of a versioned object. If not specified, the current
|
|
version is returned.
|
|
|
|
:rtype: :class:`.gs.acl.ACL`
|
|
"""
|
|
if self.bucket != None:
|
|
return self.bucket.get_acl(self.name, headers=headers,
|
|
generation=generation)
|
|
|
|
def get_xml_acl(self, headers=None, generation=None):
|
|
"""Returns the ACL string of this object.
|
|
|
|
:param dict headers: Additional headers to set during the request.
|
|
|
|
:param int generation: If specified, gets the ACL for a specific
|
|
generation of a versioned object. If not specified, the current
|
|
version is returned.
|
|
|
|
:rtype: str
|
|
"""
|
|
if self.bucket != None:
|
|
return self.bucket.get_xml_acl(self.name, headers=headers,
|
|
generation=generation)
|
|
|
|
def set_xml_acl(self, acl_str, headers=None, generation=None,
|
|
if_generation=None, if_metageneration=None):
|
|
"""Sets this objects's ACL to an XML string.
|
|
|
|
:type acl_str: string
|
|
:param acl_str: A string containing the ACL XML.
|
|
|
|
:type headers: dict
|
|
:param headers: Additional headers to set during the request.
|
|
|
|
:type generation: int
|
|
:param generation: If specified, sets the ACL for a specific generation
|
|
of a versioned object. If not specified, the current version is
|
|
modified.
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the acl
|
|
will only be updated if its current generation number is this value.
|
|
|
|
:type if_metageneration: int
|
|
:param if_metageneration: (optional) If set to a metageneration number,
|
|
the acl will only be updated if its current metageneration number is
|
|
this value.
|
|
"""
|
|
if self.bucket != None:
|
|
return self.bucket.set_xml_acl(acl_str, self.name, headers=headers,
|
|
generation=generation,
|
|
if_generation=if_generation,
|
|
if_metageneration=if_metageneration)
|
|
|
|
def set_canned_acl(self, acl_str, headers=None, generation=None,
|
|
if_generation=None, if_metageneration=None):
|
|
"""Sets this objects's ACL using a predefined (canned) value.
|
|
|
|
:type acl_str: string
|
|
:param acl_str: A canned ACL string. See
|
|
:data:`~.gs.acl.CannedACLStrings`.
|
|
|
|
:type headers: dict
|
|
:param headers: Additional headers to set during the request.
|
|
|
|
:type generation: int
|
|
:param generation: If specified, sets the ACL for a specific generation
|
|
of a versioned object. If not specified, the current version is
|
|
modified.
|
|
|
|
:type if_generation: int
|
|
:param if_generation: (optional) If set to a generation number, the acl
|
|
will only be updated if its current generation number is this value.
|
|
|
|
:type if_metageneration: int
|
|
:param if_metageneration: (optional) If set to a metageneration number,
|
|
the acl will only be updated if its current metageneration number is
|
|
this value.
|
|
"""
|
|
if self.bucket != None:
|
|
return self.bucket.set_canned_acl(
|
|
acl_str,
|
|
self.name,
|
|
headers=headers,
|
|
generation=generation,
|
|
if_generation=if_generation,
|
|
if_metageneration=if_metageneration
|
|
)
|