quantum-framework 0.18.0__py3-none-any.whl

quantum/core/parsers/control_flow/set_parser.py

@@ -0,0 +1,93 @@
+"""
+Set Parser - Parse q:set statements
+
+Handles variable assignment with validation and persistence.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.features.state_management.src.ast_node import SetNode
+
+
+class SetParser(BaseTagParser):
+    """
+    Parser for q:set statements.
+
+    Supports:
+    - Type-safe variable assignment
+    - Validation rules
+    - Scope management
+    - Operations (assign, append, increment, etc.)
+    - State persistence
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['set']
+
+    def parse(self, element: ET.Element) -> SetNode:
+        """
+        Parse q:set statement.
+
+        Args:
+            element: XML element for q:set
+
+        Returns:
+            SetNode AST node
+        """
+        name = self.get_attr(element, 'name')
+
+        if not name:
+            raise ParserError("Set requires 'name' attribute")
+
+        set_node = SetNode(name)
+
+        # Type and value
+        set_node.type = self.get_attr(element, 'type', 'string')
+        set_node.value = self.get_attr(element, 'value')
+        set_node.default = self.get_attr(element, 'default')
+
+        # Validation
+        set_node.required = self.get_bool_attr(element, 'required', False)
+        set_node.nullable = self.get_bool_attr(element, 'nullable', True)
+        set_node.validate_rule = self.get_attr(element, 'validate')
+        set_node.pattern = self.get_attr(element, 'pattern')
+        if element.get('mask') is not None:
+            # A2: accepted and never applied.
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:set name="{set_node.name}"> mask= is not supported: it was accepted and '
+                f'never did anything. To validate a format use pattern=.')
+        set_node.range = self.get_attr(element, 'range')
+        set_node.enum = self.get_attr(element, 'enum')
+        set_node.unique = self.get_attr(element, 'unique')
+        set_node.min = self.get_attr(element, 'min')
+        set_node.max = self.get_attr(element, 'max')
+        set_node.minlength = self.get_attr(element, 'minlength')
+        set_node.maxlength = self.get_attr(element, 'maxlength')
+
+        # Behavior
+        set_node.scope = self.get_attr(element, 'scope', 'local')
+        set_node.operation = self.get_attr(element, 'operation', 'assign')
+
+        # Step for increment/decrement
+        set_node.step = self.get_int_attr(element, 'step', 1)
+
+        # Collection operations
+        set_node.index = self.get_attr(element, 'index')
+        set_node.key = self.get_attr(element, 'key')
+        set_node.source = self.get_attr(element, 'source')
+
+        # SET-2: browser persistence never ran in a page.
+        persist = [a for a in ('persist', 'persistKey', 'persistTtl', 'persistEncrypt')
+                   if element.get(a) is not None]
+        if persist:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:set name="{set_node.name}"> {persist[0]}= was removed in Quantum 0.16: it '
+                f'kept the variable in the browser, and a page\'s variables live on the server, '
+                f'for one request. Keep what must last in session.{set_node.name} (per user) '
+                f'or in the database.')
+
+        return set_node

quantum/core/parsers/data/__init__.py

@@ -0,0 +1,12 @@
+"""
+Data Parsers
+
+Parsers for data operations: query, invoke, data, transaction.
+"""
+
+from .query_parser import QueryParser
+from .invoke_parser import InvokeParser
+from .data_parser import DataParser
+from .transaction_parser import TransactionParser
+
+__all__ = ['QueryParser', 'InvokeParser', 'DataParser', 'TransactionParser']

quantum/core/parsers/data/data_parser.py

