fishertools 0.2.1__py3-none-any.whl

fishertools/errors/exceptions.py

@@ -0,0 +1,191 @@
+"""
+Custom exception classes for fishertools error handling.
+
+This module defines the exception hierarchy for fishertools, providing
+specific error types for different failure scenarios.
+"""
+
+
+class FishertoolsError(Exception):
+    """
+    Base exception class for all fishertools-specific errors.
+    
+    This is the parent class for all custom exceptions in fishertools.
+    It provides a consistent interface and allows catching all fishertools
+    errors with a single except clause.
+    """
+    
+    def __init__(self, message: str, original_error: Exception = None):
+        """
+        Initialize the fishertools error.
+        
+        Args:
+            message: Human-readable error message in Russian
+            original_error: The original exception that caused this error (optional)
+        """
+        super().__init__(message)
+        self.message = message
+        self.original_error = original_error
+    
+    def __str__(self) -> str:
+        """Return the error message."""
+        return self.message
+    
+    def get_full_message(self) -> str:
+        """
+        Get the full error message including original error if available.
+        
+        Returns:
+            Complete error message with context
+        """
+        if self.original_error:
+            return f"{self.message} (Причина: {self.original_error})"
+        return self.message
+
+
+class ExplanationError(FishertoolsError):
+    """
+    Exception raised when error explanation fails.
+    
+    This exception is raised when the ErrorExplainer cannot create
+    a proper explanation for a given exception, typically due to
+    pattern matching failures or internal processing errors.
+    """
+    
+    def __init__(self, message: str, exception_type: str = None, original_error: Exception = None):
+        """
+        Initialize the explanation error.
+        
+        Args:
+            message: Description of what went wrong during explanation
+            exception_type: The type of exception that couldn't be explained
+            original_error: The original exception that caused this error
+        """
+        super().__init__(message, original_error)
+        self.exception_type = exception_type
+    
+    def get_full_message(self) -> str:
+        """Get the full error message with exception type context."""
+        base_message = super().get_full_message()
+        if self.exception_type:
+            return f"{base_message} (Тип исключения: {self.exception_type})"
+        return base_message
+
+
+class FormattingError(FishertoolsError):
+    """
+    Exception raised when output formatting fails.
+    
+    This exception is raised when formatters cannot properly format
+    an ErrorExplanation, typically due to invalid formatter configuration
+    or output generation issues.
+    """
+    
+    def __init__(self, message: str, formatter_type: str = None, original_error: Exception = None):
+        """
+        Initialize the formatting error.
+        
+        Args:
+            message: Description of what went wrong during formatting
+            formatter_type: The type of formatter that failed
+            original_error: The original exception that caused this error
+        """
+        super().__init__(message, original_error)
+        self.formatter_type = formatter_type
+    
+    def get_full_message(self) -> str:
+        """Get the full error message with formatter type context."""
+        base_message = super().get_full_message()
+        if self.formatter_type:
+            return f"{base_message} (Тип форматтера: {self.formatter_type})"
+        return base_message
+
+
+class ConfigurationError(FishertoolsError):
+    """
+    Exception raised when configuration is invalid.
+    
+    This exception is raised when ExplainerConfig or other configuration
+    objects contain invalid values that prevent proper system operation.
+    """
+    
+    def __init__(self, message: str, config_field: str = None, config_value: str = None, original_error: Exception = None):
+        """
+        Initialize the configuration error.
+        
+        Args:
+            message: Description of the configuration problem
+            config_field: The configuration field that has an invalid value
+            config_value: The invalid value that caused the error
+            original_error: The original exception that caused this error
+        """
+        super().__init__(message, original_error)
+        self.config_field = config_field
+        self.config_value = config_value
+    
+    def get_full_message(self) -> str:
+        """Get the full error message with configuration context."""
+        base_message = super().get_full_message()
+        if self.config_field and self.config_value:
+            return f"{base_message} (Поле: {self.config_field}, Значение: {self.config_value})"
+        elif self.config_field:
+            return f"{base_message} (Поле: {self.config_field})"
+        return base_message
+
+
+class PatternError(FishertoolsError):
+    """
+    Exception raised when error pattern operations fail.
+    
+    This exception is raised when ErrorPattern objects cannot be created,
+    loaded, or used properly, typically due to invalid pattern definitions
+    or pattern matching failures.
+    """
+    
+    def __init__(self, message: str, pattern_type: str = None, original_error: Exception = None):
+        """
+        Initialize the pattern error.
+        
+        Args:
+            message: Description of the pattern problem
+            pattern_type: The type of pattern that caused the error
+            original_error: The original exception that caused this error
+        """
+        super().__init__(message, original_error)
+        self.pattern_type = pattern_type
+    
+    def get_full_message(self) -> str:
+        """Get the full error message with pattern type context."""
+        base_message = super().get_full_message()
+        if self.pattern_type:
+            return f"{base_message} (Тип паттерна: {self.pattern_type})"
+        return base_message
+
+
+class SafeUtilityError(FishertoolsError):
+    """
+    Exception raised when safe utility operations fail.
+    
+    This exception is raised when safe utility functions encounter
+    errors that cannot be handled gracefully, typically due to
+    invalid inputs or system-level failures.
+    """
+    
+    def __init__(self, message: str, utility_name: str = None, original_error: Exception = None):
+        """
+        Initialize the safe utility error.
+        
+        Args:
+            message: Description of the utility problem
+            utility_name: The name of the utility function that failed
+            original_error: The original exception that caused this error
+        """
+        super().__init__(message, original_error)
+        self.utility_name = utility_name
+    
+    def get_full_message(self) -> str:
+        """Get the full error message with utility name context."""
+        base_message = super().get_full_message()
+        if self.utility_name:
+            return f"{base_message} (Утилита: {self.utility_name})"
+        return base_message

