Files
MeshTerm/meshterm/ui/preferences.py
T
Jean-Pierre MartineauandClaude Fable 5.1 c9f5a71ce7 Every Python file names its licence with an SPDX identifier
Apache-2.0 does not require per-file headers, but a file lifted out of the tree carried no marking at all. One comment line, first (or right after a shebang), on every .py under meshterm/, tests/, packaging/ and scripts/, plus the extensionless SPI bridge; tests/test_spdx.py keeps a new file from landing without one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-13 13:09:18 -04:00

450 lines
18 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The Preferences page: MeshTerm's own behaviour, staged and saved.
The app-side twin of the device-configuration editor (:mod:`meshterm.ui.config_editor`),
built out of the same parts on purpose — one grouped, lane-aligned list; a row that stages
``current → new`` in the warn style; an Apply/Back pair that appears only once something
is staged; the shared discard confirm on the way out. Two editors that stage values should
not be two different screens to learn, so the only things that differ here are what is
being edited (:mod:`meshterm.core.preferences`, not the radio) and where Apply writes
(``preferences.toml``, not the companion).
Its rows scroll sideways, which the device editor's do not: a preference's explanation is
the widest thing on its row and the only part that runs past the edge, so ←→ slide the
DESCRIPTION lane under a pinned setting and value rather than letting it die at the fold.
What the page adds is the **Defaults** section: one row that stages every preference back
to its built-in default. It follows the same rule the Apply/Back pair does — it is drawn
only while there is something to reset, because a row offering to undo nothing is a row
that does nothing. Resetting *stages*; it does not write. So the reset is as reviewable,
and as discardable with Esc, as any other change on the page, and the file is still only
ever written by the one action at the bottom.
:func:`preferences_table` is the same content as a printed table, for the CLI's
``preferences show``.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from rich import box
from rich.cells import cell_len
from rich.table import Table
from rich.text import Text
from ..core.preferences import (
PREFERENCES,
PreferenceError,
Preferences,
PrefSpec,
by_group,
format_value,
get_spec,
parse_value,
range_hint,
)
from ..platforms import get_platform
from ..services import consolefont
from .menus import (
confirm_discard,
exit_rows,
lane_header,
lane_row,
section_heading,
)
from .tui import Choice, Separator
if TYPE_CHECKING:
from ..context import AppContext
#: Menu action sentinels, distinct from the plain-string preference keys the rows carry.
_RESET = "__reset__"
_APPLY = "__apply__"
_CANCEL = "__cancel__"
async def edit_preferences(ctx: AppContext) -> dict[str, Any] | None:
"""Run the Preferences editor and return the values to save.
Nothing is written here: the staged map goes back to
:class:`~meshterm.tools.preferences.PreferencesTool` to apply and log, the same
division of labour the device-config editor keeps with its own tool.
Args:
ctx: Shared application context (provides the preferences and the UI surface).
Returns:
The staged ``key -> value`` map to write, or ``None`` if the reader left with
nothing staged (or chose to discard what was).
"""
from .tui import CANCEL, SelectScreen
session = getattr(ctx.ui, "session", None)
if session is None: # pragma: no cover - guarded by the menu-only caller
raise RuntimeError("the preferences editor is only available in the menu")
prefs = ctx.preferences
pending: dict[str, Any] = {} # preference key -> staged new value
# The console font previews. A VT loads one font for the whole screen, so the only
# honest way to show what the 6x8 build looks like is to load it — and this page is
# the preview: it repaints at the new row count the moment the value is picked.
# ``shown`` is what the console is drawn in right now; a discard puts the saved value
# back, and Apply's own re-apply after the write finds nothing to change.
previewing = consolefont.applies()
shown = prefs.get(consolefont.PREFERENCE_KEY)
def preview() -> None:
nonlocal shown
if not previewing:
return
want = _effective(prefs, consolefont.PREFERENCE_KEY, pending)
if want != shown and consolefont.apply(want):
shown = want
# The rows *are* the data — each carries its own staged ``current → new`` value and
# the title counts what is staged — so they refresh in place after every round
# (``replace_items``) rather than being rebuilt as a new screen. One screen for the
# whole visit means the typed filter survives editing a preference, not just the cursor.
title, items = _menu_items(prefs, pending)
menu = SelectScreen(
title,
items,
footer_hint="↑↓ move · type to filter · Enter select · Esc back",
)
async with session.stay(menu) as visit:
while True:
choice = await visit.result()
if choice is CANCEL: # Esc at the list
choice = _CANCEL
if choice in (None, _CANCEL):
if pending and not await confirm_discard(ctx, len(pending), verb="saving"):
continue # keep editing — the same list, the same place in it
if previewing and shown != prefs.get(consolefont.PREFERENCE_KEY):
consolefont.apply(prefs.get(consolefont.PREFERENCE_KEY))
return None
if choice == _APPLY:
return dict(pending) or None
if choice == _RESET:
await _stage_reset(ctx, prefs, pending)
else: # a preference key
await _stage_preference(ctx, prefs, choice, pending)
preview()
title, items = _menu_items(prefs, pending)
menu.replace_items(items, title=title)
# --- rendering ----------------------------------------------------------------
def _effective(prefs: Preferences, key: str, pending: dict[str, Any]) -> Any:
"""What ``key`` would be worth if the staged changes were applied right now."""
return pending[key] if key in pending else prefs.get(key)
def _resettable(prefs: Preferences, pending: dict[str, Any]) -> list[str]:
"""The keys whose *effective* value differs from their default — what a reset would touch.
Staged values count, so a preference edited this visit is resettable before it is ever
saved, and one staged back to its own default already isn't.
"""
return [
spec.key for spec in _all_specs() if _effective(prefs, spec.key, pending) != spec.default
]
def _page_groups() -> list[tuple[str, list[PrefSpec]]]:
"""The groups this page draws — everything the *running* platform is offered.
A preference gated to another flavour (the PicoCalc's console font, on a desktop) is a
row whose question this machine cannot answer, so it is not drawn. Its value is still
in the registry and still round-trips through the file, which is what keeps a
``preferences.toml`` written on the handheld from being quietly emptied by a desktop.
"""
return by_group(get_platform().name)
def _all_specs() -> list[PrefSpec]:
"""Every spec the page draws, in page order (the grouping flattened)."""
return [spec for _, specs in _page_groups() for spec in specs]
#: Cell cap on *each side* of a VALUE lane's ``current → staged``. The lane is sized to
#: its widest row, and the description lane gets whatever is left — so one long value (the
#: basemap URL, at 36 cells) would otherwise spend a third of the screen on itself and
#: shred every other row's prose down to an ellipsis. Capped, only that row is shortened,
#: and the row still opens to a prompt showing the value in full.
_VALUE_CAP = 20
def _capped(text: str) -> Text:
"""One side of a VALUE lane, shortened to :data:`_VALUE_CAP` with an ellipsis."""
value = Text(text)
value.truncate(_VALUE_CAP, overflow="ellipsis")
return value
def _preference_value(prefs: Preferences, spec: PrefSpec, pending: dict[str, Any]) -> Text:
"""One preference's VALUE lane: ``current [→ staged]``.
The staged arrow is drawn in the warn style so a dirty row stands out at a glance; the
span survives the select highlight, which only tints the row's base style. Both sides
are capped independently, so a staged change never hides behind the value it replaces.
"""
value = _capped(format_value(spec, prefs.get(spec.key)))
if spec.key in pending:
staged = _capped(format_value(spec, pending[spec.key]))
value.append(" → ", style="warn")
value.append_text(Text(staged.plain, style="warn"))
return value
def _menu_items(prefs: Preferences, pending: dict[str, Any]) -> tuple[str, list]:
"""Build the page's title and rows for the current values plus whatever is staged.
The rows sit in three aligned lanes — preference, current value (and any staged new
value), description — under one pinned header, so the page reads as the editor it is.
"""
sections: list[tuple[str, list[tuple[str, Text, str, Any]]]] = []
for group, specs in _page_groups():
sections.append(
(
group,
[
(
spec.label,
_preference_value(prefs, spec, pending),
spec.description,
spec.key,
)
for spec in specs
],
)
)
# The reset row is drawn only while a reset would do something, for the reason the
# Apply/Back pair is drawn only while something is staged (see menus.exit_rows): an
# affordance that undoes nothing is one the reader has to try to learn that.
resettable = _resettable(prefs, pending)
if resettable:
count = len(resettable)
sections.append(
(
"Defaults",
[
(
"Reset to defaults…",
Text(),
f"Return {count} changed values to default"
if count > 1
else "Return the one changed value to default",
_RESET,
)
],
)
)
label_w = max(cell_len(label) for _, rows in sections for label, _, _, _ in rows)
value_w = max(cell_len(value.plain) for _, rows in sections for _, value, _, _ in rows)
# The shared editor header (menus.lane_header), pinned for the whole list: the lanes
# mean the same in every group, so a scrolled row keeps both its column header and its
# section heading overhead.
items: list = [Separator(lambda w: lane_header(label_w, value_w, w), pinned=True)]
# Everything up to the DESCRIPTION lane is the row's identity — which preference, and
# what it is set to — and it always fits. Only the explanation runs past the edge, so
# ←→ slide *it* under a pinned setting and value (Choice.hscroll_from, the same
# arrangement menu_rows gives a command list). Without it the descriptions simply died
# at the fold, which on the PicoCalc's 53 columns is most of every one of them.
description_at = label_w + 2 + value_w + 2
for group, rows in sections:
items.append(section_heading(group))
for label, value, help_text, key in rows:
items.append(
Choice(
title=lane_row(label, value, help_text, label_w, value_w),
value=key,
hscroll_from=description_at,
)
)
# Nothing at all while the page is clean — Esc leaves. With changes staged the pair
# appears below one blank line: Apply is the save action, and Back spells out what
# leaving instead would cost (see menus.exit_rows).
items.extend(exit_rows(len(pending), apply_value=_APPLY, back_value=_CANCEL))
title = "Preferences" + (f" — {len(pending)} staged" if pending else "")
return title, items
#: Widest terminal that still can't hold the DESCRIPTION lane. The three lanes the table
#: can't do without — the key you would type into ``preferences set``, what it is set to,
#: and what it would be if you hadn't — take about eighty cells between them, and the
#: descriptions are the lane that gives way, exactly as they do in the device-config table
#: on a narrow console. They are still on the page, and in the file's own comments.
_DESCRIBE_FROM = 100
def preferences_table(prefs: Preferences, width: int = _DESCRIBE_FROM) -> Table:
"""Build the full preferences table — every value, its default, and what it does.
The printed face of the page, for ``meshterm preferences show``. Unlike the screen it
lists *every* preference's default beside its value, because a terminal print has no
row to open and no reset row to infer the difference from — and it names each
preference by its **key**, since that is what ``preferences set`` takes.
"Every" is meant literally, platform gates included (``by_group()`` with no argument):
a command line is regularly typed on one machine about a file that belongs to another,
and a key the listing hid is a key nobody would think to ``set``.
Args:
prefs: The preferences to render.
width: The console's width, which decides whether the DESCRIPTION lane is drawn.
Returns:
A Rich :class:`Table` ready to hand to ``ctx.ui.show``.
"""
# Same frameless SIMPLE_HEAD shape as the device-config table, so the two printed
# settings views read as one family.
table = Table(
title="[accent]Preferences[/accent]",
title_justify="left",
box=box.SIMPLE_HEAD,
show_edge=False,
pad_edge=False,
header_style="muted",
expand=False,
padding=(0, 2, 0, 0),
)
describe = width >= _DESCRIBE_FROM
# The key lane is pinned to the longest key so no key is ever elided: a truncated
# `direct_message_s…` is not a thing anyone can type back. The two value lanes wrap
# instead (the basemap URL is 36 cells on its own), and DESCRIPTION takes the rest.
keys_w = max(len(spec.key) for spec in PREFERENCES) + 2
table.add_column("PREFERENCE", style="muted", no_wrap=True, min_width=keys_w)
table.add_column("VALUE")
table.add_column("DEFAULT", style="muted")
if describe:
table.add_column("DESCRIPTION", style="muted")
def row(cells: list[str]) -> list[str]:
"""Trim a row to the lanes this width actually draws."""
return cells if describe else cells[:-1]
for group, specs in by_group():
table.add_section()
table.add_row(*row([f"[accent]── {group} ──[/accent]", "", "", ""]))
for spec in specs:
value = format_value(spec, prefs.get(spec.key))
# An overridden value is the only thing on the row worth a colour: it is what
# this install disagrees with the code about.
table.add_row(
*row(
[
f" {spec.key}",
f"[warn]{value}[/warn]" if prefs.is_overridden(spec.key) else value,
format_value(spec, spec.default),
spec.description,
]
)
)
return table
# --- staging individual changes -----------------------------------------------
async def _stage_preference(
ctx: AppContext, prefs: Preferences, key: str, pending: dict[str, Any]
) -> None:
"""Prompt for one preference's new value and stage it.
Staging the value already in force is a no-op, so a row set back to where it started
reads clean again rather than counting as a change that changes nothing.
"""
spec = get_spec(key)
value = await _prompt_value(ctx, spec, _effective(prefs, key, pending))
if value is None:
return
if value == prefs.get(key):
pending.pop(key, None)
else:
pending[key] = value
async def _prompt_value(ctx: AppContext, spec: PrefSpec, current: Any) -> Any:
"""Prompt for a typed value for ``spec`` in the fitting dialog; ``None`` on cancel."""
if spec.value_type == "bool":
# A straight two-state choice reads best as a button pair, with the current state
# highlighted so Enter changes nothing by accident.
return await ctx.ui.dialog(
spec.description,
[("Off", False), ("On", True)],
title=spec.label,
default=1 if current else 0,
keys={"0": False, "1": True, "n": False, "y": True},
)
if spec.value_type == "enum" and spec.choices is not None:
items = [
Choice(
title=f"{label}" + (" (current)" if value == current else ""),
value=value,
)
for value, label in spec.choices.items()
]
return await ctx.ui.select(
spec.label, items, prompt=f"{spec.description}:", default=current
)
def validate(text: str) -> bool | str:
try:
parse_value(spec, text)
return True
except PreferenceError as exc:
return str(exc)
raw = await ctx.ui.text(
spec.label,
prompt=f"{spec.description}:",
default="" if current is None else str(current),
validate=validate,
help_text=range_hint(spec),
)
return None if raw is None else parse_value(spec, raw)
async def _stage_reset(ctx: AppContext, prefs: Preferences, pending: dict[str, Any]) -> None:
"""Confirm, then stage every changed preference back to its built-in default.
Amber rather than red: nothing is written yet and Esc still discards it, but one press
undoing every preference you have ever changed deserves to be asked about first.
"""
keys = _resettable(prefs, pending)
if not keys: # pragma: no cover - the row is only drawn when there is something to reset
return
plural = "" if len(keys) == 1 else "s"
if (
await ctx.ui.dialog(
f"Stage {len(keys)} preference{plural} back to their built-in defaults?",
[("Cancel", False), ("Reset", True)],
title="Reset to defaults",
default=1,
danger=True,
)
is not True
):
return
for key in keys:
default = get_spec(key).default
# Same rule as a hand-edited row: stage the default only where the *saved* value
# isn't already it — where it is, the entry was a staged change and simply goes.
if prefs.get(key) == default:
pending.pop(key, None)
else:
pending[key] = default
__all__ = ["edit_preferences", "preferences_table"]