Required plugin settings (M5 part 2a)

[txoof-bot]

Part of #238 (M5 web interface, part 2a)

What changed

Plugins can now mark a setting as required: a setting the plugin can't work without, such as a place, an email address or an API key. Agreed with txoof in the terminal on 2026-10-07 (option B).

• paperpi.plugin.setting(default, required=True, ...): pydantic's Field plus PaperPi's own options. This is the one standard place for a setting's options; later ones (the web location helper that looks up latitude and longitude, part 3c) go here too. A required setting's default must be "not set" (None, empty text or an empty secret), or the plugin is refused as broken.
• A plugin that is switched on but missing a required setting is not shown and not counted as broken. The config check gives a warning naming the settings, paperpi list shows needs email in its "on" column, and paperpi run counts only the plugins it shows. Filling the setting in and reloading starts the plugin.
• met_no and moon_phase require lat, lon and email. met.no's terms of service ask for a real email address.
• paperpi render --live stops early and names the missing settings.

Choices I made without asking (please check):

1. The example config no longer fills in you@example.com: that made-up address would be sent to met.no. The example still loads without errors, but the two weather blocks are not shown (and warn) until you fill in email. README and config-format.md say so.
2. The default plugin's message for "nothing to show" is now "No plugins are ready to show." (was "No plugins are switched on."), because a plugin can be switched on and still wait for its settings.
3. Text of only spaces counts as "not set" (for future API keys).

Docs: docs/writing-plugins.md, update notes in docs/decisions/plugin-interface.md, config-format.md, live-config-reload.md; README; met_no and moon_phase READMEs.

Next parts (listed in #238): 2b Active Plugins + Plugin Library pages (shows "Needs settings" in place of the on switch), 3a settings form, 3b Preview, 3c location lookup, 4, 5.

Note for after the splash_screen PR (#236) merges: its texts say "no plugin is switched on"; they should say "no plugin is ready to show". Its code needs no change (it uses the scheduler's list, which already leaves these plugins out).

Area

core (src/paperpi/plugin.py, config.py, scheduler.py, cli.py, example.py), plugins/met_no, plugins/moon_phase, plugins/default, docs, paperpi.example.toml. config.py and plugin.py are shared files: the only other open PR changing them is #236 (adds one [display] setting; no overlap with PluginEntry).

Tests

New tests for setting() / is_set / missing, the config warning and its line, the scheduler (not updated; starts after the email is filled in; leaves the screen when the email is removed; default plugin when every plugin waits), paperpi list (needs lat, lon, email vs no), the paperpi run count, render --live, and the example's "(required)" comments.

• uv run pytest passes (1123 passed)
• uv run ruff check . passes
• Hardware tests: not needed (no display or driver code changed)

Review

• Review agents' comments answered. Four reviews (code quality, tests, security, docs) were run before the first push and fixed in the second commit: setting() keeps other json_schema_extra values, needs a default, and is_required survives a wrongly shaped option; screen message and docstrings; plain wording in docs; tests for the run count, list, reload and default screen. Not done here: on screen nothing says that a plugin waits for settings while others run (part 2b shows it in the web interface); webrequest still sends the email in the User-Agent after a redirect to another server (older code, small risk, separate follow-up).

Only txoof approves and merges this PR.

🤖 Generated with Claude Code

[txoof-bot]

Merged main into this branch to fix the conflicts: first the splash_screen plugin (#236), then again for #237 (newyorker) and #243 (splash screen uses [web] port). The conflicts were only in explanation text. While merging:

• Texts that said "no plugin is switched on" now say "no plugin is ready to show" (switched on, with all its required settings filled in): scheduler, splash_screen, the splash_time help text (and paperpi.example.toml), README, plugin-scheduling.md, live-config-reload.md. The code already used this rule.
• A test changed: when every plugin waits for its settings, the splash screen now stays on the screen (like with no plugins at all); only when it fails does "No plugins are ready to show." appear.

All tests pass (1258); CI green. #244 and #245 have the same merges.