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:
- 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
Available Implementations¶
AWS S3 Client - For interacting with Amazon S3 storage
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")