quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/executors/scripting/python_executor.py

@@ -0,0 +1,249 @@
+"""
+Python Executor - Execute q:python statements
+
+Handles embedded Python code execution.
+"""
+
+import logging
+import textwrap
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import PythonNode
+
+logger = logging.getLogger(__name__)
+
+
+def normalise_python_source(raw: str) -> str:
+    """Make XML-indented Python compile.
+
+    The code inside <q:python> is indented to match the surrounding markup,
+    which is what anyone writing XML does:
+
+        <q:python>
+          total = 0
+          for i in range(5):
+              total += i
+        </q:python>
+
+    This was passed through `.strip()`, which removes the leading whitespace
+    of the string — so the FIRST line lost its indentation and every other
+    line kept it. Python then said "unexpected indent (<string>, line 2)".
+    Every multi-line q:python block in the documentation fails that way.
+
+    Strategy: try the candidate forms in order and take the first that
+    compiles. The current behaviour is tried first, so nothing that worked
+    before changes; dedent covers the ordinary case; and dedenting the tail
+    separately covers code that starts on the tag's own line.
+    """
+    text = (raw or "").replace("\r\n", "\n").replace("\r", "\n")
+    if not text.strip():
+        return ""
+
+    candidates = [text.strip(), textwrap.dedent(text).strip("\n")]
+
+    lines = text.split("\n")
+    if lines and lines[0].strip() and len(lines) > 1:
+        tail = textwrap.dedent("\n".join(lines[1:]))
+        candidates.append((lines[0].strip() + "\n" + tail).strip("\n"))
+
+    for candidate in candidates:
+        try:
+            compile(candidate, "<q:python>", "exec")
+            return candidate
+        except SyntaxError:
+            continue
+
+    # None compile: the code is genuinely broken. Hand back the dedented
+    # form, so the error the user sees points at their code rather than at
+    # indentation this function should have handled.
+    return candidates[1]
+
+
+class PythonExecutor(BaseExecutor):
+    """
+    Executor for q:python statements.
+
+    Supports:
+    - Inline Python code execution
+    - Component, isolated, and module scopes
+    - Async execution
+    - Timeout limits
+    - Bridge object for context access
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [PythonNode]
+
+    def execute(self, node: PythonNode, exec_context) -> Any:
+        """
+        Execute Python code block.
+
+        Args:
+            node: PythonNode with Python code
+            exec_context: Execution context
+
+        Returns:
+            Execution result (if result attribute set)
+        """
+        try:
+            self.require_python_scripting('q:python')
+
+            context = exec_context.get_all_variables()
+
+            # Build bridge object for q.variable access
+            bridge = QuantumBridge(exec_context, context)
+
+            # Build execution namespace
+            namespace = {
+                'q': bridge,
+                '__quantum_context__': context
+            }
+
+            # Add component scope variables if not isolated
+            if node.scope == 'component':
+                namespace.update(context)
+
+            # Execute code (dedented — see normalise_python_source)
+            code = normalise_python_source(node.code)
+
+            if node.async_mode:
+                result = self._execute_async(code, namespace, node.timeout)
+            else:
+                result = self._execute_sync(code, namespace, node.timeout)
+
+            # Store result if requested
+            if node.result:
+                exec_context.set_variable(node.result, result, scope="component")
+
+            # Export bridge changes to context
+            for key, value in bridge._exports.items():
+                exec_context.set_variable(key, value, scope="component")
+
+            return result
+
+        except Exception as e:
+            raise ExecutorError(f"Python execution error: {e}")
+
+    def _execute_sync(self, code: str, namespace: Dict, timeout: str = None) -> Any:
+        """Execute Python code synchronously."""
+        # Handle return statements
+        if 'return ' in code:
+            # Wrap in function
+            wrapped = f"def __quantum_exec__():\n"
+            for line in code.split('\n'):
+                wrapped += f"    {line}\n"
+            wrapped += "__quantum_result__ = __quantum_exec__()"
+            exec(wrapped, namespace)
+            return namespace.get('__quantum_result__')
+        else:
+            exec(code, namespace)
+            return None
+
+    def _execute_async(self, code: str, namespace: Dict, timeout: str = None) -> Any:
+        """Execute Python code asynchronously."""
+        import asyncio
+
+        async def run_async():
+            # Wrap in async function
+            wrapped = f"async def __quantum_async__():\n"
+            for line in code.split('\n'):
+                wrapped += f"    {line}\n"
+            exec(wrapped, namespace)
+            return await namespace['__quantum_async__']()
+
+        # Parse timeout
+        timeout_seconds = None
+        if timeout:
+            timeout_seconds = self._parse_timeout(timeout)
+
+        return asyncio.run(asyncio.wait_for(run_async(), timeout=timeout_seconds))
+
+    def _parse_timeout(self, timeout: str) -> float:
+        """Parse timeout string to seconds."""
+        if timeout.endswith('s'):
+            return float(timeout[:-1])
+        elif timeout.endswith('m'):
+            return float(timeout[:-1]) * 60
+        elif timeout.endswith('h'):
+            return float(timeout[:-1]) * 3600
+        return float(timeout)
+
+
+class QuantumBridge:
+    """Bridge object for accessing Quantum context from Python."""
+
+    def __init__(self, exec_context, context: Dict[str, Any]):
+        self._exec_context = exec_context
+        self._context = context
+        self._exports = {}
+        self._missing_reported = set()
+
+    def __getattr__(self, name: str) -> Any:
+        """Get variable from context.
+
+        A name that is not in the context returns None, as before — scripts
+        do test optional variables. But it now says so once: `q.info(...)`
+        in the shipped example resolved to None and then raised
+        "'NoneType' object is not callable" four frames away, with nothing
+        naming `info`. (q.info exists now; the diagnosis should still work
+        for the next typo.)
+        """
+        if name.startswith('_'):
+            return object.__getattribute__(self, name)
+        if name not in self._context:
+            if name not in self._missing_reported:
+                self._missing_reported.add(name)
+                logger.warning(
+                    "q:python read q.%s, which is not defined in the "
+                    "component — it is None. Calling it raises "
+                    "\"'NoneType' object is not callable\".", name
+                )
+        return self._context.get(name)
+
+    # -- logging from a script --------------------------------------------
+    #
+    # The documented example calls q.info(...). There was no such method, so
+    # it resolved to None through __getattr__ above and the whole block died
+    # on the call. These are what that example always meant.
+
+    def log(self, *parts: Any) -> None:
+        """Log at info level."""
+        logger.info("q:python: %s", " ".join(str(p) for p in parts))
+
+    def info(self, *parts: Any) -> None:
+        self.log(*parts)
+
+    def debug(self, *parts: Any) -> None:
+        logger.debug("q:python: %s", " ".join(str(p) for p in parts))
+
+    def warn(self, *parts: Any) -> None:
+        logger.warning("q:python: %s", " ".join(str(p) for p in parts))
+
+    warning = warn
+
+    def error(self, *parts: Any) -> None:
+        logger.error("q:python: %s", " ".join(str(p) for p in parts))
+
+    def __setattr__(self, name: str, value: Any):
+        """Set variable in context."""
+        if name.startswith('_'):
+            object.__setattr__(self, name, value)
+        else:
+            self._exports[name] = value
+
+    def export(self, name: str, value: Any):
+        """Explicitly export a variable."""
+        self._exports[name] = value
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """Get variable with default."""
+        return self._context.get(name, default)
+
+    def set(self, name: str, value: Any):
+        """Set variable."""
+        self._exports[name] = value
+
+    def has(self, name: str) -> bool:
+        """Check if variable exists."""
+        return name in self._context

quantum/runtime/executors/services/__init__.py

@@ -0,0 +1,12 @@
+"""
+Service Executors
+
+Executors for service operations: log, dump, file, mail.
+"""
+
+from .log_executor import LogExecutor
+from .dump_executor import DumpExecutor
+from .file_executor import FileExecutor
+from .mail_executor import MailExecutor
+
+__all__ = ['LogExecutor', 'DumpExecutor', 'FileExecutor', 'MailExecutor']

quantum/runtime/executors/services/dump_executor.py

@@ -0,0 +1,72 @@
+"""
+Dump Executor - Execute q:dump statements
+
+Handles variable inspection and debugging output.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.features.dump.src import DumpNode
+
+
+class DumpExecutor(BaseExecutor):
+    """
+    Executor for q:dump statements.
+
+    Supports:
+    - Variable inspection with depth control
+    - Multiple output formats (text, json, html)
+    - Conditional dumping
+    - Labeled output
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [DumpNode]
+
+    def execute(self, node: DumpNode, exec_context) -> Any:
+        """
+        Execute variable dump/inspection.
+
+        Args:
+            node: DumpNode with dump configuration
+            exec_context: Execution context
+
+        Returns:
+            Formatted dump output string
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Check conditional execution
+            if node.when:
+                condition_result = self.apply_databinding(node.when, context)
+                if not self.services.dump.should_dump(condition_result):
+                    return
+
+            # Resolve variable to dump
+            var_expr = node.var
+            try:
+                var_value = self.apply_databinding(var_expr, context)
+            except Exception as e:
+                var_value = f"<Variable '{var_expr}' not found: {e}>"
+
+            # Generate dump output
+            dump_output = self.services.dump.dump(
+                var=var_value,
+                label=node.label,
+                format=node.format,
+                depth=node.depth
+            )
+
+            # Print dump output
+            print(dump_output)
+
+            # Store in context for potential template rendering
+            dump_var_name = f"_dump_{node.label.replace(' ', '_')}"
+            exec_context.set_variable(dump_var_name, dump_output, scope="component")
+
+            return dump_output
+
+        except Exception as e:
+            raise ExecutorError(f"Dump error: {e}")

