quantum-framework 0.9.0__py3-none-any.whl

quantum/core/features/query/src/database_service.py

@@ -0,0 +1,322 @@
+"""
+Quantum Database Service - Manages database connections and query execution
+"""
+
+import time
+import requests
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class QueryResult:
+    """Container for query results and metadata"""
+    data: List[Dict[str, Any]]
+    column_list: List[str]
+    execution_time: float  # in milliseconds
+    record_count: int
+    sql: Optional[str] = None  # Set in debug mode
+    page: Optional[int] = None
+    total_pages: Optional[int] = None
+    has_more: bool = False
+    cached: bool = False
+
+    def to_dict(self):
+        """Convert to dictionary for template access"""
+        result = asdict(self)
+        # Rename column_list to columnList for JavaScript compatibility
+        result['columnList'] = result.pop('column_list')
+        result['recordCount'] = result.pop('record_count')
+        result['executionTime'] = result.pop('execution_time')
+        result['totalPages'] = result.pop('total_pages')
+        result['hasMore'] = result.pop('has_more')
+        return result
+
+
+class DatabaseConnectionError(Exception):
+    """Raised when database connection fails"""
+    pass
+
+
+class QueryExecutionError(Exception):
+    """Raised when query execution fails"""
+    pass
+
+
+class DatabaseService:
+    """Manages database connections and query execution"""
+
+    def __init__(self, admin_api_url: str = "http://localhost:8000"):
+        self.admin_api_url = admin_api_url
+        self.connection_pool: Dict[str, Any] = {}  # Cache connections by datasource name
+
+    def get_datasource_config(self, datasource_name: str) -> Dict[str, Any]:
+        """
+        Fetch datasource configuration from Quantum Admin API
+
+        Args:
+            datasource_name: Name of the datasource
+
+        Returns:
+            Dict with datasource configuration
+
+        Raises:
+            DatabaseConnectionError: If datasource not found or not ready
+        """
+        try:
+            url = f"{self.admin_api_url}/api/datasources/by-name/{datasource_name}"
+            response = requests.get(url, timeout=5)
+
+            if response.status_code == 404:
+                raise DatabaseConnectionError(f"Datasource '{datasource_name}' not found")
+            elif response.status_code == 503:
+                raise DatabaseConnectionError(
+                    f"Datasource '{datasource_name}' is not ready. Please check Quantum Admin."
+                )
+            elif response.status_code != 200:
+                raise DatabaseConnectionError(
+                    f"Failed to fetch datasource '{datasource_name}': {response.status_code}"
+                )
+
+            return response.json()
+
+        except requests.exceptions.ConnectionError:
+            raise DatabaseConnectionError(
+                f"Cannot connect to Quantum Admin API at {self.admin_api_url}. "
+                "Please ensure Quantum Admin is running."
+            )
+        except requests.exceptions.Timeout:
+            raise DatabaseConnectionError(
+                f"Timeout connecting to Quantum Admin API at {self.admin_api_url}"
+            )
+
+    def get_connection(self, datasource_config: Dict[str, Any]):
+        """
+        Get or create database connection
+
+        Args:
+            datasource_config: Datasource configuration from Admin API
+
+        Returns:
+            Database connection object
+
+        Raises:
+            DatabaseConnectionError: If connection fails
+        """
+        datasource_name = datasource_config['name']
+        db_type = datasource_config['type']
+
+        # Check if connection already exists in pool
+        if datasource_name in self.connection_pool:
+            conn = self.connection_pool[datasource_name]
+            # Test connection is still alive
+            if self._test_connection(conn, db_type):
+                return conn
+            else:
+                # Connection dead, remove from pool
+                del self.connection_pool[datasource_name]
+
+        # Create new connection
+        try:
+            if db_type == 'postgresql':
+                conn = self._create_postgres_connection(datasource_config)
+            elif db_type in ['mysql', 'mariadb']:
+                conn = self._create_mysql_connection(datasource_config)
+            else:
+                raise DatabaseConnectionError(f"Unsupported database type: {db_type}")
+
+            # Store in pool
+            self.connection_pool[datasource_name] = conn
+            return conn
+
+        except Exception as e:
+            raise DatabaseConnectionError(f"Failed to connect to database: {e}")
+
+    def _create_postgres_connection(self, config: Dict[str, Any]):
+        """Create PostgreSQL connection"""
+        try:
+            import psycopg2
+            return psycopg2.connect(
+                host=config['host'],
+                port=config['port'],
+                database=config['database_name'],
+                user=config['username'],
+                password=config['password']
+            )
+        except ImportError:
+            raise DatabaseConnectionError(
+                "psycopg2 not installed. Install with: pip install psycopg2-binary"
+            )
+
+    def _create_mysql_connection(self, config: Dict[str, Any]):
+        """Create MySQL/MariaDB connection"""
+        try:
+            import pymysql
+            return pymysql.connect(
+                host=config['host'],
+                port=config['port'],
+                database=config['database_name'],
+                user=config['username'],
+                password=config['password'],
+                cursorclass=pymysql.cursors.DictCursor  # Return results as dictionaries
+            )
+        except ImportError:
+            raise DatabaseConnectionError(
+                "pymysql not installed. Install with: pip install pymysql"
+            )
+
+    def _test_connection(self, conn, db_type: str) -> bool:
+        """Test if connection is still alive"""
+        try:
+            cursor = conn.cursor()
+            if db_type == 'postgresql':
+                cursor.execute("SELECT 1")
+            elif db_type in ['mysql', 'mariadb']:
+                cursor.execute("SELECT 1")
+            cursor.close()
+            return True
+        except:
+            return False
+
+    def execute_query(self, datasource_name: str, sql: str, params: Dict[str, Any] = None) -> QueryResult:
+        """
+        Execute SQL with parameter binding
+
+        Args:
+            datasource_name: Name of the datasource
+            sql: SQL query with :param placeholders
+            params: Dictionary of parameter values
+
+        Returns:
+            QueryResult with data and metadata
+
+        Raises:
+            QueryExecutionError: If query execution fails
+        """
+        if params is None:
+            params = {}
+
+        # Get datasource config
+        config = self.get_datasource_config(datasource_name)
+        db_type = config['type']
+
+        # Get connection
+        conn = self.get_connection(config)
+
+        # Start timing
+        start_time = time.time()
+
+        try:
+            cursor = conn.cursor()
+
+            # Convert :param syntax to database-specific placeholder
+            prepared_sql, prepared_params = self._prepare_query(sql, params, db_type)
+
+            # Execute query
+            cursor.execute(prepared_sql, prepared_params)
+
+            # Check if it's a SELECT query (returns data)
+            if cursor.description:
+                # Fetch results
+                rows = cursor.fetchall()
+
+                # Get column names
+                if db_type == 'postgresql':
+                    column_names = [desc[0] for desc in cursor.description]
+                    # Convert rows to dictionaries for PostgreSQL
+                    data = [dict(zip(column_names, row)) for row in rows]
+                elif db_type in ['mysql', 'mariadb']:
+                    # pymysql with DictCursor already returns dictionaries
+                    column_names = list(rows[0].keys()) if rows else []
+                    data = rows
+                else:
+                    column_names = []
+                    data = []
+
+                record_count = len(data)
+            else:
+                # Non-SELECT query (INSERT, UPDATE, DELETE)
+                conn.commit()
+                data = []
+                column_names = []
+                record_count = cursor.rowcount
+
+                # For INSERT with RETURNING (PostgreSQL)
+                if db_type == 'postgresql' and cursor.description:
+                    rows = cursor.fetchall()
+                    column_names = [desc[0] for desc in cursor.description]
+                    data = [dict(zip(column_names, row)) for row in rows]
+                    record_count = len(data)
+
+            cursor.close()
+
+            # Calculate execution time
+            execution_time = (time.time() - start_time) * 1000  # Convert to ms
+
+            return QueryResult(
+                data=data,
+                column_list=column_names,
+                execution_time=execution_time,
+                record_count=record_count
+            )
+
+        except Exception as e:
+            # Rollback on error
+            conn.rollback()
+            raise QueryExecutionError(f"Query execution failed: {e}")
+
+    def _prepare_query(self, sql: str, params: Dict[str, Any], db_type: str) -> tuple:
+        """
+        Convert :param syntax to database-specific placeholders
+
+        Args:
+            sql: SQL with :param placeholders
+            params: Dictionary of parameters
+            db_type: Database type (postgresql, mysql, mariadb)
+
+        Returns:
+            Tuple of (prepared_sql, prepared_params)
+        """
+        import re
+
+        # Find all :param placeholders
+        param_pattern = r':(\w+)'
+        param_names = re.findall(param_pattern, sql)
+
+        if db_type == 'postgresql':
+            # PostgreSQL uses %s placeholders
+            prepared_sql = sql
+            for i, param_name in enumerate(param_names, 1):
+                # Replace :param with %s
+                prepared_sql = prepared_sql.replace(f':{param_name}', '%s', 1)
+
+            # Build parameter list in correct order
+            prepared_params = [params.get(name) for name in param_names]
+
+        elif db_type in ['mysql', 'mariadb']:
+            # MySQL uses %s placeholders
+            prepared_sql = sql
+            for param_name in param_names:
+                prepared_sql = prepared_sql.replace(f':{param_name}', '%s', 1)
+
+            # Build parameter list in correct order
+            prepared_params = [params.get(name) for name in param_names]
+
+        else:
+            raise QueryExecutionError(f"Unsupported database type: {db_type}")
+
+        return prepared_sql, prepared_params
+
+    def close_connection(self, datasource_name: str):
+        """Close database connection"""
+        if datasource_name in self.connection_pool:
+            try:
+                self.connection_pool[datasource_name].close()
+            except:
+                pass
+            del self.connection_pool[datasource_name]
+
+    def close_all_connections(self):
+        """Close all database connections"""
+        for datasource_name in list(self.connection_pool.keys()):
+            self.close_connection(datasource_name)

