Storage Module

The storage module provides a unified interface for interacting with different storage backends. It defines a base StorageClient class that can be implemented by specific storage providers.

Base Storage Interface

The StorageClient abstract base class defines the common interface that all storage clients must implement.

class prs_commons.storage.base.StorageClient[source]

Bases: ABC

Abstract base class for storage clients.

This class defines the common interface that all storage clients must implement.

abstract property client: Any

Get the underlying storage client instance.

Returns:

The client instance used to interact with the storage service.

Raises:

RuntimeError – If the client cannot be initialized.

abstractmethod async upload_file(file_path: str, bucket: str, key: str, **kwargs: Any) Dict[str, Any][source]

Upload a file to storage.

Parameters:
  • file_path – Path to the local file

  • bucket – Target bucket name

  • key – Object key (path in the bucket)

  • **kwargs – Additional implementation-specific arguments

Returns:

Dictionary containing status and operation details

abstractmethod async download_file(bucket: str, key: str, file_path: str, **kwargs: Any) bool[source]

Download a file from storage.

Parameters:
  • bucket – Source bucket name

  • key – Object key (path in the bucket)

  • file_path – Local filesystem path where the file will be saved

  • **kwargs – Additional implementation-specific arguments

Returns:

True if the file was downloaded successfully, False otherwise

Return type:

bool

abstractmethod async delete_object(bucket: str, key: str) Dict[str, Any][source]

Delete an object from storage.

Parameters:
  • bucket – Bucket name

  • key – Object key to delete

Returns:

Dictionary containing status and operation details

abstractmethod async generate_presigned_url(bucket: str, key: str, operation: str = 'get_object', expiration: int = 3600, **kwargs: Any) str | None[source]

Generate a pre-signed URL for an object.

Parameters:
  • bucket – Bucket name

  • key – Object key

  • operation – The operation to allow with this URL

  • expiration – Time in seconds until the URL expires

  • **kwargs – Additional parameters for the operation

Returns:

Pre-signed URL as string, or None if credentials are invalid

abstractmethod async generate_upload_url(bucket: str, key: str, expiration: int = 3600, **kwargs: Any) str | None[source]

Generate a pre-signed URL for uploading a file.

Parameters:
  • bucket – Bucket name

  • key – Object key where the file will be stored

  • expiration – Time in seconds until the URL expires

  • **kwargs – Additional parameters for the put_object operation

Returns:

Pre-signed URL as string, or None if credentials are invalid

abstractmethod async generate_download_url(bucket: str, key: str, expiration: int = 3600, **kwargs: Any) str | None[source]

Generate a pre-signed URL for downloading a file.

Parameters:
  • bucket – Bucket name

  • key – Object key of the file to download

  • expiration – Time in seconds until the URL expires

  • **kwargs – Additional parameters for the get_object operation

Returns:

Pre-signed URL as string, or None if credentials are invalid

abstractmethod async upload_string_as_file(bucket: str, key: str, data: str, **kwargs: Any) str | None[source]

Upload a file from a base64-encoded string.

Parameters:
  • bucket – Bucket name

  • key – Object key where the file will be stored

  • data – Base64-encoded string of the file contents

  • **kwargs – Additional arguments for the upload operation

Returns:

The uploaded file’s key, or None if upload fails

Return type:

Optional[str]

abstractmethod async download_as_base64(bucket: str, key: str, check_exists: bool = True, **kwargs: Any) str | None[source]

Download a file and return its contents as a base64-encoded string.

Parameters:
  • bucket – Bucket name

  • key – Object key to download

  • check_exists – If True, check if the object exists before downloading

  • **kwargs – Additional arguments for the download operation

Returns:

Base64-encoded string of the file contents, or None if download fails

abstractmethod async file_exists(bucket: str, key: str) bool[source]

Check if a file exists in the bucket.

Parameters:
  • bucket – Bucket name

  • key – Object key to check

Returns:

True if the file exists, False otherwise

Available Implementations

Creating a Custom Storage Client

To create a custom storage client, inherit from the StorageClient base class and implement all required methods:

from prs_commons.storage.base import StorageClient

class CustomStorageClient(StorageClient):
    def __init__(self, connection_string: str):
        self.connection_string = connection_string
        self._client = self._initialize_client()

    @property
    def client(self) -> Any:
        """Return the underlying client instance."""
        return self._client

    def upload_file(
        self, file_path: str, bucket: str, key: str, **kwargs: Any
    ) -> Dict[str, Any]:
        # Implementation here
        pass

    # Implement other required methods...


# Usage
storage = CustomStorageClient("your-connection-string")
storage.upload_file("local.txt", "bucket", "remote.txt")