fishertools 0.2.1__py3-none-any.whl

fishertools/config/parser.py

@@ -0,0 +1,265 @@
+"""
+Configuration file parser supporting multiple formats.
+"""
+
+import json
+import os
+from typing import Dict, Any, Optional
+from dataclasses import asdict
+from .models import LearningConfig, ValidationResult, ConfigError, ErrorSeverity, ConfigFormat
+
+try:
+    import yaml
+    YAML_AVAILABLE = True
+except ImportError:
+    YAML_AVAILABLE = False
+
+
+class ConfigurationParser:
+    """
+    Parses configuration files in various formats with validation.
+    
+    Supports JSON, YAML, and TOML formats with comprehensive
+    error reporting and validation.
+    """
+    
+    def __init__(self):
+        """Initialize the configuration parser."""
+        pass
+    
+    def parse_file(self, config_path: str) -> Dict[str, Any]:
+        """
+        Parse a configuration file based on its extension.
+        
+        Args:
+            config_path: Path to the configuration file
+            
+        Returns:
+            Dict[str, Any]: Parsed configuration data
+            
+        Raises:
+            ValueError: If file format is unsupported
+            FileNotFoundError: If file doesn't exist
+        """
+        if not os.path.exists(config_path):
+            raise FileNotFoundError(f"Configuration file not found: {config_path}")
+        
+        format_type = self.detect_format(config_path)
+        
+        with open(config_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        
+        if format_type == ConfigFormat.JSON:
+            return self.parse_json(content)
+        elif format_type == ConfigFormat.YAML:
+            return self.parse_yaml(content)
+        else:
+            raise ValueError(f"Unsupported configuration format: {format_type}")
+    
+    def parse_json(self, content: str) -> Dict[str, Any]:
+        """
+        Parse JSON configuration content.
+        
+        Args:
+            content: JSON content to parse
+            
+        Returns:
+            Dict[str, Any]: Parsed configuration data
+            
+        Raises:
+            ValueError: If JSON is invalid
+        """
+        try:
+            return json.loads(content)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON configuration: {e}")
+    
+    def parse_yaml(self, content: str) -> Dict[str, Any]:
+        """
+        Parse YAML configuration content.
+        
+        Args:
+            content: YAML content to parse
+            
+        Returns:
+            Dict[str, Any]: Parsed configuration data
+            
+        Raises:
+            ValueError: If YAML is invalid
+        """
+        if not YAML_AVAILABLE:
+            raise ValueError("YAML support not available. Install PyYAML to use YAML configurations.")
+        
+        try:
+            return yaml.safe_load(content) or {}
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML configuration: {e}")
+    
+    def format_to_json(self, config: LearningConfig) -> str:
+        """
+        Format configuration as JSON string.
+        
+        Args:
+            config: Configuration to format
+            
+        Returns:
+            str: JSON formatted configuration
+        """
+        config_dict = asdict(config)
+        return json.dumps(config_dict, indent=2, ensure_ascii=False)
+    
+    def format_to_yaml(self, config: LearningConfig) -> str:
+        """
+        Format configuration as YAML string.
+        
+        Args:
+            config: Configuration to format
+            
+        Returns:
+            str: YAML formatted configuration
+        """
+        if not YAML_AVAILABLE:
+            raise ValueError("YAML support not available. Install PyYAML to use YAML configurations.")
+        
+        config_dict = asdict(config)
+        return yaml.dump(config_dict, default_flow_style=False, allow_unicode=True, indent=2)
+    
+    def validate_structure(self, config_data: Dict[str, Any]) -> ValidationResult:
+        """
+        Validate configuration structure and types.
+        
+        Args:
+            config_data: Configuration data to validate
+            
+        Returns:
+            ValidationResult: Validation result with errors/warnings
+        """
+        errors = []
+        warnings = []
+        
+        # Define expected fields and their types
+        expected_fields = {
+            'default_level': str,
+            'explanation_verbosity': str,
+            'visual_aids_enabled': bool,
+            'diagram_style': str,
+            'color_scheme': str,
+            'progress_tracking_enabled': bool,
+            'save_progress_locally': bool,
+            'suggested_topics_count': int,
+            'max_examples_per_topic': int,
+            'exercise_difficulty_progression': list,
+            'readthedocs_project': (str, type(None)),
+            'sphinx_theme': str,
+            'enable_interactive_sessions': bool,
+            'session_timeout_minutes': int,
+            'max_hint_count': int
+        }
+        
+        # Valid values for enum-like fields
+        valid_values = {
+            'default_level': ['beginner', 'intermediate', 'advanced'],
+            'explanation_verbosity': ['brief', 'detailed', 'comprehensive']
+        }
+        
+        # Check for missing required fields
+        required_fields = ['default_level', 'explanation_verbosity']
+        for field in required_fields:
+            if field not in config_data:
+                errors.append(ConfigError(
+                    message=f"Required field '{field}' is missing",
+                    field_path=field,
+                    severity=ErrorSeverity.ERROR,
+                    suggested_fix=f"Add '{field}' field with a valid value"
+                ))
+        
+        # Check field types and values
+        for field, expected_type in expected_fields.items():
+            if field in config_data:
+                value = config_data[field]
+                
+                # Handle nullable fields
+                if isinstance(expected_type, tuple):
+                    if value is not None and not isinstance(value, expected_type[0]):
+                        errors.append(ConfigError(
+                            message=f"Field '{field}' has invalid type. Expected {expected_type[0].__name__} or None, got {type(value).__name__}",
+                            field_path=field,
+                            severity=ErrorSeverity.ERROR,
+                            suggested_fix=f"Change '{field}' to a {expected_type[0].__name__} value or null"
+                        ))
+                else:
+                    if not isinstance(value, expected_type):
+                        errors.append(ConfigError(
+                            message=f"Field '{field}' has invalid type. Expected {expected_type.__name__}, got {type(value).__name__}",
+                            field_path=field,
+                            severity=ErrorSeverity.ERROR,
+                            suggested_fix=f"Change '{field}' to a {expected_type.__name__} value"
+                        ))
+                
+                # Check valid values for enum-like fields
+                if field in valid_values and value not in valid_values[field]:
+                    errors.append(ConfigError(
+                        message=f"Field '{field}' has invalid value '{value}'. Valid values: {valid_values[field]}",
+                        field_path=field,
+                        severity=ErrorSeverity.ERROR,
+                        suggested_fix=f"Set '{field}' to one of: {', '.join(valid_values[field])}"
+                    ))
+        
+        # Check for unknown fields (warnings)
+        for field in config_data:
+            if field not in expected_fields:
+                warnings.append(ConfigError(
+                    message=f"Unknown field '{field}' will be ignored",
+                    field_path=field,
+                    severity=ErrorSeverity.WARNING,
+                    suggested_fix=f"Remove '{field}' field or check for typos"
+                ))
+        
+        # Validate numeric ranges
+        if 'suggested_topics_count' in config_data:
+            value = config_data['suggested_topics_count']
+            if isinstance(value, int) and (value < 1 or value > 10):
+                warnings.append(ConfigError(
+                    message=f"Field 'suggested_topics_count' value {value} is outside recommended range (1-10)",
+                    field_path='suggested_topics_count',
+                    severity=ErrorSeverity.WARNING,
+                    suggested_fix="Set 'suggested_topics_count' to a value between 1 and 10"
+                ))
+        
+        if 'max_examples_per_topic' in config_data:
+            value = config_data['max_examples_per_topic']
+            if isinstance(value, int) and (value < 1 or value > 20):
+                warnings.append(ConfigError(
+                    message=f"Field 'max_examples_per_topic' value {value} is outside recommended range (1-20)",
+                    field_path='max_examples_per_topic',
+                    severity=ErrorSeverity.WARNING,
+                    suggested_fix="Set 'max_examples_per_topic' to a value between 1 and 20"
+                ))
+        
+        return ValidationResult(
+            is_valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings
+        )
+    
+    def detect_format(self, file_path: str) -> ConfigFormat:
+        """
+        Detect configuration file format from extension.
+        
+        Args:
+            file_path: Path to the configuration file
+            
+        Returns:
+            ConfigFormat: Detected file format
+        """
+        _, ext = os.path.splitext(file_path.lower())
+        
+        if ext == '.json':
+            return ConfigFormat.JSON
+        elif ext in ['.yaml', '.yml']:
+            return ConfigFormat.YAML
+        elif ext == '.toml':
+            return ConfigFormat.TOML
+        else:
+            # Default to JSON if extension is unknown
+            return ConfigFormat.JSON

fishertools/decorators.py

@@ -0,0 +1,93 @@
+"""
+Полезные декораторы для отладки, профилирования и других задач
+"""
+
+import time
+import functools
+from typing import Any, Callable
+
+
+def timer(func: Callable) -> Callable:
+    """Декоратор для измерения времени выполнения функции"""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        print(f"{func.__name__} выполнилась за {end_time - start_time:.4f} секунд")
+        return result
+    return wrapper
+
+
+def debug(func: Callable) -> Callable:
+    """Декоратор для отладки - выводит аргументы и результат функции"""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        print(f"Вызов {func.__name__} с аргументами: args={args}, kwargs={kwargs}")
+        result = func(*args, **kwargs)
+        print(f"{func.__name__} вернула: {result}")
+        return result
+    return wrapper
+
+
+def retry(max_attempts: int = 3, delay: float = 1.0):
+    """Декоратор для повторных попыток выполнения функции при ошибке"""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    if attempt == max_attempts - 1:
+                        raise e
+                    print(f"Попытка {attempt + 1} не удалась: {e}. Повтор через {delay} сек...")
+                    time.sleep(delay)
+        return wrapper
+    return decorator
+
+
+def cache_result(func: Callable) -> Callable:
+    """Простой декоратор для кеширования результатов функции"""
+    cache = {}
+    
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # Создаем ключ из аргументов
+        key = str(args) + str(sorted(kwargs.items()))
+        
+        if key in cache:
+            print(f"Результат {func.__name__} взят из кеша")
+            return cache[key]
+        
+        result = func(*args, **kwargs)
+        cache[key] = result
+        return result
+    
+    return wrapper
+
+
+def validate_types(**expected_types):
+    """Декоратор для проверки типов аргументов функции"""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Получаем имена параметров функции
+            import inspect
+            sig = inspect.signature(func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+            
+            # Проверяем типы
+            for param_name, expected_type in expected_types.items():
+                if param_name in bound_args.arguments:
+                    value = bound_args.arguments[param_name]
+                    if not isinstance(value, expected_type):
+                        raise TypeError(
+                            f"Параметр '{param_name}' должен быть типа {expected_type.__name__}, "
+                            f"получен {type(value).__name__}"
+                        )
+            
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

fishertools/documentation/__init__.py

@@ -0,0 +1,38 @@
+"""
+Documentation Generation Module
+
+Provides automatic API documentation generation with Sphinx integration
+and ReadTheDocs publishing capabilities.
+"""
+
+from .generator import DocumentationGenerator
+from .visual import VisualDocumentation
+from .api import APIGenerator
+from .models import (
+    APIInfo,
+    FunctionInfo,
+    SphinxDocuments,
+    NavigationTree,
+    ExampleCode,
+    PublishResult,
+    MermaidDiagram,
+    FlowDiagram,
+    Flowchart,
+    StructureDiagram
+)
+
+__all__ = [
+    "DocumentationGenerator",
+    "VisualDocumentation",
+    "APIGenerator",
+    "APIInfo",
+    "FunctionInfo", 
+    "SphinxDocuments",
+    "NavigationTree",
+    "ExampleCode",
+    "PublishResult",
+    "MermaidDiagram",
+    "FlowDiagram",
+    "Flowchart",
+    "StructureDiagram"
+]

fishertools/documentation/api.py

@@ -0,0 +1,242 @@
+"""
+API documentation generator with Sphinx AutoAPI integration.
+"""
+
+import ast
+import os
+import inspect
+from typing import List, Dict, Any, Optional
+from .models import APIInfo, FunctionInfo
+
+
+class APIGenerator:
+    """
+    Generates API documentation using Sphinx AutoAPI.
+    
+    Extracts docstrings, parameter types, and function signatures
+    to create comprehensive API documentation.
+    """
+    
+    def __init__(self):
+        """Initialize the API generator."""
+        pass
+    
+    def parse_module(self, module_path: str) -> APIInfo:
+        """
+        Parse a Python module and extract API information.
+        
+        Args:
+            module_path: Path to the Python module file
+            
+        Returns:
+            APIInfo: Extracted API information
+        """
+        with open(module_path, 'r', encoding='utf-8') as f:
+            source_code = f.read()
+        
+        tree = ast.parse(source_code)
+        module_name = os.path.splitext(os.path.basename(module_path))[0]
+        
+        functions = []
+        classes = []
+        constants = {}
+        imports = []
+        
+        # Extract module-level docstring
+        module_docstring = self.extract_docstring(tree)
+        
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                # Only include top-level functions (not nested or class methods)
+                if isinstance(node.parent if hasattr(node, 'parent') else None, ast.Module) or not hasattr(node, 'parent'):
+                    func_info = self.extract_function_info(node, module_path)
+                    functions.append(func_info)
+            
+            elif isinstance(node, ast.ClassDef):
+                class_info = {
+                    'name': node.name,
+                    'docstring': self.extract_docstring(node),
+                    'methods': [],
+                    'line_number': node.lineno
+                }
+                
+                # Extract class methods
+                for item in node.body:
+                    if isinstance(item, ast.FunctionDef):
+                        method_info = self.extract_function_info(item, module_path)
+                        class_info['methods'].append(method_info)
+                
+                classes.append(class_info)
+            
+            elif isinstance(node, ast.Assign):
+                # Extract module-level constants
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id.isupper():
+                        constants[target.id] = ast.unparse(node.value) if hasattr(ast, 'unparse') else str(node.value)
+            
+            elif isinstance(node, (ast.Import, ast.ImportFrom)):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        imports.append(f"import {alias.name}")
+                else:
+                    module = node.module or ""
+                    for alias in node.names:
+                        imports.append(f"from {module} import {alias.name}")
+        
+        return APIInfo(
+            module_name=module_name,
+            functions=functions,
+            classes=classes,
+            constants=constants,
+            imports=imports,
+            docstring=module_docstring
+        )
+    
+    def extract_function_info(self, func_node: ast.FunctionDef, module_path: str) -> FunctionInfo:
+        """
+        Extract information from a function AST node.
+        
+        Args:
+            func_node: AST node representing a function
+            module_path: Path to the module containing the function
+            
+        Returns:
+            FunctionInfo: Extracted function information
+        """
+        docstring = self.extract_docstring(func_node)
+        parameters = self.extract_type_annotations(func_node)
+        
+        # Extract return type annotation
+        return_type = None
+        if func_node.returns:
+            if hasattr(ast, 'unparse'):
+                return_type = ast.unparse(func_node.returns)
+            else:
+                return_type = str(func_node.returns)
+        
+        return FunctionInfo(
+            name=func_node.name,
+            docstring=docstring,
+            parameters=parameters,
+            return_type=return_type,
+            module_path=module_path,
+            line_number=func_node.lineno
+        )
+    
+    def extract_docstring(self, node: ast.AST) -> Optional[str]:
+        """
+        Extract docstring from an AST node.
+        
+        Args:
+            node: AST node (function, class, or module)
+            
+        Returns:
+            Optional[str]: Extracted docstring or None
+        """
+        if not hasattr(node, 'body') or not node.body:
+            return None
+        
+        first_stmt = node.body[0]
+        if isinstance(first_stmt, ast.Expr) and isinstance(first_stmt.value, ast.Constant):
+            if isinstance(first_stmt.value.value, str):
+                return first_stmt.value.value
+        elif isinstance(first_stmt, ast.Expr) and isinstance(first_stmt.value, ast.Str):
+            # For older Python versions
+            return first_stmt.value.s
+        
+        return None
+    
+    def extract_type_annotations(self, func_node: ast.FunctionDef) -> Dict[str, str]:
+        """
+        Extract type annotations from a function.
+        
+        Args:
+            func_node: Function AST node
+            
+        Returns:
+            Dict[str, str]: Parameter names mapped to type annotations
+        """
+        parameters = {}
+        
+        for arg in func_node.args.args:
+            param_name = arg.arg
+            if arg.annotation:
+                if hasattr(ast, 'unparse'):
+                    param_type = ast.unparse(arg.annotation)
+                else:
+                    param_type = str(arg.annotation)
+                parameters[param_name] = param_type
+            else:
+                parameters[param_name] = "Any"
+        
+        # Handle keyword-only arguments
+        for arg in func_node.args.kwonlyargs:
+            param_name = arg.arg
+            if arg.annotation:
+                if hasattr(ast, 'unparse'):
+                    param_type = ast.unparse(arg.annotation)
+                else:
+                    param_type = str(arg.annotation)
+                parameters[param_name] = param_type
+            else:
+                parameters[param_name] = "Any"
+        
+        return parameters
+    
+    def generate_sphinx_rst(self, api_info: APIInfo) -> str:
+        """
+        Generate Sphinx RST documentation from API information.
+        
+        Args:
+            api_info: API information to document
+            
+        Returns:
+            str: Generated RST content
+        """
+        rst_content = []
+        
+        # Module header
+        module_title = f"{api_info.module_name} Module"
+        rst_content.append(module_title)
+        rst_content.append("=" * len(module_title))
+        rst_content.append("")
+        
+        # Module docstring
+        if api_info.docstring:
+            rst_content.append(api_info.docstring)
+            rst_content.append("")
+        
+        # Functions section
+        if api_info.functions:
+            rst_content.append("Functions")
+            rst_content.append("-" * 9)
+            rst_content.append("")
+            
+            for func in api_info.functions:
+                rst_content.append(f".. autofunction:: {api_info.module_name}.{func.name}")
+                rst_content.append("")
+        
+        # Classes section
+        if api_info.classes:
+            rst_content.append("Classes")
+            rst_content.append("-" * 7)
+            rst_content.append("")
+            
+            for cls in api_info.classes:
+                rst_content.append(f".. autoclass:: {api_info.module_name}.{cls['name']}")
+                rst_content.append("   :members:")
+                rst_content.append("   :undoc-members:")
+                rst_content.append("   :show-inheritance:")
+                rst_content.append("")
+        
+        # Constants section
+        if api_info.constants:
+            rst_content.append("Constants")
+            rst_content.append("-" * 9)
+            rst_content.append("")
+            
+            for name, value in api_info.constants.items():
+                rst_content.append(f".. autodata:: {api_info.module_name}.{name}")
+                rst_content.append("")
+        
+        return "\n".join(rst_content)