"""
Storage exceptions for image upload operations.

This module defines the exception hierarchy for storage operations,
providing specific error types for different failure scenarios.
"""


class StorageError(Exception):
    """
    Base exception for all storage operations.
    
    This is the root exception class that all storage-related errors inherit from.
    It provides a common interface for handling storage failures across different
    backend implementations (filesystem, Cloudinary, S3, etc.).
    """
    pass


class StorageUploadError(StorageError):
    """
    Exception raised when file upload fails.
    
    This exception is raised when an upload operation fails due to network issues,
    authentication problems, or other upload-specific errors.
    
    Attributes:
        retryable (bool): Whether the operation can be retried. True for transient
                         errors like network timeouts, False for permanent errors
                         like authentication failures.
    """
    
    def __init__(self, message: str, retryable: bool = False):
        """
        Initialize upload error.
        
        Args:
            message: Descriptive error message
            retryable: Whether the operation can be retried
        """
        super().__init__(message)
        self.retryable = retryable


class StorageDeleteError(StorageError):
    """
    Exception raised when file deletion fails.
    
    This exception is raised when a delete operation fails due to network issues,
    permission problems, or other deletion-specific errors. Note that attempting
    to delete a non-existent file should not raise this exception.
    """
    pass


class StorageNotFoundError(StorageError):
    """
    Exception raised when a requested file is not found in storage.
    
    This exception is raised when attempting to access, retrieve metadata for,
    or perform operations on a file that doesn't exist in the storage backend.
    """
    pass


class StorageQuotaError(StorageError):
    """
    Exception raised when storage quota is exceeded.
    
    This exception is raised when an upload would exceed the available storage
    quota for the user or the entire storage backend.
    """
    pass


class CloudinaryAuthError(StorageError):
    """
    Exception raised when Cloudinary authentication fails.
    
    This exception is raised when Cloudinary API calls fail due to invalid
    credentials (cloud_name, api_key, or api_secret).
    """
    pass


class CloudinaryRateLimitError(StorageError):
    """
    Exception raised when Cloudinary rate limit is exceeded.
    
    This exception is raised when Cloudinary API returns a rate limit error.
    The retry_after attribute indicates how long to wait before retrying.
    
    Attributes:
        retry_after (int): Number of seconds to wait before retrying the request.
    """
    
    def __init__(self, message: str, retry_after: int = 60):
        """
        Initialize rate limit error.
        
        Args:
            message: Descriptive error message
            retry_after: Seconds to wait before retrying (default: 60)
        """
        super().__init__(message)
        self.retry_after = retry_after