quantum-framework 0.9.0__py3-none-any.whl

quantum/core/features/logging/src/ast_node.py

@@ -0,0 +1,111 @@
+"""
+AST Node for q:log - Structured Logging
+"""
+
+from typing import Optional
+from quantum.core.ast_nodes import QuantumNode
+
+
+class LogNode(QuantumNode):
+    """
+    Represents a <q:log> - Structured logging statement
+
+    Example:
+        <q:log level="info" message="User {userName} logged in" context="{user}" />
+        <q:log level="error" message="API failed" when="{!api_result.success}" />
+    """
+
+    VALID_LEVELS = ['trace', 'debug', 'info', 'warning', 'error', 'critical']
+
+    # Spellings people actually write, mapped to the level they mean. `warn`
+    # is what Python's own logging, JavaScript's console and most log
+    # libraries call it, and two examples in this repository use it — one of
+    # them the only q:websocket example there is, which therefore did not
+    # parse. Rejecting a word the whole industry uses is not strictness, it
+    # is a papercut.
+    LEVEL_ALIASES = {
+        'warn': 'warning',
+        'fatal': 'critical',
+        'err': 'error',
+        'verbose': 'trace',
+    }
+
+    def __init__(
+        self,
+        level: str,
+        message: str,
+        context: Optional[str] = None,
+        when: Optional[str] = None,
+        provider: Optional[str] = None,
+        async_mode: bool = True,
+        correlation_id: Optional[str] = None
+    ):
+        """
+        Initialize a LogNode
+
+        Args:
+            level: Log severity level (trace, debug, info, warning, error, critical)
+            message: Log message with databinding support
+            context: Optional structured data (JSON expression)
+            when: Optional conditional expression
+            provider: Optional output destination (Phase 2)
+            async_mode: Async logging mode (Phase 2)
+            correlation_id: Optional request tracking ID (Phase 2)
+        """
+        # Validate level
+        if not level:
+            raise ValueError("Log requires 'level' attribute")
+
+        level = self.LEVEL_ALIASES.get(str(level).strip().lower(), level)
+
+        if level not in self.VALID_LEVELS:
+            raise ValueError(
+                f"Invalid log level '{level}'. Must be one of: {', '.join(self.VALID_LEVELS)}"
+            )
+
+        # Validate message
+        if message is None:
+            raise ValueError("Log requires 'message' attribute")
+
+        self.level = level
+        self.message = message
+        self.context = context
+        self.when = when
+        self.provider = provider
+        self.async_mode = async_mode
+        self.correlation_id = correlation_id
+
+    def __repr__(self):
+        attrs = [f"level={self.level!r}", f"message={self.message!r}"]
+        if self.context:
+            attrs.append(f"context={self.context!r}")
+        if self.when:
+            attrs.append(f"when={self.when!r}")
+        return f"LogNode({', '.join(attrs)})"
+
+    def to_dict(self):
+        """Convert node to dictionary for debugging/serialization"""
+        return {
+            "type": "log",
+            "level": self.level,
+            "message": self.message[:50] + "..." if self.message and len(self.message) > 50 else self.message,
+            "context": self.context,
+            "when": self.when,
+            "provider": self.provider,
+            "async": self.async_mode,
+            "correlation_id": self.correlation_id
+        }
+
+    def validate(self):
+        """Validate the node and return list of errors"""
+        errors = []
+
+        if not self.level:
+            errors.append("Log requires 'level' attribute")
+        elif self.level not in self.VALID_LEVELS:
+            errors.append(f"Invalid log level '{self.level}'. Must be one of: {', '.join(self.VALID_LEVELS)}")
+
+        if not self.message:
+            errors.append("Log requires 'message' attribute")
+
+        return errors

quantum/core/features/logging/src/parser.py

