Connect to this Region’s endpoint. Returns an connection object pointing to the endpoint associated with this region. You may pass any of the arguments accepted by the connection class’s constructor as keyword arguments and they will be passed along to the connection object.
| Return type: | Connection object |
|---|---|
| Returns: | The connection to this regions endpoint |
Get all available regions for the Amazon S3 service.
| Return type: | list |
|---|---|
| Returns: | A list of boto.regioninfo.RegionInfo |
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: |
|
|---|
To verify that all parts have been removed, so you don’t get charged for the part storage, you should call the List Parts operation and ensure the parts list is empty.
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 existence 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: |
Get the website configuration as a boto.s3.website.WebsiteConfiguration object.
Returns the current status of website configuration on the bucket as unparsed XML.
| Return type: | 2-Tuple |
|---|---|
| Returns: | 2-tuple containing:
|
Get raw website configuration xml
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.
Note
Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.
| 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: |
|
|---|---|
| Return type: | |
| 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: |
|
|---|
| Parameters: | config (boto.s3.website.WebsiteConfiguration) – Configuration data |
|---|
Upload xml website configuration
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
|
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 a European bucket (S3) or European Union bucket (GCS).
| Parameters: |
|
|---|
Removes an S3 bucket.
In order to remove the bucket, it must first be empty. If the bucket is not empty, an S3ResponseError will be raised.
| Parameters: |
|---|
Retrieves a bucket by name.
If the bucket does not exist, an S3ResponseError will be raised. If you are unsure if the bucket exists or not, you can use the S3Connection.lookup method, which will either return a valid bucket or None.
If validate=False is passed, no request is made to the service (no charge/communication delay). This is only safe to do if you are sure the bucket exists.
If the default validate=True is passed, a request is made to the service to ensure the bucket exists. Prior to Boto v2.25.0, this fetched a list of keys (but with a max limit set to 0, always returning an empty list) in the bucket (& included better error messages), at an increased expense. As of Boto v2.25.0, this now performs a HEAD request (less expensive but worse error messages).
If you were relying on parsing the error message before, you should call something like:
bucket = conn.get_bucket('<bucket_name>', validate=False)
bucket.get_all_keys(maxkeys=0)
| 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. |
Determines if a bucket exists by name.
If the bucket does not exist, an S3ResponseError will be raised.
| Parameters: | |
|---|---|
| Returns: | A <Bucket> object |
Attempts to get a bucket from S3.
Works identically to S3Connection.get_bucket, save for that it will return None if the bucket does not exist instead of throwing an exception.
| Parameters: |
|---|
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: |
|
|---|
Represents a key (object) in an S3 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: |
|
|---|
Close this key.
| Parameters: | fast (bool) – True if you want the connection to be closed without first |
|---|
reading the content. This should only be used in cases where subsequent calls don’t need to return the content from the open HTTP connection. Note: As explained at http://docs.python.org/2/library/httplib.html#httplib.HTTPConnection.getresponse, callers must read the whole response before sending a new request to the server. Calling Key.close(fast=True) and making a subsequent request to the server will work because boto will get an httplib exception and close/reopen the connection.
| Parameters: |
|
|---|
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: | bytes or str |
| Returns: | The contents of the file as bytes or 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.
Return the redirect location configured for this key.
If no redirect is configured (via set_redirect), then None will be returned.
Get a torrent file (see to get_file)
| Parameters: |
|
|---|
Used by Key subclasses to do additional, provider-specific processing of response headers. No-op for this base class.
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: |
|---|
Restore an object from an archive.
| Parameters: | days (int) – The lifetime of the restored object (must be at least 1 day). If the object is already restored then this parameter can be used to readjust the lifetime of the restored object. In this case, the days param is with respect to the initial time of the request. If the object has not been restored, this param is with respect to the completion time of the request. |
|---|
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: |
|
|---|---|
| Return type: | int |
| Returns: | The number of bytes written to the key. |
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: |
|
|---|
Configure this key to redirect to another location.
When the bucket associated with this key is accessed from the website endpoint, a 301 redirect will be issued to the specified redirect_location.
| Parameters: | redirect_location (string) – The location to redirect. |
|---|
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.
Note
After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.
| Parameters: |
|---|
The other parameters are exactly as defined for the boto.s3.key.Key set_contents_from_file method.
| Return type: | boto.s3.key.Key or subclass |
|---|---|
| Returns: | The uploaded part containing the etag. |
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.
When an object will expire.
| Variables: |
|
|---|
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 Lifecycle rule for an S3 bucket.
| Variables: |
|
|---|
A transition to a different storage class.
| Variables: |
|
|---|