# <GRACE_MODULE id="superset_tool.exceptions" name="exceptions.py">
#   @SEMANTICS: exception, error, hierarchy
#   @PURPOSE: Определяет иерархию пользовательских исключений для всего инструмента, обеспечивая единую точку обработки ошибок.
#   @RELATION: ALL_CLASSES -> INHERITS_FROM -> SupersetToolError (or other exception in this module)

# <IMPORTS>
from pathlib import Path
from typing import Optional, Dict, Any, Union
# </IMPORTS>

# --- Начало кода модуля ---

# <ANCHOR id="SupersetToolError" type="Class">
#   @PURPOSE: Базовый класс для всех ошибок, генерируемых инструментом.
#   @INHERITS_FROM: Exception
class SupersetToolError(Exception):
    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None):
        self.context = context or {}
        super().__init__(f"{message} | Context: {self.context}")
# </ANCHOR id="SupersetToolError">

# <ANCHOR id="AuthenticationError" type="Class">
#   @PURPOSE: Ошибки, связанные с аутентификацией или авторизацией.
#   @INHERITS_FROM: SupersetToolError
class AuthenticationError(SupersetToolError):
    def __init__(self, message: str = "Authentication failed", **context: Any):
        super().__init__(f"[AUTH_FAILURE] {message}", context={"type": "authentication", **context})
# </ANCHOR id="AuthenticationError">

# <ANCHOR id="PermissionDeniedError" type="Class">
#   @PURPOSE: Ошибка, возникающая при отказе в доступе к ресурсу.
#   @INHERITS_FROM: AuthenticationError
class PermissionDeniedError(AuthenticationError):
    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})
# </ANCHOR id="PermissionDeniedError">

# <ANCHOR id="SupersetAPIError" type="Class">
#   @PURPOSE: Общие ошибки при взаимодействии с Superset API.
#   @INHERITS_FROM: SupersetToolError
class SupersetAPIError(SupersetToolError):
    def __init__(self, message: str = "Superset API error", **context: Any):
        super().__init__(f"[API_FAILURE] {message}", context={"type": "api_call", **context})
# </ANCHOR id="SupersetAPIError">

# <ANCHOR id="ExportError" type="Class">
#   @PURPOSE: Ошибки, специфичные для операций экспорта.
#   @INHERITS_FROM: SupersetAPIError
class ExportError(SupersetAPIError):
    def __init__(self, message: str = "Dashboard export failed", **context: Any):
        super().__init__(f"[EXPORT_FAILURE] {message}", context={"subtype": "export", **context})
# </ANCHOR id="ExportError">

# <ANCHOR id="DashboardNotFoundError" type="Class">
#   @PURPOSE: Ошибка, когда запрошенный дашборд или ресурс не найден (404).
#   @INHERITS_FROM: SupersetAPIError
class DashboardNotFoundError(SupersetAPIError):
    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})
# </ANCHOR id="DashboardNotFoundError">

# <ANCHOR id="DatasetNotFoundError" type="Class">
#   @PURPOSE: Ошибка, когда запрашиваемый набор данных не существует (404).
#   @INHERITS_FROM: SupersetAPIError
class DatasetNotFoundError(SupersetAPIError):
    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})
# </ANCHOR id="DatasetNotFoundError">

# <ANCHOR id="InvalidZipFormatError" type="Class">
#   @PURPOSE: Ошибка, указывающая на некорректный формат или содержимое ZIP-архива.
#   @INHERITS_FROM: SupersetToolError
class InvalidZipFormatError(SupersetToolError):
    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})
# </ANCHOR id="InvalidZipFormatError">

# <ANCHOR id="NetworkError" type="Class">
#   @PURPOSE: Ошибки, связанные с сетевым соединением.
#   @INHERITS_FROM: SupersetToolError
class NetworkError(SupersetToolError):
    def __init__(self, message: str = "Network connection failed", **context: Any):
        super().__init__(f"[NETWORK_FAILURE] {message}", context={"type": "network", **context})
# </ANCHOR id="NetworkError">

# <ANCHOR id="FileOperationError" type="Class">
#   @PURPOSE: Общие ошибки файловых операций (I/O).
#   @INHERITS_FROM: SupersetToolError
class FileOperationError(SupersetToolError):
    pass
# </ANCHOR id="FileOperationError">

# <ANCHOR id="InvalidFileStructureError" type="Class">
#   @PURPOSE: Ошибка, указывающая на некорректную структуру файлов или директорий.
#   @INHERITS_FROM: FileOperationError
class InvalidFileStructureError(FileOperationError):
    pass
# </ANCHOR id="InvalidFileStructureError">

# <ANCHOR id="ConfigurationError" type="Class">
#   @PURPOSE: Ошибки, связанные с неверной конфигурацией инструмента.
#   @INHERITS_FROM: SupersetToolError
class ConfigurationError(SupersetToolError):
    pass
# </ANCHOR id="ConfigurationError">

# --- Конец кода модуля ---

# </GRACE_MODULE id="superset_tool.exceptions">