fishertools/errors/explainer.py

@@ -0,0 +1,303 @@
+"""
+Main error explainer implementation.
+
+This module contains the ErrorExplainer class and explain_error function.
+"""
+
+from typing import Optional, List
+from .models import ErrorExplanation, ExplainerConfig, ErrorPattern
+from .patterns import load_default_patterns
+from .exceptions import ExplanationError, FormattingError, ConfigurationError, FishertoolsError
+
+
+class ErrorExplainer:
+    """
+    Main class for explaining Python errors in simple terms.
+    
+    Uses pattern matching to provide contextual explanations for different
+    types of Python exceptions.
+    """
+    
+    def __init__(self, config: Optional[ExplainerConfig] = None):
+        """
+        Initialize the error explainer with optional configuration.
+        
+        Args:
+            config: Configuration for the explainer behavior
+            
+        Raises:
+            ConfigurationError: If the provided configuration is invalid
+            ExplanationError: If pattern loading fails
+        """
+        try:
+            self.config = config or ExplainerConfig()
+            self.patterns = self._load_patterns()
+        except Exception as e:
+            if isinstance(e, (ConfigurationError, ExplanationError)):
+                raise
+            raise ExplanationError(f"Не удалось инициализировать ErrorExplainer: {e}", original_error=e)
+    
+    def _load_patterns(self) -> List[ErrorPattern]:
+        """
+        Load error patterns for matching exceptions.
+        
+        Returns:
+            List of ErrorPattern objects
+            
+        Raises:
+            ExplanationError: If patterns cannot be loaded
+        """
+        try:
+            return load_default_patterns()
+        except Exception as e:
+            raise ExplanationError(f"Не удалось загрузить паттерны ошибок: {e}", original_error=e)
+    
+    def explain(self, exception: Exception) -> ErrorExplanation:
+        """
+        Create an explanation for the given exception.
+        
+        Args:
+            exception: The exception to explain
+            
+        Returns:
+            Structured explanation of the error
+            
+        Raises:
+            ExplanationError: If explanation creation fails
+        """
+        if not isinstance(exception, Exception):
+            raise ExplanationError(f"Параметр должен быть экземпляром Exception, получен {type(exception).__name__}")
+        
+        try:
+            # Try to find a matching pattern
+            pattern = self._match_pattern(exception)
+            
+            if pattern:
+                return self._create_explanation_from_pattern(exception, pattern)
+            else:
+                return self._create_fallback_explanation(exception)
+                
+        except Exception as e:
+            if isinstance(e, ExplanationError):
+                raise
+            # Graceful degradation - create a minimal explanation if all else fails
+            return self._create_emergency_explanation(exception, e)
+    
+    def _match_pattern(self, exception: Exception) -> Optional[ErrorPattern]:
+        """
+        Find the best matching pattern for the given exception.
+        
+        Args:
+            exception: The exception to match
+            
+        Returns:
+            Matching ErrorPattern or None if no match found
+        """
+        try:
+            for pattern in self.patterns:
+                if pattern.matches(exception):
+                    return pattern
+            return None
+        except Exception as e:
+            # If pattern matching fails, log the error but don't raise
+            # This allows fallback explanation to work
+            return None
+    
+    def _create_explanation_from_pattern(self, exception: Exception, 
+                                       pattern: ErrorPattern) -> ErrorExplanation:
+        """
+        Create explanation using a matched pattern.
+        
+        Args:
+            exception: The original exception
+            pattern: The matched pattern
+            
+        Returns:
+            ErrorExplanation based on the pattern
+            
+        Raises:
+            ExplanationError: If explanation creation fails
+        """
+        try:
+            return ErrorExplanation(
+                original_error=str(exception),
+                error_type=type(exception).__name__,
+                simple_explanation=pattern.explanation,
+                fix_tip=pattern.tip,
+                code_example=pattern.example,
+                additional_info=f"Частые причины: {', '.join(pattern.common_causes)}"
+            )
+        except Exception as e:
+            raise ExplanationError(f"Не удалось создать объяснение из паттерна: {e}", 
+                                 exception_type=type(exception).__name__, original_error=e)
+    
+    def _create_fallback_explanation(self, exception: Exception) -> ErrorExplanation:
+        """
+        Create a generic explanation for unsupported exceptions.
+        
+        Args:
+            exception: The exception to explain
+            
+        Returns:
+            Generic ErrorExplanation
+        """
+        try:
+            error_type = type(exception).__name__
+            
+            return ErrorExplanation(
+                original_error=str(exception),
+                error_type=error_type,
+                simple_explanation=f"Произошла ошибка типа {error_type}. Это означает, что в вашем коде что-то пошло не так.",
+                fix_tip="Внимательно прочитайте сообщение об ошибке и проверьте строку кода, где произошла ошибка. Убедитесь, что все переменные определены и имеют правильные типы.",
+                code_example=f"# Пример обработки ошибки {error_type}:\ntry:\n    # ваш код здесь\n    pass\nexcept {error_type} as e:\n    print(f'Ошибка: {{e}}')",
+                additional_info="Если вы не можете решить проблему самостоятельно, попробуйте поискать информацию об этом типе ошибки в документации Python или задать вопрос на форуме."
+            )
+        except Exception as e:
+            # If even fallback fails, create emergency explanation
+            return self._create_emergency_explanation(exception, e)
+    
+    def _create_emergency_explanation(self, exception: Exception, original_error: Exception) -> ErrorExplanation:
+        """
+        Create a minimal explanation when all other methods fail.
+        
+        This is the last resort for graceful degradation.
+        
+        Args:
+            exception: The original exception to explain
+            original_error: The error that prevented normal explanation
+            
+        Returns:
+            Minimal ErrorExplanation that should always work
+        """
+        try:
+            error_type = getattr(type(exception), '__name__', 'Unknown')
+            error_message = str(exception) if exception else 'Неизвестная ошибка'
+            
+            return ErrorExplanation(
+                original_error=error_message,
+                error_type=error_type,
+                simple_explanation="Произошла ошибка в вашем коде. К сожалению, не удалось создать подробное объяснение.",
+                fix_tip="Проверьте сообщение об ошибке выше и попробуйте найти проблему в коде. Обратитесь за помощью, если не можете решить проблему самостоятельно.",
+                code_example="# Общий способ обработки ошибок:\ntry:\n    # ваш код\n    pass\nexcept Exception as e:\n    print(f'Ошибка: {e}')",
+                additional_info=f"Внутренняя ошибка fishertools: {original_error}"
+            )
+        except Exception:
+            # Absolute last resort - create explanation with minimal dependencies
+            return ErrorExplanation(
+                original_error="Критическая ошибка",
+                error_type="Critical",
+                simple_explanation="Произошла критическая ошибка в системе объяснения ошибок.",
+                fix_tip="Обратитесь к разработчикам fishertools с описанием проблемы.",
+                code_example="# Обратитесь за помощью",
+                additional_info="Критическая ошибка системы"
+            )
+
+
+def explain_error(exception: Exception, 
+                 language: str = 'ru',
+                 format_type: str = 'console',
+                 **kwargs) -> None:
+    """
+    Main public API function for explaining Python errors in simple terms.
+    
+    This function takes any Python exception and provides a beginner-friendly
+    explanation in Russian, including what the error means, how to fix it,
+    and a relevant code example.
+    
+    Args:
+        exception: The Python exception to explain (required)
+        language: Language for explanations ('ru' or 'en', default: 'ru')
+        format_type: Output format ('console', 'plain', 'json', default: 'console')
+        **kwargs: Additional formatting parameters:
+            - use_colors: Whether to use colors in console output (default: True)
+            - show_original_error: Whether to show original error message (default: True)
+            - show_traceback: Whether to show traceback (default: False)
+    
+    Raises:
+        TypeError: If exception parameter is not an Exception instance
+        ValueError: If language or format_type parameters are invalid
+    
+    Examples:
+        >>> try:
+        ...     result = 10 / 0
+        ... except Exception as e:
+        ...     explain_error(e)
+        
+        >>> explain_error(TypeError("'str' object cannot be interpreted as an integer"))
+        
+        >>> explain_error(ValueError("invalid literal"), format_type='json')
+    """
+    # Parameter validation with custom exceptions
+    if not isinstance(exception, Exception):
+        raise TypeError(f"Параметр 'exception' должен быть экземпляром Exception, "
+                       f"получен {type(exception).__name__}")
+    
+    # Validate language parameter
+    valid_languages = ['ru', 'en']
+    if language not in valid_languages:
+        raise ValueError(f"Параметр 'language' должен быть одним из {valid_languages}, "
+                        f"получен '{language}'")
+    
+    # Validate format_type parameter
+    valid_formats = ['console', 'plain', 'json']
+    if format_type not in valid_formats:
+        raise ValueError(f"Параметр 'format_type' должен быть одним из {valid_formats}, "
+                        f"получен '{format_type}'")
+    
+    try:
+        from .formatters import get_formatter
+        
+        # Create configuration based on parameters
+        config = ExplainerConfig(
+            language=language,
+            format_type=format_type,
+            use_colors=kwargs.get('use_colors', True),
+            show_original_error=kwargs.get('show_original_error', True),
+            show_traceback=kwargs.get('show_traceback', False)
+        )
+        
+        # Create explainer and get explanation
+        explainer = ErrorExplainer(config)
+        explanation = explainer.explain(exception)
+        
+        # Get appropriate formatter and format output
+        formatter = get_formatter(format_type, use_colors=config.use_colors)
+        formatted_output = formatter.format(explanation)
+        
+        # Output to console by default
+        print(formatted_output)
+        
+    except ExplanationError as e:
+        # Handle explanation-specific errors gracefully
+        print(f"Ошибка при объяснении исключения: {e.get_full_message()}")
+        print(f"Оригинальная ошибка: {type(exception).__name__}: {exception}")
+        if e.original_error:
+            print(f"Техническая информация: {e.original_error}")
+        
+    except FormattingError as e:
+        # Handle formatting errors - try to show basic explanation
+        print(f"Ошибка форматирования: {e.get_full_message()}")
+        try:
+            # Try to create a basic explanation without formatting
+            explainer = ErrorExplainer()
+            explanation = explainer.explain(exception)
+            print(f"Простое объяснение: {explanation.simple_explanation}")
+            print(f"Совет: {explanation.fix_tip}")
+        except Exception:
+            print(f"Оригинальная ошибка: {type(exception).__name__}: {exception}")
+        
+    except ConfigurationError as e:
+        # Handle configuration errors
+        print(f"Ошибка конфигурации: {e.get_full_message()}")
+        print(f"Оригинальная ошибка: {type(exception).__name__}: {exception}")
+        
+    except FishertoolsError as e:
+        # Handle any other fishertools-specific errors
+        print(f"Ошибка fishertools: {e.get_full_message()}")
+        print(f"Оригинальная ошибка: {type(exception).__name__}: {exception}")
+        
+    except Exception as e:
+        # Ultimate fallback for any unexpected errors
+        print(f"Неожиданная ошибка в fishertools: {e}")
+        print(f"Оригинальная ошибка: {type(exception).__name__}: {exception}")
+        print("Пожалуйста, сообщите об этой проблеме разработчикам fishertools.")