quantum-framework 0.9.0__py3-none-any.whl

quantum/core/parsers/persistence/__init__.py

@@ -0,0 +1,9 @@
+"""
+Persistence Parsers
+
+Parsers for persistence-related tags: persist
+"""
+
+from .persist_parser import PersistParser
+
+__all__ = ['PersistParser']

quantum/core/parsers/persistence/persist_parser.py

@@ -0,0 +1,64 @@
+"""
+Persist Parser - Parse q:persist 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 PersistNode
+
+
+class PersistParser(BaseTagParser):
+    """
+    Parser for q:persist statements for explicit persistence configuration.
+
+    Examples:
+        <q:persist scope="local" prefix="myapp_">
+            <q:var name="theme" />
+            <q:var name="locale" />
+        </q:persist>
+
+        <q:persist scope="sync" key="user_prefs" encrypt="true">
+            <q:var name="darkMode" />
+            <q:var name="fontSize" />
+        </q:persist>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['persist']
+
+    def parse(self, element: ET.Element) -> PersistNode:
+        """Parse q:persist element"""
+        scope = element.get('scope', 'local')
+        prefix = element.get('prefix')
+        key = element.get('key')
+        encrypt = element.get('encrypt', 'false').lower() == 'true'
+        storage = element.get('storage')
+
+        ttl = None
+        ttl_attr = element.get('ttl')
+        if ttl_attr:
+            try:
+                ttl = int(ttl_attr)
+            except ValueError:
+                pass
+
+        persist_node = PersistNode(
+            scope=scope,
+            prefix=prefix,
+            key=key,
+            encrypt=encrypt,
+            ttl=ttl,
+            storage=storage
+        )
+
+        # Parse q:var children
+        for child in element:
+            child_type = self._get_element_name(child)
+            if child_type == 'var':
+                var_name = child.get('name')
+                if var_name:
+                    persist_node.add_variable(var_name)
+
+        return persist_node

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,82 @@
+"""
+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", "persist",
+    "python", "pyclass", "pyimport", "class", "decorator", "pydecorator",
+    "dispatchEvent", "transaction",
+})
+
+SUPPORTED = CORE | DIFERENCIAL
+
+
+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 reset_warnings() -> None:
+    """For tests, and for a reloading server."""
+    _warned.clear()