Driver

class cloudstorage.base.Driver(key: str, secret: str = None, region: str = None, **kwargs: typing.Dict) → None[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) – 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) → bool[source]

Determines whether or not the container exists.

Parameters:container (Container or str) – Container or container name.
Returns:True if the container exists.
Return type:bool
__iter__() → typing.Iterable[cloudstorage.base.Container][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]
__len__() → int[source]

The total number of containers in the driver.

Returns:Number of containers belonging to this driver.
Return type:int
regions

List of supported regions for this driver.

Returns:List of region strings.
Return type:list[str]
create_container(container_name: str, acl: str = None, meta_data: typing.Dict[str, str] = None) → cloudstorage.base.Container[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)
  • 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: str) → cloudstorage.base.Container[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: cloudstorage.base.Container) → None[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: cloudstorage.base.Container) → None[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: cloudstorage.base.Container) → str[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: cloudstorage.base.Container) → bool[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: cloudstorage.base.Container) → bool[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: cloudstorage.base.Container, filename: typing.Union[str, typing.IO[_io.BytesIO], _io.BytesIO, _io.FileIO, _io.TextIOWrapper], blob_name: str = None, acl: str = None, meta_data: typing.Dict[str, str] = None, content_type: str = None, content_disposition: str = None, extra: typing.Dict[str, str] = None) → cloudstorage.base.Blob[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.
  • extra (Dict[str, str] or None) – (optional) Extra parameters for the request.
Returns:

The uploaded blob.

Return type:

Blob

get_blob(container: cloudstorage.base.Container, blob_name: str) → cloudstorage.base.Blob[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: cloudstorage.base.Container) → typing.Iterable[cloudstorage.base.Blob][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: cloudstorage.base.Blob, destination: typing.Union[str, typing.IO[_io.BytesIO], _io.BytesIO, _io.FileIO, _io.TextIOWrapper]) → None[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: cloudstorage.base.Blob) → None[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: cloudstorage.base.Blob) → None[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: cloudstorage.base.Blob) → str[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: cloudstorage.base.Container, blob_name: str, expires: int = 3600, acl: str = None, meta_data: typing.Dict[str, str] = None, content_disposition: str = None, content_length: typing.Dict[int, int] = None, content_type: str = None, extra: typing.Dict[str, str] = None) → typing.Dict[str, typing.Dict[str, str]][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[str, str] 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.
  • extra (Dict[str, str] or None) – (optional) Extra parameters for the request.
Returns:

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

Return type:

Dict[str, str]

generate_blob_download_url(blob: cloudstorage.base.Blob, expires: int = 3600, method: str = 'GET', content_disposition: str = None, extra: typing.Dict[str, str] = None) → str[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[str, str] or None) – (optional) Extra parameters for the request.
Returns:

Pre-signed URL for downloading a blob.

Return type:

str