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
+71 -1
View File
@@ -3,7 +3,26 @@
import httpx
import pytest
from fluksio.sdk import SyncError
from fluksio.sdk.client import WAIT_TOLERANCE, ApiError, Client, RunHandle
from fluksio.sdk.resolve import Unresolved
#: What the engine lists: `train` under an issued id, and the grandfathered
#: `heating`, now keyed `warmth`, whose old key a later flow took.
LISTED = [
{"id": "f_train000", "name": "train"},
{"id": "heating", "name": "warmth"},
{"id": "f_heat0000", "name": "heating"},
]
def listing(request):
"""The engine's answer to the lookups a flow argument costs, else None."""
if request.url.path == "/api/v1/flows/":
return httpx.Response(200, json={"data": LISTED, "count": len(LISTED)})
if request.url.path == "/api/v1/runs/overview":
return httpx.Response(200, json=[])
return None
def a_client(handler, monkeypatch, **kwargs):
@@ -65,6 +84,9 @@ def test_submit_carries_one_key_across_its_retries(monkeypatch):
bodies = []
def handler(request):
if listed := listing(request):
return listed
assert request.url.path == "/api/v1/runs/flows/f_train000"
bodies.append(httpx.Response(200, content=request.content).json())
if len(bodies) < 3:
raise httpx.ConnectError("no route", request=request)
@@ -81,6 +103,8 @@ def test_a_sweep_keys_every_entry(monkeypatch):
seen = {}
def handler(request):
if listed := listing(request):
return listed
body = httpx.Response(200, content=request.content).json()
seen["runs"] = body["runs"]
return httpx.Response(202, json=[{"id": "r1"}, {"id": "r2"}])
@@ -137,6 +161,8 @@ def test_an_export_is_read_as_rows(monkeypatch):
seen = {}
def handler(request):
if listed := listing(request):
return listed
seen.update(request.url.params)
return httpx.Response(
200,
@@ -149,7 +175,8 @@ def test_an_export_is_read_as_rows(monkeypatch):
assert seen["format"] == "jsonl"
assert seen["ids"] == "r1,r2"
assert seen["flow"] == "train"
# The key, resolved: the API takes the id and only the id.
assert seen["flow"] == "f_train000"
assert seen["status"] == "ok"
assert [row["step"] for row in rows] == [0, 1]
@@ -201,3 +228,46 @@ def test_a_name_cannot_climb_out_of_its_route(monkeypatch):
"/api/v1/flows/%2E%2E/nodes/%2E%2E%2Fx/source",
"/api/v1/runs/%2E%2E",
]
def test_a_flow_argument_goes_through_the_resolver(monkeypatch):
"""A read of a name two flows answer to warns; a run of it is refused."""
asked = []
def handler(request):
if listed := listing(request):
return listed
asked.append(
f"{request.method} {request.url.path}?{request.url.query.decode()}"
)
return httpx.Response(200, json=[])
client = a_client(handler, monkeypatch)
with pytest.warns(UserWarning, match="Pass key:heating for the other"):
client.runs(flow="heating")
with pytest.raises(Unresolved, match="Pass id:heating or key:heating"):
client.submit("heating")
client.runs(flow="key:heating")
assert asked == [
"GET /api/v1/runs?limit=20&flow=heating",
"GET /api/v1/runs?limit=20&flow=f_heat0000",
]
def test_an_engine_from_before_ids_is_named_as_such(monkeypatch):
"""It lists flows without ids and has no route to create one by."""
def handler(request):
if request.method == "POST":
return httpx.Response(405, json={"detail": "Method Not Allowed"})
return httpx.Response(200, json={"data": [{"name": "train"}], "count": 1})
client = a_client(handler, monkeypatch)
for call in (
lambda: client.runs(flow="train"),
lambda: client.find_flow("train"),
lambda: client.create_flow({"name": "train"}),
):
with pytest.raises(SyncError, match="older than flow ids"):
call()
+4
View File
@@ -8,6 +8,7 @@ import pytest
from fluksio.sdk import FLOWS, SyncError, cli
from fluksio.sdk.declare import ImportFailed, declare, declare_module
from fluksio.sdk.resolve import Resolved
STUDY = """\
import os
@@ -131,6 +132,9 @@ def test_a_failing_import_is_reported_by_sync_and_warned_about_by_run(
assert "Traceback" in seen.err and "study.py" in seen.err
class Engine:
def resolve_flow(self, flow, **how):
return Resolved(flow, flow)
def get_flow(self, name):
return {
"definition": {"origin": {"declared_in": "study.py", "module": "study"}}
+74
View File
@@ -0,0 +1,74 @@
"""Which flow an argument names: the one matrix every client relies on."""
import pytest
from fluksio.sdk.resolve import Resolved, Unresolved, resolve
#: `heating` is the grandfathered id of the flow now keyed `warmth`; a later
#: flow took the key `heating` under an issued id.
FLOWS = [
("heating", "warmth"),
("f_k3q7m2xa", "heating"),
("train", "train"),
("f_aaaaaaaa", "lights"),
]
def test_an_id_alone_picks_its_flow():
assert resolve("f_aaaaaaaa", FLOWS) == Resolved("f_aaaaaaaa", "lights")
def test_a_key_alone_picks_its_flow():
assert resolve("lights", FLOWS) == Resolved("f_aaaaaaaa", "lights")
def test_an_id_that_is_its_own_key_is_no_ambiguity():
assert resolve("train", FLOWS, mutation=True) == Resolved("train", "train")
def test_one_flows_id_and_anothers_key_reads_the_id_with_a_warning():
found = resolve("heating", FLOWS)
assert (found.id, found.key) == ("heating", "warmth")
assert found.warning == (
"'heating' is the id of 'warmth' and the key of 'f_k3q7m2xa'. "
"Using the id. Pass key:heating for the other."
)
def test_a_change_refuses_a_name_two_flows_answer_to():
with pytest.raises(Unresolved, match="Pass id:heating or key:heating"):
resolve("heating", FLOWS, mutation=True)
def test_the_explicit_forms_say_which():
assert resolve("id:heating", FLOWS, mutation=True) == Resolved("heating", "warmth")
assert resolve("key:heating", FLOWS, mutation=True) == Resolved(
"f_k3q7m2xa", "heating"
)
def test_neither_names_the_closest_keys():
with pytest.raises(Unresolved) as caught:
resolve("lihgts", FLOWS)
assert str(caught.value) == (
"No flow with the id or key 'lihgts'. Closest keys: lights."
)
with pytest.raises(Unresolved, match="No flow with the key 'f_aaaaaaaa'"):
resolve("key:f_aaaaaaaa", FLOWS)
def test_an_explicit_id_outlives_its_flow():
"""History stays filed under a deleted flow's id, which nobody lists."""
assert resolve("id:f_gone0000", FLOWS) == Resolved("f_gone0000", "")
def test_a_key_history_holds_twice_is_refused_not_guessed():
"""A deleted flow and the later one that took its key."""
history = [("f_old00000", "train"), ("f_new00000", "train")]
for value in ("train", "key:train"):
with pytest.raises(Unresolved, match="f_old00000, f_new00000"):
resolve(value, history)
assert resolve("id:f_old00000", history) == Resolved("f_old00000", "train")