databay-cli 0.1.0__py3-none-any.whl

databay/cli/common.py

@@ -0,0 +1,93 @@
+"""What every hand-written command shares with the generated ones: the common flags and the console."""
+
+from __future__ import annotations
+
+import sys
+from contextlib import contextmanager
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+from databay.cli.build import click_parameter
+from databay.cli.flags import common_flags
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+    import click
+    import httpx
+
+    from databay.cli.console import Console
+    from databay.invoke import CallValues, Result
+    from databay.operation import Operation
+
+
+def common_options(command: Callable[..., Any], *, profile_help: str | None = None) -> Callable[..., Any]:
+    """
+    Add ``--output``, ``--profile``, ``--verbose`` and ``--no-retry``, built as the generated commands build them.
+
+    ``profile_help`` replaces the help of ``--profile`` for a command that writes the profile (``login``).
+    """
+    flags = [replace(f, help=profile_help) if profile_help and f.role == "profile" else f for f in common_flags()]
+    params = getattr(command, "__click_params__", [])
+    params.extend(click_parameter(flag) for flag in reversed(flags))
+    command.__click_params__ = params  # type: ignore[attr-defined]
+    return command
+
+
+def login_options(command: Callable[..., Any]) -> Callable[..., Any]:
+    from databay.settings import DEFAULT_PROFILE  # noqa: PLC0415
+
+    return common_options(command, profile_help=f"the profile to create or update (default: {DEFAULT_PROFILE})")
+
+
+def console_for(ctx: click.Context, values: dict[str, Any]) -> tuple[Console, dict[str, Any]]:
+    """The command's console, registered in the CLI state so a failure is printed through it."""
+    from databay.cli.console import Console, output_format  # noqa: PLC0415
+
+    state: dict[str, Any] = ctx.ensure_object(dict)
+    console = Console(output=output_format(values.get("output"), sys.stdout), verbose=bool(values.get("verbose")))
+    state["console"] = console
+    return console, state
+
+
+@contextmanager
+def http_client(state: dict[str, Any]) -> Iterator[httpx.Client]:
+    """The httpx client requests go through: the one ``main`` was handed (tests), else a new one closed after."""
+    if state.get("http") is not None:
+        yield state["http"]
+        return
+    from databay.settings import SETTINGS  # noqa: PLC0415
+    from databay.transport import new_http_client  # noqa: PLC0415
+
+    with new_http_client(SETTINGS) as client:
+        yield client
+
+
+def call_once(ctx: click.Context, values: dict[str, Any], op: Operation, call: CallValues) -> tuple[Console, Result]:
+    """Send ``op`` once as a curated read (``sql``, ``metrics query``), recording the context a failure prints."""
+    from databay.cli.runner import open_session  # noqa: PLC0415
+    from databay.invoke import resolve_project  # noqa: PLC0415
+
+    console, state = console_for(ctx, values)
+    session, chosen = open_session(values, console, state)
+    try:
+        state["context"] = {
+            "server": chosen.server,
+            "profile": chosen.name,
+            "project": resolve_project(op, call, session.active_project),
+            "request_id": session.transport.request_id,
+        }
+        state["reading"] = True
+        result = session.call(op, call)
+    finally:
+        session.transport.close()
+    state["context"]["request_id"] = result.request_id
+    return console, result
+
+
+def result_envelope(result: Result) -> dict[str, Any]:
+    """``{"result": ..., "project": ...}``: the JSON a curated command prints."""
+    envelope: dict[str, Any] = {"result": result.raw}
+    if result.project is not None:
+        envelope["project"] = result.project
+    return envelope

databay/cli/console.py

