quantum-framework 0.18.0__py3-none-any.whl

quantum/core/parsers/routing/__init__.py

@@ -0,0 +1,9 @@
+"""
+Routing Parsers
+
+Parsers for routing-related tags: route
+"""
+
+from .route_parser import RouteParser
+
+__all__ = ['RouteParser']

quantum/core/parsers/routing/route_parser.py

@@ -0,0 +1,41 @@
+"""
+Route Parser - Parse q:route 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 QuantumRoute
+
+
+class RouteParser(BaseTagParser):
+    """
+    Parser for q:route statements.
+
+    Examples:
+        <q:route path="/users" method="GET" />
+        <q:route path="/api/products/{id}" method="POST">
+            <q:return name="product" type="object" />
+        </q:route>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['route']
+
+    def parse(self, element: ET.Element) -> QuantumRoute:
+        """Parse q:route element"""
+        path = element.get('path', '/')
+        method = element.get('method', 'GET').upper()
+
+        route = QuantumRoute(path, method)
+
+        # Parse q:return inside the route
+        for child in element:
+            child_type = self._get_element_name(child)
+            if child_type == 'return':
+                return_node = self.parse_child(child)
+                if return_node:
+                    route.returns.append(return_node)
+
+        return route

quantum/core/parsers/scripting/__init__.py

@@ -0,0 +1,12 @@
+"""
+Scripting Parsers
+
+Parsers for Python scripting: python, pyimport, pyclass, pydecorator.
+"""
+
+from .python_parser import PythonParser
+from .pyimport_parser import PyImportParser
+from .pyclass_parser import PyClassParser
+from .pydecorator_parser import PyDecoratorParser
+
+__all__ = ['PythonParser', 'PyImportParser', 'PyClassParser', 'PyDecoratorParser']

quantum/core/parsers/scripting/pyclass_parser.py

@@ -0,0 +1,62 @@
+"""
+PyClass Parser - Parse q:class statements
+
+Handles inline Python class definitions.
+"""
+
+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 PyClassNode
+
+
+class PyClassParser(BaseTagParser):
+    """
+    Parser for q:class statements.
+
+    Supports:
+    - Class definition
+    - Base class inheritance
+    - Decorator application
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['class', 'pyclass']
+
+    def parse(self, element: ET.Element) -> PyClassNode:
+        """
+        Parse q:class statement.
+
+        Args:
+            element: XML element for q:class
+
+        Returns:
+            PyClassNode AST node
+        """
+        name = self.get_attr(element, 'name')
+        code = self.get_text(element)
+
+        if not name:
+            raise ParserError("class requires 'name' attribute")
+        if not code or not code.strip():
+            raise ParserError("class body cannot be empty")
+
+        # Parse bases
+        bases_attr = self.get_attr(element, 'bases')
+        bases = []
+        if bases_attr:
+            bases = [b.strip() for b in bases_attr.split(',')]
+
+        # Parse decorators
+        decorators_attr = self.get_attr(element, 'decorators')
+        decorators = []
+        if decorators_attr:
+            decorators = [d.strip() for d in decorators_attr.split(',')]
+
+        return PyClassNode(
+            name=name,
+            code=code,
+            bases=bases,
+            decorators=decorators
+        )

quantum/core/parsers/scripting/pydecorator_parser.py

@@ -0,0 +1,68 @@
+"""
+PyDecorator Parser - Parse q:decorator statements
+"""
+
+import textwrap
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import PyDecoratorNode
+
+
+class PyDecoratorParser(BaseTagParser):
+    """
+    Parser for q:decorator statements for Python decorator definitions.
+
+    Examples:
+        <!-- Caching decorator -->
+        <q:decorator name="cached">
+            from functools import wraps
+            def decorator(func):
+                cache = {}
+                @wraps(func)
+                def wrapper(*args):
+                    if args in cache:
+                        return cache[args]
+                    result = func(*args)
+                    cache[args] = result
+                    return result
+                return wrapper
+            return decorator
+        </q:decorator>
+
+        <!-- Decorator with parameters -->
+        <q:decorator name="retry" params="attempts, delay">
+            import time
+            def decorator(func):
+                def wrapper(*args, **kwargs):
+                    for i in range(attempts):
+                        try:
+                            return func(*args, **kwargs)
+                        except Exception as e:
+                            if i == attempts - 1:
+                                raise
+                            time.sleep(delay)
+                return wrapper
+            return decorator
+        </q:decorator>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['decorator', 'pydecorator']
+
+    def parse(self, element: ET.Element) -> PyDecoratorNode:
+        """Parse q:decorator element"""
+        name = element.get('name', '')
+        code = element.text or ""
+        code = textwrap.dedent(code).strip()
+
+        # Parse params (comma-separated)
+        params_str = element.get('params', '')
+        params = [p.strip() for p in params_str.split(',') if p.strip()]
+
+        return PyDecoratorNode(
+            name=name,
+            code=code,
+            params=params
+        )

