DigitalOcean Spaces Storage Driver Documentation

Spaces is an S3-interoperable object storage service from cloud provider DigitalOcean.

Connecting to Spaces

To connect to DigitalOcean Spaces you need an access key and secret key. These can be retrieved on the “Applications & API” page of the DigitalOcean control panel.

Instantiating a driver

Once you have obtained your credentials you can instantiate the driver as shown below.

from libcloud.storage.types import Provider
from libcloud.storage.providers import get_driver

cls = get_driver(Provider.DIGITALOCEAN_SPACES)

driver = cls(key='DO_ACCESS_KEY', secret='DO_SECRET_KEY')

Spaces supports both the v2 and v4 AWS signature types. By default, this driver will use v2. You can configure it to use v4 by passing the signature_version argument when instantiating the driver as shown below.

from libcloud.storage.types import Provider
from libcloud.storage.providers import get_driver

cls = get_driver(Provider.DIGITALOCEAN_SPACES)

driver = cls(key='DO_ACCESS_KEY',
             secret='DO_SECRET_KEY',
             signature_version='4')

Specifying canned ACLs

Spaces supports a limited set of canned ACLs. In order to specify an ACL when uploading an object, you can pass an extra argument with the acl attribute to the upload methods.

For example:

from libcloud.storage.types import Provider
from libcloud.storage.providers import get_driver

FILE_PATH = '/home/user/myfile.tar.gz'

cls = get_driver(Provider.DIGITALOCEAN_SPACES)
driver = cls('api key', 'api secret key')

container = driver.get_container(container_name='my-backups-12345')

# This method blocks until all the parts have been uploaded.
extra = {'content_type': 'application/octet-stream',
         'acl': 'public-read'}

with open(FILE_PATH, 'rb') as iterator:
    obj = driver.upload_object_via_stream(iterator=iterator,
                                          container=container,
                                          object_name='backup.tar.gz',
                                          extra=extra)

At this time, valid values for this attribute are only:

  • private (default)
  • public-read

API Docs

class libcloud.storage.drivers.digitalocean_spaces.DigitalOceanSpacesStorageDriver(key, secret=None, secure=True, host=None, port=None, api_version=None, region='nyc3', **kwargs)[source]
connectionCls

alias of libcloud.storage.drivers.s3.BaseS3Connection

create_container(container_name)

Create a new container.

Parameters:container_name (str) – Container name.
Returns:Container instance on success.
Return type:libcloud.storage.base.Container
delete_container(container)

Delete a container.

Parameters:container (libcloud.storage.base.Container) – Container instance
Returns:True on success, False otherwise.
Return type:bool
delete_object(obj)

Delete an object.

Parameters:obj (libcloud.storage.base.Object) – Object instance.
Returns:bool True on success.
Return type:bool
download_object(obj, destination_path, overwrite_existing=False, delete_on_failure=True)

Download an object to the specified destination path.

Parameters:
  • obj (libcloud.storage.base.Object) – Object instance.
  • destination_path (str) – Full path to a file or a directory where the incoming file will be saved.
  • overwrite_existing (bool) – True to overwrite an existing file, defaults to False.
  • delete_on_failure (bool) – True to delete a partially downloaded file if the download was not successful (hash mismatch / file size).
Returns:

True if an object has been successfully downloaded, False otherwise.

Return type:

bool

download_object_as_stream(obj, chunk_size=None)

Return a iterator which yields object data.

Parameters:
Return type:

iterator of bytes

download_object_range(obj, destination_path, start_bytes, end_bytes=None, overwrite_existing=False, delete_on_failure=True)

Download part of an object.

Parameters:
  • obj (libcloud.storage.base.Object) – Object instance.
  • destination_path (str) – Full path to a file or a directory where the incoming file will be saved.
  • start_bytes (int) – Start byte offset (inclusive) for the range download. Offset is 0 index based so the first byte in file file is “0”.
  • end_bytes (int) – End byte offset (non-inclusive) for the range download. If not provided, it will default to the end of the file.
  • overwrite_existing (bool) – True to overwrite an existing file, defaults to False.
  • delete_on_failure (bool) – True to delete a partially downloaded file if the download was not successful (hash mismatch / file size).
