quantum-framework 0.18.0__py3-none-any.whl

quantum/__init__.py

@@ -0,0 +1 @@
+# Quantum main package

quantum/cli/__init__.py

@@ -0,0 +1,2 @@
+# CLI Quantum modules
+from .runner import QuantumRunner, main

quantum/cli/admin.py

@@ -0,0 +1,131 @@
+"""`quantum admin` — serve the Quantum Admin (quantum_admin/components/admin).
+
+The admin is a Quantum app: .q screens over declared services. This command
+writes its configuration into a data folder and starts the same server as
+`quantum start`, so nothing has to be set up by hand.
+
+    quantum admin                      # data in ./.quantum-admin, projects under ./
+    quantum admin --data quantum_admin # the repository's own admin data
+
+The data folder holds the admin database, its settings (connectors, global
+settings, process PIDs) and the generated config. Paths of projects are
+relative to the folder the command runs in (--root to change it).
+"""
+
+import os
+import secrets
+from pathlib import Path
+
+MODULES = [
+    "quantum_admin.services.auth",
+    "quantum_admin.services.projects",
+    "quantum_admin.services.yaml_import",
+    "quantum_admin.services.connectors",
+    "quantum_admin.services.settings",
+    "quantum_admin.services.components",
+    "quantum_admin.services.apps",
+    "quantum_admin.services.repository",
+]
+
+INSTALL_HINT = 'pip install "quantum-framework[admin]"'
+
+
+def create_admin_parser(subparsers):
+    parser = subparsers.add_parser('admin', help='Start the Quantum Admin')
+    parser.add_argument('--port', type=int, default=8090, help='Port (default 8090)')
+    parser.add_argument('--data', default='.quantum-admin',
+                        help='Folder for the admin database and settings (default ./.quantum-admin)')
+    parser.add_argument('--root', default='.',
+                        help='Folder the project paths are relative to (default: current folder)')
+    return parser
+
+
+def missing_dependencies():
+    """Names of the [admin] extra's packages that do not import."""
+    faltando = []
+    for modulo, pacote in (("sqlalchemy", "SQLAlchemy"), ("jwt", "PyJWT"),
+                           ("cryptography", "cryptography")):
+        try:
+            __import__(modulo)
+        except ImportError:
+            faltando.append(pacote)
+    return faltando
+
+
+def _package() -> Path:
+    import quantum_admin
+    return Path(quantum_admin.__file__).resolve().parent
+
+
+def screens_folder() -> Path:
+    return _package() / "components"
+
+
+def assets_folder() -> Path:
+    """The screens' CSS and JS, served under /static/."""
+    return _package() / "assets"
+
+
+def _secret(arquivo: Path) -> str:
+    """A key kept in the data folder, so sessions survive a restart."""
+    if arquivo.exists():
+        return arquivo.read_text(encoding="utf-8").strip()
+    chave = secrets.token_hex(32)
+    arquivo.write_text(chave, encoding="utf-8")
+    try:
+        arquivo.chmod(0o600)
+    except OSError:
+        pass
+    return chave
+
+
+def prepare(data: str, root: str, port: int) -> Path:
+    """Create the data folder, point the admin at it, write the config. Returns its path."""
+    import yaml
+
+    pasta = Path(data).resolve()
+    (pasta / "settings").mkdir(parents=True, exist_ok=True)
+
+    # Read by quantum_admin.backend at import time, so set before any import.
+    os.environ["QUANTUM_ADMIN_DATABASE_URL"] = f"sqlite:///{(pasta / 'quantum_admin.db').as_posix()}"
+    os.environ["QUANTUM_ADMIN_SETTINGS_DIR"] = str(pasta / "settings")
+    os.environ["QUANTUM_ADMIN_ROOT"] = str(Path(root).resolve())
+    os.environ.setdefault("JWT_SECRET_KEY", _secret(pasta / "jwt_secret"))
+
+    config = pasta / "quantum.config.yaml"
+    config.write_text(
+        "# Generated by `quantum admin` on every start; edits are overwritten.\n" +
+        yaml.safe_dump({
+            "server": {"host": "127.0.0.1", "port": port, "reload": False, "debug": False},
+            "paths": {"components": screens_folder().as_posix(),
+                      "static": assets_folder().as_posix(),
+                      "uploads": (pasta / "uploads").as_posix(),
+                      "logs": (pasta / "logs").as_posix()},
+            "security": {"login_url": "/admin/login", "secret_key": _secret(pasta / "session_secret")},
+            "logging": {"level": "WARNING", "console": True, "file": False},
+            "services": MODULES,
+        }, sort_keys=False),
+        encoding="utf-8")
+    return config
+
+
+def handle_admin(args) -> int:
+    faltando = missing_dependencies()
+    if faltando:
+        print(f"[ERROR] The admin needs {', '.join(faltando)}. Install with:\n  {INSTALL_HINT}")
+        return 1
+
+    config = prepare(args.data, args.root, args.port)
+
+    from quantum.runtime.web_server import QuantumWebServer
+    from quantum_admin.backend.auth_service import get_auth_service
+
+    # Created now, not at the first login, so a generated password is printed
+    # before the URL instead of in the middle of the request log.
+    get_auth_service()
+    print(f"\n  Quantum Admin: http://127.0.0.1:{args.port}/admin"
+          f"\n  data: {config.parent}\n")
+
+    server = QuantumWebServer(str(config))
+    server.PID_FILE = str(config.parent / "admin.pid")
+    return server.start() or 0

