## protocols.objstorage.ObjectStorageProtocol

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol"></span>


Protocol for interacting with S3-like Object Storages.


Usage

``` python
protocols.objstorage.ObjectStorageProtocol()
```


## Classes

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

<span id="BucketAlreadyExistsError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.BucketAlreadyExistsError"></span>


#### BucketAlreadyExistsError


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


Usage

``` python
BucketAlreadyExistsError(bucket_id)
```


<span id="BucketError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.BucketError"></span>

------------------------------------------------------------------------


#### BucketError


Generic base exception for error that occur while handling buckets.


Usage

``` python
BucketError()
```


<span id="BucketIdValidationError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.BucketIdValidationError"></span>

------------------------------------------------------------------------


#### BucketIdValidationError


Thrown when a bucket ID is not valid.


Usage

``` python
BucketIdValidationError(bucket_id, reason)
```


<span id="BucketNotEmptyError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.BucketNotEmptyError"></span>

------------------------------------------------------------------------


#### BucketNotEmptyError


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


Usage

``` python
BucketNotEmptyError(bucket_id)
```


<span id="BucketNotFoundError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.BucketNotFoundError"></span>

------------------------------------------------------------------------


#### BucketNotFoundError


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


Usage

``` python
BucketNotFoundError(bucket_id)
```


<span id="MultiPartUploadAbortError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.MultiPartUploadAbortError"></span>

------------------------------------------------------------------------


#### MultiPartUploadAbortError


Thrown when failed to abort a multi-part upload.


Usage

``` python
MultiPartUploadAbortError(upload_id, bucket_id, object_id)
```


<span id="MultiPartUploadAlreadyExistsError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.MultiPartUploadAlreadyExistsError"></span>

------------------------------------------------------------------------


#### MultiPartUploadAlreadyExistsError


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


Usage

``` python
MultiPartUploadAlreadyExistsError(bucket_id, object_id)
```


upload is already active.


<span id="MultiPartUploadConfirmError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.MultiPartUploadConfirmError"></span>

------------------------------------------------------------------------


#### MultiPartUploadConfirmError


Thrown when a confirmation of an upload is rejected.


Usage

``` python
MultiPartUploadConfirmError(upload_id, bucket_id, object_id, reason=None)
```


<span id="MultiPartUploadError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.MultiPartUploadError"></span>

------------------------------------------------------------------------


#### MultiPartUploadError


Thrown when a confirmation of an upload is rejected.


Usage

``` python
MultiPartUploadError()
```


<span id="MultiPartUploadNotFoundError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.MultiPartUploadNotFoundError"></span>

------------------------------------------------------------------------


#### MultiPartUploadNotFoundError


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


Usage

``` python
MultiPartUploadNotFoundError(upload_id, bucket_id, object_id, details=None)
```


<span id="MultipleActiveUploadsError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.MultipleActiveUploadsError"></span>

------------------------------------------------------------------------


#### MultipleActiveUploadsError


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


Usage

``` python
MultipleActiveUploadsError(bucket_id, object_id, upload_ids)
```


<span id="ObjectAlreadyExistsError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.ObjectAlreadyExistsError"></span>

------------------------------------------------------------------------


#### ObjectAlreadyExistsError


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


Usage

``` python
ObjectAlreadyExistsError(bucket_id=None, object_id=None)
```


<span id="ObjectError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.ObjectError"></span>

------------------------------------------------------------------------


#### ObjectError


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


Usage

``` python
ObjectError()
```


<span id="ObjectIdValidationError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.ObjectIdValidationError"></span>

------------------------------------------------------------------------


#### ObjectIdValidationError


Thrown when an object ID is not valid.


Usage

``` python
ObjectIdValidationError(object_id, reason)
```


<span id="ObjectNotFoundError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.ObjectNotFoundError"></span>

------------------------------------------------------------------------


#### ObjectNotFoundError


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


Usage

``` python
ObjectNotFoundError(bucket_id=None, object_id=None)
```


<span id="ObjectStorageProtocolError"></span>

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.ObjectStorageProtocolError"></span>

