Object Storage Support

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

This API Reference is based on DeGirum Tools version 0.18.0.

Object Storage Support Module Overview

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

ObjectStorageConfig

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.

Functions

construct_direct_url(object_name)

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

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.

Functions

__init__(config)

__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)

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)

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

delete_bucket()

Delete the bucket and all of its objects.

Raises:

Type	Description
RuntimeError	If the bucket cannot be removed.

delete_bucket_contents

delete_bucket_contents()

Remove all objects from the bucket.

delete_file_from_object_storage(object_name)

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, ...)

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

ensure_bucket_exists()

Create the bucket if it does not exist.

Raises:

Type	Description
RuntimeError	If bucket creation fails.

generate_presigned_url(object_name)

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

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, ...)

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.