quantum/core/features/query/src/query_validators.py

@@ -0,0 +1,20 @@
+"""
+Quantum Query Validators — re-export of the canonical implementation.
+
+This module used to hold a full 290-line COPY of QueryValidator. Nothing
+imported it, so it quietly drifted out of step with the module the runtime
+actually uses (quantum/runtime/query_validators.py) — and by the time the
+audit looked, the two copies of a SECURITY validator disagreed with each
+other. A stale duplicate of a validator is worse than no duplicate: whoever
+reads this one believes they are reading what runs.
+
+It re-exports instead of copying, so the two cannot diverge again. Import
+from quantum.runtime.query_validators directly in new code.
+"""
+
+from quantum.runtime.query_validators import (  # noqa: F401
+    QueryValidationError,
+    QueryValidator,
+)
+
+__all__ = ["QueryValidationError", "QueryValidator"]

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

@@ -0,0 +1,11 @@
+"""
+State Management Feature (q:set)
+
+Enables declaration and manipulation of component state variables
+with type safety, validation, and scope management.
+"""
+
+from .ast_node import SetNode
+
+__all__ = ['SetNode']
+__version__ = '1.0.0'

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

@@ -0,0 +1,228 @@
+"""
+AST Node for State Management (q:set)
+
+This module contains the SetNode class, which represents the <q:set> tag
+for state management in Quantum Language.
+
+State Persistence Support:
+    - persist="local" - localStorage (browser) or file (desktop)
+    - persist="session" - sessionStorage (browser) or memory (desktop)
+    - persist="sync" - synchronized across tabs/windows (browser) or network (desktop)
+"""
+
+from typing import Dict, Any, List, Optional
+
+# Import base class from parent AST nodes
+import sys
+from pathlib import Path
+from quantum.core.ast_nodes import QuantumNode
+
+
+class SetNode(QuantumNode):
+    """Represents a <q:set> - State Management"""
+
+    def __init__(self, name: str):
+        # Obrigatórios
+        self.name = name
+
+        # Tipo e valor
+        self.type = "string"
+        self.value = None
+        self.default = None
+
+        # Validação
+        self.required = False
+        self.nullable = True
+        self.validate_rule = None  # Renomeado de 'validate' para não conflitar com o método
+        self.pattern = None
+        self.mask = None
+        self.range = None
+        self.enum = None
+        self.unique = None
+        self.min = None
+        self.max = None
+        self.minlength = None
+        self.maxlength = None
+
+        # Comportamento
+        self.scope = "local"
+        self.operation = "assign"
+        self.step = 1
+
+        # Para operações em collections
+        self.index = None
+        self.key = None
+        self.source = None
+
+        # State Persistence
+        self.persist: Optional[str] = None  # None, "local", "session", "sync"
+        self.persist_key: Optional[str] = None  # Custom storage key (defaults to name)
+        self.persist_encrypt: bool = False  # Encrypt persisted data
+        self.persist_ttl: Optional[int] = None  # TTL in seconds for cached persistence
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "type": "set",
+            "name": self.name,
+            "value_type": self.type,
+            "value": self.value,
+            "default": self.default,
+            "scope": self.scope,
+            "operation": self.operation,
+            "required": self.required,
+            "nullable": self.nullable,
+            "validation": {
+                "validate": self.validate_rule,
+                "pattern": self.pattern,
+                "mask": self.mask,
+                "range": self.range,
+                "enum": self.enum,
+                "unique": self.unique,
+                "min": self.min,
+                "max": self.max,
+                "minlength": self.minlength,
+                "maxlength": self.maxlength
+            }
+        }
+        # Add persistence info if enabled
+        if self.persist:
+            result["persistence"] = {
+                "scope": self.persist,
+                "key": self.persist_key or self.name,
+                "encrypt": self.persist_encrypt,
+                "ttl": self.persist_ttl
+            }
+        return result
+
+    def validate(self) -> List[str]:
+        errors = []
+
+        if not self.name:
+            errors.append("Set variable name is required")
+
+        # Validar tipo
+        # 'integer' was missing here even though SetExecutor._convert_to_type()
+        # already handles it (target_type in ("integer", "number")), and other
+        # AST nodes like AgentToolParamNode accept it — this rejected any
+        # q:set/q:param using type="integer" (test-query-loop.q,
+        # test-query-params.q, and every qg: sprite param in game_engine_2d).
+        valid_types = ['string', 'number', 'integer', 'decimal', 'boolean', 'date', 'datetime',
+                      'array', 'object', 'json', 'binary', 'null']
+        if self.type not in valid_types:
+            errors.append(f"Invalid type: {self.type}. Must be one of {valid_types}")
+
+        # Validar operação
+        valid_operations = ['assign', 'increment', 'decrement', 'add', 'multiply',
+                           'append', 'prepend', 'remove', 'removeAt', 'clear', 'sort',
+                           'reverse', 'unique', 'merge', 'setProperty', 'deleteProperty',
+                           'clone', 'uppercase', 'lowercase', 'trim', 'format']
+        if self.operation not in valid_operations:
+            errors.append(f"Invalid operation: {self.operation}")
+
+        # Validar valor obrigatório para assign
+        if self.operation == "assign" and not self.value and not self.default and self.required:
+            errors.append("Set value or default is required when required=true")
+
+        # Validar enum
+        if self.enum and self.value:
+            enum_values = [v.strip() for v in self.enum.split(',')]
+            if self.value not in enum_values:
+                errors.append(f"Value '{self.value}' not in enum: {enum_values}")
+
+        # Validar minlength/maxlength
+        if self.type == "string" and self.value:
+            if self.minlength and len(str(self.value)) < int(self.minlength):
+                errors.append(f"Value length {len(str(self.value))} is less than minlength {self.minlength}")
+            if self.maxlength and len(str(self.value)) > int(self.maxlength):
+                errors.append(f"Value length {len(str(self.value))} exceeds maxlength {self.maxlength}")
+
+        # Validar persist scope
+        if self.persist:
+            valid_persist_scopes = ['local', 'session', 'sync']
+            if self.persist not in valid_persist_scopes:
+                errors.append(f"Invalid persist scope: {self.persist}. Must be one of {valid_persist_scopes}")
+
+        return errors
+
+
+class PersistNode(QuantumNode):
+    """
+    Represents a <q:persist> - Explicit persistence configuration.
+
+    Allows fine-grained control over state persistence beyond the persist attribute on q:set.
+
+    Examples:
+      <q:persist scope="local" prefix="myapp_">
+        <q:var name="theme" />
+        <q:var name="locale" />
+      </q:persist>
+
+      <q:persist scope="sync" key="user_preferences" encrypt="true">
+        <q:var name="darkMode" />
+        <q:var name="fontSize" />
+      </q:persist>
+
+    Attributes:
+      scope: "local" (localStorage), "session" (sessionStorage), "sync" (cross-tab/network)
+      prefix: Optional prefix for all storage keys
+      key: If set, all vars are stored under this single key as an object
+      encrypt: Whether to encrypt persisted data
+      ttl: Time-to-live in seconds (for cache invalidation)
+      storage: Override storage backend ("localStorage", "indexedDB", "file", "db")
+    """
+
+    def __init__(
+        self,
+        scope: str = "local",
+        prefix: Optional[str] = None,
+        key: Optional[str] = None,
+        encrypt: bool = False,
+        ttl: Optional[int] = None,
+        storage: Optional[str] = None
+    ):
+        self.scope = scope
+        self.prefix = prefix
+        self.key = key
+        self.encrypt = encrypt
+        self.ttl = ttl
+        self.storage = storage
+        self.variables: List[str] = []  # List of variable names to persist
+
+    def add_variable(self, name: str):
+        """Add a variable name to persist."""
+        self.variables.append(name)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "persist",
+            "scope": self.scope,
+            "prefix": self.prefix,
+            "key": self.key,
+            "encrypt": self.encrypt,
+            "ttl": self.ttl,
+            "storage": self.storage,
+            "variables": self.variables
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+
+        # Validate scope
+        valid_scopes = ['local', 'session', 'sync']
+        if self.scope not in valid_scopes:
+            errors.append(f"Invalid persist scope: {self.scope}. Must be one of {valid_scopes}")
+
+        # Validate storage backend if specified
+        if self.storage:
+            valid_storage = ['localStorage', 'sessionStorage', 'indexedDB', 'file', 'db']
+            if self.storage not in valid_storage:
+                errors.append(f"Invalid storage backend: {self.storage}. Must be one of {valid_storage}")
+
+        # Validate variables
+        if not self.variables:
+            errors.append("q:persist must contain at least one q:var element")
+
+        return errors
+
+    def __repr__(self):
+        return f'<PersistNode scope={self.scope} vars={len(self.variables)}>'

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

