quantum-framework 0.18.0__py3-none-any.whl

quantum/core/parsers/data/transaction_parser.py

@@ -0,0 +1,86 @@
+"""
+Transaction Parser - Parse q:transaction statements
+
+Handles atomic database transactions.
+"""
+
+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 TransactionNode
+
+
+class TransactionParser(BaseTagParser):
+    """
+    Parser for q:transaction statements.
+
+    Supports:
+    - Atomic transaction blocks
+    - Automatic rollback on error
+    - Nested statement execution
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['transaction']
+
+    def parse(self, element: ET.Element) -> TransactionNode:
+        """
+        Parse q:transaction statement.
+
+        Args:
+            element: XML element for q:transaction
+
+        Returns:
+            TransactionNode AST node
+        """
+        # datasource= is optional. Requiring it was stricter than the runtime
+        # (DatabaseService.begin_transaction defaults it) and stricter than
+        # everything written against it: all four q:transaction blocks in this
+        # repository omit it, and three of them are tests that had been
+        # failing on this line — "Transaction requires 'datasource'
+        # attribute" — rather than on anything about transactions.
+        datasource = self.get_attr(element, 'datasource')
+
+        transaction_node = TransactionNode(datasource or '')
+
+        # Isolation level. Everything written in this repository and in the
+        # docs spells it isolationLevel; the parser read `isolation`, so the
+        # level was silently dropped every time. Both spellings work.
+        transaction_node.isolation = (
+            self.get_attr(element, 'isolationLevel')
+            or self.get_attr(element, 'isolation')
+        )
+
+        # DB-4: a q:query inside a transaction with datasource= uses it. Every
+        # query had to repeat it, or parsing failed with "Query requires
+        # either 'datasource' or 'source' attribute" — the guide's own
+        # transaction example did not parse.
+        for child in element:
+            if datasource and self.get_element_name(child) == 'query' \
+                    and not child.get('datasource') and not child.get('source'):
+                child.set('datasource', datasource)
+
+        # Parse child statements
+        for child in element:
+            statement = self.parse_statement(child)
+            if statement:
+                transaction_node.add_statement(statement)
+
+        if not datasource:
+            # Take it from the queries being wrapped, which is what the author
+            # means by wrapping them. Only if none of them names one does this
+            # fall back to "default".
+            transaction_node.datasource = (
+                self._datasource_of_children(transaction_node) or 'default'
+            )
+
+        return transaction_node
+
+    def _datasource_of_children(self, transaction_node) -> str:
+        """The datasource of the first child query that names one."""
+        for statement in getattr(transaction_node, 'statements', []) or []:
+            name = getattr(statement, 'datasource', None)
+            if name:
+                return name
+        return ''

quantum/core/parsers/events/__init__.py

@@ -0,0 +1,9 @@
+"""
+Events Parsers
+
+Parsers for event-related tags: dispatchEvent
+"""
+
+from .dispatch_event_parser import DispatchEventParser
+
+__all__ = ['DispatchEventParser']

quantum/core/parsers/events/dispatch_event_parser.py

@@ -0,0 +1,44 @@
+"""
+DispatchEvent Parser - Parse q:dispatchEvent statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import DispatchEventNode
+
+
+class DispatchEventParser(BaseTagParser):
+    """
+    Parser for q:dispatchEvent statements.
+
+    Examples:
+        <q:dispatchEvent event="userCreated" data="{userData}" />
+        <q:dispatchEvent event="orderPlaced" queue="orders" priority="high" />
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['dispatchEvent']
+
+    def parse(self, element: ET.Element) -> DispatchEventNode:
+        """Parse q:dispatchEvent element"""
+        event = element.get('event')
+
+        if not event:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError("dispatchEvent requires 'event' attribute")
+
+        dispatch_node = DispatchEventNode(event)
+
+        # Optional attributes
+        dispatch_node.data = element.get('data')
+        dispatch_node.queue = element.get('queue')
+        dispatch_node.exchange = element.get('exchange')
+        dispatch_node.routing_key = element.get('routingKey')
+        dispatch_node.priority = element.get('priority', 'normal')
+        dispatch_node.delay = element.get('delay')
+        dispatch_node.ttl = element.get('ttl')
+        dispatch_node.metadata = element.get('metadata')
+
+        return dispatch_node

quantum/core/parsers/forms/__init__.py

@@ -0,0 +1,11 @@
+"""
+Forms & Actions Parsers
+
+Parsers for form handling tags: action, redirect, flash
+"""
+
+from .action_parser import ActionParser
+from .redirect_parser import RedirectParser
+from .flash_parser import FlashParser
+
+__all__ = ['ActionParser', 'RedirectParser', 'FlashParser']

quantum/core/parsers/forms/action_parser.py

@@ -0,0 +1,79 @@
+"""
+Action Parser - Parse q:action statements for form handling
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import ActionNode
+
+
+_NEVER_ENFORCED = {
+    'require_auth': 'Protect the page with require_auth / require_role on the '
+                    'q:component: that covers its actions too (AUTH-1, AUTH-6).',
+    'csrf': 'There is no CSRF token; the session cookie is SameSite=Lax (AUTH-5).',
+    'rate_limit': 'Nothing limits requests; put a reverse proxy in front for that.',
+}
+
+
+class ActionParser(BaseTagParser):
+    """
+    Parser for q:action statements.
+
+    Examples:
+        <q:action name="createUser" method="POST">
+            <q:param name="email" type="email" required="true" />
+            <q:query datasource="db">...</q:query>
+            <q:redirect url="/users" flash="User created!" />
+        </q:action>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['action']
+
+    def parse(self, element: ET.Element) -> ActionNode:
+        """Parse q:action element"""
+        name = element.get('name', '')
+        method = element.get('method', 'POST')
+        action_node = ActionNode(name, method)
+
+        # AUTH-7: attributes that were parsed and never enforced. The worst
+        # is require_auth="true": the action ran for anyone, while the page
+        # read as protected. The docs promised csrf= and rate_limit= too.
+        for attr, porque in _NEVER_ENFORCED.items():
+            if element.get(attr) is not None:
+                from quantum.core.parser import QuantumParseError
+                raise QuantumParseError(
+                    f'<q:action name="{name}"> {attr}= is not supported: it was accepted '
+                    f'and never enforced. {porque}')
+
+        # UI-10 (M17): the action's params come from a table's schema, read
+        # from the database when the action is used; a q:param written wins.
+        action_node.table = element.get('table')
+        action_node.table_datasource = element.get('datasource')
+        colunas = element.get('columns')
+        action_node.table_columns = [c.strip() for c in colunas.split(',') if c.strip()] if colunas else None
+        if (action_node.table_datasource or colunas) and not action_node.table:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:action name="{name}"> datasource= and columns= describe table=, which is missing')
+        if action_node.table and not action_node.table_datasource:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:action name="{name}" table="{action_node.table}"> needs datasource= (where the table is)')
+
+        # Parse children (params, statements)
+        for child in element:
+            child_type = self._get_element_name(child)
+
+            if child_type == 'param':
+                param = self.parse_param(child)
+                action_node.add_param(param)
+            else:
+                # Parse other statements (query, set, redirect, etc.)
+                statement = self.parse_child(child)
+                if statement:
+                    action_node.add_statement(statement)
+
+        return action_node

quantum/core/parsers/forms/flash_parser.py

@@ -0,0 +1,34 @@
+"""
+Flash Parser - Parse q:flash statements for flash messages
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import FlashNode
+
+
+class FlashParser(BaseTagParser):
+    """
+    Parser for q:flash statements.
+
+    Examples:
+        <q:flash type="success" message="User created!" />
+        <q:flash type="error" message="{errorMessage}" />
+        <q:flash type="warning">Please verify your email</q:flash>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['flash']
+
+    def parse(self, element: ET.Element) -> FlashNode:
+        """Parse q:flash element"""
+        flash_type = element.get('type', 'info')
+        message = element.get('message')
+
+        # If message not in attribute, check text content
+        if not message and element.text:
+            message = element.text.strip()
+
+        return FlashNode(message, flash_type)

quantum/core/parsers/forms/redirect_parser.py

@@ -0,0 +1,33 @@
+"""
+Redirect Parser - Parse q:redirect statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import RedirectNode
+
+
+class RedirectParser(BaseTagParser):
+    """
+    Parser for q:redirect statements.
+
+    Examples:
+        <q:redirect url="/thank-you" />
+        <q:redirect url="/users/{userId}" />
+        <q:redirect url="/products" flash="Product created!" />
+        <q:redirect url="/error" status="500" flash="Error occurred" />
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['redirect']
+
+    def parse(self, element: ET.Element) -> RedirectNode:
+        """Parse q:redirect element"""
+        # Accept to= as an alias for url= (both appear across examples)
+        url = element.get('url') or element.get('to', '')
+        flash = element.get('flash')
+        status = int(element.get('status', '302'))
+
+        return RedirectNode(url, flash, status)

quantum/core/parsers/functions/__init__.py

@@ -0,0 +1,11 @@
+"""
+Functions Parsers
+
+Parsers for function-related tags: function, return, param
+"""
+
+from .function_parser import FunctionParser
+from .return_parser import ReturnParser
+from .param_parser import ParamParser
+
+__all__ = ['FunctionParser', 'ReturnParser', 'ParamParser']

quantum/core/parsers/functions/function_parser.py

@@ -0,0 +1,98 @@
+"""
+Function Parser - Parse q:function statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import FunctionNode
+
+
+_NO_OP = "it was accepted and never did anything, and was removed in Quantum 0.11"
+_NEVER_IMPLEMENTED = {
+    'validate': "parameters are always converted and checked against their rules (FN-1); remove it",
+    'cache': _NO_OP, 'memoize': _NO_OP, 'pure': _NO_OP, 'async': _NO_OP,
+    'retry': _NO_OP, 'timeout': _NO_OP, 'access': _NO_OP,
+    'scope': "a function belongs to its component; scope=\"global\" never made it callable from another page. " + _NO_OP,
+    'endpoint': "functions are not served as REST endpoints; " + _NO_OP,
+    'method': _NO_OP, 'produces': _NO_OP, 'consumes': _NO_OP, 'auth': _NO_OP,
+    'roles': _NO_OP, 'rateLimit': _NO_OP, 'cors': _NO_OP, 'status': _NO_OP,
+}
+
+
+class FunctionParser(BaseTagParser):
+    """
+    Parser for q:function statements.
+
+    Examples:
+        <q:function name="calculateTotal" returnType="number">
+            <q:param name="items" type="array" />
+            <q:set name="total" value="0" />
+            <q:loop array="{items}" item="item">
+                <q:set name="total" value="{total + item.price}" />
+            </q:loop>
+        </q:function>
+
+        <q:function name="getUser" endpoint="/api/users/{id}" method="GET">
+            <q:param name="id" type="integer" source="path" />
+            <q:query datasource="db">SELECT * FROM users WHERE id = :id</q:query>
+        </q:function>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['function']
+
+    def parse(self, element: ET.Element) -> FunctionNode:
+        """Parse q:function element"""
+        name = element.get('name')
+
+        if not name:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError("Function requires 'name' attribute")
+
+        func_node = FunctionNode(name)
+
+        # FN-2: attributes that were parsed into the AST and never did anything.
+        # memoize="true" or endpoint="/api/x" looked like working features —
+        # the guide documented them — and silently changed nothing.
+        for attr in element.attrib:
+            if attr in _NEVER_IMPLEMENTED:
+                from quantum.core.parser import QuantumParseError
+                raise QuantumParseError(
+                    f'<q:function name="{name}"> {attr}= is not supported: '
+                    f'{_NEVER_IMPLEMENTED[attr]}')
+
+        # Core attributes
+        func_node.return_type = element.get('returnType', 'any')
+        # FN-4: returnType is checked on every return (see ComponentRuntime).
+        from quantum.runtime.param_validation import RETURN_TYPES
+        if func_node.return_type.lower() not in RETURN_TYPES:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:function name="{name}"> returnType="{func_node.return_type}" is not a type; '
+                f'use one of: {", ".join(sorted(RETURN_TYPES))}')
+        func_node.description = element.get('description')
+        func_node.hint = element.get('hint')
+
+        # Parse function params and body
+        for child in element:
+            child_type = self._get_element_name(child)
+
+            if child_type == 'param':
+                param = self.parse_param(child)
+                func_node.add_param(param)
+            elif child_type == 'return':
+                # ReturnParser is deliberately not in the tag registry (it is
+                # an internal parser), so parse_child() returns None for it —
+                # which silently dropped every <q:return> from every function
+                # body, making functions return nothing. Parse it directly.
+                from quantum.core.parsers.functions.return_parser import ReturnParser
+                func_node.add_statement(ReturnParser(self._parser).parse(child))
+            else:
+                # Parse body statements
+                statement = self.parse_child(child)
+                if statement:
+                    func_node.add_statement(statement)
+
+        return func_node

quantum/core/parsers/functions/param_parser.py

@@ -0,0 +1,73 @@
+"""
+Param Parser - Parse q:param statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import QuantumParam
+
+
+class ParamParser(BaseTagParser):
+    """
+    Parser for q:param statements.
+
+    Examples:
+        <q:param name="email" type="email" required="true" />
+        <q:param name="password" type="string" minlength="8" />
+        <q:param name="age" type="integer" min="0" max="150" />
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['param']
+
+    def parse(self, element: ET.Element) -> QuantumParam:
+        """Parse q:param element"""
+        param = QuantumParam(
+            name=element.get('name', ''),
+            type=element.get('type', 'string'),
+            required=element.get('required', 'false').lower() == 'true',
+            default=element.get('default'),
+            description=element.get('description')
+        )
+        if element.get('validation') is not None:
+            # A2: accepted and never read. The rules are validate=, type=,
+            # pattern=, min/max, minlength/maxlength and enum=.
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:param name="{element.get("name", "")}"> validation= is not supported: it was '
+                f'accepted and never did anything. Use type=, pattern=, min/max, '
+                f'minlength/maxlength or enum=.')
+
+        # REST-specific
+        param.source = element.get('source', 'auto')
+
+        # Validation
+        param.validate_rule = element.get('validate')
+        param.pattern = element.get('pattern')
+        param.min = element.get('min')
+        param.max = element.get('max')
+
+        minlength_str = element.get('minlength')
+        if minlength_str:
+            try:
+                param.minlength = int(minlength_str)
+            except ValueError:
+                pass
+
+        maxlength_str = element.get('maxlength')
+        if maxlength_str:
+            try:
+                param.maxlength = int(maxlength_str)
+            except ValueError:
+                pass
+
+        param.range = element.get('range')
+        param.enum = element.get('enum')
+
+        # File upload
+        param.maxsize = element.get('maxsize')
+        param.accept = element.get('accept')
+
+        return param

quantum/core/parsers/functions/return_parser.py

@@ -0,0 +1,31 @@
+"""
+Return Parser - Parse q:return statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import QuantumReturn
+
+
+class ReturnParser(BaseTagParser):
+    """
+    Parser for q:return statements.
+
+    Examples:
+        <q:return name="result" type="string" value="{computedValue}" />
+        <q:return type="integer" value="42" />
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['return']
+
+    def parse(self, element: ET.Element) -> QuantumReturn:
+        """Parse q:return element"""
+        return QuantumReturn(
+            name=element.get('name'),
+            type=element.get('type', 'string'),
+            value=element.get('value', ''),
+            description=element.get('description')
+        )

quantum/core/parsers/html/__init__.py

@@ -0,0 +1,10 @@
+"""
+HTML Parsers
+
+Parsers for HTML elements and component calls.
+"""
+
+from .html_parser import HTMLParser
+from .component_call_parser import ComponentCallParser
+
+__all__ = ['HTMLParser', 'ComponentCallParser']

quantum/core/parsers/html/component_call_parser.py

@@ -0,0 +1,130 @@
+"""
+Component Call Parser - Parse component invocations
+
+Handles parsing of component calls (PascalCase tags).
+"""
+
+from typing import List, Optional, Dict, Any
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import ComponentCallNode, TextNode
+
+
+class ComponentCallParser(BaseTagParser):
+    """
+    Parser for component call elements.
+
+    Component calls are identified by PascalCase naming convention:
+    - <MyComponent /> -> calls imported component "MyComponent"
+    - <UserCard name="John" /> -> calls "UserCard" with props
+
+    These are similar to React/Vue component usage.
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        """
+        Component call parser doesn't register for specific tags.
+        Instead, it's called when a PascalCase tag is detected.
+        """
+        return []
+
+    def parse(self, element: ET.Element) -> ComponentCallNode:
+        """
+        Parse component call element.
+
+        Args:
+            element: XML element representing component call
+
+        Returns:
+            ComponentCallNode AST node
+        """
+        component_name = self._get_local_name(element)
+
+        # Get props from attributes
+        props = self._parse_props(element)
+
+        # Create component call node
+        call_node = ComponentCallNode(component_name, props)
+
+        # Parse children (slot content)
+        call_node.children = self._parse_children(element)
+
+        return call_node
+
+    def _get_local_name(self, element: ET.Element) -> str:
+        """Extract local name from element tag."""
+        tag = element.tag
+        if '}' in tag:
+            return tag.split('}')[1]
+        if ':' in tag:
+            return tag.split(':')[1]
+        return tag
+
+    def _parse_props(self, element: ET.Element) -> Dict[str, Any]:
+        """
+        Parse element attributes as component props.
+
+        Handles:
+        - Simple string values: name="John"
+        - Databinding expressions: user="{currentUser}"
+        - Boolean shorthand: disabled (treated as disabled="true")
+        """
+        props = {}
+
+        for key, value in element.attrib.items():
+            # Skip namespace declarations
+            if key.startswith('xmlns'):
+                continue
+
+            # Handle namespaced attributes
+            if '}' in key:
+                key = key.split('}')[1]
+
+            props[key] = value
+
+        return props
+
+    def _parse_children(self, element: ET.Element) -> List:
+        """Parse child elements as slot content."""
+        children = []
+
+        # Add leading text if present
+        if element.text and element.text.strip():
+            children.append(TextNode(element.text))
+
+        # Parse child elements
+        for child in element:
+            child_node = self.parse_statement(child)
+            if child_node:
+                children.append(child_node)
+
+            # Add tail text after child
+            if child.tail and child.tail.strip():
+                children.append(TextNode(child.tail))
+
+        return children
+
+    @staticmethod
+    def is_component_call(tag_name: str) -> bool:
+        """
+        Check if tag name represents a component call.
+
+        Components use PascalCase naming:
+        - MyComponent -> True
+        - UserCard -> True
+        - div -> False
+        - myComponent -> False
+        """
+        if not tag_name:
+            return False
+
+        # Must start with uppercase letter
+        if not tag_name[0].isupper():
+            return False
+
+        # Should not be all uppercase (likely a constant/builtin)
+        if tag_name.isupper():
+            return False
+
+        return True