animedex.render.jq

--jq <expr> post-filter via the native jq Python wheel.

The jq wheel statically links libjq, so the engine version is pinned at install time rather than inherited from whatever the host distribution ships. This means:

  • The frozen-binary distribution (PyInstaller make build) ships with jq linked in — Windows users no longer need to install jq separately to use --jq.

  • Per-call cost is in-process — no subprocess spawn, no UTF-8 round trip, no Windows cp1252 trap.

  • selftest() does a real round-trip in well under 100 ms, so the offline diagnostic catches binding regressions.

The output of jq.compile.input_text(payload).text() matches the default jq shape (one JSON value per line for multi-emit filters), so callers see the same string a host jq would produce.

apply_jq

animedex.render.jq.apply_jq(payload: str, expression: str) → str[source]

Filter payload (JSON text) through expression.

Parameters:

  • payload (str) – JSON text to filter.

  • expression (str) – jq filter expression (e.g. ".title.romaji").

Returns:

jq’s stringified output. Multi-emit filters produce one value per line, matching the default jq shape.

Return type:

str

Raises:

ApiError – reason="jq-missing" when the wheel is not importable. With jq>=1.11 listed as a hard runtime dependency, this is reachable only if a user has deliberately broken their install (pip uninstall jq) — the typed error gives them a friendlier message than a raw ImportError. reason="jq-failed" when the expression fails to compile or execute, or when payload is not valid JSON (libjq raises ValueError from input_text in that case too).

selftest

animedex.render.jq.selftest() → bool[source]

Smoke-test the binding with a real .input_text round-trip.