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.
Parameters: |
|
---|
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.
Parameters: |
|
---|
Complete a multipart upload operation.
Configure lifecycle for this bucket.
Parameters: | lifecycle_config (boto.s3.lifecycle.Lifecycle) – The lifecycle configuration you want to configure for this bucket. |
---|
Configure versioning for this bucket.
..note:: This feature is currently in beta.
Parameters: |
|
---|
Configure this bucket to act as a website
Parameters: |
|
---|
Create a new key in the bucket by copying another existing key.
Parameters: |
|
---|---|
Return type: | boto.s3.key.Key or subclass |
Returns: | An instance of the newly created key object |
Removes all CORS configuration from the bucket.
Deletes a key from the bucket. If a version_id is provided, only that version of the key will be deleted.
Parameters: |
|
---|---|
Return type: | 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. |
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.
Parameters: |
|
---|---|
Returns: | An instance of MultiDeleteResult |
Removes all lifecycle configuration from the bucket.
Removes all website configuration from the bucket.
Disable logging on a bucket.
Return type: | bool |
---|---|
Returns: | True if ok or raises an exception. |
Enable logging on a bucket.
Parameters: |
|
---|---|
Return type: | bool |
Returns: | True if ok or raises an exception. |
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.
Parameters: |
|
---|---|
Return type: | ResultSet |
Returns: | The result from S3 listing the keys requested |
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.
Parameters: |
|
---|---|
Return type: | ResultSet |
Returns: | The result from S3 listing the uploads requested |
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.
Parameters: |
|
---|---|
Return type: | ResultSet |
Returns: | The result from S3 listing the keys requested |
Returns the current CORS configuration on the bucket.
Return type: | boto.s3.cors.CORSConfiguration |
---|---|
Returns: | A CORSConfiguration object that describes all current CORS rules in effect for the bucket. |
Returns the current CORS configuration on the bucket as an XML document.
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
Parameters: |
|
---|---|
Return type: | |
Returns: | A Key object from this bucket. |
Returns the current lifecycle configuration on the bucket.
Return type: | boto.s3.lifecycle.Lifecycle |
---|---|
Returns: | A LifecycleConfig object that describes all current lifecycle rules in effect for the bucket. |
Returns the LocationConstraint for the bucket.
Return type: | str |
---|---|
Returns: | The LocationConstraint for the bucket or the empty string if no constraint was specified when bucket was created. |
Get the logging status for this bucket.
Return type: | boto.s3.bucketlogging.BucketLogging |
---|---|
Returns: | A BucketLogging object for this bucket. |
Returns the JSON policy associated with the bucket. The policy is returned as an uninterpreted JSON string.
Get a subresource for a bucket or key.
Parameters: |
|
---|---|
Return type: | string |
Returns: | The value of the subresource. |
Returns the current status of versioning on the bucket.
Return type: | 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. |
Returns the current status of website configuration on the bucket.
Return type: | dict |
---|---|
Returns: | A dictionary containing a Python representation of the XML response from S3. The overall structure is: |
Returns the current status of website configuration on the bucket as unparsed XML.
Return type: | 2-Tuple |
---|---|
Returns: | 2-tuple containing: |
of the XML response from GCS. 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
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.
Start a multipart upload operation.
Parameters: |
|
---|
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.
Parameters: |
|
---|---|
Return type: | |
Returns: | an instance of a BucketListResultSet that handles paging, etc |
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.
Parameters: | marker (string) – The “marker” of where you are in the result set |
---|---|
Return type: | boto.s3.bucketlistresultset.BucketListResultSet |
Returns: | an instance of a BucketListResultSet that handles paging, etc |
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.
Parameters: |
|
---|---|
Return type: | |
Returns: | an instance of a BucketListResultSet that handles paging, etc |
Deprecated: Please use get_key method.
Parameters: | key_name (string) – The name of the key to retrieve |
---|---|
Return type: | boto.s3.key.Key |
Returns: | A Key object from this bucket. |
Creates a new key
Parameters: | key_name (string) – The name of the key to create |
---|---|
Return type: | boto.s3.key.Key or subclass |
Returns: | An instance of the newly created key object |
Setup the current bucket as a logging target by granting the necessary permissions to the LogDelivery group to write log files to this bucket.
Set the CORS for this bucket given a boto CORSConfiguration object.
Parameters: | cors_config (boto.s3.cors.CORSConfiguration) – The CORS configuration you want to configure for this bucket. |
---|
Set the CORS (Cross-Origin Resource Sharing) for a bucket.
Parameters: | cors_xml (str) – The XML document describing your desired CORS configuration. See the S3 documentation for details of the exact syntax required. |
---|
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.
Parameters: | key_class (class) – A subclass of Key that can be more specific |
---|
Add or replace the JSON policy associated with the bucket.
Parameters: | policy (str) – The JSON policy as a string. |
---|
Set a subresource for a bucket or key.
Parameters: |
|
---|
Set logging on a bucket directly to the given xml string.
Parameters: | logging_str (unicode string) – 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. |
---|---|
Return type: | bool |
Returns: | True if ok or raises an exception. |
A resultset for listing keys within a bucket. Uses the bucket_lister generator function and implements the iterator interface. This transparently handles the results paging from S3 so even if you have many thousands of keys within the bucket you can iterate over all keys in a reasonably efficient manner.
A resultset for listing multipart uploads within a bucket. Uses the multipart_upload_lister generator function and implements the iterator interface. This transparently handles the results paging from S3 so even if you have many thousands of uploads within the bucket you can iterate over all keys in a reasonably efficient manner.
A resultset for listing versions within a bucket. Uses the bucket_lister generator function and implements the iterator interface. This transparently handles the results paging from S3 so even if you have many thousands of keys within the bucket you can iterate over all keys in a reasonably efficient manner.
A generator function for listing keys in a bucket.
A generator function for listing multipart uploads in a bucket.
A generator function for listing versions in a bucket.
Taken from the AWS book Python examples and modified for use with boto This only returns the arguments required for the post form, not the actual form. This does not return the file input field which also needs to be added
Parameters: |
|
---|---|
Return type: | dict |
Returns: | A dictionary containing field names/values as well as a url to POST to {
"action": action_url_to_post_to,
"fields": [
{
"name": field_name,
"value": field_value
},
{
"name": field_name2,
"value": field_value2
}
]
}
|
Taken from the AWS book Python examples and modified for use with boto
Creates a new located bucket. By default it’s in the USA. You can pass Location.EU to create an European bucket.
Parameters: |
|
---|
Convenience method that returns the “CanonicalUserID” of the user who’s credentials are associated with the connection. The only way to get this value is to do a GET request on the service which returns all buckets associated with the account. As part of that response, the canonical userid is returned. This method simply does all of that and then returns just the user id.
Return type: | string |
---|---|
Returns: | A string containing the canonical user id. |
Set the Bucket class associated with this bucket. By default, this would be the boto.s3.key.Bucket class but if you want to subclass that for some reason this allows you to associate your new class.
Parameters: | bucket_class (class) – A subclass of Bucket that can be more specific |
---|
Bucket names must not contain uppercase characters. We check for this by appending a lowercase character and testing with islower(). Note this also covers cases like numeric bucket names with dashes.
>>> check_lowercase_bucketname("Aaaa")
Traceback (most recent call last):
...
BotoClientError: S3Error: Bucket names cannot contain upper-case
characters when using either the sub-domain or virtual hosting calling
format.
>>> check_lowercase_bucketname("1234-5678-9123")
True
>>> check_lowercase_bucketname("abcdefg1234")
True
A container for the rules associated with a CORS configuration.
Add a rule to this CORS configuration. This only adds the rule to the local copy. To install the new rule(s) on the bucket, you need to pass this CORS config object to the set_cors method of the Bucket object.
Parameters: |
|
---|
Returns a string containing the XML version of the Lifecycle configuration as defined by S3.
CORS rule for a bucket.
Variables: |
|
---|
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 S3.
Parameters: |
|
---|
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 S3.
Parameters: |
|
---|
Change the storage class of an existing key. Depending on whether a different destination bucket is supplied or not, this will either move the item within the bucket, preserving all metadata and ACL info bucket changing the storage class or it will copy the item to the provided destination bucket, also preserving metadata and ACL info.
Parameters: |
|
---|
Parameters: |
|
---|---|
Return type: | tuple |
Returns: | A tuple containing the hex digest version of the MD5 hash as the first element and the base64 encoded version of the plain digest as the second element. |
Copy this Key to another bucket.
Parameters: |
|
---|---|
Return type: | boto.s3.key.Key or subclass |
Returns: | An instance of the newly created key object |
Delete this key from S3
Returns True if the key exists
Return type: | bool |
---|---|
Returns: | Whether the key exists on S3 |
Generate a URL to access this key.
Parameters: |
|
---|---|
Return type: | string |
Returns: | The URL to access the key |
Retrieve an object from S3 using the name of the Key object as the key in S3. Return the contents of the object as a string. See get_contents_to_file method for details about the parameters.
Parameters: |
|
---|---|
Return type: | string |
Returns: | The contents of the file as a string |
Retrieve an object from S3 using the name of the Key object as the key in S3. Write the contents of the object to the file pointed to by ‘fp’.
Parameters: |
|
---|
Retrieve an object from S3 using the name of the Key object as the key in S3. Store contents of the object to a file named by ‘filename’. See get_contents_to_file method for details about the parameters.
Parameters: |
|
---|
Retrieves a file from an S3 Key
Parameters: |
|
---|---|
Param: | headers to send when retrieving the files |
A utility function to create the 2-tuple (md5hexdigest, base64md5) from just having a precalculated md5_hexdigest.
Get a torrent file (see to get_file)
Parameters: |
|
---|
By providing a next method, the key object supports use as an iterator. For example, you can now say:
All of the HTTP connection stuff is handled for you.
Open this key for reading
Parameters: |
|
---|
Open this key for writing. Not yet implemented
Parameters: |
---|
Upload a file to a key into a bucket on S3.
Parameters: |
|
---|
Store an object in S3 using the name of the Key object as the key in S3 and the contents of the file pointed to by ‘fp’ as the contents. The data is read from ‘fp’ from its current position until ‘size’ bytes have been read or EOF.
Parameters: |
|
---|---|
Return type: | int |
Returns: | The number of bytes written to the key. |
Store an object in S3 using the name of the Key object as the key in S3 and the contents of the file named by ‘filename’. See set_contents_from_file method for details about the parameters.
Parameters: |
|
---|
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.
Parameters: |
|
---|
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: |
|
---|
Represents a completed MultiPart Upload. Contains the following useful attributes:
location - The URI of the completed upload
- bucket_name - The name of the bucket in which the upload
is contained
key_name - The name of the new, completed key
etag - The MD5 hash of the completed, combined upload
version_id - The version_id of the completed upload
encrypted - The value of the encryption header
Represents a MultiPart Upload operation.
Cancels a MultiPart Upload operation. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.
Complete the MultiPart Upload operation. This method should be called when all parts of the file have been successfully uploaded to S3.
Return type: | boto.s3.multipart.CompletedMultiPartUpload |
---|---|
Returns: | An object representing the completed upload. |
Copy another part of this MultiPart Upload.
Parameters: |
---|
Return the uploaded parts of this MultiPart Upload. This is a lower-level method that requires you to manually page through results. To simplify this process, you can just use the object itself as an iterator and it will automatically handle all of the paging with S3.
Upload another part of this MultiPart Upload.
Parameters: |
---|
The other parameters are exactly as defined for the boto.s3.key.Key set_contents_from_file method.
Represents a single part in a MultiPart upload. Attributes include:
- part_number - The integer part number
- last_modified - The last modified date of this part
- etag - The MD5 hash of this part
- size - The size, in bytes, of this part
A generator function for listing parts of a multipart upload.
A successfully deleted object in a multi-object delete request.
Variables: |
|
---|
An unsuccessful deleted object in a multi-object delete request.
Variables: |
|
---|
The status returned from a MultiObject Delete request.
Variables: |
|
---|
Proxy class that translates progress callbacks made by boto.s3.Key.get_file(), taking into account that we’re resuming a download.
Handler for resumable downloads.
Constructor. Instantiate once for each downloaded file.
Parameters: |
|
---|
Retrieves a file from a Key :type key: boto.s3.key.Key or subclass :param key: The Key object from which upload is to be downloaded
Parameters: |
|
---|---|
Param: | headers to send when retrieving the files |
Returns size of file, optionally leaving fp positioned at EOF.
A container for the rules associated with a Lifecycle configuration.
Add a rule to this Lifecycle configuration. This only adds the rule to the local copy. To install the new rule(s) on the bucket, you need to pass this Lifecycle config object to the configure_lifecycle method of the Bucket object.
Parameters: |
|
---|---|
Iparam prefix: | Prefix identifying one or more objects to which the rule applies. |
Returns a string containing the XML version of the Lifecycle configuration as defined by S3.
A Lifcycle rule for an S3 bucket.
Variables: |
|
---|