S3Driver

class cloudstorage.drivers.amazon.S3Driver(key, secret=None, region='us-east-1', **kwargs)[source]

Driver for interacting with Amazon Simple Storage Service (S3).

from cloudstorage.drivers.amazon import S3Driver

storage = S3Driver(key='<my-aws-access-key-id>',
           secret='<my-aws-secret-access-key>',
           region='us-east-1')
# <Driver: S3 us-east-1>

References:

Parameters

  • key (str) – AWS Access Key ID.

  • secret (str) – AWS Secret Access Key.

  • region (str) – (optional) Region to connect to. Defaults to us-east-1.

  • kwargs (dict) – (optional) Extra driver options.

__iter__()[source]

Get all containers associated to the driver.

for container in storage:
    print(container.name)
Yield

Iterator of all containers belonging to this driver.

Yield type

Iterable[Container]

Return type

Iterable[Container]

__len__()[source]

The total number of containers in the driver.

Returns

Number of containers belonging to this driver.

Return type

int

property session

Amazon Web Services session.

Returns

AWS session.

Return type

boto3.session.Session

property s3

S3 service resource.

Returns

The s3 resource instance.

Return type

boto3.resources.base.ServiceResource

validate_credentials()[source]

Validate driver credentials (key and secret).

Returns

None

Return type

None

Raises

CredentialsError – If driver authentication fails.

property regions

List of supported regions for this driver.

Returns

List of region strings.

Return type

list[str]

create_container(container_name, acl=None, meta_data=None)[source]

Create a new container.

For example:

container = storage.create_container('container-name')
# <Container container-name driver-name>
Parameters

  • container_name (str) – The container name to create.

  • acl (str or None) –

    (optional) Container canned Access Control List (ACL). If None, defaults to storage backend default.

    • private

    • public-read

    • public-read-write

    • authenticated-read

    • bucket-owner-read

    • bucket-owner-full-control

    • aws-exec-read (Amazon S3)

    • project-private (Google Cloud Storage)

    • container-public-access (Microsoft Azure Storage)

    • blob-public-access (Microsoft Azure Storage)

  • meta_data (Dict[str, str] or None) – (optional) A map of metadata to store with the container.

Returns

The newly created or existing container.

Return type

Container

Raises

CloudStorageError – If the container name contains invalid characters.

get_container(container_name)[source]

Get a container by name.

For example:

container = storage.get_container('container-name')
# <Container container-name driver-name>
Parameters

container_name (str) – The name of the container to retrieve.

Returns

The container if it exists.

Return type

Container

Raises

NotFoundError – If the container doesn’t exist.

patch_container(container)[source]

Saves all changed attributes for the container.

Important

This class method is called by Container.save().

Parameters

container (Container) – A container instance.

Returns

NoneType

Return type

None

Raises

NotFoundError – If the container doesn’t exist.

delete_container(container)[source]

Delete this container.

Important

This class method is called by Container.delete().

Parameters

container (Container) – A container instance.

Returns

NoneType

Return type

None

Raises
container_cdn_url(container)[source]

The Content Delivery Network URL for this container.

Important

This class method is called by Container.cdn_url.

Returns

The CDN URL for this container.

Return type

str

enable_container_cdn(container)[source]

(Optional) Enable Content Delivery Network (CDN) for the container.

Important

This class method is called by Container.enable_cdn().

Parameters

container (Container) – A container instance.

Returns

True if successful or false if not supported.

Return type

bool

disable_container_cdn(container)[source]

(Optional) Disable Content Delivery Network (CDN) on the container.

Important

This class method is called by Container.disable_cdn().

Parameters

container (Container) – A container instance.

Returns

True if successful or false if not supported.

Return type

bool

upload_blob(container, filename, blob_name=None, acl=None, meta_data=None, content_type=None, content_disposition=None, cache_control=None, chunk_size=1024, extra=None)[source]

Upload a filename or file like object to a container.

Important

This class method is called by Container.upload_blob().