@@ -0,0 +1,121 @@
+"""
+Where the CLI writes: the result on stdout, everything else on stderr.
+
+stdout carries only the result, so piping it never mixes in progress or hints. On stderr, a
+terminal gets short human lines and captured output gets one JSON object per line.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Any, TextIO
+
+from databay.errors import DatabayUsageError
+from databay.settings import ENV_NO_COLOR, ENV_OUTPUT, OUTPUT_FORMATS, OutputFormat
+
+
+def output_format(flag: str | None, stdout: TextIO) -> OutputFormat:
+    """``--output``, else ``$DATABAY_OUTPUT``, else a table on a terminal and JSON when captured."""
+    return output_rule(flag, stdout)[0]
+
+
+def output_rule(flag: str | None, stdout: TextIO) -> tuple[OutputFormat, str]:
+    """The output format and which part of the output rule chose it (``databay status`` prints it)."""
+    if flag is not None:
+        return flag, "--output"  # type: ignore[return-value] — click already checked the choice
+    env = os.environ.get(ENV_OUTPUT)
+    if env:
+        if env not in OUTPUT_FORMATS:
+            raise DatabayUsageError(f"{ENV_OUTPUT}={env!r} is not one of {', '.join(OUTPUT_FORMATS)}")
+        return env, ENV_OUTPUT  # type: ignore[return-value]
+    if stdout.isatty():
+        return "table", "stdout is a terminal"
+    return "json", "stdout is captured"
+
+
+@dataclass
+class Console:
+    output: OutputFormat = "json"
+    verbose: bool = False
+    stdout: TextIO = field(default_factory=lambda: sys.stdout)
+    stderr: TextIO = field(default_factory=lambda: sys.stderr)
+    _live_line: bool = False
+    #: What ``notice`` already showed on a terminal, so the error lines do not repeat it.
+    _noticed: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def stderr_tty(self) -> bool:
+        return self.stderr.isatty()
+
+    @property
+    def color(self) -> bool:
+        return self.stdout.isatty() and not os.environ.get(ENV_NO_COLOR)
+
+    def _end_live_line(self) -> None:
+        if self._live_line:
+            self.stderr.write("\n")
+            self._live_line = False
+
+    def event(self, name: str, fields: dict[str, Any]) -> None:
+        """One stderr event; ``request`` and ``response`` events only under ``--verbose``."""
+        if name in {"request", "response", "cache_invalid", "cache_write_failed"} and not self.verbose:
+            return
+        if not self.stderr_tty:
+            self.stderr.write(json.dumps({"event": name, **fields}, default=str) + "\n")
+            self.stderr.flush()
+            return
+        self._end_live_line()
+        details = " ".join(f"{key}={value}" for key, value in fields.items() if value is not None)
+        self.stderr.write(f"{name}: {details}\n")
+        self.stderr.flush()
+
+    def progress(self, state: str | None, elapsed_s: float, operation: str) -> None:
+        """A wait's state: a live line on a terminal, one ``wait`` event per state change when captured."""
+        if not self.stderr_tty:
+            self.event("wait", {"state": state, "elapsed_s": round(elapsed_s, 1), "status_operation": operation})
+            return
+        self.stderr.write(f"\rwaiting: {state} ({round(elapsed_s)}s)\033[K")
+        self.stderr.flush()
+        self._live_line = True
+
+    def notice(self, name: str, value: str, *, only_on_terminal: bool) -> None:
+        """
+        A value the result does not carry, such as ``next``: ``name: value`` on a terminal, an event when captured.
+
+        ``only_on_terminal`` is for JSON output, whose envelope already holds the value.
+        """
+        if self.stderr_tty:
+            self._end_live_line()
+            self.stderr.write(f"{name}: {value}\n")
+            self._noticed[name] = value
+            return
+        if not only_on_terminal:
+            self.event(name, {"value": value})
+
+    def inform(self, name: str, fields: dict[str, Any], text: str) -> None:
+        """Something the user must act on: ``text`` on a terminal, the ``name`` event with ``fields`` when captured."""
+        if not self.stderr_tty:
+            self.event(name, fields)
+            return
+        self._end_live_line()
+        self.stderr.write(text + "\n")
+        self.stderr.flush()
+
+    def error(self, body: dict[str, Any]) -> None:
+        self._end_live_line()
+        if not self.stderr_tty:
+            self.stderr.write(json.dumps({"error": body}, default=str) + "\n")
+            self.stderr.flush()
+            return
+        self.stderr.write(f"error: {body['code']}: {body['message']}\n")
+        if body.get("hint"):
+            self.stderr.write(f"hint: {body['hint']}\n")
+        if body.get("next") and self._noticed.get("next") != body["next"]:
+            self.stderr.write(f"next: {body['next']}\n")
+        trace_id = (body.get("details") or {}).get("trace_id")
+        if trace_id and (body.get("status") or 0) >= 500:  # noqa: PLR2004
+            self.stderr.write(f"trace_id: {trace_id}\n")
+        self.stderr.flush()