quantum/runtime/executors/services/file_executor.py

@@ -0,0 +1,89 @@
+"""
+File Executor - Execute q:file statements
+
+Handles file upload and delete operations.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import FileNode
+
+
+class FileExecutor(BaseExecutor):
+    """
+    Executor for q:file statements.
+
+    Supports:
+    - File upload with conflict handling
+    - File deletion
+    - Result storage in context
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [FileNode]
+
+    def execute(self, node: FileNode, exec_context) -> Any:
+        """
+        Execute file operation.
+
+        Args:
+            node: FileNode with file operation configuration
+            exec_context: Execution context
+
+        Returns:
+            File operation result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            if node.action == 'upload':
+                return self._execute_upload(node, context, exec_context)
+            elif node.action == 'delete':
+                return self._execute_delete(node, context, exec_context)
+            else:
+                raise ExecutorError(f"Unsupported file action: {node.action}")
+
+        except Exception as e:
+            raise ExecutorError(f"File execution error: {e}")
+
+    def _execute_upload(self, node: FileNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Execute file upload"""
+        # Resolve file variable
+        file_var = node.file.strip('{}')
+        file_obj = context.get(file_var)
+
+        if not file_obj:
+            raise ExecutorError(f"File variable '{file_var}' not found")
+
+        # Resolve destination
+        destination = self.apply_databinding(node.destination, context)
+
+        # Upload file
+        result = self.services.file_upload.upload_file(
+            file=file_obj,
+            destination=destination,
+            name_conflict=node.name_conflict
+        )
+
+        # Store results
+        if node.result:
+            exec_context.set_variable(node.result, result, scope="component")
+
+        exec_context.set_variable(f"{file_var}_upload", result, scope="component")
+
+        return result
+
+    def _execute_delete(self, node: FileNode, context: Dict[str, Any], exec_context) -> Dict:
+        """Execute file deletion"""
+        # Resolve filepath
+        filepath = self.apply_databinding(node.file, context)
+
+        # Delete file
+        result = self.services.file_upload.delete_file(filepath)
+
+        # Store result
+        if node.result:
+            exec_context.set_variable(node.result, result, scope="component")
+
+        return result

