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]
- Parameters:
key (
str
) – API key or username to be used (required)secret (
str
) – Secret password to be used (required)secure (
bool
) – Whether to use HTTPS or HTTP. Note: Some providers only support HTTPS, and it is on by default.host (
str
) – Override hostname used for connections.port (
int
) – Override port used for connections.api_version (
str
) – Optional API version. Only used by drivers which support multiple API versions.region (
str
) – Optional driver region. Only used by drivers which support multiple regions.
- Return type:
None
- connectionCls
alias of
BaseS3Connection
- create_container(container_name)
Create a new container.
- Parameters:
container_name (
str
) – Container name.- Returns:
Container instance on success.
- Return type:
- 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:
obj (
libcloud.storage.base.Object
) – Object instancechunk_size (
int
) – Optional chunk size (in bytes).
- Return type:
iterator
ofbytes
- 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 instancestart_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
ofbytes
- enable_container_cdn(container: Container) bool
Enable container CDN.
- Parameters:
container (
libcloud.storage.base.Container
) – Container instance- Return type:
bool
- enable_object_cdn(obj: Object) bool
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 uploadsprefix (
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 uploadsprefix (
str
) – Print only uploads of objects with this prefixdelimiter (
str
) – The object/key names are grouped based on being split by this delimiter
- Returns:
A generator of S3MultipartUpload instances.
- Return type:
generator
ofS3MultipartUpload
- get_container(container_name)
Return a container instance.
- Parameters:
container_name (
str
) – Container name.- Returns:
Container
instance.- Return type:
- get_container_cdn_url(container: Container) str
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:
- get_object_cdn_url(obj: Object) str
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 instanceprefix (
str
) – Only return objects starting with prefixex_prefix (
str
) – Only return objects starting with ex_prefix
- Returns:
A generator of Object instances.
- Return type:
generator
ofObject
- iterate_containers()
Return a iterator of containers for the given account
- Returns:
A iterator of Container instances.
- Return type:
iterator
oflibcloud.storage.base.Container
- list_container_objects(container: Container, prefix: str | None = None, ex_prefix: str | None = None) List[Object]
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
oflibcloud.storage.base.Object
- list_containers() List[Container]
Return a list of containers.
- Returns:
A list of Container instances.
- Return type:
list
ofContainer
- 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