@@ -0,0 +1,21 @@
+"""
+Terminal Engine - AST nodes and parser for the qt: namespace.
+"""
+
+from .ast_nodes import (
+    ScreenNode, PanelNode, LayoutNode, TableNode, ColumnNode,
+    TerminalInputNode, ButtonNode, MenuNode, OptionNode,
+    TextNode_Terminal, ProgressNode, TreeNode, TabsNode, TabNode,
+    LogNode_Terminal, HeaderNode_Terminal, FooterNode, StatusNode,
+    KeybindingNode, TimerNode_Terminal, ServiceNode, CssNode,
+    OnEventNode_Terminal, RawCodeNode_Terminal,
+)
+
+__all__ = [
+    'ScreenNode', 'PanelNode', 'LayoutNode', 'TableNode', 'ColumnNode',
+    'TerminalInputNode', 'ButtonNode', 'MenuNode', 'OptionNode',
+    'TextNode_Terminal', 'ProgressNode', 'TreeNode', 'TabsNode', 'TabNode',
+    'LogNode_Terminal', 'HeaderNode_Terminal', 'FooterNode', 'StatusNode',
+    'KeybindingNode', 'TimerNode_Terminal', 'ServiceNode', 'CssNode',
+    'OnEventNode_Terminal', 'RawCodeNode_Terminal',
+]