fishertools 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

fishertools/__init__.py

@@ -11,7 +11,7 @@ Fishertools - инструменты, которые делают Python удо
     legacy - функции для обратной совместимости
 """
 
-__version__ = "0.2.1"
+__version__ = "0.3.4"
 __author__ = "f1sherFM"
 
 # Primary API - main interface for users
@@ -19,7 +19,7 @@ from .errors import explain_error
 
 # Exception classes for error handling
 from .errors import (
-    FishertoolsError, ExplanationError, FormattingError, 
+    FishertoolsError, ExceptionExplanation, ExplanationError, FormattingError, 
     ConfigurationError, PatternError, SafeUtilityError
 )
 
@@ -27,7 +27,8 @@ from .errors import (
 from .safe import (
     safe_get, safe_divide, safe_max, safe_min, safe_sum,
     safe_read_file, safe_write_file, safe_file_exists, 
-    safe_get_file_size, safe_list_files
+    safe_get_file_size, safe_list_files,
+    safe_open, find_file, project_root
 )
 
 # Learning tools - educational functions
@@ -36,6 +37,11 @@ from .learn import (
     list_available_concepts, list_available_topics
 )
 
+# Input validation functions
+from .input_utils import (
+    ask_int, ask_float, ask_str, ask_choice
+)
+
 # Legacy imports for backward compatibility
 from . import utils
 from . import decorators  
@@ -46,6 +52,7 @@ from . import errors
 from . import safe
 from . import learn
 from . import legacy
+from . import input_utils
 
 # New enhancement modules (fishertools-enhancements)
 from . import learning
@@ -59,13 +66,17 @@ __all__ = [
     "explain_error",
     
     # Exception classes for error handling
-    "FishertoolsError", "ExplanationError", "FormattingError", 
+    "FishertoolsError", "ExceptionExplanation", "ExplanationError", "FormattingError", 
     "ConfigurationError", "PatternError", "SafeUtilityError",
     
     # Safe utilities - direct access to commonly used functions
     "safe_get", "safe_divide", "safe_max", "safe_min", "safe_sum",
     "safe_read_file", "safe_write_file", "safe_file_exists", 
     "safe_get_file_size", "safe_list_files",
+    "safe_open", "find_file", "project_root",
+    
+    # Input validation functions
+    "ask_int", "ask_float", "ask_str", "ask_choice",
     
     # Learning tools - direct access to educational functions
     "generate_example", "show_best_practice", 
@@ -75,7 +86,7 @@ __all__ = [
     "utils", "decorators", "helpers",
     
     # New modules for advanced usage
-    "errors", "safe", "learn", "legacy",
+    "errors", "safe", "learn", "legacy", "input_utils",
     
     # Enhancement modules (fishertools-enhancements)
     "learning", "documentation", "examples", "config", "integration"

fishertools/errors/__init__.py

@@ -8,7 +8,7 @@ for beginners learning Python.
 from .explainer import ErrorExplainer, explain_error
 from .patterns import ErrorPattern
 from .formatters import ConsoleFormatter, PlainFormatter, JsonFormatter, get_formatter
-from .models import ErrorExplanation, ExplainerConfig
+from .models import ErrorExplanation, ExplainerConfig, ExceptionExplanation
 from .exceptions import (
     FishertoolsError, ExplanationError, FormattingError, 
     ConfigurationError, PatternError, SafeUtilityError
@@ -17,13 +17,21 @@ from .recovery import (
     ErrorRecoveryManager, ErrorSeverity, RecoveryStrategy, ErrorContext, RecoveryAction,
     get_recovery_manager, handle_error_with_recovery, with_error_recovery
 )
+from .exception_types import (
+    identify_exception_type, get_exception_type_info, is_supported_exception_type,
+    get_exception_type_mapping, get_supported_exception_types, ExceptionTypeInfo,
+    EXCEPTION_TYPE_MAPPING
+)
 
 __all__ = [
     "ErrorExplainer", "explain_error", "ErrorPattern", 
     "ConsoleFormatter", "PlainFormatter", "JsonFormatter", "get_formatter",
-    "ErrorExplanation", "ExplainerConfig",
+    "ErrorExplanation", "ExceptionExplanation", "ExplainerConfig",
     "FishertoolsError", "ExplanationError", "FormattingError", 
     "ConfigurationError", "PatternError", "SafeUtilityError",
     "ErrorRecoveryManager", "ErrorSeverity", "RecoveryStrategy", "ErrorContext", "RecoveryAction",
-    "get_recovery_manager", "handle_error_with_recovery", "with_error_recovery"
+    "get_recovery_manager", "handle_error_with_recovery", "with_error_recovery",
+    "identify_exception_type", "get_exception_type_info", "is_supported_exception_type",
+    "get_exception_type_mapping", "get_supported_exception_types", "ExceptionTypeInfo",
+    "EXCEPTION_TYPE_MAPPING"
 ]

fishertools/errors/exception_types.py

@@ -0,0 +1,282 @@
+"""
+Exception type identification module.
+
+This module provides utilities for identifying and mapping Python exception types
+to explanation templates. It supports the following exception types:
+- TypeError
+- ValueError
+- IndexError
+- KeyError
+- AttributeError
+- FileNotFoundError
+- PermissionError
+- ZeroDivisionError
+- NameError
+- And provides fallback for unknown exception types
+"""
+
+from typing import Dict, Type, Optional, Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class ExceptionTypeInfo:
+    """Information about an exception type."""
+    exception_class: Type[Exception]
+    name: str
+    description: str
+    common_causes: list
+
+
+# Mapping of exception types to their information and explanation templates
+EXCEPTION_TYPE_MAPPING: Dict[Type[Exception], ExceptionTypeInfo] = {
+    TypeError: ExceptionTypeInfo(
+        exception_class=TypeError,
+        name="TypeError",
+        description="Type mismatch or incompatible operation",
+        common_causes=[
+            "Mixing incompatible types (e.g., adding string and number)",
+            "Wrong number of function arguments",
+            "Calling a non-callable object",
+            "Invalid operation for the given type"
+        ]
+    ),
+    ValueError: ExceptionTypeInfo(
+        exception_class=ValueError,
+        name="ValueError",
+        description="Invalid value for the operation",
+        common_causes=[
+            "Invalid literal for type conversion",
+            "Unpacking wrong number of values",
+            "Invalid argument value",
+            "String format error"
+        ]
+    ),
+    IndexError: ExceptionTypeInfo(
+        exception_class=IndexError,
+        name="IndexError",
+        description="Sequence index out of range",
+        common_causes=[
+            "Accessing list/string index that doesn't exist",
+            "Index too large or negative",
+            "Empty sequence access",
+            "Off-by-one error in loop"
+        ]
+    ),
+    KeyError: ExceptionTypeInfo(
+        exception_class=KeyError,
+        name="KeyError",
+        description="Dictionary key not found",
+        common_causes=[
+            "Accessing non-existent dictionary key",
+            "Typo in key name",
+            "Key not added to dictionary",
+            "Wrong key type"
+        ]
+    ),
+    AttributeError: ExceptionTypeInfo(
+        exception_class=AttributeError,
+        name="AttributeError",
+        description="Attribute or method not found on object",
+        common_causes=[
+            "Typo in attribute/method name",
+            "Wrong object type",
+            "Object not initialized",
+            "Attribute doesn't exist on this type"
+        ]
+    ),
+    FileNotFoundError: ExceptionTypeInfo(
+        exception_class=FileNotFoundError,
+        name="FileNotFoundError",
+        description="File or directory not found",
+        common_causes=[
+            "File path is incorrect",
+            "File doesn't exist",
+            "Wrong working directory",
+            "Typo in filename"
+        ]
+    ),
+    PermissionError: ExceptionTypeInfo(
+        exception_class=PermissionError,
+        name="PermissionError",
+        description="Permission denied for file operation",
+        common_causes=[
+            "Insufficient file permissions",
+            "File is read-only",
+            "Directory is protected",
+            "Running without required privileges"
+        ]
+    ),
+    ZeroDivisionError: ExceptionTypeInfo(
+        exception_class=ZeroDivisionError,
+        name="ZeroDivisionError",
+        description="Division by zero",
+        common_causes=[
+            "Dividing by zero",
+            "Modulo by zero",
+            "Denominator is zero",
+            "Variable contains zero unexpectedly"
+        ]
+    ),
+    NameError: ExceptionTypeInfo(
+        exception_class=NameError,
+        name="NameError",
+        description="Name not defined",
+        common_causes=[
+            "Variable not defined",
+            "Typo in variable name",
+            "Variable used before definition",
+            "Variable out of scope"
+        ]
+    ),
+}
+
+
+def identify_exception_type(exception: Exception) -> str:
+    """
+    Identify the type of an exception and return its name.
+    
+    Args:
+        exception: The exception object to identify
+        
+    Returns:
+        String name of the exception type (e.g., "TypeError", "ValueError")
+        
+    Raises:
+        TypeError: If the argument is not an Exception instance
+        
+    Example:
+        >>> try:
+        ...     x = 1 / 0
+        ... except Exception as e:
+        ...     exc_type = identify_exception_type(e)
+        ...     print(exc_type)  # "ZeroDivisionError"
+    """
+    if not isinstance(exception, Exception):
+        raise TypeError(f"Expected Exception instance, got {type(exception).__name__}")
+    
+    exception_class = type(exception)
+    
+    # Check if it's a known exception type
+    if exception_class in EXCEPTION_TYPE_MAPPING:
+        return EXCEPTION_TYPE_MAPPING[exception_class].name
+    
+    # Check if it's a subclass of a known exception type
+    for known_type, info in EXCEPTION_TYPE_MAPPING.items():
+        if isinstance(exception, known_type):
+            return info.name
+    
+    # Fallback for unknown exception types
+    return exception_class.__name__
+
+
+def get_exception_type_info(exception: Exception) -> ExceptionTypeInfo:
+    """
+    Get detailed information about an exception type.
+    
+    Args:
+        exception: The exception object
+        
+    Returns:
+        ExceptionTypeInfo object with details about the exception type,
+        or a generic info object for unknown types
+        
+    Raises:
+        TypeError: If the argument is not an Exception instance
+        
+    Example:
+        >>> try:
+        ...     d = {}
+        ...     value = d['missing_key']
+        ... except Exception as e:
+        ...     info = get_exception_type_info(e)
+        ...     print(info.description)  # "Dictionary key not found"
+    """
+    if not isinstance(exception, Exception):
+        raise TypeError(f"Expected Exception instance, got {type(exception).__name__}")
+    
+    exception_class = type(exception)
+    
+    # Check if it's a known exception type
+    if exception_class in EXCEPTION_TYPE_MAPPING:
+        return EXCEPTION_TYPE_MAPPING[exception_class]
+    
+    # Check if it's a subclass of a known exception type
+    for known_type, info in EXCEPTION_TYPE_MAPPING.items():
+        if isinstance(exception, known_type):
+            return info
+    
+    # Fallback for unknown exception types
+    return ExceptionTypeInfo(
+        exception_class=exception_class,
+        name=exception_class.__name__,
+        description="An unexpected error occurred",
+        common_causes=["Unknown cause - check the error message for details"]
+    )
+
+
+def is_supported_exception_type(exception: Exception) -> bool:
+    """
+    Check if an exception type is explicitly supported.
+    
+    Args:
+        exception: The exception object to check
+        
+    Returns:
+        True if the exception type is in the supported list, False otherwise
+        
+    Raises:
+        TypeError: If the argument is not an Exception instance
+        
+    Example:
+        >>> try:
+        ...     x = 1 / 0
+        ... except Exception as e:
+        ...     if is_supported_exception_type(e):
+        ...         print("This exception type is supported")
+    """
+    if not isinstance(exception, Exception):
+        raise TypeError(f"Expected Exception instance, got {type(exception).__name__}")
+    
+    exception_class = type(exception)
+    
+    # Check if it's a known exception type
+    if exception_class in EXCEPTION_TYPE_MAPPING:
+        return True
+    
+    # Check if it's a subclass of a known exception type
+    for known_type in EXCEPTION_TYPE_MAPPING.keys():
+        if isinstance(exception, known_type):
+            return True
+    
+    return False
+
+
+def get_exception_type_mapping() -> Dict[Type[Exception], ExceptionTypeInfo]:
+    """
+    Get the complete exception type mapping.
+    
+    Returns:
+        Dictionary mapping exception classes to their information
+        
+    Example:
+        >>> mapping = get_exception_type_mapping()
+        >>> for exc_class, info in mapping.items():
+        ...     print(f"{info.name}: {info.description}")
+    """
+    return EXCEPTION_TYPE_MAPPING.copy()
+
+
+def get_supported_exception_types() -> list:
+    """
+    Get a list of all supported exception types.
+    
+    Returns:
+        List of supported exception type names
+        
+    Example:
+        >>> types = get_supported_exception_types()
+        >>> print(types)
+        ['TypeError', 'ValueError', 'IndexError', ...]
+    """
+    return [info.name for info in EXCEPTION_TYPE_MAPPING.values()]

fishertools/errors/explainer.py

@@ -5,7 +5,7 @@ This module contains the ErrorExplainer class and explain_error function.
 """
 
 from typing import Optional, List
