# Object Storage Support

{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}

## Object Storage Support Module Overview <a href="#object-storage-support-module-overview" id="object-storage-support-module-overview"></a>

Helper utilities for interacting with cloud object storage services such as MinIO. The module also provides a lightweight local file-system backend for testing without a remote service.

Key Classes

* `ObjectStorageConfig`: Configuration parameters for object storage.
* `ObjectStorage`: Convenience wrapper around common bucket operations.

Typical Usage

1. Create an `ObjectStorageConfig` with connection parameters.
2. Instantiate `ObjectStorage` using the configuration.
3. Upload, download, or delete files using the instance methods.

## Classes <a href="#classes" id="classes"></a>

## ObjectStorageConfig <a href="#objectstorageconfig" id="objectstorageconfig"></a>

`ObjectStorageConfig`

`dataclass`

Configuration for object storage connections.

Attributes:

| Name               | Type  | Description                                |
| ------------------ | ----- | ------------------------------------------ |
| `endpoint`         | `str` | Object storage endpoint URL or local path. |
| `access_key`       | `str` | Access key for the storage account.        |
| `secret_key`       | `str` | Secret key for the storage account.        |
| `bucket`           | `str` | Bucket name or local directory name.       |
| `url_expiration_s` | `int` | Expiration time for presigned URLs.        |

### ObjectStorageConfig Methods <a href="#objectstorageconfig-methods" id="objectstorageconfig-methods"></a>

#### construct\_direct\_url(object\_name) <a href="#construct_direct_url" id="construct_direct_url"></a>

`construct_direct_url(object_name)`

Construct a direct URL to an object.

Parameters:

| Name          | Type  | Description                           | Default    |
| ------------- | ----- | ------------------------------------- | ---------- |
| `object_name` | `str` | Name of the object inside the bucket. | *required* |

## ObjectStorage <a href="#objectstorage" id="objectstorage"></a>

`ObjectStorage`

Convenience wrapper around common object storage operations.

This helper abstracts interaction with either a real MinIO server or a local directory acting as an object store. It exposes simple methods for bucket management and file uploads/downloads.

### ObjectStorage Methods <a href="#objectstorage-methods" id="objectstorage-methods"></a>

#### \_\_init\_\_(config) <a href="#init" id="init"></a>

`__init__(config)`

Initialize the storage helper.

Depending on `config.endpoint` this helper connects either to a real MinIO server or to a local directory used as a mock object store.

Parameters:

| Name     | Type                  | Description            | Default    |
| -------- | --------------------- | ---------------------- | ---------- |
| `config` | `ObjectStorageConfig` | Storage configuration. | *required* |

#### check\_bucket\_exits(retries=1) <a href="#check_bucket_exits" id="check_bucket_exits"></a>

`check_bucket_exits(retries=1)`

Check whether the configured bucket exists.

Parameters:

| Name      | Type  | Description               | Default |
| --------- | ----- | ------------------------- | ------- |
| `retries` | `int` | Number of retry attempts. | `1`     |

Returns:

| Name   | Type   | Description                  |
| ------ | ------ | ---------------------------- |
| `bool` | `bool` | `True` if the bucket exists. |

#### check\_file\_exists\_in\_object\_storage(object\_name) <a href="#check_file_exists_in_object_storage" id="check_file_exists_in_object_storage"></a>

`check_file_exists_in_object_storage(object_name)`

Check whether a file exists in the configured bucket.

Parameters:

| Name          | Type  | Description                           | Default    |
| ------------- | ----- | ------------------------------------- | ---------- |
| `object_name` | `str` | Name of the object within the bucket. | *required* |

#### delete\_bucket <a href="#delete_bucket" id="delete_bucket"></a>

`delete_bucket()`

Delete the bucket and all of its objects.

Raises:

| Type           | Description                      |
| -------------- | -------------------------------- |
| `RuntimeError` | If the bucket cannot be removed. |

#### delete\_bucket\_contents <a href="#delete_bucket_contents" id="delete_bucket_contents"></a>

`delete_bucket_contents()`

Remove all objects from the bucket.

#### delete\_file\_from\_object\_storage(object\_name) <a href="#delete_file_from_object_storage" id="delete_file_from_object_storage"></a>

`delete_file_from_object_storage(object_name)`

Delete a file from the configured bucket.

Parameters:

| Name          | Type  | Description                           | Default    |
| ------------- | ----- | ------------------------------------- | ---------- |
| `object_name` | `str` | Name of the object within the bucket. | *required* |

Raises:

| Type           | Description            |
| -------------- | ---------------------- |
| `RuntimeError` | If the deletion fails. |

#### download\_file\_from\_object\_storage(object\_name, ...) <a href="#download_file_from_object_storage" id="download_file_from_object_storage"></a>

`download_file_from_object_storage(object_name, file_path)`

Download a file from the configured bucket.

Parameters:

| Name          | Type  | Description                              | Default    |
| ------------- | ----- | ---------------------------------------- | ---------- |
| `object_name` | `str` | Name of the object within the bucket.    | *required* |
| `file_path`   | `str` | Local path where the file will be saved. | *required* |

Raises:

| Type           | Description            |
| -------------- | ---------------------- |
| `RuntimeError` | If the download fails. |

#### ensure\_bucket\_exists <a href="#ensure_bucket_exists" id="ensure_bucket_exists"></a>

`ensure_bucket_exists()`

Create the bucket if it does not exist.

Raises:

| Type           | Description               |
| -------------- | ------------------------- |
| `RuntimeError` | If bucket creation fails. |

#### generate\_presigned\_url(object\_name) <a href="#generate_presigned_url" id="generate_presigned_url"></a>

`generate_presigned_url(object_name)`

Return a presigned download URL for an object.

Parameters:

| Name          | Type  | Description                           | Default    |
| ------------- | ----- | ------------------------------------- | ---------- |
| `object_name` | `str` | Name of the object within the bucket. | *required* |

Returns:

| Type  | Description                            |
| ----- | -------------------------------------- |
| `str` | Temporary download URL for the object. |

#### list\_bucket\_contents <a href="#list_bucket_contents" id="list_bucket_contents"></a>

`list_bucket_contents()`

List objects in the bucket.

Returns:

| Type               | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `Iterable or None` | Iterator over objects, or `None` if the bucket does not exist. |

Raises:

| Type           | Description       |
| -------------- | ----------------- |
| `RuntimeError` | If listing fails. |

#### upload\_file\_to\_object\_storage(file\_path, ...) <a href="#upload_file_to_object_storage" id="upload_file_to_object_storage"></a>

`upload_file_to_object_storage(file_path, object_name)`

Upload a file to the configured bucket.

Parameters:

| Name          | Type  | Description                           | Default    |
| ------------- | ----- | ------------------------------------- | ---------- |
| `file_path`   | `str` | Path of the local file to upload.     | *required* |
| `object_name` | `str` | Name of the object within the bucket. | *required* |

Raises:

| Type           | Description          |
| -------------- | -------------------- |
| `RuntimeError` | If the upload fails. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.degirum.com/degirum-tools/support/object_storage_support.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.