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/__init__.py +20 -0
- dh/_version.py +24 -0
- dh/commands/__init__.py +0 -0
- dh/commands/admin.py +353 -0
- dh/commands/api.py +79 -0
- dh/commands/auth.py +266 -0
- dh/commands/catalog.py +426 -0
- dh/commands/dbt.py +272 -0
- dh/commands/grant.py +129 -0
- dh/commands/health.py +64 -0
- dh/commands/profile.py +80 -0
- dh/commands/query.py +239 -0
- dh/commands/saved.py +213 -0
- dh/commands/session.py +210 -0
- dh/config.py +263 -0
- dh/context.py +166 -0
- dh/errors.py +175 -0
- dh/execute.py +204 -0
- dh/introspect.py +78 -0
- dh/main.py +224 -0
- dh/output/__init__.py +175 -0
- dh/repl.py +158 -0
- dh/resolve.py +146 -0
- dh/rest.py +201 -0
- duckhaven_cli-0.1.0.dist-info/METADATA +69 -0
- duckhaven_cli-0.1.0.dist-info/RECORD +29 -0
- duckhaven_cli-0.1.0.dist-info/WHEEL +4 -0
- duckhaven_cli-0.1.0.dist-info/entry_points.txt +2 -0
- duckhaven_cli-0.1.0.dist-info/licenses/LICENSE +201 -0
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")
|