databay-cli 0.1.0__py3-none-any.whl

databay/cli/metrics.py

@@ -0,0 +1,171 @@
+"""``databay metrics describe`` and ``databay metrics query``: the curated commands of the metrics API."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import click
+
+from databay.cli.common import call_once, common_options, result_envelope
+from databay.models.metrics import Grain
+
+#: Who ran the query, for the server's per-caller count: ``--caller``, ``cli`` unless an agent passes ``agent``.
+CALLER_HEADER = "X-Databay-Caller"
+CALLERS = ("cli", "agent")
+#: ``--where`` operators; ``!=``, ``>=`` and ``<=`` come before ``=``, ``>`` and ``<`` so the regex reads them whole.
+WHERE_OPS = {"!=": "notEquals", ">=": "gte", "<=": "lte", "=": "equals", ">": "gt", "<": "lt"}
+_WHERE = re.compile(
+    r"\s*([a-z][a-z0-9_]*)\s*(" + "|".join(map(re.escape, WHERE_OPS)) + r")\s*([^=<>\s].*?)\s*", re.DOTALL
+)
+_ORDER = re.compile(r"([a-z][a-z0-9_]*)(?::(asc|desc))?")
+_PROJECT_HELP = "the project to act in (default: the active project)"
+
+
+def parse_order(text: str) -> dict[str, str]:
+    """One ``--order``: ``member`` or ``member:asc|desc``."""
+    from databay.errors import DatabayUsageError  # noqa: PLC0415
+
+    match = _ORDER.fullmatch(text.strip())
+    if match is None:
+        raise DatabayUsageError(f"--order {text!r}: write <member> or <member>:desc (net_sales:desc)")
+    return {"member": match[1], "direction": match[2] or "asc"}
+
+
+def parse_where(text: str) -> dict[str, Any]:
+    """
+    One ``--where`` as a filter: ``member<op>value`` with ``=``, ``!=``, ``>``, ``>=``, ``<`` or ``<=``.
+
+    The value is the rest, without the spaces around it; commas and inner spaces stay. A value starting
+    with ``=``, ``<`` or ``>`` (``a==b``, ``a=>b``) is refused as a mistyped operator.
+    """
+    from databay.errors import DatabayUsageError  # noqa: PLC0415
+
+    match = _WHERE.fullmatch(text)
+    if match is None:
+        raise DatabayUsageError(
+            f"--where {text!r}: write <dimension><op><value>, op one of {', '.join(WHERE_OPS)} (channel=paid)"
+        )
+    member, symbol, value = match.groups()
+    return {"member": member, "op": WHERE_OPS[symbol], "values": [value]}
+
+
+DESCRIBE_HELP = """Describe one metric: its dimensions, time grains, filter operators, warehouses and state.
+
+\b
+Example:
+  databay metrics describe net_sales"""
+
+
+@click.command("describe", help=DESCRIBE_HELP, short_help="Describe one metric you can query")
+@click.argument("metric", metavar="METRIC")
+@click.option("--project", default=None, help=_PROJECT_HELP)
+@common_options
+@click.pass_context
+def describe(ctx: click.Context, metric: str, project: str | None, **values: Any) -> None:  # noqa: ANN401
+    from databay.cli.output import emit  # noqa: PLC0415
+    from databay.invoke import CallValues  # noqa: PLC0415
+    from databay.operations.metrics import METRICS_DESCRIBE  # noqa: PLC0415
+
+    call = CallValues(path={"metric": metric}, project_flag=project)
+    console, result = call_once(ctx, values, METRICS_DESCRIBE, call)
+    emit(console, result_envelope(result), ())
+
+
+QUERY_HELP = """Query one metric, grouped by dimensions and a time grain.
+
+\b
+A table or CSV prints the rows under their columns; JSON prints the whole
+answer (columns, rows, row_count, truncated, answer_path, model_version,
+warehouse, explain). --explain adds the metric's definition, the SQL it
+compiled to and its lineage; --dry-run answers that without running it.
+\b
+--where member=value filters on a dimension; it also takes !=, >, >=, <
+and <=, and repeats (each must hold). --order member[:desc] sorts, and
+repeats; with --limit it answers a top N.
+\b
+--caller agent marks a query an AI agent ran, so the server counts it
+apart from a person's; without it the query counts as cli.
+\b
+Examples:
+  databay metrics query net_sales --grain day --last 30d
+  databay metrics query channel_sessions --by channel --grain week --last 90d --where channel=Direct
+  databay metrics query net_sales --grain day --last 30d --explain"""
+
+
+@click.command("query", help=QUERY_HELP, short_help="Query one metric by dimensions and time grain")
+@click.argument("metric", metavar="METRIC")
+@click.option("--by", "by", multiple=True, metavar="DIMENSION", help="group by this dimension; repeat for more")
+@click.option(
+    "--grain",
+    type=click.Choice([g.value for g in Grain]),
+    default=None,
+    help="group by the metric's time at this grain",
+)
+@click.option("--last", default=None, metavar="ND", help="the N UTC days that end today, such as 30d")
+@click.option("--from", "start", default=None, metavar="YYYY-MM-DD", help="first day (with --to)")
+@click.option("--to", "end", default=None, metavar="YYYY-MM-DD", help="last day, inclusive (with --from)")
+@click.option("--where", "where", multiple=True, metavar="FILTER", help="member=value (or != > >= < <=); repeat")
+@click.option("--order", "order", multiple=True, metavar="MEMBER[:desc]", help="sort by this member; repeat")
+@click.option("--limit", type=click.IntRange(min=1), default=None, help="most rows to answer")
+@click.option("--warehouse", default=None, help="the warehouse, when the metric is in several")
+@click.option("--model-version", "model_version", type=click.IntRange(min=1), default=None, help="pin a model version")
+@click.option("--explain", is_flag=True, default=False, help="add the definition, compiled SQL and lineage")
+@click.option("--dry-run", "dry_run", is_flag=True, default=False, help="answer the explain without running it")
+@click.option("--caller", type=click.Choice(CALLERS), default="cli", help="who runs the query: cli or agent")
+@click.option("--project", default=None, help=_PROJECT_HELP)
+@common_options
+@click.pass_context
+def query(
+    ctx: click.Context,
+    metric: str,
+    by: tuple[str, ...],
+    grain: str | None,
+    last: str | None,
+    start: str | None,
+    end: str | None,
+    where: tuple[str, ...],
+    order: tuple[str, ...],
+    limit: int | None,
+    warehouse: str | None,
+    model_version: int | None,
+    explain: bool,
+    dry_run: bool,
+    caller: str,
+    project: str | None,
+    **values: Any,  # noqa: ANN401
+) -> None:
+    from databay.cli.output import emit_grid  # noqa: PLC0415
+    from databay.invoke import CallValues  # noqa: PLC0415
+    from databay.operations.metrics import METRICS_QUERY  # noqa: PLC0415
+
+    filters = [parse_where(text) for text in where]
+    ordering = [parse_order(text) for text in order]
+    time = {k: v for k, v in {"grain": grain, "last": last, "from": start, "to": end}.items() if v is not None}
+    body: dict[str, Any] = {"metric": metric, "explain": explain, "dry_run": dry_run}
+    optional = {
+        "dimensions": list(by) or None,
+        "time": time or None,
+        "filters": filters or None,
+        "order": ordering or None,
+        "limit": limit,
+        "warehouse": warehouse,
+        "model_version": model_version,
+    }
+    body.update({k: v for k, v in optional.items() if v is not None})
+    call = CallValues(body=body, has_body=True, headers={CALLER_HEADER: caller}, project_flag=project)
+    console, result = call_once(ctx, values, METRICS_QUERY, call)
+    answer = result.parsed
+    if answer.truncated:
+        console.notice(
+            "truncated",
+            f"the server returned the first {answer.row_count} rows",
+            only_on_terminal=console.output == "json",
+        )
+    emit_grid(console, result_envelope(result), [c.name for c in answer.columns], [list(row) for row in answer.rows])
+    if answer.explain is None or console.output == "json":
+        return
+    if console.output == "table":
+        console.stdout.write(f"sql:\n{answer.explain.sql.text}\n")
+    else:
+        console.notice("explain", "CSV holds only the rows; pass --output json for the explain", only_on_terminal=False)

databay/cli/org.py

@@ -0,0 +1,193 @@
+"""
+``databay org switch``, and the organization ``databay login`` makes active.
+
+The server stores the active organization and every token names that one. Switching is a write
+(``PUT /api/auth/me/active-org``) followed by a token renewal; the new token is checked to name the
+organization before the command reports it. An organization is named by its key or its display name.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from databay.cli.common import common_options, console_for
+from databay.cli.handwritten import HANDWRITTEN
+
+if TYPE_CHECKING:
+    from databay.cli.console import Console
+    from databay.invoke import Session
+    from databay.models.org import MyOrganizationOut, MyOrganizationsResponse
+    from databay.profiles import Profile
+
+SWITCH_HELP = """Make ORGANIZATION the active organization and refresh the token.
+
+\b
+ORGANIZATION is a key (org-...) or a display name; `databay org list` shows
+both. Every later command acts in that organization. The profile's active
+project belongs to the previous organization, so it is cleared.
+
+\b
+Example:
+  databay org switch <organization>"""
+
+
+def list_orgs(session: Session) -> MyOrganizationsResponse:
+    from databay.invoke import CallValues  # noqa: PLC0415
+    from databay.operations.org import ORG_LIST  # noqa: PLC0415
+
+    return session.call(ORG_LIST, CallValues()).parsed
+
+
+def resolve_org(listing: MyOrganizationsResponse, wanted: str, server: str) -> MyOrganizationOut:
+    """The organization ``wanted`` names: a key, else exactly one display name, compared without case."""
+    from databay.errors import DatabayUsageError, api_error  # noqa: PLC0415
+
+    keys = [org.organization for org in listing.organizations]
+    by_key = [org for org in listing.organizations if org.organization == wanted]
+    if by_key:
+        return _usable(by_key[0])
+    by_name = [org for org in listing.organizations if org.display_name.casefold() == wanted.casefold()]
+    if len(by_name) > 1:
+        raise DatabayUsageError(
+            f"{len(by_name)} of your organizations are named {wanted!r}; pass the key instead",
+            details={"organizations": [org.organization for org in by_name]},
+        )
+    if not by_name:
+        raise api_error(
+            "org_not_member",
+            f"you belong to no organization {wanted!r} on {server}",
+            status=403,
+            details={"organization": wanted, "organizations": keys},
+        )
+    return _usable(by_name[0])
+
+
+def _usable(org: MyOrganizationOut) -> MyOrganizationOut:
+    """``org``, unless it is disabled: no token can name a disabled organization."""
+    from databay.errors import api_error  # noqa: PLC0415
+
+    if not org.enabled:
+        raise api_error(
+            "org_disabled",
+            f"{org.display_name} ({org.organization}) is disabled",
+            status=403,
+            details={"organization": org.organization},
+        )
+    return org
+
+
+def switch_to(
+    session: Session, profile: Profile, org: MyOrganizationOut, console: Console, state: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Store ``org`` as active, renew the profile's token and check it names ``org``.
+
+    A profile whose token comes from ``$DATABAY_TOKEN`` cannot renew it: the switch is stored and
+    ``token_refreshed`` is false. The active project is cleared when the token named another organization.
+    """
+    from databay.errors import DatabayError  # noqa: PLC0415
+    from databay.invoke import CallValues  # noqa: PLC0415
+    from databay.operations.org import ORG_SWITCH  # noqa: PLC0415
+    from databay.profiles import edit_config  # noqa: PLC0415
+    from databay.settings import ENV_TOKEN  # noqa: PLC0415
+    from databay.stored_token import StoredToken  # noqa: PLC0415
+
+    before = _token_org(session)
+    state["sent"] = True
+    session.call(ORG_SWITCH, CallValues(body={"organization": org.organization}, has_body=True))
+    tokens = session.transport.tokens
+    refreshed = isinstance(tokens, StoredToken)
+    if refreshed:
+        tokens.renewed()
+        now = _token_org(session)
+        if now != org.organization:
+            raise DatabayError(
+                f"switched to {org.organization}, but the renewed token names {now or 'no organization'}",
+                code="org_not_in_token",
+                details={"organization": org.organization, "token_organization": now},
+                next_command="databay status",
+            )
+    else:
+        console.inform(
+            "token_not_refreshed",
+            {"organization": org.organization, "auth": profile.auth},
+            f"{org.organization} is now your active organization, but ${ENV_TOKEN} still holds a token "
+            "for the previous one: get a new token before the next command.",
+        )
+    cleared = None
+    if before != org.organization and profile.active_project is not None:
+        cleared = profile.active_project
+
+        def change(data: dict[str, Any]) -> None:
+            data["profiles"][profile.name].pop("active_project", None)
+
+        edit_config(change)
+    return {
+        "profile": profile.name,
+        "organization": org.organization,
+        "display_name": org.display_name,
+        "role": None if org.role is None else str(org.role),
+        "token_refreshed": refreshed,
+        "cleared_active_project": cleared,
+    }
+
+
+def _token_org(session: Session) -> str | None:
+    """The organization the token now names, as the server reads it."""
+    from databay.invoke import CallValues  # noqa: PLC0415
+    from databay.operations.me import ME_GET  # noqa: PLC0415
+
+    me = session.call(ME_GET, CallValues()).parsed
+    return me.organization[0] if me.organization else None
+
+
+def choose_interactively(listing: MyOrganizationsResponse, console: Console) -> MyOrganizationOut:
+    """Ask on the terminal which organization to make active."""
+    usable = [org for org in listing.organizations if org.enabled]
+    lines = ["You belong to several organizations. Which one should be active?"]
+    for number, org in enumerate(usable, start=1):
+        role = f", {org.role}" if org.role is not None else ""
+        lines.append(f"  {number}) {org.display_name} ({org.organization}{role})")
+    console.inform("org_choice", {}, "\n".join(lines))
+    picked = click.prompt("Organization", type=click.IntRange(1, len(usable)), err=True)
+    return usable[picked - 1]
+
+
+def report_no_usable_org(listing: MyOrganizationsResponse, server: str, console: Console) -> None:
+    """Say that no token can name an organization: every one is disabled, or there is none."""
+    console.inform(
+        "no_usable_org",
+        {"organizations": [org.organization for org in listing.organizations]},
+        f"You are signed in, but none of your organizations on {server} can be used "
+        f"({'every one is disabled' if listing.organizations else 'you belong to none'}). "
+        "Create one in the web app, or ask an organization admin to add you.",
+    )
+
+
+def interactive(console: Console) -> bool:
+    return sys.stdin.isatty() and console.stderr_tty
+
+
+@click.command("switch", help=SWITCH_HELP, short_help=HANDWRITTEN["org switch"][2])
+@click.argument("organization")
+@common_options
+@click.pass_context
+def org_switch(ctx: click.Context, organization: str, **values: Any) -> None:  # noqa: ANN401
+    from databay.cli.output import emit  # noqa: PLC0415
+    from databay.cli.runner import open_session  # noqa: PLC0415
+    from databay.errors import DatabayUsageError  # noqa: PLC0415
+
+    console, state = console_for(ctx, values)
+    session, chosen = open_session(values, console, state)
+    state["context"] = {"server": chosen.server, "profile": chosen.name}
+    if chosen.auth == "api_key":
+        raise DatabayUsageError(f"profile {chosen.name} signs in as an org API key, which belongs to one organization")
+    try:
+        org = resolve_org(list_orgs(session), organization, chosen.server)
+        result = switch_to(session, chosen, org, console, state)
+    finally:
+        session.transport.close()
+    emit(console, {"result": result, "next": "databay status"}, ())

databay/cli/output.py

@@ -0,0 +1,134 @@
+"""
+Printing a command's result.
+
+JSON is one envelope: ``{"result": <the server's answer>}``, plus ``project`` when the command
+acted in one, ``wait`` after ``--wait``, ``idempotency_key`` on a create and ``next`` when there is
+an obvious next command. A table or CSV prints the answer alone: a list of objects as rows (the
+operation's declared columns, else every key), an object as one row per field.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from typing import TYPE_CHECKING, Any
+
+from databay.errors import DatabayResponseInvalid
+from databay.invoke import pointer
+
+if TYPE_CHECKING:
+    from databay.cli.console import Console
+
+MAX_CELL = 80
+
+
+def _text(value: Any) -> str:  # noqa: ANN401
+    if value is None:
+        return ""
+    return value if isinstance(value, str) else json.dumps(value, default=str)
+
+
+def _cell(value: Any) -> str:  # noqa: ANN401
+    """A table cell, cut to ``MAX_CELL`` characters; CSV keeps the whole value."""
+    text = _text(value)
+    return text if len(text) <= MAX_CELL else text[: MAX_CELL - 1] + "…"
+
+
+def _rows(result: Any, columns: tuple[str, ...], cell: Any = _cell) -> tuple[list[str], list[list[str]]]:  # noqa: ANN401
+    if isinstance(result, list) and all(isinstance(item, dict) for item in result):
+        header = list(columns)
+        if not header:
+            for item in result:
+                header += [key for key in item if key not in header]
+        return header, [[cell(item.get(key)) for key in header] for item in result]
+    if isinstance(result, dict):
+        return ["field", "value"], [[key, cell(value)] for key, value in result.items()]
+    if isinstance(result, list):
+        return ["value"], [[cell(item)] for item in result]
+    return ["value"], [[cell(result)]]
+
+
+def _csv_rows(result: Any, columns: tuple[str, ...]) -> tuple[list[str], list[list[str]]]:  # noqa: ANN401
+    if isinstance(result, dict):
+        header = list(columns) or list(result)
+        return header, [[_text(result.get(key)) for key in header]]
+    return _rows(result, columns, _text)
+
+
+def emit(console: Console, envelope: dict[str, Any], columns: tuple[str, ...], rows: str | None = None) -> None:
+    """
+    Print ``envelope`` in the console's format.
+
+    ``rows`` is the JSON pointer of the list a table or CSV shows when the answer is an object
+    holding it (``/keys``); a table or CSV reports ``idempotency_key`` and ``next`` on stderr.
+    """
+    _write(console, envelope, columns, rows)
+    for name in ("idempotency_key", "next"):
+        if envelope.get(name):
+            console.notice(name, envelope[name], only_on_terminal=console.output == "json")
+
+
+def emit_grid(console: Console, envelope: dict[str, Any], header: list[str], rows: list[list[Any]]) -> None:
+    """
+    Print an answer that carries its own grid of ``header`` and ``rows`` (``sql``).
+
+    JSON prints ``envelope``; a table or CSV prints the grid as it is, so repeated column names stay apart.
+    """
+    out = console.stdout
+    if console.output == "json":
+        out.write(json.dumps(envelope, indent=2 if out.isatty() else None, default=str) + "\n")
+        return
+    if console.output == "csv":
+        writer = csv.writer(out)
+        writer.writerow(header)
+        writer.writerows([[_text(value) for value in row] for row in rows])
+        return
+    if envelope.get("project"):
+        out.write(f"project: {envelope['project']}\n")
+    from rich.console import Console as RichConsole  # noqa: PLC0415 — tables only
+    from rich.table import Table  # noqa: PLC0415
+
+    table = Table(*header, show_lines=False)
+    for row in rows:
+        table.add_row(*[_cell(value) for value in row])
+    RichConsole(file=out, no_color=not console.color, soft_wrap=False, markup=False, highlight=False).print(table)
+
+
+def _write(console: Console, envelope: dict[str, Any], columns: tuple[str, ...], rows: str | None) -> None:
+    out = console.stdout
+    result = envelope["result"]
+    if console.output == "json":
+        indent = 2 if out.isatty() else None
+        out.write(json.dumps(envelope, indent=indent, default=str) + "\n")
+        return
+    if isinstance(result, str):
+        out.write(result if result.endswith("\n") else result + "\n")
+        return
+    if rows is not None and isinstance(result, dict):
+        try:
+            result = pointer(result, rows)
+        except (KeyError, IndexError, ValueError):
+            raise DatabayResponseInvalid(f"the answer has no {rows}, the list its columns describe") from None
+    if console.output == "csv":
+        header, cells = _csv_rows(result, columns)
+        writer = csv.writer(out)
+        writer.writerow(header)
+        writer.writerows(cells)
+        return
+    if envelope.get("project"):
+        out.write(f"project: {envelope['project']}\n")
+    if "wait" in envelope:
+        wait = envelope["wait"]
+        reason = f"{wait['reason']}, " if wait.get("reason") else ""
+        out.write(f"wait: {wait['outcome']} ({reason}{wait['state']}, {wait['elapsed_s']}s)\n")
+    if result is None:
+        out.write("done\n")
+        return
+    from rich.console import Console as RichConsole  # noqa: PLC0415 — tables only
+    from rich.table import Table  # noqa: PLC0415
+
+    header, cells = _rows(result, columns)
+    table = Table(*header, show_lines=False)
+    for row in cells:
+        table.add_row(*row)
+    RichConsole(file=out, no_color=not console.color, soft_wrap=False, markup=False, highlight=False).print(table)