quantum/core/parsers/scripting/pyimport_parser.py

@@ -0,0 +1,52 @@
+"""
+PyImport Parser - Parse q:pyimport statements
+
+Handles Python module imports.
+"""
+
+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 PyImportNode
+
+
+class PyImportParser(BaseTagParser):
+    """
+    Parser for q:pyimport statements.
+
+    Supports:
+    - Module import with alias
+    - Specific name imports
+    - Star imports
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['pyimport']
+
+    def parse(self, element: ET.Element) -> PyImportNode:
+        """
+        Parse q:pyimport statement.
+
+        Args:
+            element: XML element for q:pyimport
+
+        Returns:
+            PyImportNode AST node
+        """
+        module = self.get_attr(element, 'module')
+
+        if not module:
+            raise ParserError("pyimport requires 'module' attribute")
+
+        # Parse names if present
+        names_attr = self.get_attr(element, 'names')
+        names = []
+        if names_attr:
+            names = [n.strip() for n in names_attr.split(',')]
+
+        return PyImportNode(
+            module=module,
+            alias=self.get_attr(element, 'as'),
+            names=names
+        )

quantum/core/parsers/scripting/python_parser.py

@@ -0,0 +1,49 @@
+"""
+Python Parser - Parse q:python statements
+
+Handles embedded Python code.
+"""
+
+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 PythonNode
+
+
+class PythonParser(BaseTagParser):
+    """
+    Parser for q:python statements.
+
+    Supports:
+    - Inline Python code
+    - Scope management
+    - Async execution
+    - Result capture
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['python']
+
+    def parse(self, element: ET.Element) -> PythonNode:
+        """
+        Parse q:python statement.
+
+        Args:
+            element: XML element for q:python
+
+        Returns:
+            PythonNode AST node
+        """
+        code = self.get_text(element)
+
+        if not code or not code.strip():
+            raise ParserError("Python block cannot be empty")
+
+        return PythonNode(
+            code=code,
+            scope=self.get_attr(element, 'scope', 'component'),
+            async_mode=self.get_bool_attr(element, 'async', False),
+            timeout=self.get_attr(element, 'timeout'),
+            result=self.get_attr(element, 'result')
+        )

quantum/core/parsers/services/__init__.py

@@ -0,0 +1,12 @@
+"""
+Services Parsers
+
+Parsers for service operations: log, dump, file, mail.
+"""
+
+from .log_parser import LogParser
+from .dump_parser import DumpParser
+from .file_parser import FileParser
+from .mail_parser import MailParser
+
+__all__ = ['LogParser', 'DumpParser', 'FileParser', 'MailParser']

quantum/core/parsers/services/dump_parser.py

