"""Abstract base class for file storage providers."""

from abc import ABC, abstractmethod
from typing import BinaryIO


class BaseFileStorage(ABC):
    """Abstract base class for a remote file processor.

    Defines the interface for listing and processing files from
    a remote source.
    """

    @abstractmethod
    def upload_file(
        self,
        file_path: str,
        destination_blob_name: str,
        content_type: str | None = None,
    ) -> None:
        """Upload a file to the remote source.

        Args:
            file_path: The local path to the file to upload.
            destination_blob_name: Name of the file in remote storage.
            content_type: The content type of the file.

        """
        ...

    @abstractmethod
    def list_files(self, path: str | None = None) -> list[str]:
        """List files from a remote location.

        Args:
            path: Path to a specific file or directory. If None,
                  recursively lists all files in the bucket.

        Returns:
            A list of file paths.

        """
        ...

    @abstractmethod
    def get_file_stream(self, file_name: str) -> BinaryIO:
        """Get a file from the remote source as a file-like object.

        Args:
            file_name: The name of the file to retrieve.

        Returns:
            A file-like object containing the file data.

        """
        ...