@@ -0,0 +1,229 @@
+"""
+Data Parser - Parse q:data statements
+
+Handles data import from CSV, JSON, XML sources.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.ast_nodes import (
+    DataNode, ColumnNode, FieldNode, TransformNode, HeaderNode,
+    FilterNode, SortNode, LimitNode, ComputeNode,
+)
+
+
+class DataParser(BaseTagParser):
+    """
+    Parser for q:data statements.
+
+    Supports:
+    - CSV import with column definitions
+    - JSON import with field mappings
+    - XML import with XPath
+    - Data transformations
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['data']
+
+    def parse(self, element: ET.Element) -> DataNode:
+        """
+        Parse q:data statement.
+
+        Args:
+            element: XML element for q:data
+
+        Returns:
+            DataNode AST node
+        """
+        name = self.get_attr(element, 'name')
+        source = self.get_attr(element, 'source')
+        data_type = self.get_attr(element, 'type', 'csv')
+
+        if not name:
+            raise ParserError("Data requires 'name' attribute")
+        if not source:
+            raise ParserError("Data requires 'source' attribute")
+
+        data_node = DataNode(name, source, data_type)
+
+        # Caching
+        data_node.cache = self.get_bool_attr(element, 'cache', True)
+        data_node.ttl = self.get_int_attr(element, 'ttl', 0) or None
+
+        # CSV attributes
+        data_node.delimiter = self.get_attr(element, 'delimiter', ',')
+        data_node.quote = self.get_attr(element, 'quote', '"')
+        data_node.header = self.get_bool_attr(element, 'header', True)
+        data_node.encoding = self.get_attr(element, 'encoding', 'utf-8')
+        data_node.skip_rows = self.get_int_attr(element, 'skip_rows', 0)
+
+        # XML attributes
+        data_node.xpath = self.get_attr(element, 'xpath')
+        data_node.namespace = self.get_attr(element, 'namespace')
+
+        # Result
+        data_node.result = self.get_attr(element, 'result')
+
+        # DATA-4 / INV-2: a failure stops the component unless the program says
+        # it will look at <name>_result.
+        data_node.on_error = self.get_attr(element, 'onerror', 'fail')
+        if data_node.on_error not in ('fail', 'continue'):
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f"<q:data name=\"{data_node.name}\"> onerror must be \"fail\" or "
+                f"\"continue\", not \"{data_node.on_error}\"")
+
+        # Parse child elements
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'column':
+                column = self._parse_column(child)
+                data_node.add_column(column)
+            elif child_type == 'field':
+                field = self._parse_field(child)
+                data_node.add_field(field)
+            elif child_type == 'transform':
+                transform = self._parse_transform(child)
+                data_node.add_transform(transform)
+            elif child_type == 'header':
+                header = self._parse_header(child)
+                data_node.add_header(header)
+
+        return data_node
+
+    def _parse_column(self, element: ET.Element) -> ColumnNode:
+        """Parse q:column for CSV."""
+        name = self.get_attr(element, 'name')
+        col_type = self.get_attr(element, 'type', 'string')
+
+        if not name:
+            raise ParserError("Column requires 'name' attribute")
+
+        column = ColumnNode(name, col_type)
+        column.required = self.get_bool_attr(element, 'required', False)
+        column.default = self.get_attr(element, 'default')
+        column.validate_rule = self.get_attr(element, 'validate')
+        column.pattern = self.get_attr(element, 'pattern')
+
+        # Numeric validation
+        min_val = self.get_attr(element, 'min')
+        if min_val:
+            try:
+                column.min = float(min_val)
+            except ValueError:
+                column.min = min_val
+
+        max_val = self.get_attr(element, 'max')
+        if max_val:
+            try:
+                column.max = float(max_val)
+            except ValueError:
+                column.max = max_val
+
+        column.minlength = self.get_int_attr(element, 'minlength', 0) or None
+        column.maxlength = self.get_int_attr(element, 'maxlength', 0) or None
+        column.range = self.get_attr(element, 'range')
+        column.enum = self.get_attr(element, 'enum')
+
+        return column
+
+    def _parse_field(self, element: ET.Element) -> FieldNode:
+        """Parse q:field for JSON/XML."""
+        name = self.get_attr(element, 'name')
+        # `xpath` is the attribute every example and the reference use; only
+        # `path` was read, so `xpath="@id"` became the name "id" and `type` was
+        # dropped — attributes came back None and numbers came back as text.
+        path = self.get_attr(element, 'xpath') or self.get_attr(element, 'path')
+
+        if not name:
+            raise ParserError("Field requires 'name' attribute")
+
+        return FieldNode(name, path or name, self.get_attr(element, 'type') or 'string')
+
+    def _parse_transform(self, element: ET.Element) -> TransformNode:
+        """Parse q:transform — a container of operations.
+
+        This read operation=/field=/value= off the tag and called
+        TransformNode(operation, field, value). TransformNode takes NO
+        arguments: it holds a list of child operations, which is also what
+        the runtime iterates and what all four q:transform blocks in
+        examples/ are written as:
+
+            <q:transform>
+              <q:filter condition="{active} == True" />
+            </q:transform>
+
+        So the parser rejected the only form anybody writes — "Transform
+        requires 'operation' attribute" — and would have raised TypeError if
+        it had ever got past that. Four example tests failed here.
+        """
+        transform_node = TransformNode()
+
+        for child in element:
+            tag = self._local_name(child.tag)
+
+            if tag == 'filter':
+                condition = self.get_attr(child, 'condition')
+                if not condition:
+                    raise ParserError("Filter requires 'condition' attribute")
+                transform_node.add_operation(FilterNode(condition))
+
+            elif tag == 'sort':
+                by = self.get_attr(child, 'by') or self.get_attr(child, 'field')
+                if not by:
+                    raise ParserError("Sort requires 'by' attribute")
+                order = (self.get_attr(child, 'order') or 'asc').lower()
+                if order not in ('asc', 'desc'):
+                    raise ParserError(
+                        f"Invalid sort order: {order}. Must be 'asc' or 'desc'")
+                transform_node.add_operation(SortNode(by, order))
+
+            elif tag == 'limit':
+                raw = self.get_attr(child, 'value') or self.get_attr(child, 'count')
+                if raw is None or raw == '':
+                    raise ParserError("Limit requires 'value' attribute")
+                try:
+                    limit = int(str(raw).strip())
+                except ValueError:
+                    raise ParserError(f"Limit value must be a number, got {raw!r}")
+                transform_node.add_operation(LimitNode(limit))
+
+            elif tag == 'compute':
+                field = self.get_attr(child, 'field') or self.get_attr(child, 'name')
+                expression = self.get_attr(child, 'expression')
+                if not field:
+                    raise ParserError("Compute requires 'field' attribute")
+                if not expression:
+                    raise ParserError("Compute requires 'expression' attribute")
+                transform_node.add_operation(ComputeNode(
+                    field, expression, self.get_attr(child, 'type') or 'string'))
+
+            else:
+                raise ParserError(
+                    f"Unknown transform operation 'q:{tag}'. Supported: "
+                    f"filter, sort, limit, compute")
+
+        return transform_node
+
+    @staticmethod
+    def _local_name(tag: str) -> str:
+        """'{ns}filter' or 'q:filter' -> 'filter'."""
+        if '}' in tag:
+            tag = tag.split('}', 1)[1]
+        if ':' in tag:
+            tag = tag.split(':', 1)[1]
+        return tag
+
+    def _parse_header(self, element: ET.Element) -> HeaderNode:
+        """Parse q:header for HTTP headers."""
+        name = self.get_attr(element, 'name')
+        value = self.get_attr(element, 'value')
+
+        if not name:
+            raise ParserError("Header requires 'name' attribute")
+
+        return HeaderNode(name, value or '')

