mc5-api-client 1.0.16__py3-none-any.whl → 1.0.18__py3-none-any.whl

mc5_api_client/debug.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+# ────────────[ CHIZOBA ]────────────────────────────
+# | Email    : chizoba2026@hotmail.com
+# | File     : debug.py
+# | License  | MIT License © 2026 Chizoba
+# | Brief    | Enhanced debugging utilities for MC5 API Client
+# ────────────────★─────────────────────────────────
+
+import sys
+import traceback
+import json
+from typing import Optional, Dict, Any, Callable
+from datetime import datetime
+from .telemetry import is_telemetry_enabled, report_error
+
+class DebugContext:
+    """Context manager for debugging function calls."""
+    
+    def __init__(self, function_name: str, **kwargs):
+        self.function_name = function_name
+        self.kwargs = kwargs
+        self.start_time = None
+        
+    def __enter__(self):
+        self.start_time = datetime.now()
+        # if is_telemetry_enabled():
+        #     print(f"🔍 Debug: Starting {self.function_name}")
+        #     if self.kwargs:
+        #         print(f"🔍 Debug: Parameters: {json.dumps(self.kwargs, indent=2)}")
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration = (datetime.now() - self.start_time).total_seconds()
+        
+        if exc_type is None:
+            # if is_telemetry_enabled():
+            #     print(f"✅ Debug: {self.function_name} completed successfully ({duration:.2f}s)")
+            pass
+        else:
+            # if is_telemetry_enabled():
+            #     print(f"❌ Debug: {self.function_name} failed after {duration:.2f}s")
+            #     print(f"❌ Debug: Error: {exc_type.__name__}: {exc_val}")
+            #     print(f"❌ Debug: Traceback:\n{traceback.format_exc()}")
+            
+            # Report the error
+            report_error(exc_val, self.function_name, {
+                "duration": duration,
+                "parameters": self.kwargs
+            })
+
+def debug_function(func: Callable) -> Callable:
+    """
+    Decorator to add debugging to any function.
+    
+    Args:
+        func: Function to debug
+        
+    Returns:
+        Wrapped function with debugging
+    """
+    def wrapper(*args, **kwargs):
+        function_name = f"{func.__module__}.{func.__name__}"
+        
+        # Sanitize arguments for JSON serialization
+        safe_args = []
+        for arg in args:
+            if hasattr(arg, '__dict__'):
+                safe_args.append(f"<{type(arg).__name__} object>")
+            else:
+                safe_args.append(str(arg))
+        
+        safe_kwargs = {}
+        for key, value in kwargs.items():
+            if hasattr(value, '__dict__'):
+                safe_kwargs[key] = f"<{type(value).__name__} object>"
+            else:
+                safe_kwargs[key] = str(value)
+        
+        with DebugContext(function_name, args=safe_args, kwargs=safe_kwargs):
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                # Re-raise the exception after reporting
+                raise
+    
+    return wrapper
+
+def debug_print(message: str, level: str = "info") -> None:
+    """
+    Print debug message with timestamp and level.
+    
+    Args:
+        message: Message to print
+        level: Debug level (info, warning, error, success)
+    """
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    
+    icons = {
+        "info": "🔍",
+        "warning": "⚠️", 
+        "error": "❌",
+        "success": "✅",
+        "request": "📤",
+        "response": "📥"
+    }
+    
+    icon = icons.get(level, "🔍")
+    print(f"[{timestamp}] {icon} {message}")
+
+def debug_request(method: str, url: str, data: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Debug HTTP request information.
+    
+    Args:
+        method: HTTP method
+        url: Request URL
+        data: Request data
+    """
+    debug_print(f"{method} {url}", "request")
+    if data:
+        debug_print(f"Data: {json.dumps(data, indent=2)}", "info")
+
+def debug_response(status_code: int, data: Optional[Dict[str, Any]] = None) -> None:
+    """
+    Debug HTTP response information.
+    
+    Args:
+        status_code: HTTP status code
+        data: Response data
+    """
+    if 200 <= status_code < 300:
+        debug_print(f"Response {status_code}: Success", "success")
+    else:
+        debug_print(f"Response {status_code}: Error", "error")
+    
+    if data:
+        # Truncate large responses for readability
+        data_str = json.dumps(data, indent=2)
+        if len(data_str) > 500:
+            data_str = data_str[:500] + "...\n[Response truncated]"
+        debug_print(f"Response data: {data_str}", "response")
+
+def analyze_error(error: Exception) -> Dict[str, Any]:
+    """
+    Analyze an error and provide debugging information.
+    
+    Args:
+        error: Exception to analyze
+        
+    Returns:
+        Dictionary with error analysis
+    """
+    error_type = type(error).__name__
+    error_message = str(error)
+    traceback_str = traceback.format_exc()
+    
+    analysis = {
+        "error_type": error_type,
+        "error_message": error_message,
+        "traceback": traceback_str,
+        "suggestions": []
+    }
+    
+    # Provide specific suggestions based on error type
+    if "AuthenticationError" in error_type or "401" in error_message:
+        analysis["suggestions"].extend([
+            "Check your username and password",
+            "Verify your account is not banned",
+            "Try re-authenticating with a fresh token"
+        ])
+    
+    elif "RateLimitError" in error_type or "429" in error_message:
+        analysis["suggestions"].extend([
+            "Wait before making more requests",
+            "Implement exponential backoff",
+            "Check rate limit headers for retry time"
+        ])
+    
+    elif "NetworkError" in error_type or "timeout" in error_message.lower():
+        analysis["suggestions"].extend([
+            "Check your internet connection",
+            "Try increasing timeout value",
+            "Verify MC5 servers are accessible"
+        ])
+    
+    elif "TokenExpiredError" in error_type:
+        analysis["suggestions"].extend([
+            "Enable auto_refresh in client",
+            "Call authenticate() again",
+            "Check token expiration time"
+        ])
+    
+    return analysis
+
+def print_error_analysis(error: Exception) -> None:
+    """
+    Print detailed error analysis with suggestions.
+    
+    Args:
+        error: Exception to analyze
+    """
+    analysis = analyze_error(error)
+    
+    debug_print(f"Error Analysis: {analysis['error_type']}", "error")
+    debug_print(f"Message: {analysis['error_message']}", "error")
+    
+    if analysis["suggestions"]:
+        debug_print("Suggestions:", "warning")
+        for i, suggestion in enumerate(analysis["suggestions"], 1):
+            debug_print(f"  {i}. {suggestion}", "warning")
+
+def create_debug_report() -> Dict[str, Any]:
+    """
+    Create a comprehensive debug report.
+    
+    Returns:
+        Debug report dictionary
+    """
+    import platform
+    import sys
+    
+    report = {
+        "timestamp": datetime.now().isoformat(),
+        "python_version": sys.version,
+        "platform": platform.platform(),
+        "architecture": platform.architecture(),
+        "system": platform.system(),
+        "mc5_client_version": "1.0.16",
+        "telemetry_enabled": is_telemetry_enabled()
+    }
+    
+    return report
+
+def print_debug_report() -> None:
+    """Print a comprehensive debug report."""
+    report = create_debug_report()
+    
+    debug_print("MC5 API Client Debug Report", "info")
+    debug_print("=" * 40, "info")
+    
+    for key, value in report.items():
+        debug_print(f"{key}: {value}", "info")
+
+# Convenience function for quick debugging
+def debug_mode(enable: bool = False) -> None:
+    """
+    Enable or disable debug mode.
+    
+    Args:
+        enable: Whether to enable debug mode (default: False)
+    """
+    if enable:
+        telemetry(True)
+        print_debug_report()
+        print("✅ Debug mode enabled")
+    else:
+        telemetry(False)
+        print("🔇 Debug mode disabled")