From 356ca6a94a2786b8f720a42edb462b40517cfc9c Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sun, 13 Sep 2026 01:13:18 -0400 Subject: [PATCH] The widgets CLAUDE.md names as THE widgets have public names A leading underscore says "internal to this file, don't import me", and the column-age formatter and the node glyph table wore one while seventeen modules imported them and CLAUDE.md named them as the one place each concept lives. format_age sits beside format_ago now (prose age, column age), NODE_GLYPHS and DEFAULT_GLYPH beside them, age_seconds with the ages. A mechanical rename, 140 references across 24 files, CLAUDE.md's three lines with them so the guide and the code move as one. Co-Authored-By: Claude Fable 5.1 --- CLAUDE.md | 6 +++--- meshterm/tools/chat.py | 8 ++++---- meshterm/tools/tx_optimize.py | 4 ++-- meshterm/ui/admin_picker.py | 4 ++-- meshterm/ui/channels.py | 6 +++--- meshterm/ui/contactlist.py | 18 +++++++++--------- meshterm/ui/courier_screen.py | 4 ++-- meshterm/ui/node_detail_screen.py | 16 ++++++++-------- meshterm/ui/packet_viewer.py | 10 +++++----- meshterm/ui/path_composer.py | 4 ++-- meshterm/ui/purge_screen.py | 4 ++-- meshterm/ui/script.py | 10 +++++----- meshterm/ui/specimen.py | 2 +- meshterm/ui/theme.py | 2 +- meshterm/ui/timemachine_screen.py | 8 ++++---- meshterm/ui/walk_screen.py | 14 +++++++------- meshterm/ui/watchtower_screen.py | 16 ++++++++-------- meshterm/ui/widgets.py | 28 ++++++++++++++-------------- tests/test_gallery.py | 4 ++-- tests/test_repeater_admin.py | 4 ++-- tests/test_script_output.py | 4 ++-- tests/test_timemachine.py | 10 +++++----- tests/test_watchtower.py | 10 +++++----- tests/test_widgets.py | 14 +++++++------- 24 files changed, 105 insertions(+), 105 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 410c07d..adad1cd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,7 @@ them instead of hand-rolling: the language below). - `ui/widgets.py` — `highlighted_hash` (THE key widget — shows a key, lights its hash), `format_ago` (prose ages), - `_format_age` (column ages), `channel_glyph`, `_NODE_GLYPHS`, heard-age heat colouring. + `format_age` (column ages), `channel_glyph`, `NODE_GLYPHS`, heard-age heat colouring. - `ui/theme.py` — `name_style`/`node_style` (per-node hues, hash-derived), `snr_style`, the `you` white. @@ -65,7 +65,7 @@ only). A behaviour value belongs in the preference registry, not as a module con not in `config.toml`: a code constant a reader can't reach is a preference nobody has. Relative ages: `format_ago` for prose ("now", "5m ago", "never" — never "now ago"), -`_format_age` for aligned columns ("now", "5m"). +`format_age` for aligned columns ("now", "5m"). ### Navigation — the stack @@ -429,7 +429,7 @@ splitting safe has gone, because splitting is the machine face's job now. quoting stays and always will (`script._escaped`): a node broadcasts its own name and a stranger fills in a message body, and neither may end the record it sits in. - **A time is an age** — `now`, `5m`, `3h`, `never` (`script.age`, delegating to - `widgets._format_age` so the two faces cannot drift). An absolute instant survives where + `widgets.format_age` so the two faces cannot drift). An absolute instant survives where the instant *is* the fact (`script.stamp`, `fields.instant`): the device clock, an appointment set with `--at`, a live capture's own `TIME`, every column under `--absolute`. `--absolute` is an override of the `cli_time_format` **preference**, not a switch beside diff --git a/meshterm/tools/chat.py b/meshterm/tools/chat.py index c660ce6..a1c761c 100644 --- a/meshterm/tools/chat.py +++ b/meshterm/tools/chat.py @@ -49,7 +49,7 @@ from ..ui.fields import ChannelRef, NodeRef from ..ui.menus import Lane, column_header, fit_cells, section_heading from ..ui.theme import name_style from ..ui.tui import Choice, DeleteRequest, Separator -from ..ui.widgets import _NODE_GLYPHS, _age_seconds, _format_age, channel_glyph +from ..ui.widgets import NODE_GLYPHS, age_seconds, channel_glyph, format_age from .base import Tool, ToolResult, register if TYPE_CHECKING: @@ -834,7 +834,7 @@ def _title( #: The standard companion pink — the shared plain-node ``●`` colour — the contact dot's #: hue: the shape (filled/hollow) marks history, the colour marks "a companion", and the #: name beside it carries the person's own key-derived hue. -_COMPANION_DOT_STYLE = _NODE_GLYPHS[NODE_TYPE_CHAT][1] +_COMPANION_DOT_STYLE = NODE_GLYPHS[NODE_TYPE_CHAT][1] def _append_marker( @@ -910,7 +910,7 @@ def _append_body(text: Text, body: str, key_of: NameKeyResolver) -> None: def _ago(when: Any) -> str: - """The column age for a message time, through THE grammar (``_format_age``). + """The column age for a message time, through THE grammar (``format_age``). One deliberate difference from the widget: a missing or naive timestamp (a stray one from the wire) reads as a *blank* lane rather than ``never`` — the picker wants an @@ -918,7 +918,7 @@ def _ago(when: Any) -> str: """ if getattr(when, "tzinfo", None) is None: return "" - return _format_age(_age_seconds(when)) + return format_age(age_seconds(when)) def _channel_ref(idx: int | None, label: str, secret: bytes | None) -> ChannelRef: diff --git a/meshterm/tools/tx_optimize.py b/meshterm/tools/tx_optimize.py index 626ee72..79acaf3 100644 --- a/meshterm/tools/tx_optimize.py +++ b/meshterm/tools/tx_optimize.py @@ -488,13 +488,13 @@ def _target_items(contacts: list[Contact], admin: Contact) -> list: from ..ui.theme import name_style from ..ui.tui import Choice - from ..ui.widgets import _DEFAULT_GLYPH, _NODE_GLYPHS + from ..ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS def row(contact: Contact) -> Any: # The type mark keeps its own fixed hue; the *name* takes the node's key-derived # colour like every other list of nodes (a style on the Text itself would be the # row's base and would paint the name the type's colour too). - glyph, glyph_style = _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH) label = Text() label.append(f"{glyph} ", style=glyph_style) label.append( diff --git a/meshterm/ui/admin_picker.py b/meshterm/ui/admin_picker.py index 4cb1f13..de40c88 100644 --- a/meshterm/ui/admin_picker.py +++ b/meshterm/ui/admin_picker.py @@ -45,7 +45,7 @@ def admin_picker_rows(ctx: AppContext, contacts: list[Contact]) -> tuple[list, l from .menus import section_heading from .theme import name_style from .tui import Choice - from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS + from .widgets import DEFAULT_GLYPH, NODE_GLYPHS candidates = [c for c in contacts if (c.public_key or c.key_prefix).strip()] if not candidates: @@ -55,7 +55,7 @@ def admin_picker_rows(ctx: AppContext, contacts: list[Contact]) -> tuple[list, l # The type mark keeps its own fixed hue; the *name* takes the node's key-derived # colour like every other list of nodes (a style on the Text itself would be the # row's base and would paint the name the type's colour too). - glyph, glyph_style = _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH) label = Text() label.append(f"{glyph} ", style=glyph_style) label.append( diff --git a/meshterm/ui/channels.py b/meshterm/ui/channels.py index cfde88d..2d5d485 100644 --- a/meshterm/ui/channels.py +++ b/meshterm/ui/channels.py @@ -70,7 +70,7 @@ from .menus import ( from .qr import share_screen from .theme import glyph from .tui import CANCEL, Choice, SelectScreen, Separator -from .widgets import _age_seconds, _format_age, channel_glyph, format_ago +from .widgets import age_seconds, channel_glyph, format_age, format_ago if TYPE_CHECKING: from ..context import AppContext @@ -564,7 +564,7 @@ def _slot_text(ctx: AppContext, slot: ChannelSlot, stats: _LiveStats, name_w: in # no messages drew the same glyph twice meaning different things. text.append(f"{'○':>{_COUNT_WIDTH}}", style="muted") text.append(" ") - age = _format_age(_age_seconds(st.last_at)) if st is not None and st.last_at else "" + age = format_age(age_seconds(st.last_at)) if st is not None and st.last_at else "" text.append(f"{age:>{_AGE_WIDTH}}", style="muted") text.append(" ") # The shared peak across all channels, so every row's sparkline uses one scale. @@ -676,7 +676,7 @@ def _detail_summary(ctx: AppContext, slot: ChannelSlot, stats: _LiveStats) -> st if _is_muted(ctx, slot): parts.append("muted") if st is not None and st.last_at is not None: - parts.append(f"last {format_ago(_age_seconds(st.last_at))}") + parts.append(f"last {format_ago(age_seconds(st.last_at))}") width = get_platform().readable_cols while len(parts) > 1 and cell_len(" · ".join(parts)) > width: parts.pop() diff --git a/meshterm/ui/contactlist.py b/meshterm/ui/contactlist.py index f4bf7e1..5dbf47e 100644 --- a/meshterm/ui/contactlist.py +++ b/meshterm/ui/contactlist.py @@ -34,12 +34,12 @@ from .menus import fit_cells from .theme import name_style from .tui.select import Choice, SelectScreen, Separator from .widgets import ( - _DEFAULT_GLYPH, - _NODE_GLYPHS, + DEFAULT_GLYPH, + NODE_GLYPHS, ContactsSort, - _age_seconds, - _format_age, _recency_style, + age_seconds, + format_age, highlighted_hash, ) @@ -270,7 +270,7 @@ def _header( def _lane_cell(row: ContactRow, lane: ContactLane) -> Text: """One row's value for one lane, right-aligned into the lane's width and styled by kind. - An ``age`` lane draws the relative age in the column form (:func:`_format_age`) under + An ``age`` lane draws the relative age in the column form (:func:`format_age`) under recency heat, so a fresh value glows and a cold one greys — the same reading whatever the event the lane times. A ``count`` lane draws the tally muted, or a faint ``—`` where there is nothing to count, and clamps so a runaway tally can't widen the column. @@ -280,8 +280,8 @@ def _lane_cell(row: ContactRow, lane: ContactLane) -> Text: if value is None: return Text(f"{'—':>{lane.width}}", style="faint") return Text(f"{min(value, 99999):>{lane.width}}", style="muted") - secs = _age_seconds(value) - return Text(f"{_format_age(secs):>{lane.width}}", style=_recency_style(secs)) + secs = age_seconds(value) + return Text(f"{format_age(secs):>{lane.width}}", style=_recency_style(secs)) def _you_lane( @@ -353,7 +353,7 @@ def _lane( """ if row.you: return _you_lane(row, name_w, prefix_bytes, hash_w, lanes) - glyph, glyph_style = _NODE_GLYPHS.get(row.node_type, _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(row.node_type, DEFAULT_GLYPH) text = Text(no_wrap=True, overflow="ellipsis") text.append(glyph, style=glyph_style) text.append(" ") @@ -413,7 +413,7 @@ def _ordered( value = getattr(row, lane.field, None) if lane.kind == "count": return value or 0 - secs = _age_seconds(value) + secs = age_seconds(value) return secs if secs is not None else float("inf") ordered = sorted(rows, key=key_name) diff --git a/meshterm/ui/courier_screen.py b/meshterm/ui/courier_screen.py index 946b1e6..4608828 100644 --- a/meshterm/ui/courier_screen.py +++ b/meshterm/ui/courier_screen.py @@ -34,7 +34,7 @@ from .contactlist import SORT_COLUMNS, SORT_OPENS_ASCENDING, ContactListScreen, from .menus import icon_lane, marked_label, run_steps, section_heading from .tui import CANCEL, DM_BYTE_LIMIT, Choice, SelectScreen, Separator from .watchtower_screen import contact_watch_key -from .widgets import ContactsSort, _age_seconds, contact_packets, format_ago +from .widgets import ContactsSort, age_seconds, contact_packets, format_ago if TYPE_CHECKING: from ..context import AppContext @@ -323,7 +323,7 @@ def _done_row(message: QueuedMessage, lane: int = _MARK_LANE) -> Text: when = message.finished or message.created verb = "delivered" if message.status == DELIVERED else "gave up" row.append( - f" · {verb} {format_ago(_age_seconds(when))}" + f" · {verb} {format_ago(age_seconds(when))}" f" · {message.attempts} attempt{'s' if message.attempts != 1 else ''}", style="muted", ) diff --git a/meshterm/ui/node_detail_screen.py b/meshterm/ui/node_detail_screen.py index eea0059..ac830ac 100644 --- a/meshterm/ui/node_detail_screen.py +++ b/meshterm/ui/node_detail_screen.py @@ -117,10 +117,10 @@ from .theme import mark_rgb, name_style, snr_style from .tui.render import crop_cells, render_hanging, render_lines, render_to_ansi from .tui.screen import CANCEL, ListWindow, Screen from .widgets import ( - _DEFAULT_GLYPH, - _NODE_GLYPHS, - _age_seconds, + DEFAULT_GLYPH, + NODE_GLYPHS, _recency_style, + age_seconds, format_ago, highlighted_hash, node_type_legend, @@ -1192,7 +1192,7 @@ async def open_node_detail( glyph, glyph_style = SELF_MARK name_hue = "you" else: - glyph, glyph_style = _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(node_type, DEFAULT_GLYPH) name_hue = name_style(name, key) if name else "muted" header = Text() header.append(f"{glyph} ", style=glyph_style) @@ -1235,7 +1235,7 @@ async def open_node_detail( # one node. Only a node that is no contact, or one whose merge could not read our # history, falls back to the raw reception stat. heard_at = contact.last_seen if contact else None - secs = _age_seconds(heard_at or (hn.last_seen if hn else None)) + secs = age_seconds(heard_at or (hn.last_seen if hn else None)) heard_val = Text(format_ago(secs), style=_recency_style(secs)) if first_heard is not None: heard_val.append(f" · first {first_heard.astimezone():%b %d %Y}", style="muted") @@ -1759,10 +1759,10 @@ def _cluster_presentation(members: tuple[str, ...], type_of) -> _Cluster: # noq types = {type_of(m) for m in members} only = next(iter(types)) if len(types) == 1 else None if only is not None: - glyph, color = _NODE_GLYPHS.get(only, _DEFAULT_GLYPH) + glyph, color = NODE_GLYPHS.get(only, DEFAULT_GLYPH) kind = NODE_TYPE_LABELS.get(only, "node") else: - glyph, color = _DEFAULT_GLYPH + glyph, color = DEFAULT_GLYPH kind = "node" return _Cluster(glyph=glyph, color=color, label=f"{len(members)} {kind}s", rgb=mark_rgb(color)) @@ -1953,7 +1953,7 @@ def _routes_view( return (cluster.glyph, cluster.color) if cluster is not None else base_glyph_of(node) glyph_of = _with_target_glyph( - cluster_glyph_of, _NODE_GLYPHS.get(type_of(canonical_target), _DEFAULT_GLYPH) + cluster_glyph_of, NODE_GLYPHS.get(type_of(canonical_target), DEFAULT_GLYPH) ) return _RoutesView( routes=routes, diff --git a/meshterm/ui/packet_viewer.py b/meshterm/ui/packet_viewer.py index 94fbcfc..803b4b7 100644 --- a/meshterm/ui/packet_viewer.py +++ b/meshterm/ui/packet_viewer.py @@ -60,11 +60,11 @@ from .trace_screen import snr_bar from .tui.render import render_lines, render_to_ansi from .tui.screen import Screen from .widgets import ( - _DEFAULT_GLYPH, - _NODE_GLYPHS, + DEFAULT_GLYPH, + NODE_GLYPHS, NameKeyResolver, TypeOf, - _age_seconds, + age_seconds, format_ago, highlighted_hash, node_type_legend, @@ -727,7 +727,7 @@ class PacketViewer(Screen): icon, class_label = class_chrome(entry) rows.append(("class", Text(f"{icon} {class_label}"))) - secs = _age_seconds(entry.when) + secs = age_seconds(entry.when) heard = Text(entry.when.astimezone().strftime("%b %d %H:%M:%S")) heard.append(f" ({format_ago(secs)})", style="muted") rows.append(("heard", heard)) @@ -779,7 +779,7 @@ class PacketViewer(Screen): node_type = self._type_of(entry.node) if node_type is None: return UNKNOWN_MARK - return _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH) + return NODE_GLYPHS.get(node_type, DEFAULT_GLYPH) def _tail_rows(self, entry: PacketEntry) -> list[tuple[str, RenderableType]]: """The rows below the route graph: location, the message/ack fields, the raw dump.""" diff --git a/meshterm/ui/path_composer.py b/meshterm/ui/path_composer.py index 58ae0ea..70aa8d9 100644 --- a/meshterm/ui/path_composer.py +++ b/meshterm/ui/path_composer.py @@ -79,7 +79,7 @@ from .pathline import PathLine, cut_to, path_line from .theme import snr_style from .tui.render import query_line, render_lines, render_to_ansi from .tui.screen import ListWindow, Screen -from .widgets import NodeResolver, _age_seconds, _format_age, identity_label, path_text +from .widgets import NodeResolver, age_seconds, format_age, identity_label, path_text #: Sentinel spec meaning "no forced path — let the device route" (the trace screen's #: empty-spec convention). Only meaningful in target mode; a path walk has no target @@ -551,7 +551,7 @@ class PathComposerScreen(Screen): text.append(" ↔ ", style="muted") text.append(f"{snr:+.1f} dB", style=snr_style(snr)) text.append(f" {link.samples}×", style="muted") - age = _format_age(_age_seconds(link.last_seen)) + age = format_age(age_seconds(link.last_seen)) text.append(f" · {age}", style="muted") tags = "".join(_SOURCE_TAGS[s] for s in sorted(link.sources & _SOURCE_TAGS.keys())) if tags: diff --git a/meshterm/ui/purge_screen.py b/meshterm/ui/purge_screen.py index a343f59..0df26c6 100644 --- a/meshterm/ui/purge_screen.py +++ b/meshterm/ui/purge_screen.py @@ -285,7 +285,7 @@ async def purge_contacts(ctx: AppContext, self_key: str) -> int: return await _sweep(ctx, self_key, victims) -def _age_seconds(scored: ScoredContact) -> float | None: +def age_seconds(scored: ScoredContact) -> float | None: """A scored contact's last-heard age in seconds, or ``None`` if it was never heard.""" days = scored.signals.heard_age_days return None if days is None else days * _DAY @@ -319,7 +319,7 @@ def victims_for( return sweep_candidates(ranked, keep=math.ceil(len(sweepable) * int(value) / 100)) matched = [] for scored in sweepable: - age = _age_seconds(scored) + age = age_seconds(scored) if value == _NEVER: if age is None: matched.append(scored) diff --git a/meshterm/ui/script.py b/meshterm/ui/script.py index ea64b67..6501978 100644 --- a/meshterm/ui/script.py +++ b/meshterm/ui/script.py @@ -182,7 +182,7 @@ def stamp(when: datetime | None) -> str: Stored times are timezone-aware UTC; a naive one is a time whose offset we do not actually know, which is not a fact and so reads as absent — the same rule - :func:`~meshterm.ui.widgets._age_seconds` applies to ages. + :func:`~meshterm.ui.widgets.age_seconds` applies to ages. Args: when: The instant to format. @@ -201,7 +201,7 @@ def age(when: datetime | None, *, absent: str = NONE) -> str: The default time form, and the reason is the premise change: a person at a prompt reading ``2026-09-07T19:58:53-04:00`` is doing arithmetic to answer "recently?", which is the question they typed the command to ask. Delegates to - :func:`~meshterm.ui.widgets._format_age` so the two faces cannot drift apart. + :func:`~meshterm.ui.widgets.format_age` so the two faces cannot drift apart. Args: when: The instant to age. A naive datetime has no offset we know, so it reads as @@ -214,10 +214,10 @@ def age(when: datetime | None, *, absent: str = NONE) -> str: Returns: The age, or ``absent``. """ - from .widgets import _age_seconds, _format_age + from .widgets import age_seconds, format_age - seconds = _age_seconds(when) - return absent if seconds is None else _format_age(seconds) + seconds = age_seconds(when) + return absent if seconds is None else format_age(seconds) def number(value: Any, spec: str = "") -> str: diff --git a/meshterm/ui/specimen.py b/meshterm/ui/specimen.py index 9fa2c13..37ea70b 100644 --- a/meshterm/ui/specimen.py +++ b/meshterm/ui/specimen.py @@ -76,7 +76,7 @@ def specimen_lines() -> list[RenderableType]: lines.append(status) # The node-type marks in the theme's own ``type.*`` entries — the same styles every - # typed node in the app is drawn in (ui.widgets._NODE_GLYPHS), so this row *is* the + # typed node in the app is drawn in (ui.widgets.NODE_GLYPHS), so this row *is* the # marker language rather than a restatement of it. The star and the unknown ring have # no type of their own: they take the ``you`` white and ``muted`` grey they carry # everywhere else. diff --git a/meshterm/ui/theme.py b/meshterm/ui/theme.py index 162316a..fce757e 100644 --- a/meshterm/ui/theme.py +++ b/meshterm/ui/theme.py @@ -139,7 +139,7 @@ MESH_THEME = Theme( "batt.flash": "not bold #000000 on #dc2626", "batt.flash.off": "bold #f87171", # The node-type *marks* — THE colours behind ● ▲ ■ ◉ wherever a typed node is - # drawn (see ui.widgets._NODE_GLYPHS), and the map's own marker language: clients + # drawn (see ui.widgets.NODE_GLYPHS), and the map's own marker language: clients # the loud pink, repeaters the calmer violet, rooms a white square, sensors an # orange ringed dot. Named styles rather than raw hex so the 16-slot console picks # its slot *deliberately* — a naive downsample of the violet lands on grey, which diff --git a/meshterm/ui/timemachine_screen.py b/meshterm/ui/timemachine_screen.py index 72bb743..49d1eab 100644 --- a/meshterm/ui/timemachine_screen.py +++ b/meshterm/ui/timemachine_screen.py @@ -50,8 +50,8 @@ from .tui.screen import CANCEL, Screen from .tui.select import Choice, Separator from .widgets import ( ContactsSort, - _age_seconds, _recency_style, + age_seconds, body_heading, format_ago, highlighted_hash, @@ -404,7 +404,7 @@ def _node_sections( first, last = observations[0].observed_at, observations[-1].observed_at line = Text("heard ", style="muted") line.append(f"first {_when_label(first)} · last {_when_label(last)}") - line.append(f" ({format_ago(_age_seconds(last))})", style="muted") + line.append(f" ({format_ago(age_seconds(last))})", style="muted") out.append(line) snrs = [p[1] for p in snr_pairs] if snrs: @@ -527,7 +527,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis first, last = stamps[0], stamps[-1] line = Text("active ", style="muted") line.append(f"first {_when_label(first)} · last {_when_label(last)}") - line.append(f" ({format_ago(_age_seconds(last))})", style="muted") + line.append(f" ({format_ago(age_seconds(last))})", style="muted") out.append(line) if ledger.trace_total: @@ -1073,7 +1073,7 @@ def _mesh_sections( ) ) for key, name, first in listed: - secs = _age_seconds(first) + secs = age_seconds(first) line = Text(" ", no_wrap=True, overflow="ellipsis") line.append( fit_cells(name or "unknown", name_w), diff --git a/meshterm/ui/walk_screen.py b/meshterm/ui/walk_screen.py index 0c07632..f6ac12c 100644 --- a/meshterm/ui/walk_screen.py +++ b/meshterm/ui/walk_screen.py @@ -75,7 +75,7 @@ from .theme import mark_rgb, name_style, snr_style from .trace_screen import snr_bar from .tui.render import crop_cells, query_line, render_to_ansi from .tui.screen import ListWindow, Screen -from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS, _format_age, highlighted_hash +from .widgets import DEFAULT_GLYPH, NODE_GLYPHS, format_age, highlighted_hash if TYPE_CHECKING: from ..context import AppContext @@ -752,7 +752,7 @@ class WalkScreen(Screen): line.append(f" · {ring} hop{'s' if ring != 1 else ''} out", style="muted") if contact is not None and contact.last_seen is not None: secs = max(0.0, (utcnow() - contact.last_seen).total_seconds()) - line.append(f" · heard {_format_age(secs)}", style="muted") + line.append(f" · heard {format_age(secs)}", style="muted") return line def _short_hash(self, node: str) -> str: @@ -1134,8 +1134,8 @@ class WalkScreen(Screen): legend = Text() for (glyph, colour), word in ( (SELF_MARK, " you "), - (_NODE_GLYPHS[NODE_TYPE_REPEATER], " repeater "), - (_DEFAULT_GLYPH, " node "), + (NODE_GLYPHS[NODE_TYPE_REPEATER], " repeater "), + (DEFAULT_GLYPH, " node "), (UNKNOWN_MARK, " unknown"), ): legend.append(glyph, style=colour) @@ -1280,7 +1280,7 @@ class WalkScreen(Screen): row.append(f" {min(link.samples, 999):>3}×", style="muted") tags = "".join(_SOURCE_TAGS[s] for s in sorted(link.sources & _SOURCE_TAGS.keys())) row.append(f" {tags:<4}", style="faint") - age = _format_age( + age = format_age( max(0.0, (utcnow() - link.last_seen).total_seconds()) if link.last_seen is not None and getattr(link.last_seen, "tzinfo", None) else None @@ -1392,7 +1392,7 @@ class WalkScreen(Screen): def _glyph(self, node: str) -> tuple[str, str]: """A node's mark: the type glyph and the colour that type wears app-wide. - The shared marks (:data:`~meshterm.ui.widgets._NODE_GLYPHS`) and the shared + The shared marks (:data:`~meshterm.ui.widgets.NODE_GLYPHS`) and the shared ``type.*`` colours behind them, so a node is pinned here in exactly the glyph and hue the map, the route graph and the contact list pin it in — ``▲`` violet for a repeater, ``■`` for a room, ``◉`` for a sensor, ``●`` pink for a plain node, our @@ -1410,7 +1410,7 @@ class WalkScreen(Screen): contact = self._contacts.get(node) if contact is None: return UNKNOWN_MARK - return _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH) + return NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH) def _label(self, node: str) -> str: """A node's display name: its own name for us, contact name, or short hash.""" diff --git a/meshterm/ui/watchtower_screen.py b/meshterm/ui/watchtower_screen.py index 60984fc..43fa13d 100644 --- a/meshterm/ui/watchtower_screen.py +++ b/meshterm/ui/watchtower_screen.py @@ -27,7 +27,7 @@ from ..services.trace_runner import make_name_key_resolver from .menus import icon_lane, icon_mark, marked_label, section_heading from .theme import name_style from .tui import Choice, Separator -from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS, _age_seconds, _format_age +from .widgets import DEFAULT_GLYPH, NODE_GLYPHS, age_seconds, format_age if TYPE_CHECKING: from ..context import AppContext @@ -254,10 +254,10 @@ def _alert_lanes( row.append("○ ", style="muted") else: row.append("● ", style="err") - age = _format_age(_age_seconds(alert.when)) + age = format_age(age_seconds(alert.when)) row.append(f"{age:>5} ", style="muted") row.append(alert.kind.ljust(10), style=_KIND_STYLES.get(alert.kind, "brand")) - glyph, glyph_style = _NODE_GLYPHS.get(type_of(alert.label), _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(type_of(alert.label), DEFAULT_GLYPH) row.append(f"{glyph} ", style="muted" if alert.acked else glyph_style) if alert.acked: row.append(alert.label, style="muted") @@ -282,7 +282,7 @@ def _watched_row(entry: WatchedNode, type_of: Callable[[str], int | None]) -> Te glyph — and the name takes its key-derived hue (the entry's 12-hex watch key). """ node_type = entry.node_type if entry.node_type is not None else type_of(entry.key) - glyph, glyph_style = _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(node_type, DEFAULT_GLYPH) row = Text() row.append(f"{glyph} ", style=glyph_style) row.append(entry.name, style=name_style(entry.name, entry.key)) @@ -292,7 +292,7 @@ def _watched_row(entry: WatchedNode, type_of: Callable[[str], int | None]) -> Te if entry.silent_since is not None: row.append(" · ⚠ silent", style="err") elif entry.last_heard is not None: - row.append(f" · heard {_format_age(_age_seconds(entry.last_heard))}", style="muted") + row.append(f" · heard {format_age(age_seconds(entry.last_heard))}", style="muted") return row @@ -318,19 +318,19 @@ async def _pick_node(ctx: AppContext, contacts: list[Contact]) -> None: return def recency(pair: tuple[str, Contact]) -> float: - seen = _age_seconds(pair[1].last_seen) + seen = age_seconds(pair[1].last_seen) return seen if seen is not None else float("inf") items: list = [] for key, contact in sorted(candidates, key=recency): - glyph, glyph_style = _NODE_GLYPHS.get(contact.node_type, _DEFAULT_GLYPH) + glyph, glyph_style = NODE_GLYPHS.get(contact.node_type, DEFAULT_GLYPH) row = Text() row.append(f"{glyph} ", style=glyph_style) row.append( contact.name, style=name_style(contact.name, contact.public_key or contact.key_prefix), ) - row.append(f" heard {_format_age(_age_seconds(contact.last_seen))}", style="muted") + row.append(f" heard {format_age(age_seconds(contact.last_seen))}", style="muted") items.append(Choice(row, (key, contact))) picked = await session.select( "Watch a node", diff --git a/meshterm/ui/widgets.py b/meshterm/ui/widgets.py index ad3328a..3742398 100644 --- a/meshterm/ui/widgets.py +++ b/meshterm/ui/widgets.py @@ -636,7 +636,7 @@ def route_graph_style( if type_of is not None: node_type = type_of(node) if node_type is not None: - return _NODE_GLYPHS.get(node_type, _DEFAULT_GLYPH) + return NODE_GLYPHS.get(node_type, DEFAULT_GLYPH) named = resolve(node) return NODE_MARK if named and named != node else UNKNOWN_MARK @@ -846,13 +846,13 @@ def stats_panel( # The colours are the theme's ``type.*`` entries rather than raw hex, so the 16-slot console # picks its slot deliberately (the violet would otherwise downsample to grey, and a repeater # would read as an unknown node); on the regular platform they *are* the map's hues. -_NODE_GLYPHS: dict[int, tuple[str, str]] = { +NODE_GLYPHS: dict[int, tuple[str, str]] = { NODE_TYPE_REPEATER: (REPEATER_MARK[0], "type.repeater"), NODE_TYPE_ROOM: ("■", "type.room"), NODE_TYPE_SENSOR: ("◉", "type.sensor"), NODE_TYPE_CHAT: (NODE_MARK[0], "type.node"), } -_DEFAULT_GLYPH: tuple[str, str] = (NODE_MARK[0], "type.node") +DEFAULT_GLYPH: tuple[str, str] = (NODE_MARK[0], "type.node") def node_marker(node_type: int | None) -> tuple[str, RGB]: @@ -860,13 +860,13 @@ def node_marker(node_type: int | None) -> tuple[str, RGB]: The shared node-type marks (``▲`` repeater, ``■`` room, ``◉`` sensor, ``●`` plain node) in the map's own colours, minted here for a braille raster the way - :data:`_NODE_GLYPHS` mints them for a Rich row — so a spatial drawing pins its nodes + :data:`NODE_GLYPHS` mints them for a Rich row — so a spatial drawing pins its nodes in the exact glyphs and hues the map and the nodes list use. Both read the same ``type.*`` theme entry (through :func:`~meshterm.ui.theme.mark_rgb` here), so the raster and the row agree on whatever the platform's palette can afford. An unknown type falls back to the plain node mark. """ - glyph, style = _NODE_GLYPHS.get(node_type or -1, _DEFAULT_GLYPH) + glyph, style = NODE_GLYPHS.get(node_type or -1, DEFAULT_GLYPH) return glyph, mark_rgb(style) @@ -890,14 +890,14 @@ _HEAT_STOPS: tuple[tuple[float, tuple[int, int, int]], ...] = ( _RECENCY_NEVER = "#64748b" # never heard — the coldest slate -def _age_seconds(when: datetime | None) -> float | None: +def age_seconds(when: datetime | None) -> float | None: """Seconds since ``when`` (aware UTC), or ``None`` when unknown/naive.""" if when is None or getattr(when, "tzinfo", None) is None: return None return max(0.0, (utcnow() - when).total_seconds()) -def _format_age(secs: float | None) -> str: +def format_age(secs: float | None) -> str: """A compact relative age — ``now``, ``5m``, ``3h``, ``2d``, ``4w`` — or ``never``.""" if secs is None: return "never" @@ -941,9 +941,9 @@ def format_ago(secs: float | None) -> str: sighting reads as bare ``now`` and an unknown one as bare ``never`` (neither takes the suffix — "now ago" is nonsense), while any measured age reads ``5m ago``. Callers embedding an age in a sentence or parenthetical use this; - :func:`_format_age` stays the bare column form for aligned age lanes. + :func:`format_age` stays the bare column form for aligned age lanes. """ - age = _format_age(secs) + age = format_age(secs) return age if age in ("now", "never") else f"{age} ago" @@ -1142,7 +1142,7 @@ def _sort_header(label: str, column: str, sort: ContactsSort) -> str: def node_type_legend(indent: str = "") -> Text: """The one-line key to the node-type marks: ``★ you ▲ repeater ● node …``. - Every glyph in its shared map colour (see :data:`_NODE_GLYPHS`), each named muted after + Every glyph in its shared map colour (see :data:`NODE_GLYPHS`), each named muted after it. THE legend for any surface that draws typed node markers — the contacts list under its table, the route graph under its lanes — so one glyph means one thing app-wide. @@ -1153,7 +1153,7 @@ def node_type_legend(indent: str = "") -> Text: legend.append(SELF_MARK[0], style=SELF_MARK[1]) legend.append(" you", style="muted") for node_type in (NODE_TYPE_REPEATER, NODE_TYPE_CHAT, NODE_TYPE_ROOM, NODE_TYPE_SENSOR): - glyph, color = _NODE_GLYPHS[node_type] + glyph, color = NODE_GLYPHS[node_type] legend.append(" ") legend.append(glyph, style=color) legend.append(f" {NODE_TYPE_LABELS[node_type]}", style="muted") @@ -1346,13 +1346,13 @@ def contacts_table( ) table.add_section() for c in ordered_contacts(contacts, counts, sort): - secs = _age_seconds(c.last_seen) - glyph, glyph_style = _NODE_GLYPHS.get(c.node_type, _DEFAULT_GLYPH) + secs = age_seconds(c.last_seen) + glyph, glyph_style = NODE_GLYPHS.get(c.node_type, DEFAULT_GLYPH) pkts = contact_packets(c, counts) table.add_row( Text(glyph, style=glyph_style), Text(c.name, style=name_style(c.name, c.public_key or c.key_prefix)), - Text(_format_age(secs), style=_recency_style(secs)), + Text(format_age(secs), style=_recency_style(secs)), Text(str(pkts), style="muted") if pkts else Text("—", style="faint"), highlighted_hash(c.public_key, prefix_bytes) if c.public_key else unknown, ) diff --git a/tests/test_gallery.py b/tests/test_gallery.py index 1c78023..f9bacf0 100644 --- a/tests/test_gallery.py +++ b/tests/test_gallery.py @@ -95,7 +95,7 @@ from meshterm.ui.tui.prompt import CountdownDialog from meshterm.ui.tx_screen import TxSweepScreen from meshterm.ui.walk_screen import WalkScreen from meshterm.ui.widgets import ( - _NODE_GLYPHS, + NODE_GLYPHS, ContactsSort, highlighted_hash, node_marker, @@ -276,7 +276,7 @@ def _archived(cols: int, rows: int) -> Screen: def _node_detail_header() -> Text: # Through the app's own marker and name styles, not a hand-spelled hex: the gallery is # a specimen of what the platform draws, so a stub colour would hide a palette bug. - glyph, glyph_style = _NODE_GLYPHS[NODE_TYPE_REPEATER] + glyph, glyph_style = NODE_GLYPHS[NODE_TYPE_REPEATER] header = Text(f"{glyph} ", style=glyph_style) header.append("Hilltop-Repeater", style=name_style("Hilltop-Repeater", _HUB_KEY)) header.append(" repeater", style="muted") diff --git a/tests/test_repeater_admin.py b/tests/test_repeater_admin.py index 51d2e9c..28bee60 100644 --- a/tests/test_repeater_admin.py +++ b/tests/test_repeater_admin.py @@ -363,7 +363,7 @@ def test_picker_rows_hue_each_name_by_its_own_key(tui_ctx) -> None: """ from meshterm.ui.admin_picker import admin_picker_rows from meshterm.ui.theme import name_style - from meshterm.ui.widgets import _NODE_GLYPHS + from meshterm.ui.widgets import NODE_GLYPHS contacts = [ Contact(name="Hub-North", public_key="a1" * 32, key_prefix="a1b2c3d4", node_type=2), @@ -372,7 +372,7 @@ def test_picker_rows_hue_each_name_by_its_own_key(tui_ctx) -> None: rows, candidates = admin_picker_rows(tui_ctx, contacts) assert [c.name for c in candidates] == ["Hub-North", "Hub-South"] - glyph, glyph_style = _NODE_GLYPHS[2] + glyph, glyph_style = NODE_GLYPHS[2] titles = {str(row.value): row.title for row in rows if getattr(row, "value", None) is not None} hues = set() for contact in contacts: diff --git a/tests/test_script_output.py b/tests/test_script_output.py index 524a51f..4d86237 100644 --- a/tests/test_script_output.py +++ b/tests/test_script_output.py @@ -126,7 +126,7 @@ def test_stamp_is_absolute_local_iso_to_the_second() -> None: def test_stamp_reads_an_unknown_offset_as_absent() -> None: """A naive datetime is a time whose offset we don't know, which is not a fact. - The same rule :func:`~meshterm.ui.widgets._age_seconds` applies to relative ages. + The same rule :func:`~meshterm.ui.widgets.age_seconds` applies to relative ages. """ assert script.stamp(None) == script.NONE assert script.stamp(datetime(2026, 9, 7, 22, 22, 41)) == script.NONE @@ -162,7 +162,7 @@ def test_a_time_is_an_age_unless_the_instant_is_itself_the_fact() -> None: def test_the_age_ladder_steps_where_a_person_would_step(seconds: int, expected: str) -> None: """``now``, ``5m``, ``3h``, ``2d``, ``4w`` — the menu's own column ladder. - Delegated to :func:`~meshterm.ui.widgets._format_age` rather than re-derived, so the + Delegated to :func:`~meshterm.ui.widgets.format_age` rather than re-derived, so the two faces of the same age cannot drift apart. """ assert script.age(datetime.now(timezone.utc) - timedelta(seconds=seconds)) == expected diff --git a/tests/test_timemachine.py b/tests/test_timemachine.py index 1afa557..7345f9a 100644 --- a/tests/test_timemachine.py +++ b/tests/test_timemachine.py @@ -872,7 +872,7 @@ def test_picker_glyph_reflects_resolved_node_type() -> None: """A node with no stored type takes its contact's type for the leading glyph.""" from meshterm.core.models import NODE_TYPE_REPEATER from meshterm.ui.timemachine_screen import MESH, SELF - from meshterm.ui.widgets import _DEFAULT_GLYPH, _NODE_GLYPHS + from meshterm.ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS listed = _heard_nodes() # every node's stored node_type is None repeater = listed[0][0].node # Alice's id — the one the resolver knows as a repeater @@ -882,8 +882,8 @@ def test_picker_glyph_reflects_resolved_node_type() -> None: c.value[0]: c.label.plain[0] for c in screen._choices() if c.value not in (MESH, SELF) } # The resolved repeater takes ▲; a node the resolver can't place keeps the plain-node ●. - assert glyphs[repeater] == _NODE_GLYPHS[NODE_TYPE_REPEATER][0] - assert glyphs[listed[1][0].node] == _DEFAULT_GLYPH[0] + assert glyphs[repeater] == NODE_GLYPHS[NODE_TYPE_REPEATER][0] + assert glyphs[listed[1][0].node] == DEFAULT_GLYPH[0] def test_picker_stored_node_type_wins_over_the_resolver() -> None: @@ -892,7 +892,7 @@ def test_picker_stored_node_type_wins_over_the_resolver() -> None: from meshterm.core.models import NODE_TYPE_REPEATER, NODE_TYPE_SENSOR, HeardNode from meshterm.ui.timemachine_screen import MESH, SELF - from meshterm.ui.widgets import _NODE_GLYPHS + from meshterm.ui.widgets import NODE_GLYPHS sensor = HeardNode( node="ab" * 6, @@ -906,7 +906,7 @@ def test_picker_stored_node_type_wins_over_the_resolver() -> None: ) screen = _picker([(sensor, "Probe")], type_of=lambda _node: NODE_TYPE_REPEATER) glyph = next(c.label.plain[0] for c in screen._choices() if c.value not in (MESH, SELF)) - assert glyph == _NODE_GLYPHS[NODE_TYPE_SENSOR][0] + assert glyph == NODE_GLYPHS[NODE_TYPE_SENSOR][0] def test_picker_resort_keeps_the_highlight_on_its_node_and_the_filter() -> None: diff --git a/tests/test_watchtower.py b/tests/test_watchtower.py index 502645c..5f2b76a 100644 --- a/tests/test_watchtower.py +++ b/tests/test_watchtower.py @@ -214,11 +214,11 @@ def test_watched_row_type_glyph_and_hued_name(tmp_path: Path) -> None: from meshterm.core.watch_store import WatchedNode from meshterm.ui.theme import name_style from meshterm.ui.watchtower_screen import _watched_row - from meshterm.ui.widgets import _NODE_GLYPHS + from meshterm.ui.widgets import NODE_GLYPHS entry = WatchedNode(key="a1" * 6, name="Roof", node_type=2, last_heard=utcnow()) row = _watched_row(entry, lambda key: None) - glyph, glyph_style = _NODE_GLYPHS[2] + glyph, glyph_style = NODE_GLYPHS[2] assert row.plain.startswith(f"{glyph} Roof") assert any(s.style == glyph_style and s.start == 0 for s in row.spans) name_at = row.plain.index("Roof") @@ -260,7 +260,7 @@ def test_alert_row_leads_node_name_with_type_glyph(tmp_path: Path) -> None: """The node name is preceded by its shared type glyph (own colour, muted when acked).""" from meshterm.core.watch_store import Alert from meshterm.ui.watchtower_screen import _alert_lanes - from meshterm.ui.widgets import _DEFAULT_GLYPH, _NODE_GLYPHS + from meshterm.ui.widgets import DEFAULT_GLYPH, NODE_GLYPHS def key_of(label): return None @@ -268,7 +268,7 @@ def test_alert_row_leads_node_name_with_type_glyph(tmp_path: Path) -> None: def type_of(label): return 2 if label == "Roof" else None # Roof advertises as a repeater - glyph, glyph_style = _NODE_GLYPHS[2] + glyph, glyph_style = NODE_GLYPHS[2] alert = Alert(ident=1, when=utcnow(), kind="silence", label="Roof", message="quiet") row = _alert_lanes(alert, key_of, type_of) @@ -278,7 +278,7 @@ def test_alert_row_leads_node_name_with_type_glyph(tmp_path: Path) -> None: # Unknown type (and a keyless kind like courier) falls back to the plain-node glyph. ghost = Alert(ident=2, when=utcnow(), kind="courier", label="Ghost", message="gave up") - assert f"{_DEFAULT_GLYPH[0]} Ghost" in _alert_lanes(ghost, key_of).plain + assert f"{DEFAULT_GLYPH[0]} Ghost" in _alert_lanes(ghost, key_of).plain # An acked alert mutes the glyph with the rest of its history. acked = Alert(ident=3, when=utcnow(), kind="silence", label="Roof", message="quiet", acked=True) diff --git a/tests/test_widgets.py b/tests/test_widgets.py index a1fa847..a22d26a 100644 --- a/tests/test_widgets.py +++ b/tests/test_widgets.py @@ -18,7 +18,7 @@ from meshterm.ui.pathline import ( ) from meshterm.ui.theme import node_style from meshterm.ui.widgets import ( - _format_age, + format_age, format_ago, name_chip, path_text, @@ -33,12 +33,12 @@ def _span_style(text: Text, run: str) -> Style: def test_format_age_is_the_bare_column_form() -> None: """The lane form stays suffix-free at every magnitude, for aligned age columns.""" - assert _format_age(None) == "never" - assert _format_age(5) == "now" - assert _format_age(90) == "1m" - assert _format_age(7200) == "2h" - assert _format_age(180000) == "2d" - assert _format_age(1300000) == "2w" + assert format_age(None) == "never" + assert format_age(5) == "now" + assert format_age(90) == "1m" + assert format_age(7200) == "2h" + assert format_age(180000) == "2d" + assert format_age(1300000) == "2w" def test_format_ago_speaks_grammatical_prose() -> None: