protocols.objstorage.ObjectStorageProtocol

Protocol for interacting with S3-like Object Storages.

Usage

protocols.objstorage.ObjectStorageProtocol()

Classes

Name	Description
BucketAlreadyExistsError	Thrown when trying to create a bucket with an ID that already exists.
BucketError	Generic base exception for error that occur while handling buckets.
BucketIdValidationError	Thrown when a bucket ID is not valid.
BucketNotEmptyError	Thrown when trying to delete a bucket that is not empty.
BucketNotFoundError	Thrown when trying to access a bucket with an ID that doesn’t exist.
MultiPartUploadAbortError	Thrown when failed to abort a multi-part upload.
MultiPartUploadAlreadyExistsError	Thrown when trying to create a multipart upload for an object for which another
MultiPartUploadConfirmError	Thrown when a confirmation of an upload is rejected.
MultiPartUploadError	Thrown when a confirmation of an upload is rejected.
MultiPartUploadNotFoundError	Thrown when a upload with the specified upload, bucket, and object id was not found.
MultipleActiveUploadsError	Thrown when multiple active multi-part uploads are detected for the same object.
ObjectAlreadyExistsError	Thrown when trying to access a file with an ID that doesn’t exist.
ObjectError	Generic base exception for error that occur while handling file objects.
ObjectIdValidationError	Thrown when an object ID is not valid.
ObjectNotFoundError	Thrown when trying to access a bucket with an ID that doesn’t exist.
ObjectStorageProtocolError	Generic base exception for all custom errors used by this protocol.

BucketAlreadyExistsError

Thrown when trying to create a bucket with an ID that already exists.

Usage

Source

BucketAlreadyExistsError()

BucketError

Generic base exception for error that occur while handling buckets.

Usage

Source

BucketError()

BucketIdValidationError

Thrown when a bucket ID is not valid.

Usage

Source

BucketIdValidationError()

BucketNotEmptyError

Thrown when trying to delete a bucket that is not empty.

Usage

Source

BucketNotEmptyError()

BucketNotFoundError

Thrown when trying to access a bucket with an ID that doesn’t exist.

Usage

Source

BucketNotFoundError()

MultiPartUploadAbortError

Thrown when failed to abort a multi-part upload.

Usage

Source

MultiPartUploadAbortError()

MultiPartUploadAlreadyExistsError

Thrown when trying to create a multipart upload for an object for which another

Usage

Source

MultiPartUploadAlreadyExistsError()

upload is already active.

MultiPartUploadConfirmError

Thrown when a confirmation of an upload is rejected.

Usage

Source

MultiPartUploadConfirmError()

MultiPartUploadError

Thrown when a confirmation of an upload is rejected.

Usage

Source

MultiPartUploadError()

MultiPartUploadNotFoundError

Thrown when a upload with the specified upload, bucket, and object id was not found.

Usage

Source

MultiPartUploadNotFoundError()

MultipleActiveUploadsError

Thrown when multiple active multi-part uploads are detected for the same object.

Usage

Source

MultipleActiveUploadsError()

ObjectAlreadyExistsError

Thrown when trying to access a file with an ID that doesn’t exist.

Usage

Source

ObjectAlreadyExistsError()

ObjectError

Generic base exception for error that occur while handling file objects.

Usage

Source

ObjectError()

ObjectIdValidationError

Thrown when an object ID is not valid.

Usage

Source

ObjectIdValidationError()

ObjectNotFoundError

Thrown when trying to access a bucket with an ID that doesn’t exist.

Usage

Source

ObjectNotFoundError()

ObjectStorageProtocolError

Generic base exception for all custom errors used by this protocol.

Usage

Source

ObjectStorageProtocolError()

Methods

Name	Description
abort_multipart_upload()	Cancel a multipart upload with the specified ID. All uploaded content is
complete_multipart_upload()	Completes a multipart upload with the specified ID. In addition to the
copy_object()	Copy an object from one bucket (`source_bucket_id` and `source_object_id`) to
create_bucket()	Create a bucket (= a structure that can hold multiple file objects) with the
delete_bucket()	Delete a bucket (= a structure that can hold multiple file objects) with the
delete_object()	Delete an object with the specified id (`object_id`) in the bucket with the
does_bucket_exist()	Check whether a bucket with the specified ID (`bucket_id`) exists.
does_object_exist()	Check whether an object with specified ID (`object_id`) exists in the bucket
get_all_multipart_uploads()	Gets all active multipart uploads for the given bucket ID.
get_object_download_url()	Generates and returns a presigned HTTP-URL to download a file object with
get_object_etag()	Returns the etag of an object.
get_object_metadata()	Returns object metadata without downloading the actual object.
get_object_size()	Returns the size of an object in bytes.
get_object_upload_url()	Generates and returns an HTTP URL to upload a new file object with the given
get_part_upload_url()	Given a id of an instantiated multipart upload along with the corresponding
init_multipart_upload()	Initiates a multipart upload procedure. Returns the upload ID.
list_all_object_ids()	Retrieve a list of IDs for all objects currently present in the specified bucket
list_multipart_uploads_for_object()	Lists all active multipart uploads for the given object ID.
list_parts()	Lists the parts that have been uploaded for a specific multipart upload.

abort_multipart_upload()

Cancel a multipart upload with the specified ID. All uploaded content is

Usage

Source

abort_multipart_upload(*, upload_id, bucket_id, object_id)

deleted.

complete_multipart_upload()

Completes a multipart upload with the specified ID. In addition to the

Usage

Source

complete_multipart_upload(
    *,
    upload_id,
    bucket_id,
    object_id,
    anticipated_part_quantity=None,
    anticipated_part_size=None
)

corresponding bucket and object id, you also specify an anticipated part size and an anticipated part quantity. This ensures that exactly the specified number of parts exist and that all parts (except the last one) have the specified size.

copy_object()

Copy an object from one bucket (source_bucket_id and source_object_id) to

Usage

Source

copy_object(
    *,
    source_bucket_id,
    source_object_id,
    dest_bucket_id,
    dest_object_id,
    abort_failed=True
)

another bucket (dest_bucket_id and dest_object_id).

If abort_failed is set to true (default), a failed copy operation tries to abort the ongoing multipart upload it created (if using multipart mode). This only works reliably as long as there are no other ongoing multipart operations for the same destination bucket and object ID, in which case this should be set to false.

create_bucket()

Create a bucket (= a structure that can hold multiple file objects) with the

Usage

Source

create_bucket(bucket_id)

specified unique ID.

delete_bucket()

Delete a bucket (= a structure that can hold multiple file objects) with the

Usage

Source

delete_bucket(bucket_id, *, delete_content=False)

specified unique ID. If delete_content is set to True, any contained objects will be deleted, if False (the default) a BucketNotEmptyError will be raised if the bucket is not empty.

delete_object()

Delete an object with the specified id (object_id) in the bucket with the

Usage

Source

delete_object(*, bucket_id, object_id)

specified id (bucket_id).

Deleting an object that does not exist succeeds silently. However, a BucketNotFoundError is raised if the bucket does not exist.

does_bucket_exist()

Check whether a bucket with the specified ID (bucket_id) exists.

Usage

Source

does_bucket_exist(bucket_id)

Returns True if it exists and False otherwise.

does_object_exist()

Check whether an object with specified ID (object_id) exists in the bucket

Usage

Source

does_object_exist(*, bucket_id, object_id, object_md5sum=None)

with the specified id (bucket_id). Optionally, a md5 checksum (object_md5sum) may be provided to check the objects content. Returns True if checks succeed and False otherwise.

get_all_multipart_uploads()

Gets all active multipart uploads for the given bucket ID.

Usage

Source

get_all_multipart_uploads(*, bucket_id)

Returns a dict where the keys are upload IDs and values are object IDs. S3 allows multiple ongoing multi-part uploads, so it’s possible for some upload IDs to map to the same object ID.

Raises a BucketNotFoundError if the bucket does not exist.

get_object_download_url()

Generates and returns a presigned HTTP-URL to download a file object with

Usage

Source

get_object_download_url(*, bucket_id, object_id, expires_after=86400)

the specified ID (object_id) from bucket with the specified id (bucket_id). You may also specify a custom expiry duration in seconds (expires_after).

get_object_etag()

Returns the etag of an object.

Usage

Source

get_object_etag(*, bucket_id, object_id)

get_object_metadata()

Returns object metadata without downloading the actual object.

Usage

Source

get_object_metadata(*, bucket_id, object_id)

get_object_size()

Returns the size of an object in bytes.

Usage

Source

get_object_size(*, bucket_id, object_id)

get_object_upload_url()

Generates and returns an HTTP URL to upload a new file object with the given

Usage

Source

get_object_upload_url(
    *,
    bucket_id,
    object_id,
    expires_after=DEFAULT_URL_EXPIRATION_PERIOD,
    max_upload_size=None
)

id (object_id) to the bucket with the specified id (bucket_id). You may also specify a custom expiry duration in seconds (expires_after) and a maximum size (bytes) for uploads (max_upload_size).

get_part_upload_url()

Given a id of an instantiated multipart upload along with the corresponding

Usage

Source

get_part_upload_url(
    *,
    upload_id,
    bucket_id,
    object_id,
    part_number,
    expires_after=3600,
    part_md5=None
)

bucket and object ID, it returns a presigned URL for uploading a file part with the specified number. Please note: the part number must be a non-zero, positive integer and parts should be uploaded in sequence.

init_multipart_upload()

Initiates a multipart upload procedure. Returns the upload ID.

Usage

Source

init_multipart_upload(*, bucket_id, object_id)

list_all_object_ids()

Retrieve a list of IDs for all objects currently present in the specified bucket

Usage

Source

list_all_object_ids(bucket_id)

list_multipart_uploads_for_object()

Lists all active multipart uploads for the given object ID.

Usage

Source

list_multipart_uploads_for_object(*, bucket_id, object_id)

Raises a BucketNotFoundError if the bucket does not exist.

list_parts()

Lists the parts that have been uploaded for a specific multipart upload.

Usage

Source

list_parts(
    *, bucket_id, object_id, upload_id, max_parts=None, first_part_no=None
)

Specify max_parts to return a limited parts list. If not specified, all parts will be returned (up to 10,000).

Specify first_part_no to get parts starting with that part number. If not specified, retrieved parts will start with the first part. Part numbers start at 1, not 0.

Raises

ValueError: if max_parts or first_part_no are invalid.
MultiPartUploadNotFoundError: if no upload with upload_id exists.