quai 0.3.0__tar.gz

quai-0.3.0/.gitignore

@@ -0,0 +1,4 @@
+.egg-info/
+dist/
+build/
+__pycache__/

quai-0.3.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: quai
+Version: 0.3.0
+Summary: Interactive Quarb — a session REPL where every line becomes a reusable query (&1, &2, …)
+Project-URL: Homepage, https://quarb.org/
+Project-URL: Playground, https://demo.quarb.org/quai/
+Project-URL: Cookbook, https://quarb.org/cookbooks/quai.html
+Project-URL: Repository, https://gitlab.com/quarb/engine
+Author: Bojan Đuričković
+License: MIT OR Apache-2.0
+Keywords: interactive,json,quarb,query,repl
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: quarb>=0.3
+Description-Content-Type: text/markdown
+
+# quai
+
+Interactive [Quarb][quarb] — a session REPL where every line becomes a
+reusable query.
+
+```bash
+pip install quai
+quai data.json
+```
+
+`quai` opens a session over one or more sources and holds it. Each
+line you run is labelled `&1`, `&2`, … — and every label is a
+reusable *macro*: not the printed value, but the *query* that produced
+it, ready to continue through the pipe. It is the notebook loop, cell
+by cell, except a cell is a path into your data.
+
+```
+&1  /teams/*/members/*
+    /teams/0/members/0  ⋮  (every member, across all teams, one path)
+&2  &1 | [/langs/*:: = 'Go'] | /name::
+    ada
+    eu
+&3  &1 @| count
+    6
+```
+
+- `&N` re-runs line N; continue with a pipe (`&N | /key::`,
+  `&N | [pred]`, `&N @| count`).
+- `&N#` replays line N's output frozen, as it was when it ran.
+- `def &x: … ;` adds a named fragment; `:history`, `:reset`, `:help`,
+  `:quit` are the commands.
+
+The engine rides in on the [`quarb`][quarb] dependency, so `quai`
+reaches every local source `quarb` does — JSON, YAML, TOML, CSV, XML,
+HTML, Markdown, SQLite, kaiv, the filesystem, git, archives, XLSX, and
+source code — and several at once mount under one root for
+cross-source `<=>` joins.
+
+Try it in the browser at [demo.quarb.org/quai][playground] (no
+install), and read the [graph cookbook][cookbook] for the recipes.
+
+[quarb]: https://quarb.org/
+[playground]: https://demo.quarb.org/quai/
+[cookbook]: https://quarb.org/cookbooks/quai.html
+
+## License
+
+Licensed under either of Apache License, Version 2.0 or the MIT license
+at your option.

quai-0.3.0/README.md

@@ -0,0 +1,49 @@
+# quai
+
+Interactive [Quarb][quarb] — a session REPL where every line becomes a
+reusable query.
+
+```bash
+pip install quai
+quai data.json
+```
+
+`quai` opens a session over one or more sources and holds it. Each
+line you run is labelled `&1`, `&2`, … — and every label is a
+reusable *macro*: not the printed value, but the *query* that produced
+it, ready to continue through the pipe. It is the notebook loop, cell
+by cell, except a cell is a path into your data.
+
+```
+&1  /teams/*/members/*
+    /teams/0/members/0  ⋮  (every member, across all teams, one path)
+&2  &1 | [/langs/*:: = 'Go'] | /name::
+    ada
+    eu
+&3  &1 @| count
+    6
+```
+
+- `&N` re-runs line N; continue with a pipe (`&N | /key::`,
+  `&N | [pred]`, `&N @| count`).
+- `&N#` replays line N's output frozen, as it was when it ran.
+- `def &x: … ;` adds a named fragment; `:history`, `:reset`, `:help`,
+  `:quit` are the commands.
+
+The engine rides in on the [`quarb`][quarb] dependency, so `quai`
+reaches every local source `quarb` does — JSON, YAML, TOML, CSV, XML,
+HTML, Markdown, SQLite, kaiv, the filesystem, git, archives, XLSX, and
+source code — and several at once mount under one root for
+cross-source `<=>` joins.
+
+Try it in the browser at [demo.quarb.org/quai][playground] (no
+install), and read the [graph cookbook][cookbook] for the recipes.
+
+[quarb]: https://quarb.org/
+[playground]: https://demo.quarb.org/quai/
+[cookbook]: https://quarb.org/cookbooks/quai.html
+
+## License
+
+Licensed under either of Apache License, Version 2.0 or the MIT license
+at your option.

quai-0.3.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quai"
+version = "0.3.0"
+description = "Interactive Quarb — a session REPL where every line becomes a reusable query (&1, &2, …)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT OR Apache-2.0" }
+authors = [{ name = "Bojan Đuričković" }]
+keywords = ["query", "repl", "interactive", "quarb", "json"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Utilities",
+    "Environment :: Console",
+]
+dependencies = ["quarb>=0.3"]
+
+[project.scripts]
+quai = "quai.cli:main"
+
+[project.urls]
+Homepage = "https://quarb.org/"
+Playground = "https://demo.quarb.org/quai/"
+Cookbook = "https://quarb.org/cookbooks/quai.html"
+Repository = "https://gitlab.com/quarb/engine"
+
+[tool.hatch.build.targets.wheel]
+packages = ["quai"]