-from .models import ErrorExplanation, ExplainerConfig, ErrorPattern
+from .models import ErrorExplanation, ExplainerConfig, ErrorPattern, ExceptionExplanation
 from .patterns import load_default_patterns
 from .exceptions import ExplanationError, FormattingError, ConfigurationError, FishertoolsError
 
@@ -83,6 +83,92 @@ class ErrorExplainer:
             # Graceful degradation - create a minimal explanation if all else fails
             return self._create_emergency_explanation(exception, e)
     
+    def explain_structured(self, exception: Exception) -> ExceptionExplanation:
+        """
+        Create a structured explanation for the given exception.
+        
+        This method generates an ExceptionExplanation object with all required fields:
+        - exception_type: The type of the exception
+        - simple_explanation: Plain-language explanation of what went wrong
+        - fix_suggestions: List of ways to fix the problem
+        - code_example: Minimal code example showing correct usage
+        - traceback_context: Optional traceback information
+        
+        Args:
+            exception: The exception to explain
+            
+        Returns:
+            ExceptionExplanation object with structured explanation
+            
+        Raises:
+            ExceptionError: If explanation creation fails
+            
+        Example:
+            >>> try:
+            ...     x = 1 / 0
+            ... except Exception as e:
+            ...     explanation = explainer.explain_structured(e)
+            ...     print(explanation.simple_explanation)
+        """
+        if not isinstance(exception, Exception):
+            raise ExplanationError(f"Параметр должен быть экземпляром Exception, получен {type(exception).__name__}")
+        
+        try:
+            # Get the basic explanation
+            error_explanation = self.explain(exception)
+            
+            # Convert to structured format
+            return ExceptionExplanation(
+                exception_type=error_explanation.error_type,
+                simple_explanation=error_explanation.simple_explanation,
+                fix_suggestions=[error_explanation.fix_tip],  # Convert single tip to list
+                code_example=error_explanation.code_example,
+                traceback_context=error_explanation.additional_info
+            )
+        except Exception as e:
+            if isinstance(e, ExplanationError):
+                raise
+            # Graceful degradation
+            return self._create_emergency_structured_explanation(exception, e)
+    
+    def _create_emergency_structured_explanation(self, exception: Exception, 
+                                                 original_error: Exception) -> ExceptionExplanation:
+        """
+        Create a minimal structured explanation when all other methods fail.
+        
+        Args:
+            exception: The original exception to explain
+            original_error: The error that prevented normal explanation
+            
+        Returns:
+            Minimal ExceptionExplanation that should always work
+        """
+        try:
+            error_type = getattr(type(exception), '__name__', 'Unknown')
+            error_message = str(exception) if exception else 'Unknown error'
+            
+            return ExceptionExplanation(
+                exception_type=error_type,
+                simple_explanation="An error occurred in your code. Unfortunately, a detailed explanation could not be generated.",
+                fix_suggestions=[
+                    "Check the error message above and try to find the problem in your code.",
+                    "Search for information about this error type in Python documentation.",
+                    "Ask for help if you cannot solve the problem yourself."
+                ],
+                code_example=f"# General error handling:\ntry:\n    # your code\n    pass\nexcept {error_type} as e:\n    print(f'Error: {{e}}')",
+                traceback_context=f"Internal fishertools error: {original_error}"
+            )
+        except Exception:
+            # Absolute last resort
+            return ExceptionExplanation(
+                exception_type="Critical",
+                simple_explanation="A critical error occurred in the error explanation system.",
+                fix_suggestions=["Contact fishertools developers with a description of the problem."],
+                code_example="# Please contact support",
+                traceback_context="Critical system error"
+            )
+
+    
     def _match_pattern(self, exception: Exception) -> Optional[ErrorPattern]:
         """
         Find the best matching pattern for the given exception.

fishertools/errors/models.py

@@ -225,4 +225,76 @@ class ExplainerConfig:
             return cls(**data)
         except Exception as e:
             from .exceptions import ConfigurationError
-            raise ConfigurationError(f"Не удалось создать ExplainerConfig из словаря: {e}", original_error=e)
+            raise ConfigurationError(f"Не удалось создать ExplainerConfig из словаря: {e}", original_error=e)
+
+
+
+@dataclass
+class ExceptionExplanation:
+    """
+    Structured explanation of an exception.
+    
+    This dataclass provides a comprehensive explanation of a Python exception,
+    including the exception type, a simple explanation, fix suggestions,
+    a code example, and optional traceback context.
+    """
+    exception_type: str
+    simple_explanation: str
+    fix_suggestions: List[str]
+    code_example: str
+    traceback_context: Optional[str] = None
+    
+    def __post_init__(self):
+        """Validate the explanation after initialization."""
+        from .exceptions import ExplanationError
+        
+        if not self.exception_type.strip():
+            raise ExplanationError("exception_type cannot be empty")
+        if not self.simple_explanation.strip():
+            raise ExplanationError("simple_explanation cannot be empty")
+        if not self.fix_suggestions:
+            raise ExplanationError("fix_suggestions cannot be empty")
+        if not all(isinstance(s, str) and s.strip() for s in self.fix_suggestions):
+            raise ExplanationError("All fix_suggestions must be non-empty strings")
+        if not self.code_example.strip():
+            raise ExplanationError("code_example cannot be empty")
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert explanation to dictionary for serialization.
+        
+        Returns:
+            Dictionary representation of the explanation
+        """
+        return asdict(self)
+    
+    def to_json(self) -> str:
+        """
+        Convert explanation to JSON string.
+        
+        Returns:
+            JSON representation of the explanation
+        """
+        try:
+            return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+        except Exception as e:
+            from .exceptions import FormattingError
+            raise FormattingError(f"Could not convert explanation to JSON: {e}", 
+                                formatter_type="json", original_error=e)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'ExceptionExplanation':
+        """
+        Create ExceptionExplanation from dictionary.
+        
+        Args:
+            data: Dictionary containing explanation data
+            
+        Returns:
+            ExceptionExplanation instance
+        """
+        try:
+            return cls(**data)
+        except Exception as e:
+            from .exceptions import ExplanationError
+            raise ExplanationError(f"Could not create ExceptionExplanation from dictionary: {e}", original_error=e)

