fractal refactor

superset_tool/exceptions.py

@@ -1,32 +1,79 @@
+# [MODULE] Иерархия исключений
+# @contract: Все ошибки наследуют SupersetToolError
+# @semantic: Каждый тип соответствует конкретной проблемной области
+# @coherence:
+#   - Полное покрытие всех сценариев клиента
+#   - Четкая классификация по уровню серьезности
+
+# [IMPORTS] Exceptions
+from typing import Optional, Dict, Any
+
 class SupersetToolError(Exception):
-    """Base exception class for all tool errors"""
+    """[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):
-    """Authentication related errors"""
+    """[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):
-    """General API communication errors"""
+    """[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}
+        )
 
-class ExportError(SupersetToolError):
-    """Dashboard export errors"""
+# [ERROR-SUBCLASS] Детализированные ошибки API
+class ExportError(SupersetAPIError):
+    """[API:EXPORT] Проблемы экспорта дашбордов"""
+    ...
 
-class ImportError(SupersetToolError):
-    """Dashboard import errors"""
+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}
+        )
 
-class InvalidZipFormatError(SupersetToolError):
-    "Archive zip errors"
-
-class DashboardNotFoundError(SupersetToolError):
-    "404 error"
-
-class PermissionDeniedError(SupersetToolError):
-    "403 error"
-
-class SupersetServerError(SupersetToolError):
-    "500 error"
 
+# [ERROR-GROUP] Системные и network-ошибки
 class NetworkError(SupersetToolError):
-    "Network errors"
-
-class DashboardImportError(SupersetToolError):
-    "Api import errors"
+    """[NETWORK] Проблемы соединения или таймауты"""
+    ...