GS

boto.gs.acl

class boto.gs.acl.ACL(parent=None)

acl

add_email_grant(permission, email_address)

add_group_email_grant(permission, email_address)

add_group_grant(permission, group_id)

add_user_grant(permission, user_id)

endElement(name, value, connection)

startElement(name, attrs, connection)

to_xml()

class boto.gs.acl.Entries(parent=None)

endElement(name, value, connection)

startElement(name, attrs, connection)

to_xml()

class boto.gs.acl.Entry(scope=None, type=None, id=None, name=None, email_address=None, domain=None, permission=None)

endElement(name, value, connection)

startElement(name, attrs, connection)

to_xml()

class boto.gs.acl.Scope(parent, type=None, id=None, name=None, email_address=None, domain=None)

ALLOWED_SCOPE_TYPE_SUB_ELEMS = {'GroupByDomain': ['Domain'], 'UserByEmail': ['EmailAddress', 'Name'], 'UserById': ['ID', 'Name'], 'AllUsers': [], 'GroupByEmail': ['EmailAddress', 'Name'], 'AllAuthenticatedUsers': [], 'GroupById': ['ID', 'Name']}

endElement(name, value, connection)

startElement(name, attrs, connection)

to_xml()

boto.gs.bucket

class boto.gs.bucket.Bucket(connection=None, name=None, key_class=<class 'boto.gs.key.Key'>)

