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
-
name
= None¶ Unique str driver name.
-
url
= None¶ Unique str driver URL.
-
abstract
__iter__
()[source]¶ Get all containers associated to the driver.
for container in storage: print(container.name)
-
abstract
__len__
()[source]¶ The total number of containers in the driver.
- Returns
Number of containers belonging to this driver.
- Return type
-
abstract
validate_credentials
()[source]¶ Validate driver credentials (key and secret).
- Returns
None
- Return type
- Raises
CredentialsError – If driver authentication fails.
-
abstract property
regions
¶ List of supported regions for this driver.
-
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.
(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
- 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
- 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
- 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
- Raises
IsNotEmptyError – If the container is not empty.
NotFoundError – If the container doesn’t exist.
-
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
-
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()
.
-
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()
.
-
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
-
abstract
get_blob
(container, blob_name)[source]¶ Get a blob object by name.
Important
This class method is called by
Blob.get_blob()
.- Parameters
- Returns
The blob object if it exists.
- Return type
- 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
- Returns
NoneType
- Return type
- 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
- 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
- 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
.
-
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