@@ -0,0 +1,52 @@
+"""
+Dump Parser - Parse q:dump statements
+
+Handles variable inspection and debugging.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.features.dump.src import DumpNode
+
+
+class DumpParser(BaseTagParser):
+    """
+    Parser for q:dump statements.
+
+    Supports:
+    - Variable inspection
+    - Multiple output formats
+    - Depth control
+    - Conditional dumping
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['dump']
+
+    def parse(self, element: ET.Element) -> DumpNode:
+        """
+        Parse q:dump statement.
+
+        Args:
+            element: XML element for q:dump
+
+        Returns:
+            DumpNode AST node
+        """
+        var = self.get_attr(element, 'var', '')
+        label = self.get_attr(element, 'label', var)
+        format_type = self.get_attr(element, 'format', 'text')
+        depth = self.get_int_attr(element, 'depth', 3)
+        when = self.get_attr(element, 'when')
+
+        dump_node = DumpNode(
+            var=var,
+            label=label,
+            format=format_type,
+            depth=depth,
+            when=when
+        )
+
+        return dump_node

quantum/core/parsers/services/file_parser.py

@@ -0,0 +1,48 @@
+"""
+File Parser - Parse q:file statements
+
+Handles file upload and deletion.
+"""
+
+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 FileNode
+
+
+class FileParser(BaseTagParser):
+    """
+    Parser for q:file statements.
+
+    Supports:
+    - File upload with conflict handling
+    - File deletion
+    - Result storage
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['file']
+
+    def parse(self, element: ET.Element) -> FileNode:
+        """
+        Parse q:file statement.
+
+        Args:
+            element: XML element for q:file
+
+        Returns:
+            FileNode AST node
+        """
+        action = self.get_attr(element, 'action', 'upload')
+        file_attr = self.get_attr(element, 'file')
+
+        if not file_attr:
+            raise ParserError("File requires 'file' attribute")
+
+        file_node = FileNode(action, file_attr)
+        file_node.destination = self.get_attr(element, 'destination')
+        file_node.name_conflict = self.get_attr(element, 'nameConflict', 'makeUnique')
+        file_node.result = self.get_attr(element, 'result')
+
+        return file_node

quantum/core/parsers/services/log_parser.py

@@ -0,0 +1,46 @@
+"""
+Log Parser - Parse q:log statements
+
+Handles structured logging.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.features.logging.src import LogNode
+
+
+class LogParser(BaseTagParser):
+    """
+    Parser for q:log statements.
+
+    Supports:
+    - Log levels (debug, info, warn, error)
+    - Conditional logging
+    - Context data
+    - Correlation IDs
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['log']
+
+    def parse(self, element: ET.Element) -> LogNode:
+        """
+        Parse q:log statement.
+
+        Args:
+            element: XML element for q:log
+
+        Returns:
+            LogNode AST node
+        """
+        level = self.get_attr(element, 'level', 'info')
+        message = self.get_attr(element, 'message') or self.get_text(element)
+
+        log_node = LogNode(level=level, message=message)
+        log_node.when = self.get_attr(element, 'when')
+        log_node.context = self.get_attr(element, 'context')
+        log_node.correlation_id = self.get_attr(element, 'correlationId')
+
+        return log_node

quantum/core/parsers/services/mail_parser.py

@@ -0,0 +1,65 @@
+"""
+Mail Parser - Parse q:mail statements
+
+Handles email sending.
+"""
+
+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 MailNode
+
+
+class MailParser(BaseTagParser):
+    """
+    Parser for q:mail statements.
+
+    Supports:
+    - HTML and plain text emails
+    - CC, BCC, Reply-To
+    - Attachments
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['mail']
+
+    def parse(self, element: ET.Element) -> MailNode:
+        """
+        Parse q:mail statement.
+
+        Args:
+            element: XML element for q:mail
+
+        Returns:
+            MailNode AST node
+        """
+        to = self.get_attr(element, 'to')
+        subject = self.get_attr(element, 'subject')
+
+        if not to:
+            raise ParserError("Mail requires 'to' attribute")
+        if not subject:
+            raise ParserError("Mail requires 'subject' attribute")
+
+        mail_node = MailNode(to, subject)
+
+        # Get body from content or attribute
+        mail_node.body = self.get_text(element) or self.get_attr(element, 'body', '')
+
+        # Optional attributes
+        mail_node.from_addr = self.get_attr(element, 'from')
+        mail_node.cc = self.get_attr(element, 'cc')
+        mail_node.bcc = self.get_attr(element, 'bcc')
+        mail_node.reply_to = self.get_attr(element, 'replyTo')
+        mail_node.type = self.get_attr(element, 'type', 'html')
+
+        # Parse attachments
+        for child in element:
+            child_type = self.get_element_name(child)
+            if child_type == 'attachment':
+                attachment = self.get_attr(child, 'file')
+                if attachment:
+                    mail_node.attachments.append(attachment)
+
+        return mail_node

