diff --git a/CHANGELOG.md b/CHANGELOG.md index 095c65d..ccc4efa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ The package version runs on its own semver; the schema it is generated from is ` ## Unreleased +## 0.134.0 (2026-11-17) + +- **`ApiError.fields_refusal`: everything a read's `fields` list got wrong, in one answer.** A read whose `fields` names fields the type does not have is one 422 with `param` `fields`, as before. Since 17 November 2026 onlyworlds.com names every unknown name in it, where it named only the first: the message lists them, and the error carries `unknown_fields` (each unknown name once, in the order sent), `types_with_field` (for each one another element type has, those types) and `allowed_fields` (the names this type takes). `fields_refusal` returns the three as a dict, as served, so a caller corrects the list in one try; it is `None` for any other error. A list with one unknown name keeps the message it always had, and no code in the package read that message. The npm SDK's `err.fieldsRefusal`, in 4.179.0. + ## 0.133.1 (2026-11-17) - **The LegendKeeper door says where the API's unsupported content can be read.** LegendKeeper's public API answers some blocks and properties as `unsupported`, with nothing in them. On a project seeded with LegendKeeper's tutorial these were every image inside a page (28), a list of sub-pages and the sidebar rows showing a resource's tags or aliases (17). The report's line now says that the export file holds them and that `--file` reads them. diff --git a/src/onlyworlds/_version.py b/src/onlyworlds/_version.py index 5bda946..6bf5a11 100644 --- a/src/onlyworlds/_version.py +++ b/src/onlyworlds/_version.py @@ -1 +1 @@ -__version__ = "0.133.1" +__version__ = "0.134.0" diff --git a/src/onlyworlds/errors.py b/src/onlyworlds/errors.py index deb6325..7654605 100644 --- a/src/onlyworlds/errors.py +++ b/src/onlyworlds/errors.py @@ -250,6 +250,36 @@ def refusals(self) -> list[dict[str, Any]] | None: out.append({"word": word, "stop_reason": stop, "output_tokens": tokens}) return out + @property + def fields_refusal(self) -> dict[str, Any] | None: + """What a read's ``fields`` list got wrong, from a 422 whose ``param`` is ``fields``: the + server refuses the whole list once, naming every field the type does not have, so the list + is corrected in one try. ``{"unknown_fields", "types_with_field", "allowed_fields"}`` as + served: every unknown name in the order sent; for each one another element type has, those + types; the names this type takes. None for any other error, or when the server sends no + ``unknown_fields``; an entry that is not a string is left out (as the npm SDK's + ``err.fieldsRefusal``).""" + if not (self.status == 422 and self.param == "fields"): + return None + raw_error = _envelope(self.response.body).get("error") + if not isinstance(raw_error, dict) or not isinstance(raw_error.get("unknown_fields"), list): + return None + + def strings(value: Any) -> list[str]: + return [s for s in value if isinstance(s, str)] if isinstance(value, list) else [] + + held = raw_error.get("types_with_field") + types_with_field: dict[str, list[str]] = {} + if isinstance(held, dict): + for name, types in held.items(): + if isinstance(name, str) and isinstance(types, list): + types_with_field[name] = strings(types) + return { + "unknown_fields": strings(raw_error.get("unknown_fields")), + "types_with_field": types_with_field, + "allowed_fields": strings(raw_error.get("allowed_fields")), + } + @property def is_busy(self) -> bool: """keel's admission control turned the request away (503 ``server_busy``); see ``retry_after``.""" diff --git a/tests/test_client.py b/tests/test_client.py index 305a807..52fe523 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -1177,6 +1177,64 @@ def test_refusals_leaves_out_a_row_not_in_its_shape() -> None: assert _refused([*bad, good]).refusals == [good] +def _fields_refused(status: int = 422, **changes: Any) -> ApiError: + """The server's answer to fields=name,story,hidden,narrator,nonsuch on a Character list, its + allowed list cut to four names; a change of ``...`` removes that key.""" + error: dict[str, Any] = { + "type": "invalid_request", + "code": "invalid_request", + "message": "Unknown fields in ?fields: story, hidden, narrator, nonsuch", + "param": "fields", + "doc_url": "https://onlyworlds.github.io/api/errors/#invalid_request", + "unknown_fields": ["story", "hidden", "narrator", "nonsuch"], + "types_with_field": {"story": ["narrative"], "narrator": ["narrative"]}, + "allowed_fields": ["id", "name", "description", "supertype"], + } + for key, value in changes.items(): + if value is ...: + del error[key] + else: + error[key] = value + return ApiError("GET", "x", jresp(status, {"error": error})) + + +def test_fields_refusal_reads_the_three_keys_of_a_422_on_fields_as_served() -> None: + assert _fields_refused().fields_refusal == { + "unknown_fields": ["story", "hidden", "narrator", "nonsuch"], + "types_with_field": {"story": ["narrative"], "narrator": ["narrative"]}, + "allowed_fields": ["id", "name", "description", "supertype"], + } + + +def test_fields_refusal_is_none_on_any_other_error_each_condition_alone() -> None: + assert _fields_refused(unknown_fields=...).fields_refusal is None + assert _fields_refused(param="expand").fields_refusal is None + assert _fields_refused(status=400).fields_refusal is None + assert _fields_refused(unknown_fields="story").fields_refusal is None + + +def test_fields_refusal_leaves_out_what_is_not_in_shape_and_answers_empty_for_a_missing_key() -> None: + odd = _fields_refused( + unknown_fields=["story", 7, None], + types_with_field={"story": ["narrative", 3], "narrator": "narrative"}, + allowed_fields=["id", {}, "name"], + ) + assert odd.fields_refusal == { + "unknown_fields": ["story"], + "types_with_field": {"story": ["narrative"]}, + "allowed_fields": ["id", "name"], + } + thin = _fields_refused(types_with_field=..., allowed_fields=...) + assert thin.fields_refusal == { + "unknown_fields": ["story", "hidden", "narrator", "nonsuch"], + "types_with_field": {}, + "allowed_fields": [], + } + as_list = _fields_refused(types_with_field=[["story", ["narrative"]]]).fields_refusal + assert as_list is not None + assert as_list["types_with_field"] == {} + + def test_search_sends_q_and_each_option_under_its_wire_name(make_client: MakeClient) -> None: """As the npm SDK's search (4.150.0): GET /search, q always, type, limit and as only when given.""" answer = {"query": "APP-142", "results": [], "count": 0, "truncated": False} diff --git a/tests/test_wire.py b/tests/test_wire.py index 8a6d9b5..015751f 100644 --- a/tests/test_wire.py +++ b/tests/test_wire.py @@ -486,9 +486,40 @@ def test_every_key_of_the_error_envelope_reaches_apierror(doc: dict[str, Any]) - err = doc["components"]["schemas"]["Error"]["properties"]["error"] five = {"type", "code", "message", "param", "doc_url"} # With the hidden mark on, a 409 resync_required's envelope also carries `reason`; an AI use's - # 422 answer_not_parsed carries `refusals`. Each is allowed only when declared, and then read. - assert set(err["properties"]) - five <= {"reason", "refusals"} + # 422 answer_not_parsed carries `refusals`; a 422 on a read's `fields` list carries + # `unknown_fields`, `types_with_field` and `allowed_fields`. Each is allowed only when declared, + # and then read. + fields_keys = ("unknown_fields", "types_with_field", "allowed_fields") + assert set(err["properties"]) - five <= {"reason", "refusals", *fields_keys} assert five <= set(err["properties"]) + declared = [k for k in fields_keys if k in err["properties"]] + if declared: + # each probe value is built from the kind the document declares; an unknown kind fails here + probe: dict[str, Any] = {} + for k in declared: + d = err["properties"][k] + if d.get("type") == "array": + assert d["items"] == {"type": "string"}, k + probe[k] = [f"probe-{k}-1", f"probe-{k}-2"] + else: + assert d.get("type") == "object", k + assert d["additionalProperties"] == {"type": "array", "items": {"type": "string"}}, k + probe[k] = {f"probe-{k}": ["probe-type-1", "probe-type-2"]} + probe.setdefault("unknown_fields", ["probe-name"]) + refused_fields = { + "error": { + "type": "invalid_request", + "code": "invalid_request", + "message": "m", + "param": "fields", + "doc_url": "https://x/e", + **probe, + } + } + got_fields = ApiError("GET", "x", jresp(422, refused_fields)).fields_refusal + assert got_fields is not None + for k in declared: + assert got_fields[k] == probe[k], k if "refusals" in err["properties"]: refused = { "error": {