quantum/runtime/executors/services/log_executor.py

@@ -0,0 +1,77 @@
+"""
+Log Executor - Execute q:log statements
+
+Handles structured logging with levels and context.
+"""
+
+from typing import Any, List, Dict, Type
+import json
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.features.logging.src import LogNode
+
+
+class LogExecutor(BaseExecutor):
+    """
+    Executor for q:log statements.
+
+    Supports:
+    - Multiple log levels (debug, info, warn, error)
+    - Conditional logging (when attribute)
+    - Context data attachment
+    - Correlation IDs for tracing
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [LogNode]
+
+    def execute(self, node: LogNode, exec_context) -> Any:
+        """
+        Execute logging statement.
+
+        Args:
+            node: LogNode with logging configuration
+            exec_context: Execution context
+
+        Returns:
+            None (logging is side-effect only)
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Check conditional execution
+            if node.when:
+                condition_result = self.apply_databinding(node.when, context)
+                if not self.services.logging.should_log(condition_result):
+                    return
+
+            # Resolve message
+            message = self.apply_databinding(node.message, context)
+
+            # Resolve context data
+            context_data = None
+            if node.context:
+                context_expr = self.apply_databinding(node.context, context)
+                if isinstance(context_expr, dict):
+                    context_data = context_expr
+                elif isinstance(context_expr, str):
+                    try:
+                        context_data = json.loads(context_expr)
+                    except:
+                        context_data = {'value': context_expr}
+
+            # Resolve correlation_id
+            correlation_id = None
+            if node.correlation_id:
+                correlation_id = self.apply_databinding(node.correlation_id, context)
+
+            # Execute logging
+            self.services.logging.log(
+                level=node.level,
+                message=str(message),
+                context=context_data,
+                correlation_id=correlation_id
+            )
+
+        except Exception as e:
+            raise ExecutorError(f"Logging error: {e}")