quantum/core/tiers.py

@@ -0,0 +1,164 @@
+"""
+Support tiers for Quantum tags.
+
+PRODUCTION_READINESS.md Fase 0. "Production-ready" is meaningful only relative
+to a defined surface, so the surface is defined here, in code, and a tag
+outside the supported set announces itself the first time it is used instead
+of pretending to be first-class.
+
+The lists mirror SUPPORT_TIERS.md. When they disagree, this file is the one the
+engine actually enforces, so keep it in step.
+"""
+
+import logging
+
+logger = logging.getLogger("quantum.tiers")
+
+# Documented, tested end-to-end, stable. A break here is a critical bug.
+CORE = frozenset({
+    "component", "param", "return", "set", "if", "loop", "function",
+    "query", "action", "redirect", "flash", "invoke", "data",
+    "import", "slot",
+})
+
+# The reason the project exists. Same contract as Core is the goal; some of it
+# is still being validated end-to-end (PRODUCTION_READINESS.md Fase 4).
+DIFERENCIAL = frozenset({"llm", "knowledge", "agent", "team"})
+
+# Kept and registered, but no stability promise and not in the README. Using
+# one is fine for experiments; relying on one in production is not supported.
+EXPERIMENTAL = frozenset({
+    "job", "schedule", "thread",
+    "message", "queue", "subscribe", "messageAck", "messageNack",
+    "websocket", "websocket-send", "websocket-close",
+    "mail", "file", "log", "dump",
+    "python", "pyclass", "pyimport", "class", "decorator", "pydecorator",
+    "dispatchEvent", "transaction",
+})
+
+SUPPORTED = CORE | DIFERENCIAL
+
+# Authentication is Core too (decision D4, 2026-09-10), but it is not a tag:
+# it is the require_auth / require_role attributes of q:component plus the
+# session scope. Listed here so the surface is complete in one place.
+CORE_ATTRIBUTES = frozenset({"require_auth", "require_role"})
+
+# Application types, by tier. A q:application's type decides which engine
+# runs it, so the tier of the type is the tier of the whole app.
+#
+# LABORATORIO (decision D1/D2): the 2D game engine (qg:, including the Godot
+# codegen) stays in the repository on purpose — games press on the language
+# and surface features and bugs the core needs — but it carries no stability
+# promise and is not part of the pitch. Its tests run in the main suite, so a
+# core change that breaks a game shows up in CI.
+LAB_APP_TYPES = frozenset({"game"})
+EXPERIMENTAL_APP_TYPES = frozenset({"terminal", "ui", "testing"})
+
+# Removed in 0.11 (APP-1), because they never worked: `quantum run` on a
+# type="html" application failed at once (gap G17), and the type="api" server —
+# also behind "microservices" — never executed a route's body, serving the
+# literal text of the first q:return (gap G18). A web app is pages in
+# components/ served by `quantum start`. "html" was also the default when
+# type= was left out.
+REMOVED_APP_TYPES = frozenset({"html", "api", "microservices"})
+
+
+def removed_app_type_message(app_type: str, declared: bool) -> str:
+    what = f'type="{app_type}"' if declared else 'with no type= (it meant type="html")'
+    return (
+        f"<q:application> {what} was removed in Quantum 0.11: it never ran its "
+        f"routes. Build a web app as pages in components/ (components/index.q is "
+        f"/) and run `quantum start`. See "
+        f"https://danielgregorio.github.io/quantum/guide/getting-started")
+
+
+def tier_of(tag_name: str) -> str:
+    """'core' | 'diferencial' | 'experimental' | 'unknown'."""
+    if tag_name in CORE:
+        return "core"
+    if tag_name in DIFERENCIAL:
+        return "diferencial"
+    if tag_name in EXPERIMENTAL:
+        return "experimental"
+    return "unknown"
+
+
+# Warn once per tag per process — a q:loop over 1,000 rows must not emit 1,000
+# lines, the same discipline as expression_diagnostics.
+_warned: set = set()
+
+
+def warn_if_unsupported(tag_name: str) -> None:
+    """Emit a one-time warning when an experimental tag is used.
+
+    Not an error: experimental tags still run. The point is that an operator
+    reading the log sees, once, that their app leans on something the project
+    does not promise to keep working — the audit found apps built entirely on
+    tags that parse and then explode, with nothing warning anyone.
+    """
+    tier = tier_of(tag_name)
+    if tier in ("core", "diferencial", "unknown"):
+        # 'unknown' is handled by the parser's own error path, not here.
+        return
+    if tag_name in _warned:
+        return
+    _warned.add(tag_name)
+    logger.warning(
+        "q:%s is EXPERIMENTAL — not covered by the production support surface "
+        "(SUPPORT_TIERS.md). It may change or break without notice; do not rely "
+        "on it in production.", tag_name
+    )
+
+
+def app_tier_of(app_type: str) -> str:
+    """'laboratorio' | 'experimental' | 'supported' for a q:application type."""
+    if app_type in LAB_APP_TYPES:
+        return "laboratorio"
+    if app_type in EXPERIMENTAL_APP_TYPES:
+        return "experimental"
+    return "supported"
+
+
+def warn_app_type(app_type: str) -> None:
+    """One-time warning when an application of a non-supported type runs."""
+    tier = app_tier_of(app_type)
+    key = f"application:{app_type}"
+    if tier == "supported" or key in _warned:
+        return
+    _warned.add(key)
+    if tier == "laboratorio":
+        logger.warning(
+            "q:application type=%r is LABORATÓRIO — it exists to press on the "
+            "language, with no stability promise (SUPPORT_TIERS.md). It may "
+            "change or break without notice.", app_type
+        )
+    else:
+        logger.warning(
+            "q:application type=%r is EXPERIMENTAL — not covered by the "
+            "supported surface (SUPPORT_TIERS.md). It may change or break "
+            "without notice; do not rely on it in production.", app_type
+        )
+
+
+# UI-8: React Native translates the logic to JavaScript on its own — the
+# opposite of "one runtime, many renderers" — and phones are out of 1.0. It
+# stays to press on the language, like the games.
+LAB_UI_TARGETS = frozenset({"mobile", "react-native"})
+
+
+def warn_ui_target(target: str) -> None:
+    """One-time warning when a LABORATÓRIO UI target is built."""
+    key = f"ui-target:{target}"
+    if target not in LAB_UI_TARGETS or key in _warned:
+        return
+    _warned.add(key)
+    logger.warning(
+        "quantum run --target %s is LABORATÓRIO — it translates q:set and "
+        "q:function to JavaScript with no stability promise (SUPPORT_TIERS.md). "
+        "It may change or break without notice.", target
+    )
+
+
+def reset_warnings() -> None:
+    """For tests, and for a reloading server."""
+    _warned.clear()