Returns:

True if an object has been successfully downloaded, False otherwise.

Return type:

bool

download_object_range_as_stream(obj, start_bytes, end_bytes=None, chunk_size=None)

Return a iterator which yields range / part of the object data.

Parameters:
  • obj (libcloud.storage.base.Object) – Object instance
  • start_bytes (int) – Start byte offset (inclusive) for the range download. Offset is 0 index based so the first byte in file file is “0”.
  • end_bytes (int) – End byte offset (non-inclusive) for the range download. If not provided, it will default to the end of the file.
  • chunk_size (int) – Optional chunk size (in bytes).
Return type:

iterator of bytes

enable_container_cdn(container)

Enable container CDN.

Parameters:container (libcloud.storage.base.Container) – Container instance
Return type:bool
enable_object_cdn(obj)

Enable object CDN.

Parameters:obj (libcloud.storage.base.Object) – Object instance
Return type:bool
ex_cleanup_all_multipart_uploads(container, prefix=None)

Extension method for removing all partially completed S3 multipart uploads.

Parameters:
  • container (Container) – The container holding the uploads
  • prefix (str) – Delete only uploads of objects with this prefix
ex_iterate_multipart_uploads(container, prefix=None, delimiter=None)

Extension method for listing all in-progress S3 multipart uploads.

Each multipart upload which has not been committed or aborted is considered in-progress.

Parameters:
  • container (Container) – The container holding the uploads
  • prefix (str) – Print only uploads of objects with this prefix
  • delimiter (str) – The object/key names are grouped based on being split by this delimiter
Returns:

A generator of S3MultipartUpload instances.

Return type:

generator of S3MultipartUpload

get_container(container_name)

Return a container instance.

Parameters:container_name (str) – Container name.
Returns:Container instance.
Return type:libcloud.storage.base.Container
get_container_cdn_url(container)

Return a container CDN URL.

Parameters:container (libcloud.storage.base.Container) – Container instance
Returns:A CDN URL for this container.
Return type:str
get_object(container_name, object_name)

Return an object instance.

Parameters:
  • container_name (str) – Container name.
  • object_name (str) – Object name.
Returns:

Object instance.

Return type:

libcloud.storage.base.Object

get_object_cdn_url(obj)

Return an object CDN URL.

Parameters:obj (libcloud.storage.base.Object) – Object instance
Returns:A CDN URL for this object.
Return type:str
iterate_container_objects(container, prefix=None, ex_prefix=None)

Return a generator of objects for the given container.

Parameters:
  • container (Container) – Container instance
  • prefix (str) – Only return objects starting with prefix
  • ex_prefix (str) – Only return objects starting with ex_prefix
Returns:

A generator of Object instances.

Return type:

generator of Object

iterate_containers()

Return a iterator of containers for the given account

Returns:A iterator of Container instances.
Return type:iterator of libcloud.storage.base.Container
list_container_objects(container, prefix=None, ex_prefix=None)

Return a list of objects for the given container.

Parameters:
  • container (libcloud.storage.base.Container) – Container instance.
  • prefix (str) – Filter objects starting with a prefix.
  • ex_prefix (str) – (Deprecated.) Filter objects starting with a prefix.
Returns:

A list of Object instances.

Return type:

list of libcloud.storage.base.Object

list_containers()

Return a list of containers.

Returns:A list of Container instances.
Return type:list of Container
upload_object(file_path, container, object_name, extra=None, verify_hash=True, headers=None, ex_storage_class=None)

@inherits: StorageDriver.upload_object

Parameters:ex_storage_class (str) – Storage class
upload_object_via_stream(iterator, container, object_name, extra=None, headers=None, ex_storage_class=None)

@inherits: StorageDriver.upload_object_via_stream

Parameters:ex_storage_class (str) – Storage class