quai-0.3.0/quai/__init__.py

@@ -0,0 +1,14 @@
+"""Interactive Quarb — the ``quai`` session REPL.
+
+A thin, pure-Python front end over the :mod:`quarb` engine: it opens a
+source, holds a session, and labels each accepted line ``&1``, ``&2``,
+… — every label a reusable macro (the *query*, not the printed value),
+ready to continue through the pipe. ``pip install quai`` gives you the
+``quai`` command; the engine itself rides in on the ``quarb``
+dependency.
+"""
+
+from .session import Session
+
+__version__ = "0.3.0"
+__all__ = ["Session"]

quai-0.3.0/quai/cli.py

@@ -0,0 +1,190 @@
+"""The ``quai`` command: an interactive Quarb REPL.
+
+Built on :func:`input`, with the :mod:`readline` module imported so
+backspace, arrow keys, and input-line history work out of the box. The
+color codes in the prompt are wrapped in readline's zero-width markers
+(``\\001``/``\\002``) so cursor math near the prompt stays correct.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+try:
+    import readline  # noqa: F401 — enables line editing for input()
+except ImportError:  # pragma: no cover — e.g. Windows without pyreadline
+    pass
+
+import quarb
+
+from .session import Session
+
+_CYAN = "\001\x1b[36m\002"
+_RESET = "\001\x1b[0m\002"
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        prog="quai",
+        description="Interactive Quarb — each line becomes a reusable "
+        "query (&1, &2, ...).",
+    )
+    ap.add_argument(
+        "paths",
+        nargs="*",
+        help="source(s): a document (.json/.yaml/.toml/.csv/.xml/.html/"
+        ".md), a SQLite/kaiv/xlsx file, a directory, or git:PATH. "
+        "Several mount as one root, so a single query — including a "
+        "<=> join — spans them all.",
+    )
+    args = ap.parse_args()
+    if not args.paths:
+        ap.error("quai needs at least one source (a document, a directory, or git:PATH)")
+
+    try:
+        doc = (
+            quarb.open(args.paths[0])
+            if len(args.paths) == 1
+            else quarb.mount(args.paths)
+        )
+    except Exception as e:  # noqa: BLE001 — surface the engine's message
+        sys.exit(f"quai: {e}")
+
+    session = Session(doc)
+    color = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+    print(
+        f"quai - interactive Quarb over {', '.join(args.paths)}.  "
+        ":help for commands, :quit (or Ctrl-D) to leave."
+    )
+    _repl(session, color)
+
+
+def _repl(session: Session, color: bool) -> None:
+    while True:
+        prompt = (
+            f"{_CYAN}&{session.line_no}{_RESET} " if color else f"&{session.line_no} "
+        )
+        try:
+            line = input(prompt)
+        except EOFError:
+            print()
+            break
+        except KeyboardInterrupt:
+            print()
+            continue
+        line = line.strip()
+        if not line:
+            continue
+
+        # A ':' command (a query cannot start with a lone ':').
+        if line.startswith(":") and not line.startswith("::"):
+            if _command(session, line):
+                break
+            continue
+
+        # A definition extends the macro table but is not itself run.
+        if (
+            line.startswith("def ")
+            or line == "def"
+            or line.startswith("macro ")
+            or line == "macro"
+        ):
+            try:
+                session.add_def(line)
+            except Exception as e:  # noqa: BLE001
+                print(f"error: {e}", file=sys.stderr)
+            continue
+
+        # Capture references (&N#, &N!) are resolved here, not by the
+        # engine (its lexer has no '#', and '!' marks data-aware macros).
+        try:
+            kind, arg = _prepare(line)
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr)
+            continue
+
+        if kind == "frozen":
+            snap = session.frozen(arg)
+            if snap is None:
+                print(
+                    f"error: &{arg}# has no captured result (line {arg} hasn't run)",
+                    file=sys.stderr,
+                )
+            else:
+                for v in snap:
+                    print(_render(v))
+                session.record_frozen(snap)
+            continue
+
+        try:
+            values = session.eval(arg)
+        except Exception as e:  # noqa: BLE001
+            print(f"error: {e}", file=sys.stderr)
+            continue
+        for v in values:
+            print(_render(v))
+        n = session.line_no
+        if not session.commit(arg, values):
+            print(
+                f"note: &{n} is not referenceable (its shape can't be a macro body)",
+                file=sys.stderr,
+            )
+
+
+def _prepare(line: str):
+    n = _numeric_ref(line, "#")
+    if n is not None:
+        return ("frozen", n)
+    n = _numeric_ref(line, "!")
+    if n is not None:
+        # Live re-run; for a fixed in-process document this equals &N.
+        return ("eval", f"&{n}")
+    if "#" in line:
+        raise ValueError(
+            "'#' is the frozen-history suffix, valid only as a standalone '&N#'"
+        )
+    return ("eval", line)
+
+
+def _numeric_ref(line: str, suffix: str):
+    if line.endswith(suffix) and line.startswith("&"):
+        body = line[1:-1]
+        if body.isdigit():
+            return int(body)
+    return None
+
+
+def _render(v) -> str:
+    if isinstance(v, dict):
+        return json.dumps(v, ensure_ascii=False)
+    return str(v)
+
+
+def _command(session: Session, line: str) -> bool:
+    if line in (":q", ":quit"):
+        return True
+    if line in (":help", ":?"):
+        print(
+            "  <query>       run a query; its result is labelled &N and reusable\n"
+            "  &N            re-run line N (a macro); continue with a pipe: &N | /key::\n"
+            "  &N#           replay line N's frozen output (as it was when it ran)\n"
+            "  def &x: ... ; add a named fragment to the session\n"
+            "  :history      show the macro table (&1, &2, ...)\n"
+            "  :reset        clear the history and restart numbering\n"
+            "  :quit         leave (also Ctrl-D)"
+        )
+    elif line == ":history":
+        h = session.history().strip()
+        print(h if h else "(no history yet)")
+    elif line == ":reset":
+        session.reset()
+    else:
+        print(f"unknown command '{line}' (:help lists them)")
+    return False
+
+
+if __name__ == "__main__":
+    main()

quai-0.3.0/quai/session.py

@@ -0,0 +1,89 @@
+"""The interactive session: a macro table where each accepted line
+becomes ``def &N: <line> ;``, evaluated through the :mod:`quarb`
+engine.
+
+History is the language's own reuse mechanism, not a bolted-on cell
+store: line 3 is the fragment ``&3``, continued through the pipe
+(``&3 | /name::``, ``&3 | [pred]``, ``&3 @| count``). A standalone
+``&N#`` replays a line's captured output (the frozen footprint); in
+this pure-Python front end the source is materialized once, so
+``&N``, ``&N!`` and ``&N#`` coincide for a fixed document.
+"""
+
+from __future__ import annotations
+
+import quarb
+
+
+class Session:
+    def __init__(self, doc: "quarb.Document"):
+        self.doc = doc
+        # The macro table as definition text, prepended to each query
+        # so ``&N`` history resolves inline.
+        self.defs_text = ""
+        # Each line's output, captured at commit — what ``&N#`` replays.
+        self.snapshots: dict[int, list] = {}
+        # The next line's number — the ``&N`` a fresh line will claim.
+        self.line_no = 1
+
+    def _combined(self, line: str) -> str:
+        if not self.defs_text:
+            return line
+        return f"{self.defs_text}\n{line}"
+
+    def eval(self, line: str) -> list:
+        """Run a line against the source with the current macro table
+        prepended. Node results come back as locator strings, value
+        results as typed Python values (dicts for records)."""
+        return self.doc.values(self._combined(line))
+
+    def commit(self, line: str, snapshot: list) -> bool:
+        """Register an accepted line as ``&N`` and capture its output as
+        the frozen footprint for ``&N#``. Returns whether the line's
+        shape can be a macro body (so ``&N`` will resolve); either way
+        the line number advances so labels track what the user saw."""
+        self.snapshots[self.line_no] = list(snapshot)
+        # A space before the ``;`` terminator: a line ending in a ``::``
+        # projection would otherwise lex ``::;`` as the metadata sigil.
+        candidate = f"{self.defs_text}def &{self.line_no}: {line} ;\n"
+        referenceable = self._defs_ok(candidate)
+        if referenceable:
+            self.defs_text = candidate
+        self.line_no += 1
+        return referenceable
+
+    def _defs_ok(self, candidate: str) -> bool:
+        # Validate by running the candidate table plus a reference to
+        # the new line; a parse error means it cannot be a macro body.
+        try:
+            self.doc.values(f"{candidate}&{self.line_no}")
+            return True
+        except Exception:
+            return False
+
+    def frozen(self, n: int):
+        """The frozen output of line ``n``, if captured."""
+        return self.snapshots.get(n)
+
+    def record_frozen(self, snapshot: list) -> None:
+        """Record a frozen-recall line: it takes the next number and
+        keeps its own snapshot, but is not a referenceable macro body."""
+        self.snapshots[self.line_no] = list(snapshot)
+        self.line_no += 1
+
+    def add_def(self, line: str) -> None:
+        """Add a ``def``/``macro`` line to the table (validated first)."""
+        candidate = f"{self.defs_text}{line}\n"
+        # Parse the whole table by running it with a trivial trailing
+        # query (``/`` — the root — always parses); a malformed
+        # definition raises here, before it can poison later lines.
+        self.doc.values(f"{candidate}/")
+        self.defs_text = candidate
+
+    def history(self) -> str:
+        return self.defs_text
+
+    def reset(self) -> None:
+        self.defs_text = ""
+        self.snapshots = {}
+        self.line_no = 1