quantum-framework 0.9.0__py3-none-any.whl

quantum/runtime/email_service.py

@@ -0,0 +1,162 @@
+"""
+Phase I: Email Service
+
+ColdFusion cfmail-inspired email sending with SMTP support.
+"""
+
+import smtplib
+import os
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from email.mime.base import MIMEBase
+from email import encoders
+from typing import List, Dict, Any, Optional
+from pathlib import Path
+
+
+class EmailError(Exception):
+    """Raised when email sending fails"""
+    pass
+
+
+class EmailService:
+    """Service for sending emails via SMTP"""
+
+    def __init__(self):
+        """Initialize email service with config from environment"""
+        self.smtp_host = os.getenv('SMTP_HOST', 'localhost')
+        self.smtp_port = int(os.getenv('SMTP_PORT', '587'))
+        self.smtp_user = os.getenv('SMTP_USER', '')
+        self.smtp_password = os.getenv('SMTP_PASSWORD', '')
+        self.smtp_use_tls = os.getenv('SMTP_USE_TLS', 'true').lower() == 'true'
+        self.default_from = os.getenv('SMTP_FROM', 'noreply@quantum.dev')
+
+    def send_email(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        from_addr: Optional[str] = None,
+        cc: Optional[str] = None,
+        bcc: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        email_type: str = "html",
+        attachments: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Send email via SMTP
+
+        Args:
+            to: Recipient email(s) (comma-separated)
+            subject: Email subject
+            body: Email body content
+            from_addr: Sender email (uses default if not provided)
+            cc: CC recipients (comma-separated)
+            bcc: BCC recipients (comma-separated)
+            reply_to: Reply-To address
+            email_type: 'html' or 'text'
+            attachments: List of file paths to attach
+
+        Returns:
+            Dict with send result
+
+        Raises:
+            EmailError: If sending fails
+        """
+        try:
+            # Create message
+            msg = MIMEMultipart()
+            msg['From'] = from_addr or self.default_from
+            msg['To'] = to
+            msg['Subject'] = subject
+
+            if cc:
+                msg['Cc'] = cc
+            if reply_to:
+                msg['Reply-To'] = reply_to
+
+            # Attach body
+            mime_type = 'html' if email_type == 'html' else 'plain'
+            msg.attach(MIMEText(body, mime_type, 'utf-8'))
+
+            # Attach files if provided
+            if attachments:
+                for file_path in attachments:
+                    self._attach_file(msg, file_path)
+
+            # Prepare recipients
+            recipients = self._parse_recipients(to, cc, bcc)
+
+            # Send email
+            if os.getenv('EMAIL_MOCK', 'true').lower() == 'true':
+                # Mock mode for development (don't actually send)
+                print(f"[MOCK] Email sent to {to}")
+                print(f"   Subject: {subject}")
+                print(f"   From: {msg['From']}")
+                print(f"   Type: {email_type}")
+                return {
+                    'success': True,
+                    'mock': True,
+                    'to': to,
+                    'subject': subject,
+                    'message': 'Email mock-sent successfully'
+                }
+            else:
+                # Real SMTP sending
+                with smtplib.SMTP(self.smtp_host, self.smtp_port) as server:
+                    if self.smtp_use_tls:
+                        server.starttls()
+
+                    if self.smtp_user and self.smtp_password:
+                        server.login(self.smtp_user, self.smtp_password)
+
+                    server.sendmail(msg['From'], recipients, msg.as_string())
+
+                return {
+                    'success': True,
+                    'to': to,
+                    'subject': subject,
+                    'message': 'Email sent successfully'
+                }
+
+        except Exception as e:
+            raise EmailError(f"Failed to send email: {e}")
+
+    def _attach_file(self, msg: MIMEMultipart, file_path: str):
+        """Attach a file to email message"""
+        try:
+            path = Path(file_path)
+            if not path.exists():
+                raise EmailError(f"Attachment file not found: {file_path}")
+
+            with open(file_path, 'rb') as f:
+                part = MIMEBase('application', 'octet-stream')
+                part.set_payload(f.read())
+
+            encoders.encode_base64(part)
+            part.add_header(
+                'Content-Disposition',
+                f'attachment; filename= {path.name}'
+            )
+
+            msg.attach(part)
+        except Exception as e:
+            raise EmailError(f"Failed to attach file {file_path}: {e}")
+
+    def _parse_recipients(
+        self,
+        to: str,
+        cc: Optional[str] = None,
+        bcc: Optional[str] = None
+    ) -> List[str]:
+        """Parse comma-separated email addresses into list"""
+        recipients = []
+
+        if to:
+            recipients.extend([email.strip() for email in to.split(',')])
+        if cc:
+            recipients.extend([email.strip() for email in cc.split(',')])
+        if bcc:
+            recipients.extend([email.strip() for email in bcc.split(',')])
+
+        return recipients

quantum/runtime/error_handler.py

@@ -0,0 +1,295 @@
+"""
+Enhanced Error Handler - Phase C: Developer Experience
+
+Provides better error messages with:
+- Context (line numbers, code snippets)
+- Suggestions (did you mean...?)
+- Helpful hints
+- Color-coded output
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional, List
+import difflib
+
+class QuantumError(Exception):
+    """Base class for Quantum errors with enhanced context"""
+
+    def __init__(self, message: str, file_path: Optional[str] = None,
+                 line: Optional[int] = None, column: Optional[int] = None,
+                 suggestion: Optional[str] = None, hint: Optional[str] = None):
+        self.message = message
+        self.file_path = file_path
+        self.line = line
+        self.column = column
+        self.suggestion = suggestion
+        self.hint = hint
+        super().__init__(self.format_error())
+
+    def format_error(self) -> str:
+        """Format error message with context"""
+        parts = []
+
+        # Header
+        parts.append("=" * 60)
+        parts.append("❌ QUANTUM ERROR")
+        parts.append("=" * 60)
+
+        # Location
+        if self.file_path:
+            location = f"📂 File: {self.file_path}"
+            if self.line:
+                location += f":{self.line}"
+                if self.column:
+                    location += f":{self.column}"
+            parts.append(location)
+
+        # Error message
+        parts.append(f"\n💥 {self.message}")
+
+        # Code context
+        if self.file_path and self.line:
+            context = self._get_code_context()
+            if context:
+                parts.append("\n📝 Code:")
+                parts.append(context)
+
+        # Suggestion
+        if self.suggestion:
+            parts.append(f"\n💡 Suggestion: {self.suggestion}")
+
+        # Hint
+        if self.hint:
+            parts.append(f"\n🔍 Hint: {self.hint}")
+
+        parts.append("=" * 60)
+
+        return "\n".join(parts)
+
+    def _get_code_context(self, context_lines: int = 3) -> Optional[str]:
+        """Get code context around error line"""
+        try:
+            file_path = Path(self.file_path)
+            if not file_path.exists():
+                return None
+
+            lines = file_path.read_text(encoding='utf-8').splitlines()
+
+            start = max(0, self.line - context_lines - 1)
+            end = min(len(lines), self.line + context_lines)
+
+            context_parts = []
+            for i in range(start, end):
+                line_num = i + 1
+                line_content = lines[i]
+
+                # Mark error line with arrow
+                if line_num == self.line:
+                    context_parts.append(f"  → {line_num:4d} | {line_content}")
+                    # Add column pointer if available
+                    if self.column:
+                        pointer = " " * (self.column + 10) + "^"
+                        context_parts.append(pointer)
+                else:
+                    context_parts.append(f"    {line_num:4d} | {line_content}")
+
+            return "\n".join(context_parts)
+
+        except Exception:
+            return None
+
+
+class ComponentNotFoundError(QuantumError):
+    """Component import not found"""
+
+    def __init__(self, component_name: str, file_path: str, line: int,
+                 available_components: List[str] = None):
+        # Find similar component names
+        suggestion = None
+        if available_components:
+            matches = difflib.get_close_matches(component_name, available_components, n=3, cutoff=0.6)
+            if matches:
+                if len(matches) == 1:
+                    suggestion = f"Did you mean '{matches[0]}'?"
+                else:
+                    suggestion = f"Did you mean one of: {', '.join(matches)}?"
+
+        hint = f"Add: <q:import component=\"{component_name}\" />"
+
+        super().__init__(
+            f"Component '{component_name}' not found",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class ValidationErrorWithContext(QuantumError):
+    """Validation error with context"""
+
+    def __init__(self, field_name: str, validation_type: str,
+                 value: any, file_path: str = None, line: int = None):
+        message = f"Validation failed for field '{field_name}' ({validation_type})"
+
+        if validation_type == "required":
+            suggestion = f"Field '{field_name}' is required but was not provided"
+        elif validation_type == "type":
+            suggestion = f"Expected type differs from provided value: {value}"
+        elif validation_type == "minlength":
+            suggestion = f"Value '{value}' is too short"
+        elif validation_type == "maxlength":
+            suggestion = f"Value '{value}' is too long"
+        elif validation_type == "pattern":
+            suggestion = f"Value '{value}' doesn't match required pattern"
+        else:
+            suggestion = f"Validation '{validation_type}' failed for value: {value}"
+
+        super().__init__(
+            message,
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion
+        )
+
+
+class QueryErrorWithContext(QuantumError):
+    """Query error with SQL context"""
+
+    def __init__(self, query_name: str, sql: str, error: str,
+                 file_path: str = None, line: int = None):
+        message = f"Query '{query_name}' failed"
+
+        # Provide SQL-specific suggestions
+        suggestion = None
+        if "syntax error" in error.lower():
+            suggestion = "Check your SQL syntax"
+        elif "table" in error.lower() and "doesn't exist" in error.lower():
+            suggestion = "Table doesn't exist - check your database schema"
+        elif "column" in error.lower():
+            suggestion = "Column doesn't exist - check your table structure"
+        elif "duplicate" in error.lower():
+            suggestion = "Duplicate entry - check for unique constraints"
+
+        hint = f"SQL: {sql[:100]}..." if len(sql) > 100 else f"SQL: {sql}"
+
+        super().__init__(
+            f"{message}: {error}",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class TransactionErrorWithContext(QuantumError):
+    """Transaction error with rollback info"""
+
+    def __init__(self, error: str, statements_executed: int,
+                 file_path: str = None, line: int = None):
+        message = "Transaction failed and was rolled back"
+
+        suggestion = f"{statements_executed} statement(s) were executed before failure"
+        hint = "All changes have been rolled back. Check the error above and fix the issue."
+
+        super().__init__(
+            f"{message}: {error}",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class FileUploadErrorWithContext(QuantumError):
+    """File upload error with details"""
+
+    def __init__(self, error: str, filename: str = None,
+                 file_size: int = None, max_size: int = None,
+                 file_path: str = None, line: int = None):
+        message = f"File upload failed"
+
+        suggestion = None
+        if "too large" in error.lower():
+            if file_size and max_size:
+                suggestion = f"File is {file_size} bytes but maximum is {max_size} bytes"
+        elif "type" in error.lower() or "extension" in error.lower():
+            suggestion = "File type not allowed - check allowed extensions"
+
+        hint = None
+        if filename:
+            hint = f"Filename: {filename}"
+
+        super().__init__(
+            f"{message}: {error}",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class ErrorHandler:
+    """Central error handler for better error reporting"""
+
+    _logger = None
+
+    @classmethod
+    def _get_logger(cls):
+        if cls._logger is None:
+            import logging
+            cls._logger = logging.getLogger('quantum.errors')
+        return cls._logger
+
+    @staticmethod
+    def handle_parse_error(error: Exception, file_path: str) -> QuantumError:
+        """Convert parse errors to enhanced errors"""
+        error_msg = str(error)
+
+        # Extract line and column from XML parse errors
+        line = None
+        column = None
+        if "line" in error_msg:
+            import re
+            match = re.search(r'line (\d+)', error_msg)
+            if match:
+                line = int(match.group(1))
+            match = re.search(r'column (\d+)', error_msg)
+            if match:
+                column = int(match.group(1))
+
+        return QuantumError(
+            f"Parse error: {error_msg}",
+            file_path=file_path,
+            line=line,
+            column=column,
+            suggestion="Check your XML syntax",
+            hint="Make sure all tags are properly closed and attributes are quoted"
+        )
+
+    @staticmethod
+    def handle_runtime_error(error: Exception, component_name: str,
+                            file_path: str = None) -> QuantumError:
+        """Convert runtime errors to enhanced errors"""
+        return QuantumError(
+            f"Runtime error in component '{component_name}': {error}",
+            file_path=file_path,
+            suggestion="Check your component logic and variable names",
+            hint="Use quantum inspect <component> to debug"
+        )
+
+    @classmethod
+    def print_warning(cls, message: str):
+        """Log formatted warning"""
+        cls._get_logger().warning(message)
+
+    @classmethod
+    def print_info(cls, message: str):
+        """Log formatted info"""
+        cls._get_logger().info(message)
+
+    @classmethod
+    def print_success(cls, message: str):
+        """Log formatted success"""
+        cls._get_logger().info(message)