> For the complete documentation index, see [llms.txt](https://docs.degirum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.degirum.com/degirum-tools/support/object_storage_support.md).

# Object Storage Support

DeGirum Tools API Reference Guide. MinIO/local object-storage wrappers for file and bucket ops.

{% 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. |