quantum/core/parsers/data/invoke_parser.py

@@ -0,0 +1,133 @@
+"""
+Invoke Parser - Parse q:invoke statements
+
+Handles function, component, and HTTP invocations.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.features.invocation.src.ast_node import InvokeNode, InvokeHeaderNode
+from quantum.core.ast_nodes import QuantumParam
+
+
+class InvokeParser(BaseTagParser):
+    """
+    Parser for q:invoke statements.
+
+    Supports:
+    - Function invocation
+    - Component invocation
+    - HTTP requests (REST APIs)
+    - Service invocation
+    - Authentication (bearer, basic, custom)
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['invoke']
+
+    def parse(self, element: ET.Element) -> InvokeNode:
+        """
+        Parse q:invoke statement.
+
+        Args:
+            element: XML element for q:invoke
+
+        Returns:
+            InvokeNode AST node
+        """
+        name = self.get_attr(element, 'name')
+        # Fire-and-forget invocation (no result to bind) is legitimate — the
+        # job/thread examples all use it — so name is optional.
+        invoke_node = InvokeNode(name or '')
+
+        # Parse invocation target
+        invoke_node.function = self.get_attr(element, 'function')
+        invoke_node.component = self.get_attr(element, 'component')
+        invoke_node.url = self.get_attr(element, 'url')
+        if self.get_attr(element, 'endpoint') is not None:
+            raise ParserError(
+                f'<q:invoke name="{name}"> endpoint= is not supported: it was accepted and never '
+                f'did anything, and was removed in Quantum 0.12. Use url= or service=.')
+        invoke_node.service = self.get_attr(element, 'service')
+
+        # HTTP attributes
+        invoke_node.method = self.get_attr(element, 'method', 'GET').upper()
+        invoke_node.content_type = self.get_attr(element, 'contentType', 'application/json')
+
+        # Authentication
+        invoke_node.auth_type = self.get_attr(element, 'authType')
+        invoke_node.auth_token = self.get_attr(element, 'authToken')
+        invoke_node.auth_header = self.get_attr(element, 'authHeader')
+        invoke_node.auth_username = self.get_attr(element, 'authUsername')
+        invoke_node.auth_password = self.get_attr(element, 'authPassword')
+
+        # Timeouts and retries
+        invoke_node.timeout = self.get_int_attr(element, 'timeout', 0) or None
+        invoke_node.retry = self.get_int_attr(element, 'retry', 0) or None
+        invoke_node.retry_delay = self.get_int_attr(element, 'retryDelay', 0) or None
+
+        # Response handling
+        invoke_node.response_format = self.get_attr(element, 'responseFormat', 'auto')
+        if element.get('transform') is not None:
+            # A2: accepted and never applied.
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:invoke name="{invoke_node.name}"> transform= is not supported: it was '
+                f'accepted and never did anything. Transform the result with q:set.')
+        invoke_node.cache = self.get_bool_attr(element, 'cache', False)
+        invoke_node.ttl = self.get_int_attr(element, 'ttl', 0) or None
+        invoke_node.result = self.get_attr(element, 'result')
+
+        # DATA-4 / INV-2: a failure stops the component unless the program says
+        # it will look at <name>_result.
+        invoke_node.on_error = self.get_attr(element, 'onerror', 'fail')
+        if invoke_node.on_error not in ('fail', 'continue'):
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f"<q:invoke name=\"{invoke_node.name}\"> onerror must be \"fail\" or "
+                f"\"continue\", not \"{invoke_node.on_error}\"")
+
+        # Parse child elements
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'header':
+                header = self._parse_header(child)
+                invoke_node.add_header(header)
+            elif child_type == 'param':
+                param = self._parse_param(child)
+                invoke_node.add_param(param)
+            elif child_type == 'body':
+                invoke_node.body = child.text or ""
+
+        return invoke_node
+
+    def _parse_header(self, element: ET.Element) -> InvokeHeaderNode:
+        """Parse q:header within q:invoke."""
+        name = self.get_attr(element, 'name')
+        value = self.get_attr(element, 'value')
+
+        if not name:
+            raise ParserError("Invoke header requires 'name' attribute")
+        if value is None:
+            raise ParserError(f"Invoke header '{name}' requires 'value' attribute")
+
+        return InvokeHeaderNode(name, value)
+
+    def _parse_param(self, element: ET.Element) -> QuantumParam:
+        """Parse q:param within q:invoke."""
+        name = self.get_attr(element, 'name')
+        value = self.get_attr(element, 'value')
+        param_type = self.get_attr(element, 'type', 'string')
+
+        if not name:
+            raise ParserError("Param requires 'name' attribute")
+
+        param = QuantumParam(name, param_type)
+        param.value = value
+        param.required = self.get_bool_attr(element, 'required', False)
+        param.default = self.get_attr(element, 'default')
+
+        return param

