Setting helpers: a search box for plugin settings (M5 part 3c, 1 of 2)

[txoof-bot]

Part of #238 (M5 part 3c, first half). Design: docs/decisions/setting-helpers.md (new, agreed with txoof on 2026-10-10).

What changed

A plugin can now offer a setting helper: a search box under one of its settings on the settings page. You type something, PaperPi shows a list of choices, and Use puts the chosen values into the form. Nothing is saved until Save.

• Design note setting-helpers.md: PaperPi owns the page, the plugin owns its settings. A helper is a function of the plugin. It returns choices as dictionaries whose keys are kinds: fill (settings for the form), show (texts to help pick), link (http/https addresses), plus note for the whole result. Planned kinds (add, next, disabled, picture, wait for log-ins) are described but not built. Rejected and why: plugin-sent HTML, a map, helpers written in the web code. The command line comes later (see the new issue below).
• Core: paperpi/helper.py (Helper, Query, HelperProblem, clean), Plugin.helpers with checks (a setting naming a helper the plugin doesn't have fails the plugin check), runner.run_helper. A search runs in its own process with a 30 s time limit, like an update; the runner's process code is now shared by updates and searches.
• Web: search box just before the setting it fills (its own small form, so Enter searches instead of saving), list of choices, Use (htmx puts the filled fields in place). One search at a time.
• Safety: all texts are plain text; links only http/https; at most 10 choices, 10 entries each, texts cut to 200 characters; fill values must be plain (text, numbers, true/false, lists) and can't fill secrets; API keys are replaced with **** in everything a search returns; a helper's HelperProblem message is only used for searches (in an update it is an ordinary failure).
• Test helper: the debugging plugin's text setting has a words helper (each word becomes a choice; crash, hang, problem and many misbehave on purpose).
• Docs: "Setting helpers" section in docs/writing-plugins.md, including the rule not to send a saved secret to an address taken from the settings.

Size: +1484 / -156 (after the demo fixes), over the usual 800. txoof chose one PR over a core/web split (2026-10-10). About 120 lines only moved (the field template went into _field.html, so Use can reuse it), and the review fixes added about 190.

Next (PR 2): the location helper with Open-Meteo for met_no and moon_phase, and altitude for met_no (closes #176).

Area

core (helper.py, plugin.py, runner.py, limits.py, plugins/debugging/), web (src/paperpi/web/), docs. plugin.py changes the Plugin class, not PluginEntry; no other open PR changes these files.

Tests

New: tests/test_helper.py (result rules, plugin check, real plugin processes: choices, problem, crash, hang, API key hidden, HelperProblem in an update) and tests/test_web_helpers.py (search box and its own form, choices and escaping, failures, needs, button-only helper, one at a time, stop, Use and what it refuses, the log of left-out kinds, one real search).

• uv run pytest passes: 1528 passed (-n auto, 97 s on the Pi)
• uv run ruff check . passes
• Hardware tests run on the Pi (only if display or driver code changed): not needed

Images

No browser on the Pi for screenshots. A demo is running: http://192.168.1.224:8091/plugins/1/settings?id=met_no-4b8e2f61 (login off). It runs this PR plus the start of PR 2 (weather place search).

Review

• Review agents' comments answered. Three reviews ran on the Pi before pushing (code quality, security, tests and docs); fixed: HelperProblem from an update, plain fill values, API keys in choices, secret fills, size limits, deeply nested Use data, the Use route not checking its setting, typed=False still getting typed text, missing tests, doc wording. Left as follow-ups: a minimum wait between searches and one shared lock for searches and previews (today each has its own lock, so one search and one preview can run at the same time).

Only txoof approves and merges this PR.

🤖 Generated with Claude Code

[txoof-bot]

Changes after txoof tried the weather demo (2026-10-10), in 3 commits:

• The search box comes first, then the fields it fills (it was under its field, so it sat between Latitude and Longitude). It also has a light gray background.
• The name shown on the screen is always replaced by Use (design note and docs). Filling it only while empty set it once and never again. The rule lives in the helper (fill), so this changes only docs here; the location helper comes in PR 2.
• A search gets the browser's language (Query.language, from the Accept-Language header; only 2 or 3 letters are taken, en otherwise). Open-Meteo finds "Den Haag" only when asked in Dutch; PR 2 searches in English plus this language.

Also from the demo: issue #270 (portrait layouts are drawn as landscape).

Now +1484 / -156; 1528 tests pass on the Pi.

🤖 Generated with Claude Code