Parameters

  • container (Container) – The container to upload the blob to.

  • filename (file or str) – A file handle open for reading or the path to the file.

  • acl (str or None) – (optional) Blob canned Access Control List (ACL).

  • blob_name (str or None) – (optional) Override the blob’s name. If not set, will default to the filename from path or filename of iterator object.

  • meta_data (Dict[str, str] or None) – (optional) A map of metadata to store with the blob.

  • content_type (str or None) – (optional) A standard MIME type describing the format of the object data.

  • content_disposition (str or None) – (optional) Specifies presentational information for the blob.

  • cache_control (str or None) – (optional) Specify directives for caching mechanisms for the blob.

  • chunk_size (int) – (optional) Optional chunk size for streaming a transfer.

  • extra (Dict[str, str] or None) – (optional) Extra parameters for the request.

Returns

The uploaded blob.

Return type

Blob

get_blob(container, blob_name)[source]

Get a blob object by name.

Important

This class method is called by Blob.get_blob().

Parameters

  • container (Container) – The container that holds the blob.

  • blob_name (str) – The name of the blob to retrieve.

Returns

The blob object if it exists.

Return type

Blob

Raises

NotFoundError – If the blob object doesn’t exist.

get_blobs(container)[source]

Get all blobs associated to the container.

Important

This class method is called by Blob.__iter__().

Parameters

container (Container) – A container instance.

Returns

Iterable of all blobs belonging to this container.

Return type

Iterable{Blob]

download_blob(blob, destination)[source]

Download the contents of this blob into a file-like object or into a named file.

Important

This class method is called by Blob.download().

Parameters

  • blob (Blob) – The blob object to download.

  • destination (file or str) – A file handle to which to write the blob’s data or a filename to be passed to open.

Returns

NoneType

Return type

None

Raises

NotFoundError – If the blob object doesn’t exist.

patch_blob(blob)[source]

Saves all changed attributes for this blob.

Important

This class method is called by Blob.update().

Returns

NoneType

Return type

None

Raises

NotFoundError – If the blob object doesn’t exist.

delete_blob(blob)[source]

Deletes a blob from storage.

Important

This class method is called by Blob.delete().

Parameters

blob (Blob) – The blob to delete.

Returns

NoneType

Return type

None

Raises

NotFoundError – If the blob object doesn’t exist.

blob_cdn_url(blob)[source]

The Content Delivery Network URL for the blob.

Important

This class method is called by Blob.cdn_url.

Parameters

blob (Blob) – The public blob object.

Returns

The CDN URL for the blob.

Return type

str

generate_container_upload_url(container, blob_name, expires=3600, acl=None, meta_data=None, content_disposition=None, content_length=None, content_type=None, cache_control=None, extra=None)[source]

Generate a signature and policy for uploading objects to the container.

Important

This class method is called by Container.generate_upload_url().

Parameters

  • container (Container) – A container to upload the blob object to.

  • blob_name (str or None) – The blob’s name, prefix, or ‘’ if a user is providing a file name. Note, Rackspace Cloud Files only supports prefixes.

  • expires (int) – (optional) Expiration in seconds.

  • acl (str or None) – (optional) Container canned Access Control List (ACL).

  • meta_data (Dict[Any, Any] or None) – (optional) A map of metadata to store with the blob.

  • content_disposition (str or None) – (optional) Specifies presentational information for the blob.

  • content_type (str or None) – (optional) A standard MIME type describing the format of the object data.

  • content_length (tuple[int, int] or None) – Specifies that uploaded files can only be between a certain size range in bytes.

  • cache_control (str or None) – (optional) Specify directives for caching mechanisms for the blob.

  • extra (Dict[Any, Any] or None) – (optional) Extra parameters for the request.

Returns

Dictionary with URL and form fields (includes signature or policy) or header fields.

Return type

Dict[Any, Any]

generate_blob_download_url(blob, expires=3600, method='GET', content_disposition=None, extra=None)[source]

Generates a signed URL for this blob.

Important

This class method is called by Blob.generate_download_url().

Parameters

  • blob (Blob) – The blob to download with a signed URL.

  • expires (int) – (optional) Expiration in seconds.

  • method (str) – (optional) HTTP request method. Defaults to GET.

  • content_disposition (str or None) – (optional) Sets the Content-Disposition header of the response.

  • extra (Dict[Any, Any] or None) – (optional) Extra parameters for the request.

Returns

Pre-signed URL for downloading a blob.

Return type

str