databay/cli/flags.py

@@ -0,0 +1,183 @@
+"""
+The arguments and flags of one generated command, as plain data.
+
+``databay.cli.build`` turns them into click parameters and ``databay.reference`` renders them into
+``commands.md``, so ``--help`` and the reference list the same flags with the same text. Standard
+library only: ``python/tools/gen_client.py`` reads it.
+
+- A path parameter is a positional argument, in path order. The project's own path parameter is
+  optional when nothing required follows it.
+- A query or header parameter, or a body field, is ``--<name in kebab case>``. A list repeats the
+  flag; an object takes JSON text.
+- A secret field (``format: password``) is never a value flag: ``--<name>-env NAME`` names a
+  variable that holds it and ``--<name>-stdin`` reads it from stdin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from databay.settings import OUTPUT_FORMATS
+
+if TYPE_CHECKING:
+    from databay.operation import Operation, Param
+
+Role = Literal[
+    "argument",
+    "option",
+    "secret_env",
+    "secret_stdin",
+    "project",
+    "file",
+    "yes",
+    "wait",
+    "timeout",
+    "idempotency_key",
+    "output",
+    "profile",
+    "verbose",
+    "no_retry",
+]
+
+#: Flags the CLI adds itself; a parameter or body field that would take one of these names is a
+#: generator error.
+RESERVED_FLAGS = frozenset(
+    {"project", "file", "yes", "wait", "timeout", "idempotency-key", "output", "profile", "verbose", "no-retry", "help"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Flag:
+    role: Role
+    #: The flag (``--source-id``) or the argument's metavar (``PIPE_UUID``).
+    name: str
+    dest: str
+    help: str
+    required: bool = False
+    param: Param | None = None
+    #: ``value``: takes a value; ``switch``: a bare flag; ``bool``: ``--x`` sends true and ``--no-x``
+    #: false; ``multiple``: repeated, one item each.
+    takes: Literal["value", "switch", "bool", "multiple", "argument"] = "value"
+    choices: tuple[str, ...] = ()
+    metavar: str | None = None
+
+
+def _value_help(param: Param) -> str:
+    text = param.description.strip().splitlines()[0] if param.description.strip() else ""
+    if param.kind == "json":
+        text = f"{text} (JSON)".strip()
+    return text
+
+
+def _argument(param: Param, *, required: bool) -> Flag:
+    return Flag(
+        "argument",
+        param.name.upper(),
+        param.identifier,
+        _value_help(param),
+        required=required,
+        param=param,
+        takes="argument",
+    )
+
+
+def _option(param: Param, *, role: Role = "option") -> list[Flag]:
+    if param.secret:
+        return [
+            Flag(
+                "secret_env",
+                f"--{param.flag}-env",
+                f"{param.identifier}_env",
+                f"name of the environment variable that holds {param.name} (secret)",
+                param=param,
+                metavar="NAME",
+            ),
+            Flag(
+                "secret_stdin",
+                f"--{param.flag}-stdin",
+                f"{param.identifier}_stdin",
+                f"read {param.name} (secret) from stdin",
+                param=param,
+                takes="switch",
+            ),
+        ]
+    takes = "multiple" if param.kind == "list" else "bool" if param.kind == "boolean" else "value"
+    return [
+        Flag(
+            role,
+            f"--{param.flag}",
+            param.identifier,
+            _value_help(param),
+            required=param.required,
+            param=param,
+            takes=takes,
+            choices=param.choices,
+        )
+    ]
+
+
+def _project_path_optional(op: Operation) -> bool:
+    location = op.project_location
+    if location is None or location[0] != "path":
+        return False
+    names = [p.name for p in op.path_params]
+    return names[-1] == location[1]
+
+
+def command_flags(op: Operation, variant: str | None = None) -> list[Flag]:
+    """Every argument and flag of ``op`` (of its body variant ``variant``), in the order ``--help`` shows them."""
+    location = op.project_location
+    flags: list[Flag] = []
+    optional_last = _project_path_optional(op)
+    for index, param in enumerate(op.path_params):
+        is_project = location is not None and location == ("path", param.name)
+        last = index == len(op.path_params) - 1
+        flags.append(_argument(param, required=not (is_project and optional_last and last)))
+    for param in op.params:
+        if param.location == "path":
+            continue
+        if location is not None and location == (param.location, param.name):
+            flags.append(
+                Flag("option", f"--{param.flag}", param.identifier, _value_help(param), param=param, takes="value")
+            )
+            continue
+        flags += _option(param)
+    if op.body is not None:
+        for param in op.body.fields_of(variant):
+            if location is not None and location == ("body", param.name):
+                flags.append(
+                    Flag("option", f"--{param.flag}", param.identifier, _value_help(param), param=param, takes="value")
+                )
+                continue
+            flags += _option(param)
+        flags.append(Flag("file", "--file", "file", "read the whole body as JSON from a file, or - for stdin"))
+    if op.project is not None:
+        flags.append(Flag("project", "--project", "project", "the project to act in (default: the active project)"))
+    if op.idempotent:
+        flags.append(
+            Flag(
+                "idempotency_key",
+                "--idempotency-key",
+                "idempotency_key",
+                "repeat an earlier call: the server answers it again and creates nothing (default: a new key)",
+            )
+        )
+    if op.destructive:
+        flags.append(Flag("yes", "--yes", "yes", "confirm: this removes or overwrites state", takes="switch"))
+    if op.offers_wait:
+        flags.append(Flag("wait", "--wait", "wait", "wait until it is done, polling its status", takes="switch"))
+        flags.append(
+            Flag("timeout", "--timeout", "timeout", "seconds --wait may take before exit 4 (resumable)", metavar="S")
+        )
+    flags += common_flags()
+    return flags
+
+
+def common_flags() -> list[Flag]:
+    return [
+        Flag("output", "--output", "output", "json, table or csv", choices=OUTPUT_FORMATS),
+        Flag("profile", "--profile", "profile", "the profile to use (default: current_profile)"),
+        Flag("verbose", "--verbose", "verbose", "log each request on stderr, secrets redacted", takes="switch"),
+        Flag("no_retry", "--no-retry", "no_retry", "send each request once", takes="switch"),
+    ]

databay/cli/handwritten.py

@@ -0,0 +1,22 @@
+"""
+Commands written by hand, for work no single operation does: local state, sign-in, curated flows.
+
+Each entry is ``command -> (module, attribute, summary)``. A one-word command sits beside the
+generated nouns; ``"<noun> <verb>"`` adds a verb to that generated noun (``project use``). The root
+group imports the module only when the command, or its noun, runs. An operation declared
+``agent_shape="curated:<command>"`` gets no generated command; its command belongs here.
+"""
+
+HANDWRITTEN: dict[str, tuple[str, str, str]] = {
+    "login": ("databay.cli.auth", "login", "Sign in and save a profile"),
+    "logout": ("databay.cli.auth", "logout", "Sign out: revoke and delete the profile's credential"),
+    "profile": ("databay.cli.profile", "profile", "Switch between and list profiles"),
+    "status": ("databay.cli.profile", "status", "Who and where: profile, server, user, org, project, skill"),
+    "skill": ("databay.cli.skill", "skill", "Install the agent skill for Claude Code or Codex"),
+    "org switch": ("databay.cli.org", "org_switch", "Make another organization active and refresh the token"),
+    "project use": ("databay.cli.profile", "project_use", "Set the profile's active project"),
+    "pipe wait": ("databay.cli.pipe_wait", "pipe_wait", "Wait until a pipe is active or its table is ready to query"),
+    "metrics describe": ("databay.cli.metrics", "describe", "Describe one metric you can query"),
+    "metrics query": ("databay.cli.metrics", "query", "Query one metric by dimensions and time grain"),
+    "sql": ("databay.cli.sql", "sql", "Run one read-only SQL statement"),
+}

databay/cli/main.py

@@ -0,0 +1,198 @@
+"""
+The ``databay`` entry point.
+
+Each noun's commands live in their own generated module, imported only when that noun runs, so
+``databay --help`` and ``databay pipe get --help`` load almost nothing. Every failure leaves through
+``fail``: one error object on stderr and the exit code its code names.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import time
+import traceback
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from databay.cli.handwritten import HANDWRITTEN
+from databay.errors import DatabayError
+from databay.platform_check import ensure_supported
+from databay.settings import (
+    ENV_CONFIG_DIR,
+    ENV_NO_UPDATE_CHECK,
+    ENV_OUTPUT,
+    ENV_STATE_DIR,
+    ENV_TOKEN,
+    OUTPUT_RULE,
+)
+from databay.spec import API_VERSION, NOUNS
+from databay.version import CLIENT_VERSION
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import httpx
+
+    from databay.update_check import UpdateCheck
+
+ROOT_HELP = f"""Databay from the command line: databay <noun> <verb> [ARGS] [OPTIONS].
+
+{OUTPUT_RULE} stdout carries only the result; progress, hints and errors go to stderr.
+
+\b
+Environment:
+  {ENV_TOKEN}       the access token, for a profile whose auth is "env";
+                       set under a login or api_key profile it is an error
+  {ENV_OUTPUT}      json, table or csv
+  {ENV_CONFIG_DIR}  where config.toml lives (default: the platform's config dir)
+  {ENV_STATE_DIR}   where caches and crash logs go (default: the platform's state dir)
+  {ENV_NO_UPDATE_CHECK}=1  no daily check for a newer release (also off under CI)
+  NO_COLOR             no colors in tables
+
+\b
+Exit codes: 0 ok, 1 refused, 2 usage, 3 profile or token, 4 still pending,
+5 wait failed, 6 transient, 7 version mismatch, 8 client outdated or bug,
+9 not ready. A failure prints {{"error": {{"code", "message", "hint", "next",
+"recovery", "context"}}}} on stderr when captured."""
+
+
+class RootGroup(click.Group):
+    """Lists every noun from the generated index; imports a noun's module only to run it."""
+
+    def list_commands(self, ctx: click.Context) -> list[str]:  # noqa: ARG002 — click's signature
+        return sorted(set(NOUNS) | {name for name in HANDWRITTEN if " " not in name})
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:  # noqa: ARG002
+        if cmd_name in HANDWRITTEN:
+            return _handwritten(cmd_name)
+        if cmd_name not in NOUNS:
+            return None
+        module, _ = NOUNS[cmd_name]
+        group: click.Group = importlib.import_module(f"databay.cli.commands.{module}").group
+        for verb in _handwritten_verbs(cmd_name):
+            group.add_command(_handwritten(f"{cmd_name} {verb}"), verb)
+        return group
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:  # noqa: ARG002
+        rows = [(noun, ", ".join(sorted([*verbs, *_handwritten_verbs(noun)]))) for noun, (_, verbs) in NOUNS.items()]
+        rows += [(name, summary) for name, (_, _, summary) in HANDWRITTEN.items() if " " not in name]
+        with formatter.section("Commands"):
+            formatter.write_dl(sorted(rows))
+
+
+def _handwritten(command: str) -> click.Command:
+    module, attribute, _ = HANDWRITTEN[command]
+    return getattr(importlib.import_module(module), attribute)
+
+
+def _handwritten_verbs(noun: str) -> list[str]:
+    """The hand-written verbs of a generated noun (``project use``)."""
+    return [verb for name in HANDWRITTEN for head, _, verb in [name.partition(" ")] if verb and head == noun]
+
+
+@click.group(cls=RootGroup, help=ROOT_HELP, context_settings={"max_content_width": 110})
+@click.version_option(f"{CLIENT_VERSION} (API {API_VERSION})", prog_name="databay", message="%(prog)s %(version)s")
+def root() -> None:
+    pass
+
+
+def _crash_log(exc: BaseException) -> str | None:
+    from databay.paths import state_dir  # noqa: PLC0415
+
+    try:
+        directory = state_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+        path = directory / f"crash-{time.strftime('%Y%m%dT%H%M%S')}.log"
+        path.write_text("".join(traceback.format_exception(exc)), encoding="utf-8")
+    except OSError:
+        return None
+    return str(path)
+
+
+def fail(error: DatabayError, state: dict[str, Any]) -> int:
+    from databay.cli.console import Console  # noqa: PLC0415
+
+    console: Console = state.get("console") or Console()
+    body = error.to_dict()
+    body["context"] = {
+        "cli_version": CLIENT_VERSION,
+        "api_version": API_VERSION,
+        **dict.fromkeys(("server", "profile", "project", "request_id")),
+        **state.get("context", {}),
+    }
+    console.error(body)
+    return error.exit_code
+
+
+def main(argv: Sequence[str] | None = None, *, http: httpx.Client | None = None) -> int:
+    """
+    Run the CLI and return its exit code; the console script exits with it.
+
+    ``http`` is the httpx client every request goes through; tests pass one on ``httpx.MockTransport``.
+    """
+    state: dict[str, Any] = {"http": http}
+    update = _start_update_check()
+    try:
+        ensure_supported()
+        root.main(args=list(argv) if argv is not None else None, prog_name="databay", standalone_mode=False, obj=state)
+    except DatabayError as exc:
+        code = fail(exc, state)
+    except click.exceptions.NoArgsIsHelpError as exc:
+        click.echo(exc.ctx.get_help() if exc.ctx is not None else exc.format_message())
+        code = 0
+    except click.exceptions.Abort:
+        from databay.errors import DatabayCancelled  # noqa: PLC0415
+
+        if state.get("sent"):
+            key = state.get("idempotency_key")
+            error = DatabayCancelled(
+                "interrupted after the request was sent",
+                code="interrupted",
+                details={"idempotency_key": key} if key else {},
+                next_command=state.get("next"),
+            )
+        elif state.get("reading"):
+            error = DatabayCancelled(
+                "stopped while reading; nothing was changed", code="stopped", next_command=state.get("next")
+            )
+        else:
+            error = DatabayCancelled("cancelled; nothing was sent")
+        code = fail(error, state)
+    except click.UsageError as exc:
+        from databay.errors import DatabayUsageError  # noqa: PLC0415
+
+        hint = exc.ctx.get_usage() if exc.ctx is not None else None
+        code = fail(DatabayUsageError(exc.format_message(), hint=hint), state)
+    except click.ClickException as exc:
+        from databay.errors import DatabayUsageError  # noqa: PLC0415
+
+        code = fail(DatabayUsageError(exc.format_message()), state)
+    except Exception as exc:  # noqa: BLE001 — the last line: every crash leaves as internal_error
+        path = _crash_log(exc)
+        if state.get("console") is not None and state["console"].verbose:
+            traceback.print_exception(exc, file=sys.stderr)
+        error = DatabayError(
+            f"databay crashed: {type(exc).__name__}" + (f"; the trace is in {path}" if path else ""),
+            details={"crash_log": path},
+        )
+        code = fail(error, state)
+    else:
+        code = 0
+    if update is not None:
+        console = state.get("console")
+        update.finish(sys.stderr, console.event if console is not None and console.verbose else None)
+    return code
+
+
+def _start_update_check() -> UpdateCheck | None:
+    import os  # noqa: PLC0415
+
+    from databay import update_check  # noqa: PLC0415
+
+    if not update_check.enabled(dict(os.environ), sys.stdout, sys.stderr):
+        return None
+    check = update_check.UpdateCheck()
+    check.start()
+    return check