Driver

class cloudstorage.base.Driver(key=None, secret=None, region=None, **kwargs)[source]

Abstract Base Driver Class (abc.ABCMeta) to derive from.

Todo

  • Create driver abstract method to get total number of containers.

  • Create driver abstract method to get total number of blobs in a container.

  • Support for ACL permission grants.

  • Support for CORS.

  • Support for container / blob expiration (delete_at).

Parameters

  • key (str or None) – (optional) API key, username, credentials file, or local directory.

  • secret (str) – (optional) API secret key.

  • region (str) – (optional) Region to connect to.

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

name = None

Unique str driver name.

hash_type = 'md5'

hashlib function str name used by driver.

url = None

Unique str driver URL.

__contains__(container)[source]

Determines whether or not the container exists.

Parameters

container (cloudstorage.Container or str) – Container or container name.

Returns

True if the container exists.

Return type

bool

abstract __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]

abstract __len__()[source]

The total number of containers in the driver.

Returns

Number of containers belonging to this driver.

Return type

int

abstract validate_credentials()[source]

Validate driver credentials (key and secret).

Returns

None

Return type

None

Raises

CredentialsError – If driver authentication fails.

abstract property regions

List of supported regions for this driver.

Returns

List of region strings.

Return type

list[str]

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

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

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

abstract 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
abstract 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

abstract 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

abstract 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

abstract 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

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

abstract 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]

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

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

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

abstract 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

abstract 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]

abstract 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