quantum/core/parsers/data/query_parser.py

@@ -0,0 +1,213 @@
+"""
+Query Parser - Parse q:query statements
+
+Handles SQL queries with parameter binding and RAG mode.
+"""
+
+import re
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.ast_nodes import QueryNode, QueryParamNode
+
+
+_NEVER_IMPLEMENTED = ('cache', 'ttl', 'reactive', 'interval', 'timeout', 'maxrows', 'batch')
+
+
+class QueryParser(BaseTagParser):
+    """
+    Parser for q:query statements.
+
+    Supports:
+    - SQL queries with parameter binding
+    - Query of Queries (source attribute)
+    - Caching and pagination
+    - RAG/knowledge base queries
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['query']
+
+    def parse(self, element: ET.Element) -> QueryNode:
+        """
+        Parse q:query statement.
+
+        Args:
+            element: XML element for q:query
+
+        Returns:
+            QueryNode AST node
+        """
+        name = self.get_attr(element, 'name')
+        datasource = self.get_attr(element, 'datasource')
+        source = self.get_attr(element, 'source')
+
+        # A write query (UPDATE/INSERT/DELETE) has no result set to bind, so
+        # name is optional — requiring it rejected the ordinary CFML-style
+        # idiom used across the job examples. Reads still want a name; without
+        # one there is simply nothing to reference the rows by.
+        if not name:
+            name = ''
+        if not datasource and not source:
+            raise ParserError("Query requires either 'datasource' or 'source' attribute")
+
+        # DB-5: attributes that were read into the AST and never used. The
+        # guide sold cache="true" ttl="3600" and reactive="true" as features.
+        for attr in _NEVER_IMPLEMENTED:
+            if element.get(attr) is not None:
+                raise ParserError(
+                    f'<q:query name="{name}"> {attr}= is not supported: it was accepted '
+                    f'and never did anything, and was removed in Quantum 0.11')
+
+        # Extract SQL content
+        sql_parts = []
+        if element.text:
+            sql_parts.append(element.text.strip())
+
+        for child in element:
+            if child.tail:
+                sql_parts.append(child.tail.strip())
+
+        sql = '\n'.join(part for part in sql_parts if part)
+
+        # Create query node
+        query_node = QueryNode(name, datasource or '', sql)
+
+        # Parse attributes
+        query_node.source = source
+        query_node.paginate = self.get_bool_attr(element, 'paginate', False)
+        # UI-13: ordered by the URL's ?sort=/&dir= (a <ui:table sort="true"> writes them)
+        query_node.sortable = self.get_bool_attr(element, 'sortable', False)
+        # DB-9: page= is an expression, resolved when the query runs; it was
+        # read as an int at parse time, so page="{query.page}" was always
+        # page 1. With paginate="true" and no page=, the page is the URL's
+        # `page` parameter — the one <ui:pager> writes.
+        pagina = element.get('page')
+        query_node.page = None
+        query_node.page_expr = None
+        if pagina is not None:
+            if '{' in pagina:
+                query_node.page_expr = pagina
+            elif pagina.strip().isdigit():
+                query_node.page = int(pagina)
+            else:
+                from quantum.core.parser import QuantumParseError
+                raise QuantumParseError(
+                    f'<q:query name="{name}" page="{pagina}">: a page number or an expression, '
+                    f'e.g. page="{{query.pagina}}"')
+        elif query_node.paginate:
+            query_node.page_expr = '{query.page}'
+        # Accept both spellings: the codebase convention is camelCase, but
+        # snake_case reads naturally in XML and the examples used it —
+        # the mismatch made page_size None and crashed pagination with
+        # 'unsupported operand type(s) for +: int and NoneType'.
+        query_node.page_size = (
+            self.get_int_attr(element, 'pageSize', 0)
+            or self.get_int_attr(element, 'page_size', 0)
+            or None
+        )
+        query_node.result = self.get_attr(element, 'result')
+
+        # RAG/Knowledge attributes
+        query_node.mode = self.get_attr(element, 'mode')
+        query_node.rag_model = self.get_attr(element, 'model')
+
+        # Parse q:param children
+        for child in element:
+            child_type = self.get_element_name(child)
+            if child_type == 'param':
+                param_node = self._parse_query_param(child)
+                query_node.add_param(param_node)
+
+        # Validate: reject direct {var} interpolation (SQL injection risk)
+        if sql and re.search(r'\{[a-zA-Z_]\w*\}', sql):
+            raise ParserError(
+                f"Query '{name}': direct {{var}} interpolation in SQL is not allowed. "
+                "Use :param_name with <q:param> for safe parameter binding"
+            )
+
+        # Validate: all :param references must have matching <q:param>
+        if sql:
+            sql_params = self._named_params(sql)
+            declared_params = {p.name for p in query_node.params}
+            missing = sql_params - declared_params
+            if missing:
+                raise ParserError(
+                    f"Query '{name}': SQL parameter(s) {', '.join(':' + p for p in sorted(missing))} "
+                    "declared in SQL but no matching <q:param> element provided"
+                )
+
+        return query_node
+
+    @staticmethod
+    def _named_params(sql: str) -> set:
+        """Os `:nome` que sao REALMENTE parametros de bind.
+
+        Isto era `re.findall(r':([a-zA-Z_]\\w*)', sql)` sobre o SQL cru, e
+        varria tambem o que esta dentro de aspas e de comentarios:
+
+            TO_CHAR(c.created_at, 'YYYY-MM-DD HH24:MI')   -> achava `:MI`
+            SELECT x::text FROM t                        -> achava `:text`
+
+        As duas formas sao SQL correto e comum — a primeira aparece em
+        projects/blog/components/post.q, que por causa disto nao parseava:
+        o arquivo era recusado com "SQL parameter(s) :MI declared in SQL but
+        no matching <q:param>", e nao havia parametro nenhum para declarar.
+
+        A varredura pula literais de texto (com '' e "" escapados), o cast
+        `::` do PostgreSQL, comentarios de linha `--` e de bloco.
+        """
+        encontrados = set()
+        i, n = 0, len(sql)
+        while i < n:
+            c = sql[i]
+            if c in ("'", '"'):
+                aspas = c
+                i += 1
+                while i < n:
+                    if sql[i] == aspas:
+                        if i + 1 < n and sql[i + 1] == aspas:
+                            i += 2      # '' escapado dentro do literal
+                            continue
+                        i += 1
+                        break
+                    i += 1
+                continue
+            if sql.startswith('--', i):
+                fim = sql.find('\n', i)
+                i = n if fim == -1 else fim + 1
+                continue
+            if sql.startswith('/*', i):
+                fim = sql.find('*/', i)
+                i = n if fim == -1 else fim + 2
+                continue
+            if c == ':':
+                if sql.startswith('::', i):
+                    i += 2              # cast do PostgreSQL, nao parametro
+                    continue
+                m = re.match(r':([a-zA-Z_]\w*)', sql[i:])
+                if m:
+                    encontrados.add(m.group(1))
+                    i += m.end()
+                    continue
+            i += 1
+        return encontrados
+
+    def _parse_query_param(self, element: ET.Element) -> QueryParamNode:
+        """Parse q:param within q:query."""
+        name = self.get_attr(element, 'name')
+        value = self.get_attr(element, 'value')
+        param_type = self.get_attr(element, 'type', 'string')
+
+        if not name:
+            raise ParserError("Query parameter requires 'name' attribute")
+        if value is None:
+            raise ParserError(f"Query parameter '{name}' requires 'value' attribute")
+
+        param_node = QueryParamNode(name, value, param_type)
+        param_node.null = self.get_bool_attr(element, 'null', False)
+        param_node.max_length = self.get_int_attr(element, 'maxLength', 0) or None
+        param_node.scale = self.get_int_attr(element, 'scale', 0) or None
+
+        return param_node