Storage

Storage Menage Repository

This is the didactic documentation for the StorageRepository class, an essential component for hybrid file management in your application.

On this page

    #1. Overview

    The StorageRepository class acts as an abstraction layer (or Repository) for image storage. Its main goal is to unify two worlds: local storage (the server's hard drive) and cloud storage (Supabase Storage).

    When you use this class, the rest of your code does not need to worry about technical details such as file path handling or network protocols; it only asks for an image to be saved, and the repository decides how and where that should happen.

    #2. Execution Flow

    The lifecycle of a common operation in this class follows these steps:

    1. Configuration: The object is created receiving a base_path (where to save locally) and a bucket_name (where to save in the cloud).
    2. Data Preparation: When it receives a list of GeneratedImage objects, the class extracts the bytes and identifies the format (MIME type).
    3. Local Persistence: If the local_repository method is called, the class generates unique names based on the current date and time to avoid file conflicts and writes the bytes to disk.
    4. Remote Synchronization: If the upload_to_supabase method is called, the class internally uses the StorageManager to send the data to the cloud and instantly retrieves the public access link.

    #3. Methods Table

    MethodTypeShort Description
    __init__ConstructorDefines the base paths and the destination bucket.
    local_repositoryPublicSaves multiple images to the local file system.
    _mime_to_extensionPrivate (Helper)Converts types such as image/png to the .png extension.
    upload_to_supabasePublicSends a file to Supabase and returns its URL.

    #4. Architecture and Insights

    • Repository Pattern: This class isolates the infrastructure logic. If tomorrow you decide to replace Supabase with Amazon S3, you will only need to change this file, without breaking the rest of the system.
    • Unique Name Generation: Using datetime.utcnow() when saving locally guarantees that, even if two images are generated in sequence, they have distinct names, preventing accidental data overwrites.
    • Extension Handling: The _mime_to_extension method acts as an integrity guardian, ensuring that only supported image types (JPEG and PNG) are processed, avoiding corrupted or unknown files.

    #5. Class Details

    #Class StorageRepository

    Description

    Manages image persistence in a hybrid way. It allows images generated by the application to be stored both in local directories and in the Supabase Storage service, standardizing file access.

    Arguments

    • base_path (str): Local base directory or folder prefix in the remote storage.
    • bucket_name (str): Name of the bucket configured in the Supabase console.

    #Methods

    #1. local_repository

    Description

    Iterates over a list of images, generates file names based on a date/time stamp (timestamp) and saves them to the local disk.

    Arguments

    • images (List[GeneratedImage]): List of objects containing the bytes and the MIME type.
    • prefix (str): Initial file name (e.g. "avatar", "post"). Default is "image".

    Returns

    • List[str]: A list containing the full path of each successfully saved file.

    Raises

    • ValueError: If an image has an unmapped MIME type.
    • IOError: If a permission or disk space error occurs while writing.

    Examples

    repo = StorageRepository(base_path="./data/exports")
paths = repo.local_repository(lista_de_imagens, prefix="geracao_ia")
# Retorno: ["./data/exports/geracao_ia_20240101_120000_1.jpg", ...]

    #2. upload_to_supabase

    Description

    Bridges the application and Supabase. It sends the raw bytes to the bucket and returns the direct link for viewing.

    Arguments

    • file_name (str): Name the file will have inside the bucket.
    • byte_data (bytes): The binary content of the image.

    Returns

    • str: The public (HTTP) URL to access the file in the cloud.

    Raises

    • ConnectionError: If there is a network failure or a problem with the Supabase credentials.
    • ValueError: If the file name parameters are invalid.

    Examples

    repo = StorageRepository(base_path="galeria", bucket_name="bucket_oficial")
url_publica = repo.upload_to_supabase("foto_perfil.png", dados_em_bytes)
print(url_publica)
Saída: https://projeto.supabase.co/storage/v1/object/public/bucket_oficial/galeria/foto_perfil.png

    #3. _mime_to_extension

    Description

    Internal support method that translates the image's MIME type into a file extension friendly to the operating system.

    Arguments

    • mime_type (str): The MIME type (e.g. "image/jpeg").

    Returns

    • str: The short extension (e.g. "jpg" or "png").

    Raises

    • ValueError: If the MIME type is not "image/jpeg" or "image/png".

    Source: src/storage/storage_repository.py

    Esc
    ↑↓navigate Enteropen