Clients take a flow's id or key: one resolver in the SDK, id first, explicit id:/key:, a warning for reads and a refusal for changes when a name means two flows, deleted flows found by their last key; sync creates by POST, retries a create race through the drift checks and reports the id; MCP gets create_flow and resolves every flow argument with the caller's token; displays show flow_name; an engine from before ids is named as such

This commit is contained in:
2026-11-02 19:39:14 +01:00
parent fd637e0f1e
commit 53916d869b
20 changed files with 816 additions and 147 deletions
+47 -17
View File
@@ -43,6 +43,7 @@ from fluksio.sdk.client import (
sync,
)
from fluksio.sdk.declare import ImportFailed, declare, declare_module
from fluksio.sdk.resolve import Unresolved
__all__ = ["add_parsers", "discover"]
@@ -72,6 +73,21 @@ def _fail(message: str) -> int:
NO_ENGINE = "Is one running? `fluksio serve` starts one."
@contextmanager
def _plain_warnings() -> Iterator[None]:
"""What the SDK warns about, one line each on stderr.
A terminal wants the sentence, not where in the library it was raised.
"""
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
try:
yield
finally:
for warning in caught:
print(f"fluksio: warning: {warning.message}", file=sys.stderr)
def _unreachable(exc: Exception, note: str = NO_ENGINE) -> int:
"""The engine did not answer. Say so as a sentence, not a traceback."""
return _fail(
@@ -387,15 +403,19 @@ def cmd_sync(args: argparse.Namespace) -> int:
return _unreachable(exc, "Nothing was published; sync again when it is back.")
for report in reports:
# The id too when it is not the key, since that is what a URL holds.
name = (
report.flow if report.id == report.flow else f"{report.flow} ({report.id})"
)
if report.unchanged:
_say(f" {report.flow}: unchanged")
_say(f" {name}: unchanged")
continue
what = "created" if report.created else "updated"
detail = ", ".join(report.changed)
# Nothing to publish is not the same as left as a draft, and saying
# the second when it was the first reads as work not finished.
state = "published" if report.published else "draft" if report.drafted else ""
_say(f" {report.flow}: {what} ({detail})" + (f" — {state}" if state else ""))
_say(f" {name}: {what} ({detail})" + (f" — {state}" if state else ""))
if any(report.forgot_code for report in reports):
engine = _engine_version(client)
_say(
@@ -533,7 +553,13 @@ def _declaration(client: Client, flow: str) -> tuple[str, str, Path] | None:
"""
if not flow:
return None
stored = client.get_flow(flow) or {}
try:
# As the run that follows will: a name two flows answer to is refused
# there, and not guessed at here.
flow_id = client.resolve_flow(flow, mutation=True).id
except Unresolved:
return None
stored = client.get_flow(flow_id) or {}
origin = (stored.get("definition") or {}).get("origin") or {}
declared_in = str(origin.get("declared_in") or "")
module = str(origin.get("module") or "")
@@ -716,7 +742,9 @@ def cmd_run(args: argparse.Namespace, rest: list[str]) -> int:
with _client_for(args) as client:
if not args.no_sync:
_sync_first(client, args.sync, args.flow)
stored = client.get_flow(args.flow)
# After the sync, which may be what creates it.
flow_id = client.resolve_flow(args.flow, mutation=True).id
stored = client.get_flow(flow_id)
if stored is None:
return _fail(f"no flow '{args.flow}' on that engine")
definition = stored.get("definition") or {}
@@ -732,7 +760,7 @@ def cmd_run(args: argparse.Namespace, rest: list[str]) -> int:
):
params = _ask_params(definition)
handle = client.submit(
args.flow,
f"id:{flow_id}",
params,
seed=args.seed,
no_cache=args.no_cache,
@@ -938,7 +966,7 @@ def _status_screen(client: Client) -> Any:
state, "red" if state == "error" else "yellow"
),
),
Text(str(row.get("flow", "")), style="dim"),
Text(str(row.get("flow_name") or row.get("flow", "")), style="dim"),
Text(_dur(row.get("duration_ms")), style="dim"),
Text(
_ago(row.get("finished_at") or row.get("created_at")), style="dim"
@@ -952,7 +980,9 @@ def _status_screen(client: Client) -> Any:
broken.add_column("")
for event in failures:
where = " ".join(
str(event.get(key, "")) for key in ("flow", "node") if event.get(key)
str(event.get(key, ""))
for key in ("flow_name", "node")
if event.get(key)
)
broken.add_row(
Text(f" {where}", style="red"),
@@ -1076,7 +1106,8 @@ def _stamp(row: dict[str, Any]) -> str:
def cmd_runs(args: argparse.Namespace) -> int:
try:
with _client_for(args, retries=0) as client:
rows = client.runs(flow=args.flow, limit=args.limit)
with _plain_warnings():
rows = client.runs(flow=args.flow, limit=args.limit)
declared = _declared(client, {str(row["flow"]) for row in rows})
except (SyncError, ApiError) as exc:
return _fail(str(exc))
@@ -1100,8 +1131,9 @@ def cmd_runs(args: argparse.Namespace) -> int:
params = json.dumps(shown)
if len(params) > room:
params = params[: room - 3] + "..."
flow = row.get("flow_name") or row["flow"]
_say(
f"{row['id']} {_status(row['status'], 9)} {row['flow']:<16} "
f"{row['id']} {_status(row['status'], 9)} {flow:<16} "
f"{_dur(row['duration_ms']):>8} {_ago(row.get('created_at')):>9} "
f"{_stamp(row):<22} {params}"
)
@@ -1269,11 +1301,12 @@ def cmd_sweep(args: argparse.Namespace) -> int:
with _client_for(args) as client:
if not args.no_sync:
_sync_first(client, args.sync, args.flow)
stored = client.get_flow(args.flow)
flow_id = client.resolve_flow(args.flow, mutation=True).id
stored = client.get_flow(flow_id)
if stored is None:
return _fail(f"no flow '{args.flow}' on that engine")
entries = _grid(stored.get("definition") or {}, args.param, args.seed)
handles = client.sweep(args.flow, entries, no_cache=args.no_cache)
handles = client.sweep(f"id:{flow_id}", entries, no_cache=args.no_cache)
for handle, entry in zip(handles, entries, strict=True):
_say(f"{handle.id} queued {json.dumps(entry['params'])}")
if not wait:
@@ -1401,13 +1434,10 @@ def _export(
try:
with _client_for(args, retries=0) as client:
try:
if getattr(args, "list_names", False):
return _list_names(client, args)
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
with _plain_warnings():
if getattr(args, "list_names", False):
return _list_names(client, args)
rows = fetch(client)
for warning in caught:
print(f"fluksio: warning: {warning.message}", file=sys.stderr)
except ApiError as exc:
if exc.status != 404:
raise