The purge preview shows the evidence in lanes of its own kind
The preview's rows led on a PCTL lane and followed it with WHY IT RANKS LOW, one header over three lanes that held a contact's n-th weakest reason — so a message count, an age, a packet tally and a hop count moved between columns from row to row and nothing in a column meant the same thing twice. The lanes are fixed by kind now: HEARD and PKTS first, in the Contacts list's own order and drawn in its own grammar (the column age under recency heat, a tally muted, a faint dash for none), then the two the sweep adds, MSGS and HOPS. Each is measured across the victims and headed by a word right-aligned over its own values. The percentile goes with the phrases. A rank is the score's reading of itself, so a lane of them restated the order the list was already in; what an audit needs is the measurements, which is what a reader can check against what they know. The row pins its name out of the horizontal scroll instead — the evidence is what a narrow terminal cuts, and the name is what says whose evidence it is. ScoredContact drops the reasons it was the only consumer of. A lane also stops trusting a name to be ordinary text. A name is written by whoever owns the radio, so fit_cells — THE lane fitter, and every column's — now cuts between glyphs rather than codepoints and folds what no terminal can draw: cutting an emoji sequence in half stranded a joiner that swallowed the ellipsis appended after it, leaving the lane a cell short of what was drawn and every column right of the name starting late, and a newline or an escape in a name ended the row mid-lane whatever it measured. Both are settled in emoji_width, which already owns what this terminal really does with these codepoints. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
1da1c9db0d
commit
282334c761
8 files changed
+356
-166
No files matched your search
@@ -41,11 +41,13 @@ admin credentials are stored, and the unobserved contact above. They are still s
|
||||
still ranked — they are real contacts and the percentile scale is the whole population —
|
||||
but they are never swept.
|
||||
|
||||
**What is displayed is the percentile, never the score.** A raw ``47.3`` means nothing
|
||||
without the distribution it came from; a contact's *rank against your other contacts* is
|
||||
self-calibrating, needs no legend, and stays comparable when the weights change. So
|
||||
:class:`ScoredContact` carries :attr:`~ScoredContact.percentile` and the UI shows only that
|
||||
(see :func:`percentile_rank`).
|
||||
**The score is never displayed.** A raw ``47.3`` means nothing without the distribution it
|
||||
came from. What this module hands a screen instead is a *rank* — the list comes back ordered,
|
||||
and :attr:`~ScoredContact.percentile` places one contact in the field without a legend and
|
||||
without going stale when the weights change (see :func:`percentile_rank`). What a screen draws
|
||||
beside a contact is neither: the purge preview shows the :class:`ContactSignals` themselves, a
|
||||
lane per measured kind, because the thing a reader can check against what they know is the
|
||||
evidence, not this module's reading of it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -198,22 +200,24 @@ class ContactSignals:
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ScoredContact:
|
||||
"""One contact's standing among the others: its score, its percentile, and why.
|
||||
"""One contact's standing among the others: its score, its rank, and the evidence for both.
|
||||
|
||||
Attributes:
|
||||
contact: The contact this describes.
|
||||
signals: The evidence the score was computed from.
|
||||
score: The weighted sum plus any newcomer grace. Never displayed — see
|
||||
:attr:`percentile`, and the module docstring for why.
|
||||
percentile: Percentile rank within the scored population, ``0``–``100``. **This is
|
||||
the only number the UI shows**: it is self-calibrating (a mesh of 30 contacts
|
||||
and one of 300 both read the same way), needs no legend, and stays meaningful
|
||||
if the weights are ever retuned.
|
||||
percentile: Percentile rank within the scored population, ``0``–``100``. The
|
||||
score's one publishable reading: self-calibrating (a mesh of 30 contacts and
|
||||
one of 300 both read the same way), needing no legend, and still meaningful if
|
||||
the weights are ever retuned.
|
||||
protection: Why this contact can never be swept, or ``None`` if it can. One of the
|
||||
``PROTECT_*`` constants.
|
||||
reasons: Short lowercase phrases naming what this contact's standing rests on —
|
||||
its weakest lanes when it is a purge candidate, so the preview row explains
|
||||
itself without the reader having to know the formula.
|
||||
|
||||
The **signals** are what a screen shows, not the score or its terms: the purge preview
|
||||
draws one lane per measured kind straight off :attr:`signals` (see
|
||||
:mod:`~meshterm.ui.purge_screen`), so a reader auditing a sweep reads the evidence in
|
||||
the same units it was gathered in rather than a phrase this module chose for them.
|
||||
"""
|
||||
|
||||
contact: Contact
|
||||
@@ -221,7 +225,6 @@ class ScoredContact:
|
||||
score: float
|
||||
percentile: int
|
||||
protection: str | None = None
|
||||
reasons: tuple[str, ...] = ()
|
||||
|
||||
@property
|
||||
def protected(self) -> bool:
|
||||
@@ -395,7 +398,7 @@ def protection_for(signals: ContactSignals) -> str | None:
|
||||
#: unknown.
|
||||
_MIN_LOCATED = 4
|
||||
|
||||
#: The term names, in the order a :class:`ScoredContact` reports its reasons.
|
||||
#: The term names, in the order the weighted sum walks them.
|
||||
_TERM_NAMES = ("dm", "recency", "volume", "channel", "hops", "distance")
|
||||
|
||||
|
||||
@@ -449,54 +452,6 @@ def percentile_rank(score: float, population: Sequence[float]) -> int:
|
||||
return int(round(100.0 * (below + 0.5 * equal) / len(population)))
|
||||
|
||||
|
||||
def _reasons(
|
||||
signals: ContactSignals, terms: dict[str, float], weights: ScoreWeights
|
||||
) -> tuple[str, ...]:
|
||||
"""Name what this contact's standing rests on, weakest lane first.
|
||||
|
||||
The preview has one line per contact and the reader should not have to know the formula
|
||||
to audit a sweep — so each row says, in plain words, the two things that put it where it
|
||||
is. Phrases are drawn from the *measured* signals rather than from the term values, so
|
||||
"3 packets" is the actual tally and not a normalised fraction.
|
||||
"""
|
||||
phrases: list[tuple[float, str]] = []
|
||||
contribution = {
|
||||
"dm": terms["dm"] * weights.dm,
|
||||
"recency": terms["recency"] * weights.recency,
|
||||
"volume": terms["volume"] * weights.volume,
|
||||
"hops": terms["hops"] * weights.hops,
|
||||
}
|
||||
if signals.dm_total:
|
||||
phrases.append((contribution["dm"], f"{signals.dm_total} messages"))
|
||||
else:
|
||||
phrases.append((0.0, "never messaged"))
|
||||
if signals.heard_age_days is None:
|
||||
phrases.append((0.0, "never heard"))
|
||||
else:
|
||||
phrases.append((contribution["recency"], _age_phrase(signals.heard_age_days)))
|
||||
packets = signals.packets
|
||||
phrases.append((contribution["volume"], f"{packets} pkt{'' if packets == 1 else 's'}"))
|
||||
if signals.hops is not None:
|
||||
hops = signals.hops
|
||||
label = "direct" if hops < 0.5 else f"{hops:g} hops"
|
||||
phrases.append((contribution["hops"], label))
|
||||
phrases.sort(key=lambda pair: pair[0])
|
||||
return tuple(phrase for _, phrase in phrases[:3])
|
||||
|
||||
|
||||
def _age_phrase(days: float) -> str:
|
||||
"""A last-heard age in the fewest words: ``today`` / ``4d`` / ``6w`` / ``9mo`` / ``2y``."""
|
||||
if days < 1:
|
||||
return "today"
|
||||
if days < 14:
|
||||
return f"{int(days)}d"
|
||||
if days < 60:
|
||||
return f"{int(days / 7)}w"
|
||||
if days < 365:
|
||||
return f"{int(days / 30)}mo"
|
||||
return f"{days / 365:.0f}y"
|
||||
|
||||
|
||||
def rank_contacts(
|
||||
contacts: Sequence[Contact],
|
||||
signals: dict[str, ContactSignals],
|
||||
@@ -550,7 +505,6 @@ def rank_contacts(
|
||||
filled = {name: _fill_unknowns(column) for name, column in columns.items()}
|
||||
|
||||
scores: list[float] = []
|
||||
per_contact_terms: list[dict[str, float]] = []
|
||||
for index, sig in enumerate(gathered):
|
||||
terms = {name: filled[name][index] for name in _TERM_NAMES}
|
||||
total = (
|
||||
@@ -562,7 +516,6 @@ def rank_contacts(
|
||||
+ terms["distance"] * weights.distance
|
||||
+ term_grace(sig, weights)
|
||||
)
|
||||
per_contact_terms.append(terms)
|
||||
scores.append(total)
|
||||
|
||||
ranked = [
|
||||
@@ -572,11 +525,8 @@ def rank_contacts(
|
||||
score=score,
|
||||
percentile=percentile_rank(score, scores),
|
||||
protection=protection_for(sig),
|
||||
reasons=_reasons(sig, terms, weights),
|
||||
)
|
||||
for contact, sig, score, terms in zip(
|
||||
contacts, gathered, scores, per_contact_terms, strict=True
|
||||
)
|
||||
for contact, sig, score in zip(contacts, gathered, scores, strict=True)
|
||||
]
|
||||
ranked.sort(key=lambda scored: (-scored.score, scored.contact.name.casefold()))
|
||||
return ranked
|
||||
|
||||
+15
-6
@@ -51,6 +51,7 @@ from rich.text import Text
|
||||
from ..platforms import get_platform
|
||||
from .theme import glyph
|
||||
from .tui import Choice, Separator
|
||||
from .tui.emoji_width import cut_cells, drawable
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ..context import AppContext
|
||||
@@ -619,6 +620,17 @@ def fit_cells(text: str, width: int, *, align: str = "left") -> str:
|
||||
truncation are measured in display cells (wide glyphs count 2), so a name carrying
|
||||
an emoji or CJK character can't skew the lanes the way ``str.ljust`` would.
|
||||
|
||||
A lane's text is very often a **node's name**, which is written by whoever owns the
|
||||
radio and arrives over the air, so two more things are settled here rather than by
|
||||
every caller: whatever a terminal cannot draw is folded to a space
|
||||
(:func:`~meshterm.ui.tui.emoji_width.drawable` — a newline or an escape in a name
|
||||
would end the row mid-lane, and no width table can measure that away), and the cut
|
||||
falls **between** glyphs (:func:`~meshterm.ui.tui.emoji_width.cut_cells`), never
|
||||
inside one. A cut a codepoint at a time slices an emoji sequence in half, and the
|
||||
stranded joiner it leaves swallows the ellipsis appended after it — the lane then
|
||||
measures one cell short of what the terminal draws, and every column to its right
|
||||
starts late.
|
||||
|
||||
Args:
|
||||
text: The text to fit.
|
||||
width: The exact cell width to return.
|
||||
@@ -627,13 +639,10 @@ def fit_cells(text: str, width: int, *, align: str = "left") -> str:
|
||||
Returns:
|
||||
A string measuring exactly ``width`` cells.
|
||||
"""
|
||||
if not text.isprintable():
|
||||
text = drawable(text)
|
||||
if cell_len(text) > width:
|
||||
kept = ""
|
||||
for ch in text:
|
||||
if cell_len(kept + ch) > width - 1:
|
||||
break
|
||||
kept += ch
|
||||
text = kept + "…"
|
||||
text = cut_cells(text, width - 1) + "…"
|
||||
pad = " " * max(0, width - cell_len(text))
|
||||
return pad + text if align == "right" else text + pad
|
||||
|
||||
|
||||
+137
-78
@@ -13,9 +13,10 @@ the pushed Contacts list:
|
||||
computed from the actual ranking rather than from arithmetic on the table size, because
|
||||
protected contacts are never victims.
|
||||
2. **Read the list, and edit it.** Every contact the sweep would take, weakest first, with
|
||||
its percentile and the two or three facts that put it there — for the age rungs too,
|
||||
since knowing how the contacts an age threshold caught actually *rank* is exactly the
|
||||
check that threshold cannot do for itself. ``Delete`` drops a row from the list, so a
|
||||
the evidence beside it in lanes — how lately it was heard, what it has sent, whether you
|
||||
ever messaged it, how far out it sits. For the age rungs too, since seeing what the
|
||||
contacts an age threshold caught have actually *done* is exactly the check that threshold
|
||||
cannot do for itself. ``Delete`` drops a row from the list, so a
|
||||
contact the reader wants to keep is spared without abandoning the whole sweep and picking
|
||||
a shallower rung; ``←→`` scroll a row too wide for the terminal. Enter on a contact opens
|
||||
its detail page to *look* at, with the page's own contact-management verbs withheld (see
|
||||
@@ -29,10 +30,15 @@ the pushed Contacts list:
|
||||
the Archived list is one row away on the Contacts screen, and a restore is a single
|
||||
write. Saving the red for what cannot be undone is what keeps the red meaning anything.
|
||||
|
||||
**Only the percentile is ever shown.** A raw score means nothing without the distribution
|
||||
it came from, and would need a legend the moment the weights were ever retuned; a contact's
|
||||
rank against your other contacts explains itself. See :mod:`~meshterm.core.contact_score`
|
||||
for the scoring itself, which is pure and lives in core.
|
||||
**The preview shows the evidence, never the verdict.** Not the score — a weighted sum means
|
||||
nothing without the distribution it came from, and would need a legend the moment the weights
|
||||
were retuned. Not the percentile either, which led the row for one round: a rank is the
|
||||
score's own reading of itself, so a lane of them restated the order the list was already in
|
||||
and spent five columns saying "trust me". What an audit needs is the measurements, each in a
|
||||
lane of its own kind — headed like the Contacts list heads the two they share — so a column
|
||||
means one thing all the way down and the reader can check the sweep against what they know
|
||||
rather than against its arithmetic. See :mod:`~meshterm.core.contact_score` for the scoring
|
||||
itself, which is pure, lives in core, and still ranks the list.
|
||||
|
||||
**Archived, not deleted.** The sweep removes each contact from the *device* — freeing the
|
||||
slot, which is the whole point — and records it in the cross-session store with an archive
|
||||
@@ -50,7 +56,8 @@ from __future__ import annotations
|
||||
|
||||
import math
|
||||
import time
|
||||
from dataclasses import replace
|
||||
from collections.abc import Callable
|
||||
from dataclasses import dataclass, replace
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from rich.cells import cell_len
|
||||
@@ -67,15 +74,16 @@ from .menus import Lane, column_header, fit_cells, section_heading
|
||||
from .theme import name_style
|
||||
from .tui import Choice, Separator
|
||||
from .tui.screen import CANCEL
|
||||
from .widgets import _recency_style, format_age
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from ..context import AppContext
|
||||
|
||||
#: The keep-the-strongest rungs the target picker offers, as a share of the *sweepable*
|
||||
#: contacts. Percentages rather than absolute counts because the score itself is only ever
|
||||
#: read as a percentile: a rung and the lane it filters against then speak one language, and
|
||||
#: the ladder means the same thing on a table of thirty and a table of three hundred without
|
||||
#: a single value needing to be retuned. Coarse at the aggressive end — the difference
|
||||
#: contacts. Percentages rather than absolute counts because a share is the one form the
|
||||
#: ladder can state once and have mean the same thing on a table of thirty and a table of
|
||||
#: three hundred — the ranking underneath is a rank, so a count would have to be retuned
|
||||
#: for every mesh and a share never does. Coarse at the aggressive end — the difference
|
||||
#: between keeping 90% and 75% is a tidy-up, between 50% and 25% a decision.
|
||||
KEEP_RUNGS: tuple[int, ...] = (90, 75, 60, 50, 25)
|
||||
|
||||
@@ -101,91 +109,142 @@ AGE_RUNGS: tuple[tuple[str, int], ...] = (
|
||||
#: The age-rung value meaning the never-heard bucket (contacts with no advert time at all).
|
||||
_NEVER = -1
|
||||
|
||||
#: Percentile lane width, plus its gap — three digits and two cells of air.
|
||||
_PCTL_W = 5
|
||||
#: The gap between two lanes, in cells — the air that keeps a right-aligned value clear of
|
||||
#: the one before it, and what a lane's declared width carries on top of its content.
|
||||
_GAP = 2
|
||||
|
||||
#: Name lane width in the preview, plus its gap. Wide enough for the 20-odd bytes a
|
||||
#: MeshCore advert name runs to, and narrow enough to leave the reasons lane readable at
|
||||
#: MeshCore advert name runs to, and narrow enough to leave the evidence lanes readable at
|
||||
#: the PicoCalc's 53 columns.
|
||||
_NAME_W = 22
|
||||
|
||||
|
||||
def _pctl_style(percentile: int) -> str:
|
||||
"""The style a percentile is drawn in — the same quality reading ``snr_style`` gives SNR.
|
||||
def _count_cell(tally: int | None) -> tuple[str, str]:
|
||||
"""A tally lane's value: the number muted, or a faint ``—`` where there is nothing.
|
||||
|
||||
Three bands rather than a gradient: the heat ramp is spoken for (it colours *ages*, and
|
||||
a second gradient in a neighbouring lane would read as the same scale), and a percentile
|
||||
in a purge preview only ever answers one question — is this contact near the bottom?
|
||||
The Contacts list's ``count`` reading exactly (see
|
||||
:func:`~meshterm.ui.contactlist._lane_cell`), clamp included — a runaway tally widens no
|
||||
column — because the reader arrived here from that list and must not have to learn a
|
||||
second grammar for the same fact.
|
||||
"""
|
||||
if percentile >= 66:
|
||||
return "ok"
|
||||
if percentile >= 33:
|
||||
return "warn"
|
||||
return "err"
|
||||
if not tally:
|
||||
return "—", "faint"
|
||||
return f"{min(tally, 99999)}", "muted"
|
||||
|
||||
|
||||
def _pctl_cell(percentile: int) -> Text:
|
||||
"""One right-aligned percentile lane: the number alone, coloured by band."""
|
||||
return Text(f"{percentile:>3} ", style=_pctl_style(percentile))
|
||||
def _heard_cell(scored: ScoredContact) -> tuple[str, str]:
|
||||
"""The last-heard lane: the column age under recency heat, or a cold ``never``.
|
||||
|
||||
|
||||
def _preview_header(width: int) -> str:
|
||||
"""The preview's pinned column header, fitted to the terminal.
|
||||
|
||||
``WHY IT RANKS LOW`` heads all three reason lanes at once rather than naming each: a
|
||||
lane holds a contact's *n*-th weakest reason, so its phrases are of mixed kinds — a
|
||||
message count over an age over a hop count — and a per-lane word would claim a kind the
|
||||
column does not keep.
|
||||
:func:`~meshterm.ui.widgets.format_age` and the heat the Contacts list colours its own
|
||||
``HEARD`` lane with — one grammar for one fact, whichever screen is asking it.
|
||||
"""
|
||||
return column_header(
|
||||
[
|
||||
Lane("PCTL", _PCTL_W),
|
||||
Lane("NAME", _NAME_W),
|
||||
Lane(("WHY IT RANKS LOW", "WHY")),
|
||||
],
|
||||
width,
|
||||
)
|
||||
secs = age_seconds(scored)
|
||||
return format_age(secs), _recency_style(secs)
|
||||
|
||||
|
||||
def _reason_lanes(victims: list[ScoredContact]) -> tuple[int, ...]:
|
||||
"""Each reason lane's width: the widest phrase any victim puts in it.
|
||||
def _hops_cell(scored: ScoredContact) -> tuple[str, str]:
|
||||
"""The distance lane: ``direct`` for a neighbour, else the mean hop count it arrives by."""
|
||||
hops = scored.signals.hops
|
||||
if hops is None:
|
||||
return "—", "faint"
|
||||
return ("direct" if hops < 0.5 else f"{hops:g}"), "muted"
|
||||
|
||||
Measured against the list rather than fixed, so the lanes are only as wide as the words
|
||||
in them — and remeasured whenever a spared row leaves, which can only tighten them.
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class _Evidence:
|
||||
"""One evidence lane: the word over it, and how to read a contact's value for it.
|
||||
|
||||
A declaration rather than a branch, like :class:`~meshterm.ui.contactlist.ContactLane`
|
||||
next door: the header builder, the row builder and the width arithmetic all walk the
|
||||
same tuple, so a lane is added — or reordered — in one place.
|
||||
|
||||
Attributes:
|
||||
label: The header word. Right-aligned over its lane, where its digits will land.
|
||||
read: The contact's value for this lane, as ``(text, style)``.
|
||||
"""
|
||||
|
||||
label: str
|
||||
read: Callable[[ScoredContact], tuple[str, str]]
|
||||
|
||||
|
||||
#: The preview's evidence lanes, left to right. ``HEARD`` and ``PKTS`` lead, in the Contacts
|
||||
#: list's own order and drawn in its own grammar: the reader has just come from that list,
|
||||
#: and these are the two lanes they were already reading. ``MSGS`` and ``HOPS`` follow — the
|
||||
#: two the sweep adds, and the two nearly always empty in a list of candidates (a contact you
|
||||
#: have messaged is rarely weak enough to be swept), so a terminal too narrow for the whole
|
||||
#: row cuts the least informative end first and ``←→`` brings it back.
|
||||
_EVIDENCE: tuple[_Evidence, ...] = (
|
||||
_Evidence("HEARD", _heard_cell),
|
||||
_Evidence("PKTS", lambda scored: _count_cell(scored.signals.packets)),
|
||||
_Evidence("MSGS", lambda scored: _count_cell(scored.signals.dm_total)),
|
||||
_Evidence("HOPS", _hops_cell),
|
||||
)
|
||||
|
||||
|
||||
def _lane_widths(victims: list[ScoredContact]) -> tuple[int, ...]:
|
||||
"""Each evidence lane's width: its header word, or the widest value under it.
|
||||
|
||||
Measured against the list rather than fixed, so a lane of single digits is one cell of
|
||||
numbers instead of five of air — and remeasured whenever a spared row leaves, which can
|
||||
only tighten it.
|
||||
"""
|
||||
count = max((len(scored.reasons) for scored in victims), default=0)
|
||||
return tuple(
|
||||
max((cell_len(s.reasons[i]) for s in victims if len(s.reasons) > i), default=0)
|
||||
for i in range(count)
|
||||
max([cell_len(lane.label), *(cell_len(lane.read(v)[0]) for v in victims)])
|
||||
for lane in _EVIDENCE
|
||||
)
|
||||
|
||||
|
||||
def _victim_row(scored: ScoredContact, reason_lanes: tuple[int, ...]) -> Text:
|
||||
"""One preview line: percentile, the contact's name in its own hue, then why it ranks low.
|
||||
def _preview_header(widths: tuple[int, ...], width: int) -> str:
|
||||
"""The preview's pinned column header: the name lane, then one word per evidence lane.
|
||||
|
||||
The name keeps its key-derived colour like everywhere else in the app — this is a list
|
||||
of nodes, and a reader picking one out of thirty rows should not have to read it letter
|
||||
by letter because the screen it is on happens to be about deleting things.
|
||||
Each word is right-aligned inside its own lane, over values right-aligned too, so a
|
||||
header sits where its digits will land rather than off to the left of them — how the
|
||||
Contacts list heads the same two lanes.
|
||||
|
||||
The reasons sit in lanes of their own (``reason_lanes``, see :func:`_reason_lanes`),
|
||||
weakest first, so each one starts in the same column on every row instead of wherever
|
||||
the phrase before it happened to end. The last phrase on a row is left unpadded, as a
|
||||
trailing lane is: nothing follows it to line up.
|
||||
One word per lane is the whole point of the layout. A single ``WHY IT RANKS LOW`` used to
|
||||
head three lanes at once, and could not name any of them: a lane held a contact's *n*-th
|
||||
weakest reason, so a message count, an age and a hop count moved between columns from row
|
||||
to row and nothing in a column meant the same thing twice. The lanes are fixed by *kind*
|
||||
now, which is what makes them comparable down the list — and what lets a reader see that
|
||||
the contact they were unsure about is the one that has never sent a packet.
|
||||
"""
|
||||
lanes = [Lane("NAME", _NAME_W)]
|
||||
last = len(_EVIDENCE) - 1
|
||||
for index, (lane, lane_w) in enumerate(zip(_EVIDENCE, widths, strict=True)):
|
||||
lanes.append(Lane(f"{lane.label:>{lane_w}}", 0 if index == last else lane_w + _GAP))
|
||||
return column_header(lanes, width)
|
||||
|
||||
|
||||
def _victim_row(scored: ScoredContact, widths: tuple[int, ...]) -> Text:
|
||||
"""One preview line: the contact's name in its own hue, then its evidence, lane by lane.
|
||||
|
||||
The name keeps its key-derived colour like everywhere else in the app — this is a list of
|
||||
nodes, and a reader picking one out of thirty rows should not have to read it letter by
|
||||
letter because the screen it is on happens to be about archiving things. It goes through
|
||||
:func:`~meshterm.ui.menus.fit_cells`, so an over-long name ends on an ellipsis that says
|
||||
it was shortened, the lane is measured in display cells, and a name carrying an emoji is
|
||||
cut between glyphs rather than through one — a name is whatever a stranger's radio
|
||||
advertised, and it is the one value on this screen that can be anything at all.
|
||||
|
||||
Every other lane is right-aligned into its measured width and carries its own style: the
|
||||
heard age its recency heat, a tally muted, an absent one a faint ``—``. The row is built
|
||||
on an unstyled :class:`~rich.text.Text` rather than under the name's own style, because
|
||||
Rich merges a base style into every span — a faint ``—`` under a name-hue base would come
|
||||
out faint *in that node's colour*.
|
||||
"""
|
||||
contact = scored.contact
|
||||
row = _pctl_cell(scored.percentile)
|
||||
name = contact.name or contact.key_prefix or "?"
|
||||
# Through ``fit_cells``, so an over-long name ends on an ellipsis that says it was
|
||||
# shortened — and so the lane is measured in display cells, which is the only measure
|
||||
# that keeps the column straight once a name carries a wide glyph.
|
||||
row = Text()
|
||||
row.append(
|
||||
fit_cells(name, _NAME_W - 2) + " ",
|
||||
fit_cells(name, _NAME_W - _GAP) + " " * _GAP,
|
||||
style=name_style(name, contact.public_key or contact.key_prefix),
|
||||
)
|
||||
last = len(scored.reasons) - 1
|
||||
for index, phrase in enumerate(scored.reasons):
|
||||
cell = phrase if index == last else fit_cells(phrase, reason_lanes[index]) + " "
|
||||
row.append(cell, style="muted")
|
||||
last = len(_EVIDENCE) - 1
|
||||
for index, (lane, lane_w) in enumerate(zip(_EVIDENCE, widths, strict=True)):
|
||||
value, style = lane.read(scored)
|
||||
row.append(fit_cells(value, lane_w, align="right"), style=style)
|
||||
if index != last:
|
||||
row.append(" " * _GAP)
|
||||
return row
|
||||
|
||||
|
||||
@@ -444,19 +503,19 @@ def _preview_items(victims: list[ScoredContact]) -> list:
|
||||
"""The preview's rows: a pinned column header, one line per victim, then Apply/Back.
|
||||
|
||||
Each contact row is ``deletable``, so ``Delete`` lifts it out of the sweep, and pins its
|
||||
percentile lane out of the ``←→`` scroll (``hscroll_from``): the number is the reader's
|
||||
place in a list ordered by it, and sliding it away to read a long reasons lane would
|
||||
cost the row its bearing to gain nothing — the percentile is the part that already fits.
|
||||
**name** out of the ``←→`` scroll (``hscroll_from``): the evidence lanes are what a
|
||||
narrow terminal cuts, and sliding the name away to read them would cost the row the one
|
||||
thing that says which contact is being read.
|
||||
|
||||
The reason lanes are measured here, across every victim, which is also why a spared row
|
||||
rebuilds the rows through this function rather than dropping one: the lanes it leaves
|
||||
behind may have been sized by the phrase that just left.
|
||||
The lanes are measured here, across every victim, which is also why a spared row rebuilds
|
||||
the rows through this function rather than dropping one: the widths it leaves behind may
|
||||
have been set by the value that just left.
|
||||
"""
|
||||
lanes = _reason_lanes(victims)
|
||||
widths = _lane_widths(victims)
|
||||
return [
|
||||
Separator(_preview_header, pinned=True),
|
||||
Separator(lambda w: _preview_header(widths, w), pinned=True),
|
||||
*(
|
||||
Choice(title=_victim_row(v, lanes), value=v, deletable=True, hscroll_from=_PCTL_W)
|
||||
Choice(title=_victim_row(v, widths), value=v, deletable=True, hscroll_from=_NAME_W)
|
||||
for v in victims
|
||||
),
|
||||
# The same shape ``exit_rows`` draws, in this flow's own words: Apply has no key of
|
||||
|
||||
@@ -87,15 +87,24 @@ presentation, an emoji outside Emoji_Presentation (``🛣`` U+1F6E3, ``🕸`` U+
|
||||
one-cell text glyph, which is what both authorities said. Forcing one to two reserves a cell the
|
||||
terminal never draws and pulls the row's border a column *in* — see :data:`_DEFAULT_WIDE_BASE` for
|
||||
the case that proved it.
|
||||
|
||||
Two jobs beside the measuring belong here, because they are the same question asked of the same
|
||||
table. **Where a string may be cut** (:func:`cut_cells`, over :func:`clusters`): a lane that
|
||||
truncates a name a codepoint at a time cuts through the middle of a glyph, and the pieces that
|
||||
leaves — a stranded joiner, half a flag — are exactly what every correction above is written
|
||||
against. And **what may be drawn at all** (:func:`drawable`): an advert name is written by a
|
||||
stranger and can carry a newline or an escape, which no width table can make safe.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sys
|
||||
from collections.abc import Callable
|
||||
import unicodedata
|
||||
from collections.abc import Callable, Iterator
|
||||
|
||||
from prompt_toolkit.layout.controls import FormattedTextControl
|
||||
from rich.cells import cell_len
|
||||
|
||||
from ...core import win32dll
|
||||
|
||||
@@ -121,6 +130,12 @@ _EXTENDERS = frozenset((_VS16, *_MODIFIERS))
|
||||
#: measured at its own East-Asian width, with no VS16 "promote to 2" step.
|
||||
_ZERO_WIDTH = (_ZWJ, _VS16)
|
||||
|
||||
#: Unicode general categories holding nothing a terminal can draw: control characters
|
||||
#: (``Cc``), the format and bidi-control block (``Cf``), surrogates (``Cs``), and the line
|
||||
#: and paragraph separators (``Zl``/``Zp``). See :func:`drawable`, which folds them to a
|
||||
#: space — and keeps the one ``Cf`` codepoint that matters, the zero-width joiner.
|
||||
_UNDRAWABLE = frozenset(("Cc", "Cf", "Cs", "Zl", "Zp"))
|
||||
|
||||
#: The probe: a sun. Its base (U+2600) is East-Asian *narrow* (1), and Rich
|
||||
#: promotes the U+2600+U+FE0F pair to 2. So a terminal that reports 1 for this is
|
||||
#: exactly the terminal whose borders Rich currently misaligns.
|
||||
@@ -234,6 +249,97 @@ def _joined_out(text: str) -> str:
|
||||
return "".join(kept)
|
||||
|
||||
|
||||
def clusters(text: str) -> Iterator[str]:
|
||||
"""Split ``text`` into the glyphs the terminal actually draws, never inside one.
|
||||
|
||||
The same run :func:`_join_zwj_clusters` gathers out of a laid-out line, read off a plain
|
||||
string instead: a base, whatever extends it (:data:`_EXTENDERS` — a variation selector, a
|
||||
skin tone), then any number of *joiner + component + extenders* groups, plus the
|
||||
Regional Indicator **pair** a country flag is drawn from. A joiner that joins nothing
|
||||
(:func:`_joins`) is a cluster of its own, because it is not part of the glyph before it.
|
||||
|
||||
The unit a lane has to cut on: every correction in this module measures a *whole* glyph,
|
||||
so a cut through the middle of one leaves two pieces neither authority can measure — a
|
||||
lone Regional Indicator drawn as a letter, a skin tone with no base, or the stranded
|
||||
joiner that goes on to swallow the ellipsis the cut appended. See :func:`cut_cells`.
|
||||
"""
|
||||
index = 0
|
||||
count = len(text)
|
||||
while index < count:
|
||||
start = index
|
||||
index += 1
|
||||
while index < count and text[index] in _EXTENDERS:
|
||||
index += 1
|
||||
if _is_regional_indicator(text[start]) and index < count:
|
||||
if _is_regional_indicator(text[index]):
|
||||
index += 1
|
||||
while index < count and text[index] in _EXTENDERS:
|
||||
index += 1
|
||||
while index + 1 < count and text[index] == _ZWJ and _joins(text[index + 1]):
|
||||
index += 2 # the joiner and the codepoint it joins
|
||||
while index < count and text[index] in _EXTENDERS:
|
||||
index += 1
|
||||
yield text[start:index]
|
||||
|
||||
|
||||
def cut_cells(text: str, width: int) -> str:
|
||||
"""The longest prefix of ``text`` that fits ``width`` cells, cut **between** glyphs.
|
||||
|
||||
What a fixed lane needs when a name outruns it (:func:`~meshterm.ui.menus.fit_cells`),
|
||||
and the reason it cannot simply walk the string a character at a time: a MeshCore name
|
||||
is written by whoever owns the radio, so it arrives carrying whatever emoji they typed,
|
||||
and a codepoint-by-codepoint cut lands inside one about as often as not. Cutting
|
||||
``"👨👩👧"`` after its first joiner leaves a stranded joiner at the end of the lane,
|
||||
which then folds the ellipsis the caller appends into the glyph before it
|
||||
(:func:`_joined_out`) — the ellipsis measures nothing, the terminal draws it anyway, and
|
||||
every lane after the name starts a column late. Cutting a flag in half leaves a lone
|
||||
Regional Indicator, which is a letter rather than half a flag.
|
||||
|
||||
So the prefix is built out of whole :func:`clusters`, and a trailing joiner — stranded
|
||||
by the cut itself, or already stranded in the name — is dropped rather than left to
|
||||
swallow whatever comes next.
|
||||
|
||||
Args:
|
||||
text: The text to cut.
|
||||
width: The most cells the result may occupy.
|
||||
|
||||
Returns:
|
||||
A prefix measuring at most ``width`` cells, with every glyph in it whole.
|
||||
"""
|
||||
kept: list[str] = []
|
||||
used = 0
|
||||
for cluster in clusters(text):
|
||||
size = cell_len(cluster)
|
||||
if used + size > width:
|
||||
break
|
||||
kept.append(cluster)
|
||||
used += size
|
||||
while kept and kept[-1] == _ZWJ:
|
||||
kept.pop()
|
||||
return "".join(kept)
|
||||
|
||||
|
||||
def drawable(text: str) -> str:
|
||||
"""``text`` with every codepoint a terminal cannot *draw* folded to a space.
|
||||
|
||||
A name comes off the air from a stranger's radio, and nothing on the way in promises it
|
||||
holds only characters. A newline in one ends the row mid-lane; an ``ESC`` starts an
|
||||
escape sequence in the middle of a screen the app composed; a bidi override (``U+202E``)
|
||||
reverses everything drawn after it. All three measure zero cells and none of them is a
|
||||
width bug that any allowlist here could fix — they are text that must not reach the
|
||||
terminal at all, so a lane folds them to the one character that is always safe.
|
||||
|
||||
Folded: control characters, the format and bidi-control block, surrogates, and the line
|
||||
and paragraph separators. **Kept:** the zero-width joiner, which is format-class too and
|
||||
is the tell that holds an emoji sequence together, along with every mark and modifier a
|
||||
glyph is built from. Private-use codepoints are kept as well — that block is where a
|
||||
Nerd Font keeps the powerline glyphs the path line is drawn with.
|
||||
"""
|
||||
return "".join(
|
||||
" " if char != _ZWJ and unicodedata.category(char) in _UNDRAWABLE else char for char in text
|
||||
)
|
||||
|
||||
|
||||
def _narrow_lone_set() -> frozenset[str]:
|
||||
"""The lone-codepoint emoji to measure as one cell (see :data:`_DEFAULT_NARROW_LONE`).
|
||||
|
||||
@@ -716,4 +822,4 @@ class ClusterTextControl(FormattedTextControl):
|
||||
return content
|
||||
|
||||
|
||||
__all__ = ["ClusterTextControl", "calibrate"]
|
||||
__all__ = ["ClusterTextControl", "calibrate", "clusters", "cut_cells", "drawable"]
|
||||
@@ -306,16 +306,6 @@ def test_a_contact_with_no_signals_at_all_is_protected() -> None:
|
||||
assert ranked[0].protection == PROTECT_UNOBSERVED
|
||||
|
||||
|
||||
def test_reasons_name_the_weakest_lanes_in_plain_words() -> None:
|
||||
"""Each preview row explains itself without the reader having to know the formula."""
|
||||
ranked = _rank(("Quiet", {"packets": 3, "heard_age_days": 240.0, "dm_total": 0}))
|
||||
reasons = ranked[0].reasons
|
||||
assert "never messaged" in reasons
|
||||
assert "3 pkts" in reasons
|
||||
# The age reads in the fewest words that are still true — months, here.
|
||||
assert any(r.endswith("mo") for r in reasons)
|
||||
|
||||
|
||||
def test_a_stronger_contact_never_scores_below_a_weaker_one_on_every_axis() -> None:
|
||||
"""Sanity: dominance is preserved — better everywhere means ranked above."""
|
||||
ranked = _by_name(
|
||||
|
||||
@@ -491,7 +491,10 @@ async def test_purge_sweeps_under_a_progress_bar_and_reports_in_a_dialog() -> No
|
||||
# The preview lists exactly who would go, and commits on its Apply row (the default).
|
||||
preview = await _step_until_screen(session, lambda s: "to archive" in getattr(s, "title", ""))
|
||||
body = _screen_text(preview)
|
||||
assert "PCTL" in body # the standing lane is a percentile, never a raw score
|
||||
# The evidence, one lane per kind — never a score, and no longer a percentile either:
|
||||
# the row shows what was measured, and the list's order is the ranking.
|
||||
lanes = ["NAME", "HEARD", "PKTS", "MSGS", "HOPS"]
|
||||
assert [body.index(word) for word in lanes] == sorted(body.index(word) for word in lanes)
|
||||
assert all(v.name in body for v in victims)
|
||||
preview.handle("enter")
|
||||
|
||||
|
||||
@@ -278,6 +278,48 @@ def test_a_stranded_joiner_leaves_the_next_character_its_cell(monkeypatch) -> No
|
||||
_restore(snap)
|
||||
|
||||
|
||||
def test_clusters_split_between_glyphs_and_never_inside_one() -> None:
|
||||
"""The unit a lane may cut on: one entry per glyph the terminal actually draws.
|
||||
|
||||
A joined run, a flag's indicator *pair*, and a toned base each come back whole, because
|
||||
each is one glyph — while a joiner that joins nothing stands on its own, as it does
|
||||
everywhere else in this module (see :func:`~meshterm.ui.tui.emoji_width._joins`).
|
||||
"""
|
||||
assert list(ew.clusters(f"a{_FAMILY}{_CA}{_THUMB}b")) == ["a", _FAMILY, _CA, _THUMB, "b"]
|
||||
# Two flags in a row pair up one at a time rather than running together into four.
|
||||
assert list(ew.clusters(_CA + _CN)) == [_CA, _CN]
|
||||
# A name cut at its byte limit just past a joiner: the joiner is not part of the flag.
|
||||
assert list(ew.clusters(_STRANDED)) == [_FLAG, _ZWJ]
|
||||
|
||||
|
||||
def test_cut_cells_keeps_every_glyph_whole_and_strands_no_joiner() -> None:
|
||||
"""A lane's truncation lands between glyphs, so nothing measures what is not drawn.
|
||||
|
||||
The failure this exists for: cutting a codepoint at a time leaves a trailing joiner,
|
||||
which folds whatever the caller appends — the lane's ellipsis — into the glyph before
|
||||
it. The ellipsis then measures nothing while the terminal still draws it, and every
|
||||
column right of the name starts a cell late.
|
||||
"""
|
||||
assert ew.cut_cells(f"Bob {_FAMILY}", 6) == f"Bob {_FAMILY}" # it fits, so it is kept
|
||||
assert ew.cut_cells(f"Bob {_FAMILY}", 5) == "Bob " # it doesn't: dropped whole
|
||||
assert ew.cut_cells(_CA, 1) == "" # half a flag is a letter, not half a glyph
|
||||
assert ew.cut_cells(_STRANDED, 4) == _FLAG # the joiner cannot swallow what follows
|
||||
assert ew.cut_cells("plain name", 5) == "plain"
|
||||
|
||||
|
||||
def test_drawable_folds_only_what_no_terminal_can_draw() -> None:
|
||||
"""A newline, an escape or a bidi override in an advert name is folded to a space.
|
||||
|
||||
None of them is a width bug an allowlist could fix — they are text that must not reach
|
||||
the terminal at all. The joiner is format-class too and is the one kept, because it is
|
||||
what holds an emoji sequence together.
|
||||
"""
|
||||
assert ew.drawable("line\nbreak") == "line break"
|
||||
assert ew.drawable("esc\x1b[31mape") == "esc [31mape"
|
||||
assert ew.drawable("flipme") == "flip me"
|
||||
assert ew.drawable(f"Bob {_FAMILY}{_THUMB}") == f"Bob {_FAMILY}{_THUMB}"
|
||||
|
||||
|
||||
def test_join_zwj_clusters_merges_only_joined_runs() -> None:
|
||||
"""The fragment merge gathers a whole sequence and leaves everything else alone.
|
||||
|
||||
|
||||
@@ -143,6 +143,37 @@ def test_fit_cells_measures_display_cells_not_characters() -> None:
|
||||
assert fit_cells("ab", 5, align="right") == " ab"
|
||||
|
||||
|
||||
def test_fit_cells_keeps_a_broken_name_inside_its_lane() -> None:
|
||||
"""A name is written by a stranger's radio, and no part of one may skew the lane.
|
||||
|
||||
Two failures, one lane. A cut through the middle of an emoji sequence leaves a stranded
|
||||
joiner, which folds the ellipsis appended after it into the glyph before it — the lane
|
||||
then measures a cell short of what the terminal draws, and every column right of the
|
||||
name starts late. And a name carrying a newline or an escape ends the row mid-lane
|
||||
whatever it measures. Both are settled inside ``fit_cells`` (see
|
||||
:mod:`meshterm.ui.tui.emoji_width`), so every column in the app is covered by the one
|
||||
helper they all fit their labels through.
|
||||
"""
|
||||
from rich.cells import cell_len
|
||||
|
||||
family = "\U0001f468\U0001f469\U0001f467" # one glyph, three joined people
|
||||
flag = "\U0001f1e8\U0001f1e6" # one glyph, two Regional Indicators
|
||||
|
||||
for name in (f"Bob {family} Family", f"{flag} Canada Hub", "line\nbreak\x1b[31m"):
|
||||
for width in range(4, 24):
|
||||
assert cell_len(fit_cells(name, width)) == width, (name, width)
|
||||
|
||||
# The cut falls between glyphs: half a family is not a glyph, and half a flag is a letter.
|
||||
assert family in fit_cells(f"Bob {family}", 8) # it fits: the glyph is kept whole
|
||||
assert "" not in fit_cells(f"Bob {family}", 5) # it doesn't: no joiner left behind
|
||||
assert fit_cells(f"{flag} Hub", 4).startswith(flag) # the pair survives, or neither does
|
||||
|
||||
# What the terminal cannot draw never reaches it; an ordinary name is left alone.
|
||||
assert "\n" not in fit_cells("line\nbreak", 12)
|
||||
assert "\x1b" not in fit_cells("esc\x1b[31mape", 12)
|
||||
assert fit_cells("plain", 12).strip() == "plain"
|
||||
|
||||
|
||||
def test_main_menu_sections_answer_the_menus_own_question() -> None:
|
||||
"""Each section is a *doing*, in workflow order, and holds only what shares it.
|
||||
|
||||
|
||||
Reference in new issue
Block a user