@@ -0,0 +1,50 @@
+"""
+Parser for q:log - Structured Logging
+"""
+
+import xml.etree.ElementTree as ET
+from typing import Optional
+from .ast_node import LogNode
+
+
+def parse_log(log_element: ET.Element) -> LogNode:
+    """
+    Parse a <q:log> element into a LogNode
+
+    Args:
+        log_element: The XML element representing the log statement
+
+    Returns:
+        LogNode instance
+
+    Raises:
+        ValueError: If required attributes are missing or invalid
+    """
+    # Get required attributes
+    level = log_element.get('level')
+    message = log_element.get('message')
+
+    # Get optional attributes
+    context = log_element.get('context')
+    when = log_element.get('when')
+    provider = log_element.get('provider')
+    async_mode_str = log_element.get('async', 'true')
+    correlation_id = log_element.get('correlation_id')
+
+    # Parse async mode
+    async_mode = async_mode_str.lower() == 'true' if async_mode_str else True
+
+    # Validate no child elements (q:log should be self-closing)
+    if len(log_element) > 0:
+        raise ValueError("Log tag must be self-closing")
+
+    # Create and return LogNode (validation happens in __init__)
+    return LogNode(
+        level=level,
+        message=message,
+        context=context,
+        when=when,
+        provider=provider,
+        async_mode=async_mode,
+        correlation_id=correlation_id
+    )

quantum/core/features/logging/src/runtime.py