quantum/runtime/executors/services/mail_executor.py

@@ -0,0 +1,81 @@
+"""
+Mail Executor - Execute q:mail statements
+
+Handles email sending with HTML/text support.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import MailNode
+
+
+class MailExecutor(BaseExecutor):
+    """
+    Executor for q:mail statements.
+
+    Supports:
+    - HTML and plain text emails
+    - CC, BCC, Reply-To
+    - Attachments
+    - Databinding in all fields
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [MailNode]
+
+    def execute(self, node: MailNode, exec_context) -> Any:
+        """
+        Execute email sending.
+
+        Args:
+            node: MailNode with email configuration
+            exec_context: Execution context
+
+        Returns:
+            Email send result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Resolve all email properties
+            to = self.apply_databinding(node.to, context)
+            subject = self.apply_databinding(node.subject, context)
+            body = self.apply_databinding(node.body, context)
+
+            from_addr = None
+            if node.from_addr:
+                from_addr = self.apply_databinding(node.from_addr, context)
+
+            cc = None
+            if node.cc:
+                cc = self.apply_databinding(node.cc, context)
+
+            bcc = None
+            if node.bcc:
+                bcc = self.apply_databinding(node.bcc, context)
+
+            reply_to = None
+            if node.reply_to:
+                reply_to = self.apply_databinding(node.reply_to, context)
+
+            # Send email
+            result = self.services.email.send_email(
+                to=to,
+                subject=subject,
+                body=body,
+                from_addr=from_addr,
+                cc=cc,
+                bcc=bcc,
+                reply_to=reply_to,
+                email_type=node.type,
+                attachments=node.attachments
+            )
+
+            # Store result
+            exec_context.set_variable('_mail_result', result, scope="component")
+
+            return result
+
+        except Exception as e:
+            raise ExecutorError(f"Mail execution error: {e}")