add_email_grant(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 GS.

Parameters:

• permission (string) – The permission being granted. Should be one of: (READ, WRITE, FULL_CONTROL).
• email_address (string) – The email address associated with the GS account your are granting the permission to.
• recursive (boolean) – A boolean value to controls whether the call 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!

add_group_email_grant(permission, email_address, recursive=False, headers=None)

Convenience method that provides a quick way to add an email group 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 GS.

Parameters:

• permission (string) – The permission being granted. Should be one of: READ|WRITE|FULL_CONTROL See http://code.google.com/apis/storage/docs/developer-guide.html#authorization for more details on permissions.
• email_address (string) – The email address associated with the Google Group to which you are granting the permission.
• recursive (bool) – A boolean value to controls whether the call 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!

add_user_grant(permission, user_id, recursive=False, headers=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 PUTs the new ACL back to GS.

Parameters:

• permission (string) – The permission being granted. Should be one of: (READ|WRITE|FULL_CONTROL)
• user_id (string) – The canonical user id associated with the GS account you are granting the permission to.
• recursive (bool) – A boolean value to controls whether the call 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!

disable_logging(headers=None)

enable_logging(target_bucket, target_prefix=None, headers=None)

get_acl(key_name='', headers=None, version_id=None)

returns a bucket’s acl. We include a version_id argument to support a polymorphic interface for callers, however, version_id is not relevant for Google Cloud Storage buckets and is therefore ignored here.

get_acl_helper(key_name, headers, query_args)

provides common functionality for get_acl() and get_def_acl()

get_def_acl(key_name='', headers=None)

returns a bucket’s default object acl

list_grants(headers=None)

set_acl(acl_or_str, key_name='', headers=None, version_id=None)

sets or changes a bucket’s acl. We include a version_id argument to support a polymorphic interface for callers, however, version_id is not relevant for Google Cloud Storage buckets and is therefore ignored here.

set_canned_acl(acl_str, key_name='', headers=None, version_id=None)

sets or changes a bucket’s acl to a predefined (canned) value. We include a version_id argument to support a polymorphic interface for callers, however, version_id is not relevant for Google Cloud Storage buckets and is therefore ignored here.

set_canned_acl_helper(acl_str, key_name, headers, query_args)

provides common functionality for set_canned_acl() and set_def_canned_acl()

set_def_acl(acl_or_str, key_name='', headers=None)

sets or changes a bucket’s default object acl

set_def_canned_acl(acl_str, key_name='', headers=None)

sets or changes a bucket’s default object acl to a predefined (canned) value

set_def_xml_acl(acl_str, key_name='', headers=None)

sets or changes a bucket’s default object

boto.gs.connection

class boto.gs.connection.GSConnection(gs_access_key_id=None, gs_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, host='commondatastorage.googleapis.com', debug=0, https_connection_factory=None, calling_format=<boto.s3.connection.SubdomainCallingFormat object at 0x6618410>, path='/', suppress_consec_slashes=True)

DefaultHost = 'commondatastorage.googleapis.com'

QueryString = 'Signature=%s&Expires=%d&AWSAccessKeyId=%s'

create_bucket(bucket_name, headers=None, location='', policy=None)

Creates a new bucket. By default it’s located in the USA. You can pass Location.EU to create an European bucket. You can also pass a LocationConstraint, which (in addition to locating the bucket in the specified location) informs Google that Google services must not copy data out of that location.

Parameters:

• bucket_name (string) – The name of the new bucket
• headers (dict) – Additional headers to pass along with the request to AWS.
• location (boto.gs.connection.Location) – The location of the new bucket
• policy (boto.s3.acl.CannedACLStrings) – A canned ACL policy that will be applied to the new key in S3.

class boto.gs.connection.Location

DEFAULT = ''

EU = 'EU'

boto.gs.key

class boto.gs.key.Key(bucket=None, name=None)

add_email_grant(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.

Parameters:

• permission (string) – 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.
• email_address (string) – The email address associated with the Google account to which you are granting the permission.

add_group_email_grant(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.

Parameters:

• permission (string) – 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.
• email_address (string) – The email address associated with the Google Group to which you are granting the permission.

add_group_grant(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.

Parameters:

• permission (string) – 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.
• group_id (string) – The canonical group id associated with the Google Groups account you are granting the permission to.

add_user_grant(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.

Parameters:

• permission (string) – 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.
• user_id (string) – The canonical user id associated with the GS account to which you are granting the permission.

set_contents_from_file(fp, headers=None, replace=True, cb=None, num_cb=10, policy=None, md5=None, res_upload_handler=None, size=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.

Parameters:

• fp (file) – the file whose contents are to be uploaded
• headers (dict) – additional HTTP headers to be sent with the PUT request.
• replace (bool) – 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.
• cb (function) – 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.
• num_cb (int) – (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.
• policy (boto.gs.acl.CannedACLStrings) – A canned ACL policy that will be applied to the new key in GS.
• 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.) – 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.
• res_upload_handler (ResumableUploadHandler) – If provided, this handler will perform the upload.
• size (int) –

  (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.

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).

set_contents_from_filename(filename, headers=None, replace=True, cb=None, num_cb=10, policy=None, md5=None, reduced_redundancy=None, res_upload_handler=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.

Parameters:

• filename (string) – The name of the file that you want to put onto GS
• headers (dict) – Additional headers to pass along with the request to GS.
• replace (bool) – If True, replaces the contents of the file if it already exists.
• cb (int) – (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.
• 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.
• policy (boto.gs.acl.CannedACLStrings) – A canned ACL policy that will be applied to the new key in GS.
• 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.) – 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.
• res_upload_handler (ResumableUploadHandler) – If provided, this handler will perform the upload.

set_contents_from_string(s, headers=None, replace=True, cb=None, num_cb=10, policy=None, md5=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.

Parameters:

• headers (dict) – Additional headers to pass along with the request to AWS.
• replace (bool) – If True, replaces the contents of the file if it already exists.
• cb (int) – 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.
• 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.
• policy (boto.s3.acl.CannedACLStrings) – A canned ACL policy that will be applied to the new key in S3.
• 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.) – 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.

boto.gs.user

class boto.gs.user.User(parent=None, id='', name='')

endElement(name, value, connection)

startElement(name, attrs, connection)

to_xml(element_name='Owner')

boto.gs.resumable_upload_handler

class boto.gs.resumable_upload_handler.ResumableUploadHandler(tracker_file_name=None, num_retries=None)

Constructor. Instantiate once for each uploaded file.

Parameters:

• tracker_file_name (string) – optional file name to save tracker URI. If supplied and the current process fails the upload, it can be retried in a new process. If called with an existing file containing a valid tracker URI, we’ll resume the upload from this URI; else we’ll start a new resumable upload (and write the URI to this tracker file).
• num_retries (int) – the number of times we’ll re-try a resumable upload making no progress. (Count resets every time we get progress, so upload can span many more than this number of retries.)

BUFFER_SIZE = 8192

RETRYABLE_EXCEPTIONS = (<class 'httplib.HTTPException'>, <type 'exceptions.IOError'>, <class 'socket.error'>, <class 'socket.gaierror'>)

SERVER_HAS_NOTHING = (0, -1)

get_tracker_uri()

Returns upload tracker URI, or None if the upload has not yet started.

send_file(key, fp, headers, cb=None, num_cb=10)

Upload a file to a key into a bucket on GS, using GS resumable upload protocol.

Parameters:

• key (boto.s3.key.Key or subclass) – The Key object to which data is to be uploaded
• fp (file-like object) – The file pointer to upload
• headers (dict) – The headers to pass along with the PUT request
• cb (function) – 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.
• num_cb (int) – (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. Providing a negative integer will cause your callback to be called with each buffer read.

Raises ResumableUploadException if a problem occurs during the transfer.