Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/onlyworlds/_version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.133.1"
__version__ = "0.134.0"
30 changes: 30 additions & 0 deletions src/onlyworlds/errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -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``."""
Expand Down
58 changes: 58 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
35 changes: 33 additions & 2 deletions tests/test_wire.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
Loading