------------------------------------------------------------------------


#### ObjectStorageProtocolError


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


Usage

``` python
ObjectStorageProtocolError()
```


## Methods

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

<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.abort_multipart_upload"></span>


#### abort_multipart_upload()


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


Usage

``` python
abort_multipart_upload(*, upload_id, bucket_id, object_id)
```


deleted.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.complete_multipart_upload"></span>

------------------------------------------------------------------------


#### complete_multipart_upload()


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


Usage

``` python
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.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.copy_object"></span>

------------------------------------------------------------------------


#### copy_object()


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


Usage

``` python
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.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.create_bucket"></span>

------------------------------------------------------------------------


#### create_bucket()


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


Usage

``` python
create_bucket(bucket_id)
```


specified unique ID.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.delete_bucket"></span>

------------------------------------------------------------------------


#### delete_bucket()


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


Usage

``` python
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.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.delete_object"></span>

------------------------------------------------------------------------


#### delete_object()


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


Usage

``` python
delete_object(*, bucket_id, object_id)
```


specified id (`bucket_id`).

Deleting an object that does not exist succeeds silently. However, a [BucketNotFoundError](protocols.objstorage.ObjectStorageProtocol.md#hexkit.protocols.objstorage.ObjectStorageProtocol.BucketNotFoundError) is raised if the bucket does not exist.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.does_bucket_exist"></span>

------------------------------------------------------------------------


#### does_bucket_exist()


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


Usage

``` python
does_bucket_exist(bucket_id)
```


Returns `True` if it exists and `False` otherwise.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.does_object_exist"></span>

------------------------------------------------------------------------


#### does_object_exist()


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


Usage

``` python
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.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_all_multipart_uploads"></span>

------------------------------------------------------------------------


#### get_all_multipart_uploads()


Gets all active multipart uploads for the given bucket ID.


Usage

``` python
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](protocols.objstorage.ObjectStorageProtocol.md#hexkit.protocols.objstorage.ObjectStorageProtocol.BucketNotFoundError) if the bucket does not exist.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_object_download_url"></span>

------------------------------------------------------------------------


#### get_object_download_url()


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


Usage

``` python
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`).


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_object_etag"></span>

------------------------------------------------------------------------


#### get_object_etag()


Returns the etag of an object.


Usage

``` python
get_object_etag(*, bucket_id, object_id)
```


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_object_metadata"></span>

------------------------------------------------------------------------


#### get_object_metadata()


Returns object metadata without downloading the actual object.


Usage

``` python
get_object_metadata(*, bucket_id, object_id)
```


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_object_size"></span>

------------------------------------------------------------------------


#### get_object_size()


Returns the size of an object in bytes.


Usage

``` python
get_object_size(*, bucket_id, object_id)
```


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_object_upload_url"></span>

------------------------------------------------------------------------


#### get_object_upload_url()


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


Usage

``` python
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`).


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.get_part_upload_url"></span>

------------------------------------------------------------------------


#### get_part_upload_url()


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


Usage

``` python
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.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.init_multipart_upload"></span>

------------------------------------------------------------------------


#### init_multipart_upload()


Initiates a multipart upload procedure. Returns the upload ID.


Usage

``` python
init_multipart_upload(*, bucket_id, object_id)
```


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.list_all_object_ids"></span>

------------------------------------------------------------------------


#### list_all_object_ids()


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


Usage

``` python
list_all_object_ids(bucket_id)
```


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.list_multipart_uploads_for_object"></span>

------------------------------------------------------------------------


#### list_multipart_uploads_for_object()


Lists all active multipart uploads for the given object ID.


Usage

``` python
list_multipart_uploads_for_object(*, bucket_id, object_id)
```


Raises a [BucketNotFoundError](protocols.objstorage.ObjectStorageProtocol.md#hexkit.protocols.objstorage.ObjectStorageProtocol.BucketNotFoundError) if the bucket does not exist.


<span id="hexkit.protocols.objstorage.ObjectStorageProtocol.list_parts"></span>

------------------------------------------------------------------------


#### list_parts()


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


Usage

``` python
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.