# pylint: disable=too-many-ancestors
"""
[MODULE] Иерархия исключений
@contract: Все ошибки наследуют `SupersetToolError` для единой точки обработки.
"""

# [IMPORTS] Standard library
from pathlib import Path

# [IMPORTS] Typing
from typing import Optional, Dict, Any, Union

class SupersetToolError(Exception):
    """[BASE] Базовый класс для всех ошибок инструмента Superset."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация базового исключения.
    #   PRECONDITIONS: `context` должен быть словарем или None.
    #   POSTCONDITIONS: Исключение создано с сообщением и контекстом.
    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None):
        if not isinstance(context, (dict, type(None))):
            raise TypeError("Контекст ошибки должен быть словарем или None")
        self.context = context or {}
        super().__init__(f"{message} | Context: {self.context}")
    # END_FUNCTION___init__

class AuthenticationError(SupersetToolError):
    """[AUTH] Ошибки аутентификации или авторизации."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения аутентификации.
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, message: str = "Authentication failed", **context: Any):
        super().__init__(f"[AUTH_FAILURE] {message}", context={"type": "authentication", **context})
    # END_FUNCTION___init__

class PermissionDeniedError(AuthenticationError):
    """[AUTH] Ошибка отказа в доступе."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения отказа в доступе.
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, message: str = "Permission denied", required_permission: Optional[str] = None, **context: Any):
        full_message = f"Permission denied: {required_permission}" if required_permission else message
        super().__init__(full_message, context={"required_permission": required_permission, **context})
    # END_FUNCTION___init__

class SupersetAPIError(SupersetToolError):
    """[API] Общие ошибки взаимодействия с Superset API."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения ошибки API.
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, message: str = "Superset API error", **context: Any):
        super().__init__(f"[API_FAILURE] {message}", context={"type": "api_call", **context})
    # END_FUNCTION___init__

class ExportError(SupersetAPIError):
    """[API:EXPORT] Проблемы, специфичные для операций экспорта."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения ошибки экспорта.
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, message: str = "Dashboard export failed", **context: Any):
        super().__init__(f"[EXPORT_FAILURE] {message}", context={"subtype": "export", **context})
    # END_FUNCTION___init__

class DashboardNotFoundError(SupersetAPIError):
    """[API:404] Запрошенный дашборд или ресурс не существует."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения "дашборд не найден".
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, dashboard_id_or_slug: Union[int, str], message: str = "Dashboard not found", **context: Any):
        super().__init__(f"[NOT_FOUND] Dashboard '{dashboard_id_or_slug}' {message}", context={"subtype": "not_found", "resource_id": dashboard_id_or_slug, **context})
    # END_FUNCTION___init__

class DatasetNotFoundError(SupersetAPIError):
    """[API:404] Запрашиваемый набор данных не существует."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения "набор данных не найден".
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, dataset_id_or_slug: Union[int, str], message: str = "Dataset not found", **context: Any):
        super().__init__(f"[NOT_FOUND] Dataset '{dataset_id_or_slug}' {message}", context={"subtype": "not_found", "resource_id": dataset_id_or_slug, **context})
    # END_FUNCTION___init__

class InvalidZipFormatError(SupersetToolError):
    """[FILE:ZIP] Некорректный формат ZIP-архива."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения некорректного формата ZIP.
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, message: str = "Invalid ZIP format or content", file_path: Optional[Union[str, Path]] = None, **context: Any):
        super().__init__(f"[FILE_ERROR] {message}", context={"type": "file_validation", "file_path": str(file_path) if file_path else "N/A", **context})
    # END_FUNCTION___init__

class NetworkError(SupersetToolError):
    """[NETWORK] Проблемы соединения."""
    # [ENTITY: Function('__init__')]
    # CONTRACT:
    #   PURPOSE: Инициализация исключения сетевой ошибки.
    #   PRECONDITIONS: None
    #   POSTCONDITIONS: Исключение создано.
    def __init__(self, message: str = "Network connection failed", **context: Any):
        super().__init__(f"[NETWORK_FAILURE] {message}", context={"type": "network", **context})
    # END_FUNCTION___init__

class FileOperationError(SupersetToolError):
    """[FILE] Ошибка файловых операций."""

class InvalidFileStructureError(FileOperationError):
    """[FILE] Некорректная структура файлов/директорий."""

class ConfigurationError(SupersetToolError):
    """[CONFIG] Ошибка в конфигурации инструмента."""