duckhaven-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
dh/execute.py ADDED
@@ -0,0 +1,204 @@
1
+ """One-shot query execution: submit, wait, fetch.
2
+
3
+ `POST /workspaces/{workspace}/queries` answers **202** with a query that has not
4
+ run yet, so every caller has to poll. This is that loop, done once and correctly.
5
+
6
+ It is deliberately not the connector's code path. `duckhaven-sql-connector`
7
+ speaks the *session* API (`connect()` opens one), and sessions are disabled by
8
+ default on the server; the one-shot route is the one that always works. The
9
+ connector is what backs `dh session` and the REPL instead.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ import time
16
+ from typing import Any
17
+
18
+ from dh.errors import ConflictError, DhError, QueryFailed
19
+ from dh.errors import TimeoutError as DhTimeoutError
20
+ from dh.rest import RestClient
21
+
22
+ #: A query is finished when it reaches one of these; the server defines no others.
23
+ TERMINAL = frozenset({"done", "failed", "cancelled"})
24
+
25
+ #: Poll schedule. Fast enough that a sub-second query feels synchronous, slow
26
+ #: enough that a forty-minute one costs about one request every two seconds.
27
+ _FIRST_DELAY = 0.2
28
+ _BACKOFF = 1.5
29
+ _MAX_DELAY = 2.0
30
+
31
+ #: The server caps `limit` here; asking for more is rejected, not truncated.
32
+ _MAX_PAGE = 1000
33
+
34
+ _DURATION = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*([smh]?)\s*$", re.IGNORECASE)
35
+ _UNITS = {"": 1, "s": 1, "m": 60, "h": 3600}
36
+
37
+
38
+ def parse_duration(value: str) -> float:
39
+ """Seconds from `30`, `30s`, `20m` or `1h`."""
40
+ match = _DURATION.match(value)
41
+ if not match:
42
+ raise ConflictError(
43
+ "invalid_duration",
44
+ f"Could not read {value!r} as a duration. Use 30s, 20m or 1h.",
45
+ )
46
+ return float(match.group(1)) * _UNITS[match.group(2).lower()]
47
+
48
+
49
+ def submit(
50
+ client: RestClient,
51
+ workspace: str,
52
+ sql: str,
53
+ *,
54
+ agent: str | None = None,
55
+ catalog: str | None = None,
56
+ timeout_s: float | None = None,
57
+ saved_query_id: str | None = None,
58
+ ) -> dict[str, Any]:
59
+ """Hand the SQL to the server. Returns the accepted, not-yet-run query."""
60
+ body: dict[str, Any] = {"sql": sql}
61
+ if agent:
62
+ body["agent_id"] = agent
63
+ if catalog:
64
+ body["catalog"] = catalog
65
+ if timeout_s:
66
+ body["timeout_s"] = timeout_s
67
+ if saved_query_id:
68
+ body["saved_query_id"] = saved_query_id
69
+ return client.post(f"workspaces/{workspace}/queries", json=body)
70
+
71
+
72
+ def wait(
73
+ client: RestClient,
74
+ query_id: str,
75
+ *,
76
+ timeout: float,
77
+ ) -> dict[str, Any]:
78
+ """Poll until the query reaches a terminal status, cancelling on Ctrl-C.
79
+
80
+ Interrupting cancels the query server-side before giving up. Without that,
81
+ Ctrl-C would leave the statement running on an agent with nobody watching it
82
+ -- the CLI would look like it had stopped while the compute kept burning.
83
+ """
84
+ deadline = time.monotonic() + timeout
85
+ delay = _FIRST_DELAY
86
+ while True:
87
+ try:
88
+ query = client.get(f"queries/{query_id}")
89
+ if query.get("status") in TERMINAL:
90
+ return query
91
+ if time.monotonic() >= deadline:
92
+ cancel(client, query_id)
93
+ raise DhTimeoutError(
94
+ "client_timeout",
95
+ f"Query {query_id} did not finish within the timeout; it was cancelled.",
96
+ )
97
+ time.sleep(min(delay, max(0.0, deadline - time.monotonic())))
98
+ delay = min(delay * _BACKOFF, _MAX_DELAY)
99
+ except KeyboardInterrupt:
100
+ cancel(client, query_id)
101
+ raise
102
+
103
+
104
+ def cancel(client: RestClient, query_id: str) -> None:
105
+ """Ask the server to stop a query. Idempotent, and never raises.
106
+
107
+ Cancelling is best effort by contract, and a failure here would mask
108
+ whatever the caller was already reporting.
109
+ """
110
+ try:
111
+ client.delete(f"queries/{query_id}")
112
+ except DhError:
113
+ pass
114
+
115
+
116
+ def fetch_rows(
117
+ client: RestClient,
118
+ query_id: str,
119
+ *,
120
+ limit: int | None = None,
121
+ page_size: int = _MAX_PAGE,
122
+ ) -> dict[str, Any]:
123
+ """Every row of a finished query, following the cursor to the end.
124
+
125
+ `RowsPageOut.cursor` goes null only on the last page, so a single fetch
126
+ silently returns the first hundred rows and looks complete. `limit` caps the
127
+ rows returned and stops fetching once it is reached.
128
+ """
129
+ columns: list[str] = []
130
+ rows: list[list[Any]] = []
131
+ cursor: str | None = None
132
+ total = 0
133
+ schema = None
134
+ while True:
135
+ want = min(page_size, _MAX_PAGE)
136
+ if limit is not None:
137
+ want = min(want, limit - len(rows))
138
+ if want <= 0:
139
+ break
140
+ params: dict[str, Any] = {"limit": want}
141
+ if cursor:
142
+ params["cursor"] = cursor
143
+ page = client.get(f"queries/{query_id}/rows", params=params)
144
+ columns = page.get("columns") or columns
145
+ schema = page.get("column_schema") or schema
146
+ total = page.get("total") or total
147
+ rows.extend(page.get("rows") or [])
148
+ cursor = page.get("cursor")
149
+ if not cursor or not page.get("rows"):
150
+ break
151
+ return {
152
+ "columns": columns,
153
+ "rows": rows,
154
+ "total": total,
155
+ "column_schema": schema,
156
+ "truncated": limit is not None and total > len(rows),
157
+ }
158
+
159
+
160
+ def raise_for_status(query: dict[str, Any]) -> None:
161
+ """Turn a terminal non-`done` query into the right failure.
162
+
163
+ A failed query exits 6, not 1: the CLI did its job, the SQL did not, and a
164
+ pipeline needs to tell those apart.
165
+ """
166
+ status = query.get("status")
167
+ if status == "done":
168
+ return
169
+ if status == "cancelled":
170
+ raise ConflictError("query_cancelled", f"Query {query.get('id')} was cancelled.")
171
+ raise QueryFailed(
172
+ "query_failed",
173
+ query.get("error") or f"Query {query.get('id')} failed.",
174
+ {"query_id": query.get("id")},
175
+ )
176
+
177
+
178
+ def resolve_agent(client: RestClient, requested: str | None) -> str | None:
179
+ """The agent to run on, by id or by name.
180
+
181
+ Elastic compute is off by default, so omitting `agent_id` gets a bare
182
+ `422 agent_required`. Resolving a *name* is something the CLI can do and the
183
+ connector cannot -- a DB-API driver should not spend a round trip on connect
184
+ -- and an ambiguous choice lists the candidates rather than passing the 422
185
+ through.
186
+ """
187
+ if requested and _looks_like_uuid(requested):
188
+ return requested
189
+ agents = client.get("agents") or []
190
+ if requested:
191
+ matches = [a for a in agents if a.get("name") == requested]
192
+ if not matches:
193
+ names = ", ".join(sorted(a.get("name", "?") for a in agents)) or "none"
194
+ raise ConflictError(
195
+ "no_such_agent", f"No agent named {requested!r}. Available: {names}"
196
+ )
197
+ return matches[0].get("id")
198
+ if len(agents) == 1:
199
+ return agents[0].get("id")
200
+ return None
201
+
202
+
203
+ def _looks_like_uuid(value: str) -> bool:
204
+ return len(value) == 36 and value.count("-") == 4
dh/introspect.py ADDED
@@ -0,0 +1,78 @@
1
+ """Walk the command tree and describe it.
2
+
3
+ Backs two things that must not disagree: the snapshot test that fails when a
4
+ command or flag is renamed or lost, and the generated `docs/reference/cli.md`.
5
+ Generating both from one walk is what stops the reference drifting from the CLI
6
+ it documents.
7
+
8
+ Deliberately structural rather than a capture of rendered `--help` text. Rich's
9
+ output shifts with terminal width and library version, so a rendered snapshot
10
+ fails for reasons that have nothing to do with the CLI changing -- and rendered
11
+ text is the wrong input for a docs page anyway.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import typer
17
+ from typer.main import get_command
18
+
19
+ # Everything below duck-types rather than using isinstance. This Typer vendors its
20
+ # own click classes (`typer._click.core.Command`), so `isinstance(cmd, click.Group)`
21
+ # is False for a group that plainly has `.commands` -- which silently walked only
22
+ # the root and produced a two-line "complete" snapshot.
23
+
24
+
25
+ def describe(app: typer.Typer) -> list[dict[str, object]]:
26
+ """Every command in the tree, depth-first by path."""
27
+ return sorted(_walk(get_command(app), []), key=lambda node: node["path"])
28
+
29
+
30
+ def _walk(command, prefix: list[str]) -> list[dict[str, object]]:
31
+ path = [*prefix, command.name] if command.name else prefix
32
+ nodes = [
33
+ {
34
+ "path": " ".join(path) or "dh",
35
+ "help": _first_line(command),
36
+ "params": _params(command),
37
+ }
38
+ ]
39
+ for name in sorted(getattr(command, "commands", {})):
40
+ nodes.extend(_walk(command.commands[name], path))
41
+ return nodes
42
+
43
+
44
+ def _first_line(command) -> str:
45
+ """The summary line, which is what a parent's command list shows."""
46
+ text = (command.help or command.short_help or "").strip()
47
+ return text.splitlines()[0] if text else ""
48
+
49
+
50
+ def _params(command) -> list[str]:
51
+ """Flags and argument names, in declaration order.
52
+
53
+ Options render as their longest spelling plus any short one, so a lost `-q`
54
+ is as visible as a lost `--query`.
55
+ """
56
+ out: list[str] = []
57
+ for param in command.params:
58
+ kind = getattr(param, "param_type_name", "")
59
+ if kind == "option":
60
+ if getattr(param, "hidden", False):
61
+ continue
62
+ out.append("/".join(sorted(param.opts, key=len, reverse=True)))
63
+ elif kind == "argument":
64
+ out.append(f"<{param.name}>")
65
+ return out
66
+
67
+
68
+ def render(app: typer.Typer) -> str:
69
+ """The tree as stable text, one command per block."""
70
+ lines: list[str] = []
71
+ for node in describe(app):
72
+ lines.append(node["path"])
73
+ if node["help"]:
74
+ lines.append(f" {node['help']}")
75
+ for param in node["params"]:
76
+ lines.append(f" . {param}")
77
+ lines.append("")
78
+ return "\n".join(lines).rstrip() + "\n"
dh/main.py ADDED
@@ -0,0 +1,224 @@
1
+ """The `dh` command tree.
2
+
3
+ Typer assembles the tree and renders `--help`; nothing else in the CLI uses Rich.
4
+ Data and errors go through plain writers, so piping `dh` into `jq` or a file never
5
+ picks up box-drawing characters or colour.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import sys
11
+ from pathlib import Path
12
+
13
+ import typer
14
+ from typer.core import TyperGroup
15
+
16
+ from dh import __version__
17
+ from dh.commands import admin as admin_commands
18
+ from dh.commands import api as api_commands
19
+ from dh.commands import auth as auth_commands
20
+ from dh.commands import catalog as catalog_commands
21
+ from dh.commands import dbt as dbt_commands
22
+ from dh.commands import grant as grant_commands
23
+ from dh.commands import health as health_commands
24
+ from dh.commands import profile as profile_commands
25
+ from dh.commands import query as query_commands
26
+ from dh.commands import saved as saved_commands
27
+ from dh.commands import session as session_commands
28
+ from dh.context import CliContext
29
+ from dh.errors import DhError, ExitCode
30
+ from dh.output import Format, default_format, write_error
31
+
32
+
33
+ class DhGroup(TyperGroup):
34
+ """Turns a DhError into the documented exit status, wherever it was raised.
35
+
36
+ The mapping belongs here rather than only in :func:`run`, so a command's exit
37
+ code is produced by the command layer itself -- which is also what makes it
38
+ testable through Click's own runner instead of only through the installed
39
+ console script.
40
+ """
41
+
42
+ def invoke(self, ctx: typer.Context): # noqa: ANN201 - Click's signature
43
+ try:
44
+ return super().invoke(ctx)
45
+ except DhError as exc:
46
+ obj = ctx.obj if isinstance(ctx.obj, CliContext) else None
47
+ write_error(exc, obj.format() if obj else _error_format())
48
+ raise SystemExit(exc.exit_code) from exc
49
+
50
+
51
+ app = typer.Typer(
52
+ cls=DhGroup,
53
+ name="dh",
54
+ help="Command-line interface for DuckHaven.",
55
+ no_args_is_help=True,
56
+ add_completion=True,
57
+ # Tracebacks are for the CLI's own bugs, not for a server saying 404. The error
58
+ # taxonomy renders those; a stack trace would bury the message that matters.
59
+ pretty_exceptions_enable=False,
60
+ )
61
+ app.add_typer(auth_commands.app)
62
+ app.add_typer(profile_commands.app)
63
+ app.command("health")(health_commands.health)
64
+ app.command("version")(health_commands.version)
65
+ app.add_typer(query_commands.app)
66
+ # The one verb-first command in the tree, registered as a leaf beside the groups.
67
+ app.command("sql")(query_commands.sql)
68
+ app.add_typer(saved_commands.saved_app)
69
+ app.add_typer(saved_commands.schedule_app)
70
+ app.command("search")(saved_commands.search)
71
+ app.add_typer(catalog_commands.workspace_app)
72
+ app.add_typer(catalog_commands.catalog_app)
73
+ app.add_typer(catalog_commands.schema_app)
74
+ app.add_typer(catalog_commands.table_app)
75
+ app.add_typer(catalog_commands.agent_app)
76
+ app.add_typer(grant_commands.app)
77
+ app.add_typer(dbt_commands.lineage_app)
78
+ app.add_typer(dbt_commands.semantic_app)
79
+ app.add_typer(session_commands.app)
80
+ app.add_typer(admin_commands.app)
81
+ app.add_typer(api_commands.app)
82
+
83
+
84
+ def _version_callback(value: bool) -> None:
85
+ if value:
86
+ typer.echo(__version__)
87
+ raise typer.Exit
88
+
89
+
90
+ @app.callback()
91
+ def main(
92
+ ctx: typer.Context,
93
+ profile: str = typer.Option(None, "--profile", help="Named profile to use.", metavar="NAME"),
94
+ host: str = typer.Option(None, "--host", help="DuckHaven base URL.", metavar="URL"),
95
+ workspace: str = typer.Option(
96
+ None, "--workspace", "-w", help="Workspace slug or UUID.", metavar="WS"
97
+ ),
98
+ catalog: str = typer.Option(None, "--catalog", help="Catalog to resolve names in."),
99
+ fmt: Format = typer.Option(
100
+ None,
101
+ "--format",
102
+ help="Output format. Defaults to table on a terminal, json otherwise.",
103
+ case_sensitive=False,
104
+ ),
105
+ # Neither of these takes a short flag, and both omissions are deliberate.
106
+ # `-q` belongs to `dh sql --query`.
107
+ output: Path = typer.Option(
108
+ None, "--output", help="Write the payload to a file instead of stdout."
109
+ ),
110
+ quiet: bool = typer.Option(False, "--quiet", help="Suppress progress and warnings."),
111
+ no_color: bool = typer.Option(False, "--no-color", help="Disable colour. See also NO_COLOR."),
112
+ debug: bool = typer.Option(False, "--debug", help="Trace resolution and requests on stderr."),
113
+ _version: bool = typer.Option(
114
+ False,
115
+ "--version",
116
+ help="Show the dh version and exit.",
117
+ callback=_version_callback,
118
+ is_eager=True,
119
+ ),
120
+ ) -> None:
121
+ """DuckHaven from the command line."""
122
+ # Stashed rather than resolved here: `dh profile list` and `dh --help` must work
123
+ # with no config at all, so resolution is deferred to the commands that need it.
124
+ ctx.obj = CliContext(
125
+ overrides={
126
+ "profile": profile,
127
+ "host": host,
128
+ "workspace": workspace,
129
+ "catalog": catalog,
130
+ },
131
+ fmt=fmt,
132
+ output=output,
133
+ quiet=quiet,
134
+ no_color=no_color,
135
+ debug_enabled=debug,
136
+ )
137
+
138
+
139
+ def _error_format() -> Format:
140
+ """The format to report a failure in, read straight from argv.
141
+
142
+ The Typer callback may never have run -- a bad option fails during parsing --
143
+ so the flag cannot be read off the context here.
144
+ """
145
+ argv = sys.argv[1:]
146
+ for index, arg in enumerate(argv):
147
+ if arg.startswith("--format="):
148
+ value = arg.partition("=")[2]
149
+ elif arg == "--format" and index + 1 < len(argv):
150
+ value = argv[index + 1]
151
+ else:
152
+ continue
153
+ try:
154
+ return Format(value.lower())
155
+ except ValueError:
156
+ break
157
+ return default_format(sys.stdout)
158
+
159
+
160
+ #: Global options, and whether each consumes a following value.
161
+ GLOBAL_OPTIONS = {
162
+ "--profile": True,
163
+ "--host": True,
164
+ "--workspace": True,
165
+ "-w": True,
166
+ "--catalog": True,
167
+ "--format": True,
168
+ "--output": True,
169
+ "--quiet": False,
170
+ "--no-color": False,
171
+ "--debug": False,
172
+ "--version": False,
173
+ }
174
+
175
+
176
+ def hoist_global_options(argv: list[str]) -> list[str]:
177
+ """Move global options ahead of the subcommand, leaving everything else in order.
178
+
179
+ Stops at ``--``, so a value that happens to look like a global option can
180
+ always be passed literally.
181
+ """
182
+ head: list[str] = []
183
+ rest: list[str] = []
184
+ index = 0
185
+ while index < len(argv):
186
+ arg = argv[index]
187
+ if arg == "--":
188
+ rest.extend(argv[index:])
189
+ break
190
+ name = arg.partition("=")[0]
191
+ takes_value = GLOBAL_OPTIONS.get(name)
192
+ if takes_value is None:
193
+ rest.append(arg)
194
+ elif "=" in arg or not takes_value:
195
+ head.append(arg)
196
+ elif index + 1 < len(argv):
197
+ head.extend((arg, argv[index + 1]))
198
+ index += 1
199
+ else:
200
+ # No value follows; hand it to Click so it reports the real problem.
201
+ head.append(arg)
202
+ index += 1
203
+ return head + rest
204
+
205
+
206
+ def run() -> None:
207
+ """Console-script entry point: render a DhError instead of a traceback.
208
+
209
+ `[project.scripts]` points here rather than at ``app`` so every failure leaves
210
+ the differentiated exit status in ``ExitCode``, and so an unexpected crash is
211
+ still reported in the same envelope a server error would use.
212
+ """
213
+ try:
214
+ app(args=hoist_global_options(sys.argv[1:]))
215
+ except DhError as exc:
216
+ # The format flag governs the error path too
217
+ write_error(exc, _error_format())
218
+ raise SystemExit(exc.exit_code) from exc
219
+ except KeyboardInterrupt:
220
+ typer.echo("Interrupted.", err=True)
221
+ raise SystemExit(ExitCode.INTERRUPTED) from None
222
+ except Exception as exc: # noqa: BLE001 - last resort, reported not swallowed
223
+ print(f"Error: {exc}", file=sys.stderr)
224
+ raise SystemExit(ExitCode.FAILURE) from exc
dh/output/__init__.py ADDED
@@ -0,0 +1,175 @@
1
+ """Rendering: one envelope for machines, a plain table for people.
2
+
3
+ Three rules hold everywhere, and each is a defect observed in a shipping CLI:
4
+
5
+ * **stdout carries only the payload.** Progress, warnings and errors go to stderr,
6
+ so `dh ... | jq` never chokes on a status line.
7
+ * **`--format json` covers the error path too.**
8
+ * **No box-drawing characters, ever.**
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import csv
14
+ import io
15
+ import json
16
+ import os
17
+ import sys
18
+ from enum import Enum
19
+ from typing import Any, TextIO
20
+
21
+ from dh.errors import DhError
22
+
23
+
24
+ class Format(str, Enum):
25
+ JSON = "json"
26
+ TABLE = "table"
27
+ CSV = "csv"
28
+
29
+
30
+ def default_format(stream: TextIO | None = None) -> Format:
31
+ """`table` for a terminal, `json` for anything else.
32
+
33
+ Someone who pipes `dh` into `jq` without reading the docs gets JSON, and a
34
+ script never accidentally parses a table laid out for human eyes.
35
+ """
36
+ stream = stream or sys.stdout
37
+ try:
38
+ interactive = stream.isatty()
39
+ except (AttributeError, ValueError): # pragma: no cover - detached stream
40
+ interactive = False
41
+ return Format.TABLE if interactive else Format.JSON
42
+
43
+
44
+ def color_enabled(stream: TextIO | None = None, *, no_color: bool = False) -> bool:
45
+ """Colour only for a terminal that has not asked us to stop.
46
+
47
+ Honours `NO_COLOR` (any non-empty value) per https://no-color.org.
48
+ """
49
+ if no_color or os.environ.get("NO_COLOR"):
50
+ return False
51
+ stream = stream or sys.stdout
52
+ try:
53
+ return stream.isatty()
54
+ except (AttributeError, ValueError): # pragma: no cover - detached stream
55
+ return False
56
+
57
+
58
+ def envelope(data: Any, cursor: str | None = None, has_more: bool = False) -> dict[str, Any]:
59
+ """The one JSON shape every command emits.
60
+
61
+ Fixed for the life of the CLI: once CI parses `.data[]` it cannot change. The
62
+ `cursor` and `has_more` keys are present even for endpoints that never
63
+ paginate, so a consumer never has to know which kind an endpoint is.
64
+ """
65
+ return {"data": data, "cursor": cursor, "has_more": has_more}
66
+
67
+
68
+ # --- Tabular shaping -------------------------------------------------------
69
+
70
+
71
+ def columns_of(rows: list[dict[str, Any]]) -> list[str]:
72
+ """Column order: first-seen wins, then any key a later row adds.
73
+
74
+ Sorting would scramble the order the server chose, which usually puts the
75
+ identifying fields first.
76
+ """
77
+ seen: list[str] = []
78
+ for row in rows:
79
+ for key in row:
80
+ if key not in seen:
81
+ seen.append(key)
82
+ return seen
83
+
84
+
85
+ def as_grid(data: Any) -> tuple[list[str], list[list[Any]]]:
86
+ """Coerce whatever a command produced into columns and rows.
87
+
88
+ Handles the three shapes commands actually return: a list of records, a
89
+ single record, and ``RowsPageOut``'s already-tabular ``{columns, rows}``.
90
+ """
91
+ if isinstance(data, dict) and isinstance(data.get("rows"), list):
92
+ cols = [str(c) for c in data.get("columns") or []]
93
+ # `RowsPageOut.rows` is a list of **dicts keyed by column name**, not a list
94
+ # of positional lists. Projecting through `columns` keeps the server's
95
+ # column order and tolerates a row missing a key. A row that really is a
96
+ # sequence (the REPL's DB-API path) is taken as already positional.
97
+ return cols, [
98
+ [r.get(c) for c in cols] if isinstance(r, dict) else list(r) for r in data["rows"]
99
+ ]
100
+ if isinstance(data, dict):
101
+ return ["field", "value"], [[k, v] for k, v in data.items()]
102
+ if isinstance(data, list) and data and all(isinstance(r, dict) for r in data):
103
+ cols = columns_of(data)
104
+ return cols, [[row.get(c) for c in cols] for row in data]
105
+ if isinstance(data, list):
106
+ return ["value"], [[item] for item in data]
107
+ return ["value"], [[data]]
108
+
109
+
110
+ def cell(value: Any) -> str:
111
+ """One cell as text. Empty is shown, not implied."""
112
+ if value is None:
113
+ return "-"
114
+ if isinstance(value, bool):
115
+ return "true" if value else "false"
116
+ if isinstance(value, (dict, list)):
117
+ return json.dumps(value, separators=(",", ":"), default=str)
118
+ return str(value)
119
+
120
+
121
+ _BOLD = "\033[1m"
122
+ _RESET = "\033[0m"
123
+
124
+
125
+ def render_table(columns: list[str], rows: list[list[Any]], *, color: bool = False) -> str:
126
+ """Space-aligned columns. No borders, no glyphs, nothing to strip."""
127
+ if not columns:
128
+ return ""
129
+ text = [[cell(v) for v in row] for row in rows]
130
+ widths = [
131
+ max(len(columns[i]), *(len(r[i]) for r in text)) if text else len(columns[i])
132
+ for i in range(len(columns))
133
+ ]
134
+ header = " ".join(col.ljust(widths[i]) for i, col in enumerate(columns)).rstrip()
135
+ lines = [f"{_BOLD}{header}{_RESET}" if color else header]
136
+ lines.extend(
137
+ " ".join(value.ljust(widths[i]) for i, value in enumerate(row)).rstrip() for row in text
138
+ )
139
+ return "\n".join(lines)
140
+
141
+
142
+ def render_csv(columns: list[str], rows: list[list[Any]]) -> str:
143
+ buffer = io.StringIO()
144
+ writer = csv.writer(buffer, lineterminator="\n")
145
+ writer.writerow(columns)
146
+ writer.writerows([cell(v) for v in row] for row in rows)
147
+ return buffer.getvalue().rstrip("\n")
148
+
149
+
150
+ # --- Writing ---------------------------------------------------------------
151
+
152
+
153
+ def render(
154
+ data: Any,
155
+ fmt: Format,
156
+ *,
157
+ cursor: str | None = None,
158
+ has_more: bool = False,
159
+ color: bool = False,
160
+ ) -> str:
161
+ if fmt is Format.JSON:
162
+ return json.dumps(envelope(data, cursor, has_more), indent=2, default=str)
163
+ columns, rows = as_grid(data)
164
+ if fmt is Format.CSV:
165
+ return render_csv(columns, rows)
166
+ return render_table(columns, rows, color=color)
167
+
168
+
169
+ def write_error(error: DhError, fmt: Format, *, stream: TextIO | None = None) -> None:
170
+ """Write a failure to stderr, in JSON when JSON was asked for."""
171
+ stream = stream or sys.stderr
172
+ if fmt is Format.JSON:
173
+ stream.write(json.dumps(error.envelope(), indent=2, default=str) + "\n")
174
+ else:
175
+ stream.write(f"Error: {error.message}\n")