@@ -0,0 +1,190 @@
+"""
+Runtime service for q:log - Structured Logging
+"""
+
+import logging
+import json
+import os
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+class LoggingService:
+    """
+    Service to handle structured logging with multiple severity levels
+
+    Phase 1 Features:
+    - Console and file output
+    - JSON structured format
+    - Multiple log levels
+    - Conditional logging
+    - Context data
+
+    Phase 2 Features (TODO):
+    - Loguru integration
+    - External services (Sentry, Datadog)
+    - Async logging
+    - Log rotation
+    - Correlation IDs
+    """
+
+    # Map Quantum log levels to Python logging levels
+    LEVEL_MAP = {
+        'trace': logging.DEBUG - 5,  # Custom level below DEBUG
+        'debug': logging.DEBUG,
+        'info': logging.INFO,
+        'warning': logging.WARNING,
+        'error': logging.ERROR,
+        'critical': logging.CRITICAL
+    }
+
+    _instance: Optional['LoggingService'] = None
+    _initialized: bool = False
+
+    def __new__(cls):
+        """Singleton pattern to ensure one logger instance"""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        """Initialize the logging service"""
+        if not LoggingService._initialized:
+            self._setup_logging()
+            LoggingService._initialized = True
+
+    @classmethod
+    def configure_from_external(cls, logger):
+        """
+        Inject an externally configured logger so q:log tags reuse
+        the same handlers without duplication.
+
+        Called by logging_setup.setup_logging() after configuring
+        the 'quantum' root logger.
+        """
+        instance = cls.__new__(cls)
+        instance.logger = logger
+        cls._instance = instance
+        cls._initialized = True
+
+    def _setup_logging(self):
+        """Setup logging configuration"""
+        # Create logger
+        self.logger = logging.getLogger('quantum')
+        self.logger.setLevel(logging.DEBUG)  # Capture all levels
+
+        # Prevent duplicate handlers
+        if self.logger.handlers:
+            return
+
+        # Console handler - formatted output for development
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(logging.DEBUG)
+        console_formatter = logging.Formatter(
+            '%(asctime)s [%(levelname)s] %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        console_handler.setFormatter(console_formatter)
+        self.logger.addHandler(console_handler)
+
+        # File handler - JSON format for production (Phase 1: basic file logging)
+        # Phase 2 will add rotation with Loguru
+        log_dir = 'logs'
+        os.makedirs(log_dir, exist_ok=True)
+        log_file = os.path.join(log_dir, f'quantum_{datetime.now().strftime("%Y%m%d")}.log')
+
+        file_handler = logging.FileHandler(log_file, encoding='utf-8')
+        file_handler.setLevel(logging.DEBUG)
+        # For now, use same format. Phase 2 will use JSON formatter
+        file_handler.setFormatter(console_formatter)
+        self.logger.addHandler(file_handler)
+
+        # Custom TRACE level
+        logging.addLevelName(self.LEVEL_MAP['trace'], 'TRACE')
+
+    def log(
+        self,
+        level: str,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Write a log entry
+
+        Args:
+            level: Log severity level
+            message: Log message (already resolved with databinding)
+            context: Optional structured context data
+            correlation_id: Optional request tracking ID
+
+        Returns:
+            Result dictionary with success status
+        """
+        try:
+            # Get Python logging level
+            py_level = self.LEVEL_MAP.get(level, logging.INFO)
+
+            # Build log entry
+            log_data = {
+                'timestamp': datetime.now().isoformat(),
+                'level': level,
+                'message': message
+            }
+
+            if context:
+                log_data['context'] = context
+
+            if correlation_id:
+                log_data['correlation_id'] = correlation_id
+
+            # Log to Python logger
+            # For Phase 1, just log the message. Phase 2 will log full JSON
+            extra_info = []
+            if context:
+                extra_info.append(f"context={json.dumps(context)}")
+            if correlation_id:
+                extra_info.append(f"correlation_id={correlation_id}")
+
+            full_message = message
+            if extra_info:
+                full_message = f"{message} | {' | '.join(extra_info)}"
+
+            self.logger.log(py_level, full_message)
+
+            return {
+                'success': True,
+                'timestamp': log_data['timestamp'],
+                'level': level,
+                'message': message,
+                'destination': 'file+console'
+            }
+
+        except Exception as e:
+            # Logging should never crash the application
+            # Silently capture errors and return failure
+            return {
+                'success': False,
+                'error': str(e)
+            }
+
+    def should_log(self, condition: Any) -> bool:
+        """
+        Evaluate if logging should occur based on 'when' condition
+
+        Args:
+            condition: Evaluated condition value
+
+        Returns:
+            True if should log, False otherwise
+        """
+        # If no condition, always log
+        if condition is None:
+            return True
+
+        # Evaluate boolean condition
+        if isinstance(condition, bool):
+            return condition
+
+        # Truthy evaluation for other types
+        return bool(condition)

quantum/core/features/loops/src/__init__.py

@@ -0,0 +1,8 @@
+"""
+Loops Feature (q:loop)
+"""
+
+from .ast_node import LoopNode
+
+__all__ = ['LoopNode']
+__version__ = '1.0.0'

quantum/core/features/loops/src/ast_node.py

@@ -0,0 +1,60 @@
+"""
+AST Node for Loops (q:loop)
+"""
+
+from typing import Dict, Any, List
+
+# Import base class
+import sys
+from pathlib import Path
+from quantum.core.ast_nodes import QuantumNode
+
+
+class LoopNode(QuantumNode):
+    """Represents a <q:loop> with various types"""
+
+    def __init__(self, loop_type: str, var_name: str):
+        self.loop_type = loop_type    # range, array, list, object, query, while
+        self.var_name = var_name      # variable name for current item
+        self.index_name = None        # optional index variable
+        self.items = None             # data source expression
+        self.condition = None         # for while loops
+        self.from_value = None        # for range loops
+        self.to_value = None          # for range loops
+        self.step_value = 1           # for range loops
+        self.delimiter = ","          # for list loops
+        self.body: List[QuantumNode] = []  # statements inside loop
+
+    def add_statement(self, statement: QuantumNode):
+        self.body.append(statement)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "loop",
+            "loop_type": self.loop_type,
+            "var_name": self.var_name,
+            "index_name": self.index_name,
+            "from_value": self.from_value,
+            "to_value": self.to_value,
+            "step_value": self.step_value,
+            "body_statements": len(self.body)
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+        if not self.var_name:
+            errors.append("Loop variable name is required")
+
+        if self.loop_type == 'range':
+            if not self.from_value:
+                errors.append("Range loop requires 'from' attribute")
+            if not self.to_value:
+                errors.append("Range loop requires 'to' attribute")
+        elif self.loop_type in ['array', 'list', 'object']:
+            if not self.items:
+                errors.append(f"{self.loop_type.title()} loop requires 'items' attribute")
+
+        for statement in self.body:
+            errors.extend(statement.validate())
+
+        return errors