quantum/cli/check.py

@@ -0,0 +1,223 @@
+"""`quantum check`: every page parses, every q:query compiles against the database,
+and every `{query.field}` a page reads is a column the query returns (M8, DEV-3).
+
+A typo in SQL or in a field name used to surface only when someone opened the
+page — `no such column` as a 500, or, for a field, an empty cell. This reads
+the project the way the server would and reports each problem with its file
+and line, without running anything: a query is compiled by the database
+(EXPLAIN) and a SELECT's columns come from running it with LIMIT 0.
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterator, List, Optional
+
+# Fields of `<name>_result` and of a query row that are not columns.
+_META = {'recordCount', 'columnList', 'executionTime', 'success', 'error', 'sql', 'page',
+         'totalPages', 'hasMore', 'cached', 'affectedRows', 'lastInsertId', 'data', 'length'}
+_EXPR = re.compile(r'\{([^{}]*)\}')
+
+
+@dataclass
+class Problem:
+    file: str
+    line: Optional[int]
+    message: str
+
+    def __str__(self) -> str:
+        return f'{self.file}:{self.line or "?"}: {self.message}'
+
+
+def _config(config_path: Path) -> dict:
+    import yaml
+    from quantum.core.config_env import expand_env
+    if not config_path.exists():
+        return {}
+    return expand_env(yaml.safe_load(config_path.read_text(encoding='utf-8')) or {})
+
+
+def _children(node) -> Iterator:
+    """The nodes inside a node, whatever the field is called."""
+    for campo in ('statements', 'body', 'if_body', 'else_body', 'children'):
+        for filho in getattr(node, campo, None) or []:
+            if hasattr(filho, '__dict__'):
+                yield filho
+    for bloco in getattr(node, 'elseif_blocks', None) or []:
+        corpo = bloco.get('body') if isinstance(bloco, dict) else getattr(bloco, 'body', None)
+        for filho in corpo or []:
+            yield filho
+
+
+def _texts(node) -> List[str]:
+    """The strings of a node that may hold {expressions}."""
+    textos = []
+    for campo, valor in vars(node).items():
+        if campo.startswith('_') or campo in ('sql',):
+            continue
+        if isinstance(valor, str) and '{' in valor:
+            textos.append(valor)
+        elif isinstance(valor, dict):
+            textos += [v for v in valor.values() if isinstance(v, str) and '{' in v]
+    return textos
+
+
+class ProjectChecker:
+    def __init__(self, project: Path, config_path: Path):
+        self.project = project
+        self.config = _config(config_path)
+        self.datasources = self.config.get('datasources') or {}
+        self._conexoes: Dict[str, object] = {}
+        self.problems: List[Problem] = []
+        self.notes: List[str] = []
+        self.queries_checked = 0
+        self.files = 0
+
+    # -- the database ---------------------------------------------------------
+
+    def _connection(self, nome: str):
+        from quantum.runtime.db_schema import SchemaError, connect_readonly
+        if nome not in self._conexoes:
+            try:
+                self._conexoes[nome] = connect_readonly(self.datasources[nome], self.project)
+            except SchemaError as exc:
+                self._conexoes[nome] = None
+                self.notes.append(f'datasource {nome!r} not checked: {exc}')
+        return self._conexoes[nome]
+
+    # -- a file ---------------------------------------------------------------
+
+    def check_file(self, arquivo: Path) -> None:
+        from quantum.core.parser import QuantumParser
+        rel = arquivo.relative_to(self.project).as_posix() if arquivo.is_relative_to(self.project) else str(arquivo)
+        self.files += 1
+        try:
+            ast = QuantumParser(use_cache=False).parse_file(str(arquivo))
+        except Exception as exc:        # a parse error is a problem like any other
+            primeira = str(exc).split('\n')[0]
+            self.problems.append(Problem(rel, getattr(exc, 'line', None), primeira))
+            return
+        colunas: Dict[str, List[str]] = {}
+        self._queries(ast, rel, colunas)
+        self._fields(ast, rel, colunas, {nome: nome for nome in colunas}, None)
+
+    def _queries(self, node, rel: str, colunas: Dict[str, List[str]]) -> None:
+        from quantum.core.ast_nodes import ActionNode, QueryNode
+        from quantum.runtime.db_schema import check_sql, read_schema
+        for filho in _children(node):
+            if isinstance(filho, ActionNode) and getattr(filho, 'table', None):
+                # UI-10: the table the action takes its params from exists, with those columns.
+                ds = filho.table_datasource
+                if ds not in self.datasources:
+                    self.problems.append(Problem(rel, getattr(filho, 'source_line', None),
+                                                 f'<q:action name="{filho.name}">: datasource {ds!r} is not '
+                                                 f'declared in quantum.config.yaml'))
+                elif self._connection(ds) is not None:
+                    esquema = read_schema(self._connection(ds))
+                    tabela = esquema.get(filho.table)
+                    if tabela is None:
+                        self.problems.append(Problem(rel, getattr(filho, 'source_line', None),
+                                                     f'<q:action name="{filho.name}" table="{filho.table}">: '
+                                                     f'no such table (tables: {", ".join(esquema) or "none"})'))
+                    else:
+                        for coluna in filho.table_columns or []:
+                            if coluna not in tabela.columns:
+                                self.problems.append(Problem(
+                                    rel, getattr(filho, 'source_line', None),
+                                    f'<q:action name="{filho.name}" columns=...>: table "{filho.table}" '
+                                    f'has no column "{coluna}"'))
+            if isinstance(filho, QueryNode):
+                ds = filho.datasource
+                if not ds or ds.startswith('knowledge:') or getattr(filho, 'source', None):
+                    pass                                 # RAG or query of queries: not SQL on a database
+                elif ds not in self.datasources:
+                    self.problems.append(Problem(rel, getattr(filho, 'source_line', None),
+                                                 f'<q:query name="{filho.name}">: datasource {ds!r} is not '
+                                                 f'declared in quantum.config.yaml'))
+                else:
+                    conexao = self._connection(ds)
+                    if conexao is not None:
+                        self.queries_checked += 1
+                        erro, cols = check_sql(conexao, filho.sql or '')
+                        if erro:
+                            self.problems.append(Problem(rel, getattr(filho, 'source_line', None),
+                                                         f'<q:query name="{filho.name}">: {erro}'))
+                        elif cols is not None:
+                            colunas[filho.name] = cols
+            self._queries(filho, rel, colunas)
+
+    def _fields(self, node, rel: str, colunas: Dict[str, List[str]], ligados: Dict[str, str],
+                linha: Optional[int]) -> None:
+        """Each `{var.field}` where var is a query, or a row of one, names a column it returns."""
+        from quantum.core.features.loops.src.ast_node import LoopNode
+        from quantum.core.features.ui_engine.src.ast_nodes import UIColumnNode, UIListNode, UITableNode
+        linha = getattr(node, 'source_line', None) or linha
+        for texto in _texts(node):
+            for expressao in _EXPR.findall(texto):
+                for var, campo in re.findall(r'(?<![\w.])(\w+)\.(\w+)', expressao):
+                    self._field(rel, linha, colunas, ligados, var, campo)
+        if isinstance(node, UIColumnNode) and node.key and '$tabela' in ligados:
+            self._field(rel, linha, colunas, ligados, '$tabela', node.key, f'<ui:column key="{node.key}">')
+
+        for filho in _children(node):
+            dentro = dict(ligados)
+            origem = None
+            if isinstance(filho, LoopNode):
+                origem = filho.query_name if filho.loop_type == 'query' else _single_name(filho.items)
+                if origem in colunas:
+                    dentro[filho.var_name] = origem
+            elif isinstance(filho, (UITableNode, UIListNode)):
+                origem = _single_name(filho.source)
+                if origem in colunas:
+                    dentro[filho.as_var or ('row' if isinstance(filho, UITableNode) else 'item')] = origem
+                    if isinstance(filho, UITableNode):
+                        dentro['$tabela'] = origem
+            self._fields(filho, rel, colunas, dentro, linha)
+
+    def _field(self, rel, linha, colunas, ligados, var, campo, como=None) -> None:
+        consulta = ligados.get(var)
+        if consulta is None or campo in _META:
+            return
+        cols = colunas.get(consulta, [])
+        if campo not in cols:
+            quem = como or f'{{{var}.{campo}}}'
+            self.problems.append(Problem(
+                rel, linha, f'{quem}: query "{consulta}" returns no column "{campo}" '
+                            f'(columns: {", ".join(cols) or "none"})'))
+
+    # -- the project ----------------------------------------------------------
+
+    def run(self) -> List[Problem]:
+        pasta = self.project / (self.config.get('paths', {}) or {}).get('components', 'components')
+        if not pasta.exists():
+            self.notes.append(f'no components folder at {pasta}')
+            return self.problems
+        for arquivo in sorted(pasta.rglob('*.q')):
+            self.check_file(arquivo)
+        for conexao in self._conexoes.values():
+            if conexao is not None:
+                conexao.close()
+        return self.problems
+
+
+def _single_name(expr: Optional[str]) -> Optional[str]:
+    """`{tarefas}` -> 'tarefas'; anything more complex -> None."""
+    m = re.fullmatch(r'\s*\{\s*(\w+)\s*\}\s*', expr or '')
+    return m.group(1) if m else None
+
+
+def run_check(config_path: str = 'quantum.config.yaml') -> int:
+    """`quantum check`: print each problem as file:line: message; exit 1 if there is any."""
+    caminho = Path(config_path).resolve()
+    checker = ProjectChecker(caminho.parent, caminho)
+    problemas = checker.run()
+    for nota in checker.notes:
+        print(f'[NOTE] {nota}')
+    for problema in problemas:
+        print(problema)
+    resumo = (f'{checker.files} file(s), {checker.queries_checked} query(ies) checked against the database')
+    if problemas:
+        print(f'\n{len(problemas)} problem(s) — {resumo}.')
+        return 1
+    print(f'OK — {resumo}.')
+    return 0

quantum/cli/commands/__init__.py

@@ -0,0 +1,15 @@
+"""
+Quantum CLI Commands
+
+Each command module provides a click command group or command.
+"""
+
+from quantum.cli.commands.new import new
+from quantum.cli.commands.dev import dev
+from quantum.cli.commands.build import build
+from quantum.cli.commands.serve import serve
+from quantum.cli.commands.test import test
+from quantum.cli.commands.lint import lint
+from quantum.cli.commands.docs import docs
+
+__all__ = ['new', 'dev', 'build', 'serve', 'test', 'lint', 'docs']