fishertools/errors/patterns.py

@@ -105,6 +105,46 @@ DEFAULT_PATTERNS = [
         tip="Внимательно проверьте строку, указанную в ошибке. Убедитесь, что все скобки закрыты, отступы правильные, и нет опечаток в ключевых словах.",
         example="# Неправильно:\n# if x > 5  # забыли двоеточие\n#     print('больше 5')\n# print('привет'  # незакрытая скобка\n\n# Правильно:\nif x > 5:  # двоеточие обязательно\n    print('больше 5')  # правильный отступ\nprint('привет')  # закрытая скобка",
         common_causes=["забыли двоеточие после if/for/def", "незакрытые скобки", "неправильные отступы", "опечатки в ключевых словах"]
+    ),
+    
+    # FileNotFoundError patterns
+    ErrorPattern(
+        error_type=FileNotFoundError,
+        error_keywords=["No such file or directory", "cannot find the file"],
+        explanation="Файл, который вы пытаетесь открыть, не существует. Возможно, неправильно указан путь к файлу или файл находится в другой папке.",
+        tip="Проверьте правильность пути к файлу. Убедитесь, что файл существует в указанной папке. Используйте абсолютный путь или проверьте текущую рабочую папку.",
+        example="# Неправильно:\n# with open('data.txt', 'r') as f:  # файл может не существовать\n#     data = f.read()\n\n# Правильно:\nimport os\nfilepath = 'data.txt'\nif os.path.exists(filepath):\n    with open(filepath, 'r') as f:\n        data = f.read()\nelse:\n    print(f'Файл {filepath} не найден')",
+        common_causes=["неправильный путь к файлу", "файл не существует", "неправильная рабочая папка", "опечатка в имени файла"]
+    ),
+    
+    # PermissionError patterns
+    ErrorPattern(
+        error_type=PermissionError,
+        error_keywords=["Permission denied", "access denied"],
+        explanation="У вас нет прав доступа для выполнения этой операции с файлом. Это может быть файл, защищенный от записи, или папка, к которой нет доступа.",
+        tip="Проверьте права доступа к файлу. Попробуйте запустить программу с правами администратора. Убедитесь, что файл не открыт в другой программе.",
+        example="# Неправильно:\n# with open('protected_file.txt', 'w') as f:  # может быть защищен\n#     f.write('data')\n\n# Правильно:\nimport os\nfilepath = 'protected_file.txt'\nif os.access(filepath, os.W_OK):\n    with open(filepath, 'w') as f:\n        f.write('data')\nelse:\n    print(f'Нет прав доступа к файлу {filepath}')",
+        common_causes=["файл защищен от записи", "недостаточно прав доступа", "файл открыт в другой программе", "папка защищена"]
+    ),
+    
+    # ZeroDivisionError patterns
+    ErrorPattern(
+        error_type=ZeroDivisionError,
+        error_keywords=["division by zero", "integer division or modulo by zero"],
+        explanation="Вы пытаетесь разделить число на ноль, что математически невозможно. Это может быть деление или операция модуля (%).",
+        tip="Проверьте, что делитель не равен нулю перед выполнением операции деления. Используйте условие if для проверки.",
+        example="# Неправильно:\n# result = 10 / 0  # ZeroDivisionError\n\n# Правильно:\ndivisor = 0\nif divisor != 0:\n    result = 10 / divisor\nelse:\n    print('Нельзя делить на ноль')\n    result = None",
+        common_causes=["деление на ноль", "модуль по нулю", "переменная содержит ноль неожиданно", "ошибка в расчетах"]
+    ),
+    
+    # NameError patterns
+    ErrorPattern(
+        error_type=NameError,
+        error_keywords=["is not defined", "name"],
+        explanation="Вы используете переменную или функцию, которая не была определена. Возможно, опечатка в имени или переменная определена в другой области видимости.",
+        tip="Проверьте правильность написания имени переменной. Убедитесь, что переменная определена перед использованием. Проверьте область видимости переменной.",
+        example="# Неправильно:\n# print(my_variable)  # NameError - переменная не определена\n\n# Правильно:\nmy_variable = 'Hello'  # определяем переменную\nprint(my_variable)  # теперь можно использовать\n\n# Или проверяем область видимости:\nif True:\n    local_var = 'local'\nprint(local_var)  # NameError - переменная локальная",
+        common_causes=["опечатка в имени переменной", "переменная не определена", "переменная в другой области видимости", "забыли импортировать модуль"]
     )
 ]