# [MODULE] Иерархия исключений
# @contract: Все ошибки наследуют SupersetToolError
# @semantic: Каждый тип соответствует конкретной проблемной области
# @coherence:
#   - Полное покрытие всех сценариев клиента
#   - Четкая классификация по уровню серьезности

# [IMPORTS] Exceptions
from typing import Optional, Dict, Any

class SupersetToolError(Exception):
    """[BASE] Базовый класс ошибок инструмента
    @semantic: Должен содержать контекст для диагностики
    """
    def __init__(self, message: str, context: Optional[dict] = None):
        self.context = context or {}
        super().__init__(f"{message} | Context: {self.context}")

# [ERROR-GROUP] Проблемы аутентификации и авторизации
class AuthenticationError(SupersetToolError):
    """[AUTH] Ошибки credentials или доступа
    @context: url, username, error_detail
    """
    def __init__(self, message="Auth failed", **context):
        super().__init__(
            f"[AUTH_FAILURE] {message}",
            {"type": "authentication", **context}
        )

class PermissionDeniedError(AuthenticationError):
    """[AUTH] Ошибка отказа в доступе из-за недостаточных прав
    @context: required_permission, user_roles
    """
    def __init__(self, required_permission: str, **context):
        super().__init__(
            f"Permission denied: {required_permission}",
            {"type": "authorization", "required_permission": required_permission, **context}
        )

# [ERROR-GROUP] Проблемы API-вызовов
class SupersetAPIError(SupersetToolError):
    """[API] Ошибки взаимодействия с Superset API
    @context: endpoint, method, status_code, response
    """
    def __init__(self, message="API error", **context):
        super().__init__(
            f"[API_FAILURE] {message}",
            {"type": "api_call", **context}
        )

# [ERROR-SUBCLASS] Детализированные ошибки API
class ExportError(SupersetAPIError):
    """[API:EXPORT] Проблемы экспорта дашбордов"""
    ...

class DashboardNotFoundError(SupersetAPIError):
    """[API:404] Запрошенный ресурс не существует"""
    def __init__(self, dashboard_id, **context):
        super().__init__(
            f"Dashboard {dashboard_id} not found",
            {"dashboard_id": dashboard_id, **context}
        )
        
# [ERROR-SUBCLASS] Детализированные ошибки обработки файлов
class InvalidZipFormatError(SupersetAPIError):
    """[API:ZIP] Некорректный формат ZIP-архива
    @context: file_path, expected_format, error_detail
    """
    def __init__(self, file_path: str, **context):
        super().__init__(
            f"Invalid ZIP format for file: {file_path}",
            {"type": "zip_validation", "file_path": file_path, **context}
        )


# [ERROR-GROUP] Системные и network-ошибки
class NetworkError(SupersetToolError):
    """[NETWORK] Проблемы соединения или таймауты"""
    ...